pqxx::pipeline Class Reference

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

#include <pipeline.hxx>

Inheritance diagram for pqxx::pipeline:

Collaboration diagram for pqxx::pipeline:

Classes
struct	getquery
class	Query

Public Types
typedef long	query_id

Public Member Functions
	pipeline (transaction_base &, const PGSTD::string &Name=PGSTD::string())
	~pipeline () throw ()
void	cancel ()
	Cancel ongoing query, if any. More...
const PGSTD::string &	classname () const throw ()
void	complete ()
	Wait for all ongoing or pending operations to complete. More...
PGSTD::string	description () const
bool	empty () const throw ()
void	flush ()
	Forget all ongoing or pending operations and retrieved results. More...
query_id	insert (const PGSTD::string &)
	Add query to the pipeline. More...
bool	is_finished (query_id) const
	Is result for given query available? More...
const PGSTD::string &	name () const throw ()
void	resume ()
	Resume retained query emission (harmless when not needed) More...
int	retain (int retain_max=2)
	Set maximum number of queries to retain before issuing them to the backend. More...
result	retrieve (query_id qid)
	Retrieve result for given query. More...
PGSTD::pair< query_id, result >	retrieve ()
	Retrieve oldest unretrieved result (possibly wait for one) More...

Protected Member Functions
void	reg_pending_error (const PGSTD::string &) throw ()
void	register_me ()
bool	registered () const throw ()
void	unregister_me () throw ()

Protected Attributes
transaction_base &	m_Trans

Private Types
typedef PGSTD::map< query_id, Query >	QueryMap

Private Member Functions
	pipeline (const pipeline &)
	Not allowed. More...
void	attach ()
void PQXX_PRIVATE	check_end_results ()
void	detach ()
query_id PQXX_PRIVATE	generate_id ()
	Create new query_id. More...
void PQXX_PRIVATE	get_further_available_results ()
bool	have_pending () const throw ()
void PQXX_PRIVATE PQXX_NORETURN	internal_error (const PGSTD::string &err) throw (PGSTD::logic_error)
void PQXX_PRIVATE	issue ()
void PQXX_PRIVATE	obtain_dummy ()
bool PQXX_PRIVATE	obtain_result (bool expect_none=false)
pipeline &	operator= (const pipeline &)
	Not allowed. More...
void PQXX_PRIVATE	receive (pipeline::QueryMap::const_iterator stop)
	Receive results, up to stop if possible. More...
void PQXX_PRIVATE	receive_if_available ()
	Receive any results that happen to be available; it's not urgent. More...
PGSTD::pair < pipeline::query_id, result >	retrieve (pipeline::QueryMap::iterator)
void	set_error_at (query_id qid) throw ()
	The given query failed; never issue anything beyond that. More...

Static Private Member Functions
static query_id	qid_limit () throw ()
	Upper bound to query id's. More...

Private Attributes
bool	m_dummy_pending
	Is there a "dummy query" pending? More...
query_id	m_error
	Point at which an error occurred; no results beyond it will be available. More...
PGSTD::pair < QueryMap::iterator, QueryMap::iterator >	m_issuedrange
int	m_num_waiting
query_id	m_q_id
QueryMap	m_queries
int	m_retain

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

typedef long pqxx::pipeline::query_id

typedef PGSTD::map<query_id,Query> pqxx::pipeline::QueryMap

private

Constructor & Destructor Documentation

pqxx::pipeline::pipeline ( transaction_base &  , const PGSTD::string &  Name = PGSTD::string()  )

explicit

pqxx::pipeline::~pipeline

(

)

throw ()

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

private

Not allowed.

Member Function Documentation

void pqxx::pipeline::attach ( )

private

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.

void PQXX_PRIVATE pqxx::pipeline::check_end_results ( )

private

const PGSTD::string& pqxx::internal::namedclass::classname ( ) const throw ()

inlineinherited

void pqxx::pipeline::complete

(

)

Wait for all ongoing or pending operations to complete.

Detaches from the transaction when done.

PGSTD::string pqxx::internal::namedclass::description ( ) const

inherited

void pqxx::pipeline::detach ( )

private

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

inline

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.

query_id PQXX_PRIVATE pqxx::pipeline::generate_id ( )

private

Create new query_id.

void PQXX_PRIVATE pqxx::pipeline::get_further_available_results ( )

private

bool pqxx::pipeline::have_pending ( ) const throw ()

inlineprivate

query_id pqxx::pipeline::insert

(

const PGSTD::string &

)

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

void PQXX_PRIVATE PQXX_NORETURN pqxx::pipeline::internal_error ( const PGSTD::string &  err ) throw (PGSTD::logic_error)

private

bool pqxx::pipeline::is_finished

(

query_id

)

const

Is result for given query available?

void PQXX_PRIVATE pqxx::pipeline::issue ( )

private

const PGSTD::string& pqxx::internal::namedclass::name ( ) const throw ()

inlineinherited

void PQXX_PRIVATE pqxx::pipeline::obtain_dummy ( )

private

bool PQXX_PRIVATE pqxx::pipeline::obtain_result ( bool  expect_none = false )

private

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

private

Not allowed.

static query_id pqxx::pipeline::qid_limit ( ) throw ()

inlinestaticprivate

Upper bound to query id's.

void PQXX_PRIVATE pqxx::pipeline::receive ( pipeline::QueryMap::const_iterator  stop )

private

Receive results, up to stop if possible.

void PQXX_PRIVATE pqxx::pipeline::receive_if_available ( )

private

Receive any results that happen to be available; it's not urgent.

void pqxx::internal::transactionfocus::reg_pending_error ( const PGSTD::string &  ) throw ()

protectedinherited

void pqxx::internal::transactionfocus::register_me ( )

protectedinherited

bool pqxx::internal::transactionfocus::registered ( ) const throw ()

inlineprotectedinherited

void pqxx::pipeline::resume

(

)

Resume retained query emission (harmless when not needed)

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

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

inline

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.

References retrieve().

Referenced by retrieve().

Here is the call graph for this function:

Here is the caller graph for this function:

PGSTD::pair<query_id, result> pqxx::pipeline::retrieve

(

)

Retrieve oldest unretrieved result (possibly wait for one)

Returns

The query's identifier and its result set

PGSTD::pair<pipeline::query_id, result> pqxx::pipeline::retrieve ( pipeline::QueryMap::iterator  )

private

void pqxx::pipeline::set_error_at ( query_id  qid ) throw ()

inlineprivate

The given query failed; never issue anything beyond that.

void pqxx::internal::transactionfocus::unregister_me ( ) throw ()

protectedinherited

Member Data Documentation

bool pqxx::pipeline::m_dummy_pending

private

Is there a "dummy query" pending?

query_id pqxx::pipeline::m_error

private

Point at which an error occurred; no results beyond it will be available.

PGSTD::pair<QueryMap::iterator,QueryMap::iterator> pqxx::pipeline::m_issuedrange

private

int pqxx::pipeline::m_num_waiting

private

query_id pqxx::pipeline::m_q_id

private

QueryMap pqxx::pipeline::m_queries

private

int pqxx::pipeline::m_retain

private

transaction_base& pqxx::internal::transactionfocus::m_Trans

protectedinherited

---

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

• /usr/include/pqxx/pipeline.hxx