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

Public Member Functions
	pipeline (const pipeline &)=delete

pipeline &	operator= (const pipeline &)=delete

	pipeline (transaction_base &, const std::string &Name=std::string())

	~pipeline () noexcept

query_id	insert (const std::string &)
	Add query to the pipeline. More...

void	complete ()
	Wait for all ongoing or pending operations to complete. 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, result >	retrieve ()
	Retrieve oldest unretrieved result (possibly wait for one) More...

bool	empty () const noexcept

int	retain (int retain_max=2)
	Set maximum number of queries to retain before issuing them to the backend. More...

void	resume ()
	Resume retained query emission (harmless when not needed) More...

Public Member Functions inherited from pqxx::internal::transactionfocus
	transactionfocus (transaction_base &t)

	transactionfocus ()=delete

	transactionfocus (const transactionfocus &)=delete

transactionfocus &	operator= (const transactionfocus &)=delete

Public Member Functions inherited from pqxx::internal::namedclass
	namedclass (const std::string &Classname)

	namedclass (const std::string &Classname, const std::string &Name)

const std::string &	name () const noexcept
	Object name, or the empty string if no name was given. More...

const std::string &	classname () const noexcept
	Class name. More...

std::string	description () const
	Combination of class name and object name; or just class name. More...

Additional Inherited Members
Protected Member Functions inherited from pqxx::internal::transactionfocus
void	register_me ()

void	unregister_me () noexcept

void	reg_pending_error (const std::string &) noexcept

bool	registered () const noexcept

Protected Attributes inherited from pqxx::internal::transactionfocus
transaction_base &	m_trans

Detailed Description

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

Use a pipeline if you want to execute queries without always sitting still while they execute. Result retrieval is decoupled from execution request; queries "go in at the front" and results "come out the back." Actually results may be retrieved in any order, if you want.

Feel free to pump as many queries into the pipeline as possible, even if they were generated after looking at a result from the same pipeline. To get the best possible throughput, try to make insertion of queries run as far ahead of results retrieval as possible; issue each query as early as possible and retrieve their results as late as possible, so the pipeline has as many ongoing queries as possible at any given time. In other words, keep it busy!

One warning: if any of the queries you insert leads to a syntactic error, the error may be returned as if it were generated by an older query. Future versions may try to work around this if working in a nontransaction.

Member Typedef Documentation

◆ query_id

using pqxx::pipeline::query_id = long

Constructor & Destructor Documentation

◆ pipeline() [1/2]

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

delete

◆ pipeline() [2/2]

pqxx::pipeline::pipeline	(	transaction_base &	t,
		const std::string &	Name = `std::string()`
	)

explicit

◆ ~pipeline()

pqxx::pipeline::~pipeline ( )

noexcept

References cancel(), pqxx::internal::transactionfocus::register_me(), pqxx::internal::transactionfocus::registered(), and pqxx::internal::transactionfocus::unregister_me().

Member Function Documentation

◆ cancel()

void 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::internal::transactionfocus::m_trans.

Referenced by ~pipeline().

◆ complete()

void pqxx::pipeline::complete ( )

Wait for all ongoing or pending operations to complete.

Detaches from the transaction when done.

◆ 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()

pipeline::query_id pqxx::pipeline::insert ( const std::string & q )

Add query to the pipeline.

Queries are accumulated in the pipeline and sent to the backend in a concatenated format, separated by semicolons. The queries you insert must not use this construct 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?

References pqxx::to_string().

◆ operator=()

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

delete

◆ resume()

void pqxx::pipeline::resume ( )

Resume retained query emission (harmless when not needed)

References pqxx::row::at(), pqxx::result::at(), pqxx::field::c_str(), pqxx::transaction_base::conn(), pqxx::transaction_base::exec(), pqxx::internal::transactionfocus::m_trans, retrieve(), pqxx::separated_list(), pqxx::result::size(), and pqxx::internal::transactionfocus::unregister_me().

Referenced by retain().

◆ 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_max A nonnegative "retention capacity;" passing zero will cause queries to be issued immediately

Returns: Old retention capacity

References resume(), and pqxx::to_string().

◆ 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< pipeline::query_id, 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:

pipeline.hxx
pipeline.cxx

Public Types

Public Member Functions

Additional Inherited Members