libpqxx  7.7.3
pqxx::pipeline Class Reference

Processes several queries in FIFO manner, optimized for high throughput. More...

#include <pipeline.hxx>

Inheritance diagram for pqxx::pipeline:

Public Types

using query_id = long
 Identifying numbers for queries. More...
 

Public Member Functions

 pipeline (pipeline const &)=delete
 
pipelineoperator= (pipeline const &)=delete
 
 pipeline (transaction_base &t)
 Start a pipeline. More...
 
 pipeline (transaction_base &t, std::string_view tname)
 Start a pipeline. Assign it a name, for more helpful error messages. More...
 
 ~pipeline () noexcept
 Close the pipeline. More...
 
query_id insert (std::string_view) &
 Add query to the pipeline. More...
 
void complete ()
 Wait for all ongoing or pending operations to complete, and detach. More...
 
void flush ()
 Forget all ongoing or pending operations and retrieved results. More...
 
void cancel ()
 Cancel ongoing query, if any. More...
 
bool is_finished (query_id) const
 Is result for given query available? More...
 
result retrieve (query_id qid)
 Retrieve result for given query. More...
 
std::pair< query_id, resultretrieve ()
 Retrieve oldest unretrieved result (possibly wait for one). More...
 
bool empty () const noexcept
 
int retain (int retain_max=2) &
 
void resume () &
 Resume retained query emission. Harmless when not needed. More...
 
- Public Member Functions inherited from pqxx::transaction_focus
 transaction_focus (transaction_base &t, std::string_view cname, std::string_view oname)
 
 transaction_focus (transaction_base &t, std::string_view cname, std::string &&oname)
 
 transaction_focus (transaction_base &t, std::string_view cname)
 
 transaction_focus ()=delete
 
 transaction_focus (transaction_focus const &)=delete
 
transaction_focusoperator= (transaction_focus const &)=delete
 
constexpr std::string_view classname () const noexcept
 Class name, for human consumption. More...
 
std::string_view name () const &noexcept
 Name for this object, if the caller passed one; empty string otherwise. More...
 
std::string description () const
 
 transaction_focus (transaction_focus &&)=delete
 Can't move a transaction_focus. More...
 
transaction_focusoperator= (transaction_focus &&)=delete
 Can't move a transaction_focus. More...
 

Additional Inherited Members

- Protected Member Functions inherited from pqxx::transaction_focus
void register_me ()
 
void unregister_me () noexcept
 
void reg_pending_error (std::string const &) noexcept
 
bool registered () const noexcept
 
- Protected Attributes inherited from pqxx::transaction_focus
transaction_basem_trans
 

Detailed Description

Processes several queries in FIFO manner, optimized for high throughput.

Use a pipeline if you want to keep doing useful work while your queries are executing. Result retrieval is decoupled from execution request; queries "go in at the front" and results "come out the back."

Actually, you can retrieve the results in any order if you want, but it may lead to surprising "time travel" effects if any of the queries fails. In particular, syntax errors in the queries can confuse things and show up too early in the stream of results.

Generally, if any of the queries fails, it will throw an exception at the point where you request its result. But it may happen earlier, especially if you request results out of chronological order.

Warning
While a pipeline is active, you cannot execute queries, open streams, etc. on the same transaction. A transaction can have at most one object of a type derived from pqxx::transaction_focus active on it at a time.

Member Typedef Documentation

◆ query_id

Identifying numbers for queries.

Constructor & Destructor Documentation

◆ pipeline() [1/3]

pqxx::pipeline::pipeline ( pipeline const &  )
delete

◆ pipeline() [2/3]

pqxx::pipeline::pipeline ( transaction_base t)
explicit

Start a pipeline.

◆ pipeline() [3/3]

pqxx::pipeline::pipeline ( transaction_base t,
std::string_view  tname 
)

Start a pipeline. Assign it a name, for more helpful error messages.

◆ ~pipeline()

pqxx::pipeline::~pipeline ( )
noexcept

Member Function Documentation

◆ cancel()

void PQXX_COLD pqxx::pipeline::cancel ( )

Cancel ongoing query, if any.

May cancel any or all of the queries that have been inserted at this point whose results have not yet been retrieved. If the pipeline lives in a backend transaction, that transaction may be left in a nonfunctional state in which it can only be aborted.

Therefore, either use this function in a nontransaction, or abort the transaction after calling it.

References pqxx::transaction_base::conn(), and pqxx::transaction_focus::m_trans.

Referenced by ~pipeline().

◆ complete()

void pqxx::pipeline::complete ( )

Wait for all ongoing or pending operations to complete, and detach.

Detaches from the transaction when done.

This does not produce the queries' results, so it may not report any errors which may have occurred in their execution. To be sure that your statements succeeded, call retrieve until the pipeline is empty.

◆ empty()

bool pqxx::pipeline::empty ( ) const
noexcept

◆ flush()

void pqxx::pipeline::flush ( )

Forget all ongoing or pending operations and retrieved results.

Queries already sent to the backend may still be completed, depending on implementation and timing.

Any error state (unless caused by an internal error) will also be cleared. This is mostly useful in a nontransaction, since a backend transaction is aborted automatically when an error occurs.

Detaches from the transaction when done.

◆ insert()

pqxx::pipeline::query_id pqxx::pipeline::insert ( std::string_view  q) &

Add query to the pipeline.

Queries accumulate in the pipeline, which sends them to the backend in a batch separated by semicolons. The queries you insert must not use this trick themselves, or the pipeline will get hopelessly confused!

Returns
Identifier for this query, unique only within this pipeline.

◆ is_finished()

bool pqxx::pipeline::is_finished ( pipeline::query_id  q) const

Is result for given query available?

◆ operator=()

pipeline& pqxx::pipeline::operator= ( pipeline const &  )
delete

◆ resume()

void pqxx::pipeline::resume ( ) &

◆ retain()

int pqxx::pipeline::retain ( int  retain_max = 2) &

Set maximum number of queries to retain before issuing them to the backend. The pipeline will perform better if multiple queries are issued at once, but retaining queries until the results are needed (as opposed to issuing them to the backend immediately) may negate any performance benefits the pipeline can offer.

Recommended practice is to set this value no higher than the number of queries you intend to insert at a time.

Parameters
retain_maxA nonnegative "retention capacity;" passing zero will cause queries to be issued immediately
Returns
Old retention capacity

References resume().

◆ retrieve() [1/2]

result pqxx::pipeline::retrieve ( query_id  qid)

Retrieve result for given query.

If the query failed for whatever reason, this will throw an exception. The function will block if the query has not finished yet.

Warning
If results are retrieved out-of-order, i.e. in a different order than the one in which their queries were inserted, errors may "propagate" to subsequent queries.

◆ retrieve() [2/2]

std::pair< pqxx::pipeline::query_id, pqxx::result > pqxx::pipeline::retrieve ( )

Retrieve oldest unretrieved result (possibly wait for one).

Returns
The query's identifier and its result set.

Referenced by resume().


The documentation for this class was generated from the following files: