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 
23 namespace pqxx
24 {
25 // TODO: libpq 14 introduced a similar "pipeline mode." Can we use that?
26 
28 
46 class PQXX_LIBEXPORT pipeline : public transaction_focus
47 {
48 public:
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 
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 
151 private:
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
Interface definition (and common code) for "transaction" classes.
Definition: transaction_base.hxx:72
pipeline(transaction_base &t)
Start a pipeline.
Definition: pipeline.hxx:56
Result set containing data returned by a query or command.
Definition: result.hxx:67
bool empty() const noexcept
Definition: pipeline.hxx:130
Processes several queries in FIFO manner, optimized for high throughput.
Definition: pipeline.hxx:46
Base class for things that monopolise a transaction&#39;s attention.
Definition: transaction_focus.hxx:24
pipeline(transaction_base &t, std::string_view tname)
Start a pipeline. Assign it a name, for more helpful error messages.
Definition: pipeline.hxx:61
long query_id
Identifying numbers for queries.
Definition: pipeline.hxx:50
result retrieve(query_id qid)
Retrieve result for given query.
Definition: pipeline.hxx:121
Internal error in libpqxx library.
Definition: except.hxx:154
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:22