Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

pqxx::pipeline Class Reference

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

#include <pipeline.hxx>

Inheritance diagram for pqxx::pipeline:

pqxx::internal::transactionfocus pqxx::internal::namedclass List of all members.

Public Types

typedef unsigned query_id

Public Member Functions

 pipeline (transaction_base &t, const PGSTD::string &PName="")
 ~pipeline () throw ()
query_id insert (const PGSTD::string &)
 Add query to the pipeline.

void complete ()
 Wait for all ongoing or pending operations to complete.

void flush ()
 Forget all pending operations and retrieved results.

bool is_running (query_id) const
 Has given query started yet?

bool is_finished (query_id) const
 Is result for given query available?

result retrieve (query_id)
 Retrieve result for given query.

PGSTD::pair< query_id, resultretrieve ()
 Retrieve oldest unretrieved result (possibly wait for one).

bool empty () const throw ()
void retain ()
 Optimization control: don't start issuing yet, more queries are coming.

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


Detailed Description

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

Warning:
This is a prototype, and it may still change radically before becoming a stable part of the library. Also, the class may be very sensitive to exceptions; in certain cases, exceptions occurring in the class may leave a pipeline in a poorly defined state.
Use a pipeline if you want to execute several queries in succession, in situations where some of the queries do not depend on the outcome of the preceding one. Result retrieval is decoupled from execution request; queries "go in at the front" and results "come out the back." In fact, results may be retrieved in any order--though this will be slower than sticking to the order in which they were entered.

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 unsigned pqxx::pipeline::query_id
 


Constructor & Destructor Documentation

pqxx::pipeline::pipeline transaction_base t,
const PGSTD::string &  PName = ""
[explicit]
 

pqxx::pipeline::~pipeline  )  throw ()
 


Member Function Documentation

void pqxx::pipeline::complete  ) 
 

Wait for all ongoing or pending operations to complete.

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

void pqxx::pipeline::flush  ) 
 

Forget all pending operations and retrieved results.

pqxx::pipeline::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!

bool pqxx::pipeline::is_finished query_id   )  const
 

Is result for given query available?

bool pqxx::pipeline::is_running query_id   )  const
 

Has given query started yet?

void pqxx::pipeline::resume  ) 
 

Resume retained query emission (harmless when not needed).

void pqxx::pipeline::retain  ) 
 

Optimization control: don't start issuing yet, more queries are coming.

The pipeline will normally issue the first query inserted into it to the backend, and accumulate any new queries inserted while it is executing; those will once again be issued at the earliest opportunity. This may not be optimal, since most of the pipeline's speed advantage comes from its ability to bundle queries together and issue them at once. The normal procedure will be too "eager" to provide the full benefit for that first query. Call retain() to tell the pipeline to hold off on issuing queries when you know that more queries are about to be inserted. Use resume() afterwards, or the queries may not be issued for some time. Query emission will be resumed implicitly, however, if results are requested for queries that have not yet been issued to the backend. For best performance, call retain() before inserting a batch of queries into a pipeline, and resume() directly afterwards to make sure the queries are sent to the backend.

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

Retrieve oldest unretrieved result (possibly wait for one).

pqxx::result pqxx::pipeline::retrieve query_id   ) 
 

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.


The documentation for this class was generated from the following files:
Generated on Mon May 10 13:19:11 2004 for libpqxx by doxygen 1.3.6-20040222