# pqxx::pipeline Class Reference

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

`#include <pipeline.hxx>`

Inheritance diagram for pqxx::pipeline:

[legend]
List of all members.

## Public Types

typedef long | query_id

## Public Member Functions

| pipeline (transaction_base &, const PGSTD::string &Name=PGSTD::string())
| ~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 ongoing or pending operations and retrieved results.
bool | is_finished (query_id) const
| Is result for given query available?
result | retrieve (query_id qid)
| Retrieve result for given query.
PGSTD::pair< query_id, result > | retrieve ()
| Retrieve oldest unretrieved result (possibly wait for one).
bool | empty () const throw ()
int | retain (int retain_max=2)
| Set maximum number of queries to retain before issuing them to the backend.
void | resume ()
| Resume retained query emission (harmless when not needed).

## Classes

struct | getquery
class | Query

## 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 may 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 long pqxx::pipeline::query_id

## Constructor & Destructor Documentation

pqxx::pipeline::pipeline | ( | transaction_base & | ,
|  | const PGSTD::string & | Name = `PGSTD::string()` |
| ) |  |  | `[explicit]`

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

## Member Function Documentation

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!

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

void pqxx::pipeline::complete | ( |  | ) |

Wait for all ongoing or pending operations to complete.

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.

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

Is result for given query available?

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.

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

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

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

void pqxx::pipeline::resume | ( |  | ) |

Resume retained query emission (harmless when not needed).

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

- pipeline.hxx
- pipeline.cxx