libpqxx 7.7.0
pipeline.hxx
1/* Definition of the pqxx::pipeline class.
2 *
3 * Throughput-optimized mechanism for executing queries.
4 *
5 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/pipeline instead.
6 *
7 * Copyright (c) 2000-2022, Jeroen T. Vermeulen.
8 *
9 * See COPYING for copyright license. If you did not receive a file called
10 * COPYING with this source code, please notify the distributor of this
11 * mistake, or contact the author.
12 */
13#ifndef PQXX_H_PIPELINE
14#define PQXX_H_PIPELINE
15
16#include <limits>
17#include <map>
18#include <string>
19
20#include "pqxx/transaction_base.hxx"
21
22
23namespace pqxx
24{
25// TODO: libpq 14 introduced a similar "pipeline mode." Can we use that?
26
28
46class PQXX_LIBEXPORT pipeline : public transaction_focus
47{
48public:
50 using query_id = long;
51
52 pipeline(pipeline const &) = delete;
53 pipeline &operator=(pipeline const &) = delete;
54
56 explicit pipeline(transaction_base &t) : transaction_focus{t, s_classname}
57 {
58 init();
59 }
61 pipeline(transaction_base &t, std::string_view tname) :
62 transaction_focus{t, s_classname, tname}
63 {
64 init();
65 }
66
68 ~pipeline() noexcept;
69
71
77 query_id insert(std::string_view) &;
78
80
86 void complete();
87
89
98 void flush();
99
101
109 void cancel();
110
112 [[nodiscard]] bool is_finished(query_id) const;
113
115
121 result retrieve(query_id qid)
122 {
123 return retrieve(m_queries.find(qid)).second;
124 }
125
127
128 std::pair<query_id, result> retrieve();
129
130 [[nodiscard]] bool empty() const noexcept { return std::empty(m_queries); }
131
134
145 int retain(int retain_max = 2) &;
146
147
149 void resume() &;
150
151private:
152 struct PQXX_PRIVATE Query
153 {
154 explicit Query(std::string_view q) :
155 query{std::make_shared<std::string>(q)}
156 {}
157
158 std::shared_ptr<std::string> query;
159 result res;
160 };
161
162 using QueryMap = std::map<query_id, Query>;
163
164 void init();
165 void attach();
166 void detach();
167
169 static constexpr query_id qid_limit() noexcept
170 {
171 // Parenthesise this to work around an eternal Visual C++ problem:
172 // Without the extra parentheses, unless NOMINMAX is defined, the
173 // preprocessor will mistake this "max" for its annoying built-in macro
174 // of the same name.
175 return (std::numeric_limits<query_id>::max)();
176 }
177
179 PQXX_PRIVATE query_id generate_id();
180
181 bool have_pending() const noexcept
182 {
183 return m_issuedrange.second != m_issuedrange.first;
184 }
185
186 PQXX_PRIVATE void issue();
187
189 void set_error_at(query_id qid) noexcept
190 {
191 PQXX_UNLIKELY
192 if (qid < m_error)
193 m_error = qid;
194 }
195
197 [[noreturn]] PQXX_PRIVATE void internal_error(std::string const &err);
198
199 PQXX_PRIVATE bool obtain_result(bool expect_none = false);
200
201 PQXX_PRIVATE void obtain_dummy();
202 PQXX_PRIVATE void get_further_available_results();
203 PQXX_PRIVATE void check_end_results();
204
206 PQXX_PRIVATE void receive_if_available();
207
209 PQXX_PRIVATE void receive(pipeline::QueryMap::const_iterator stop);
210 std::pair<pipeline::query_id, result> retrieve(pipeline::QueryMap::iterator);
211
212 QueryMap m_queries;
213 std::pair<QueryMap::iterator, QueryMap::iterator> m_issuedrange;
214 int m_retain = 0;
215 int m_num_waiting = 0;
216 query_id m_q_id = 0;
217
219 bool m_dummy_pending = false;
220
222 query_id m_error = qid_limit();
223
225
228 internal::encoding_group m_encoding;
229
230 // C++20: constinit.
231 constexpr static std::string_view s_classname{"pipeline"};
232};
233} // namespace pqxx
234#endif
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:23
Processes several queries in FIFO manner, optimized for high throughput.
Definition: pipeline.hxx:47
pipeline(transaction_base &t)
Start a pipeline.
Definition: pipeline.hxx:56
bool empty() const noexcept
Definition: pipeline.hxx:130
pipeline & operator=(pipeline const &)=delete
pipeline(transaction_base &t, std::string_view tname)
Start a pipeline. Assign it a name, for more helpful error messages.
Definition: pipeline.hxx:61
pipeline(pipeline const &)=delete
long query_id
Identifying numbers for queries.
Definition: pipeline.hxx:50
Result set containing data returned by a query or command.
Definition: result.hxx:68
Interface definition (and common code) for "transaction" classes.
Definition: transaction_base.hxx:73
Base class for things that monopolise a transaction's attention.
Definition: transaction_focus.hxx:25