# pqxx::cachedresult Class Reference

`#include <cachedresult.h>`

List of all members.

## Public Types

typedef result::size_type | size_type
typedef size_type | blocknum
typedef result::tuple | tuple
| Tuple type. Currently borrowed from result, but may change in the future.
typedef tuple | Tuple

## Public Member Functions

template<typename TRANSACTION>
| cachedresult (TRANSACTION &T, const char Query[], const PGSTD::string &BaseName="query", size_type Granularity=100)
const tuple | operator[] (size_type i) const
| Access a tuple. Invalid index yields undefined behaviour.
const tuple | at (size_type i) const
| Access a tuple. Throws exception if index is out of range.
size_type | size () const
| Number of rows in result set. First call may be slow.
bool | empty () const
| Is the result set empty, i.e. does it contain no rows? May fetch 1 block.

## Detailed Description

Cached result set. Chunks of result data are transparently fetched on-demand and stored in an internal cache for reuse. Functionality is similar to that of result, with certain restrictions and different performance characteristics. A cachedresult must live in the context of a backend transaction, so that it can fetch further rows as they are needed.

Warning:
  The transaction must have serializable isolation level to ensure that the result set of the query remains unchanged while parts of it are cached. This class is to be replaced by a C++-style iterator interface.

The class uses a Cursor internally to fetch results. Data are not fetched row-by-row, but in chunks of configurable size. For internal computational reasons, these chunks (called "blocks" here) must be at least 2 rows large.

Warning:
  PostgreSQL currently doesn't always let you move cursors backwards, which is a feature this class relies upon. As a result, cachedresult will only work on certain types of queries. To make things worse, there is no documentation to define exactly which queries those are. Therefore the only way to use cachedresult at this time is to test carefully. Hopefully this can be fixed in the future.

Deprecated:
  This class was not ported to the 2.x libpqxx API because it is to be replaced by a container/iterator interface.

## Member Typedef Documentation

typedef result::size_type pqxx::cachedresult::size_type

typedef size_type pqxx::cachedresult::blocknum

typedef result::tuple pqxx::cachedresult::tuple

Tuple type. Currently borrowed from result, but may change in the future.

typedef tuple pqxx::cachedresult::Tuple

Deprecated:
  For compatibility with old Tuple class

## Constructor & Destructor Documentation

template<typename TRANSACTION>

pqxx::cachedresult::cachedresult | ( | TRANSACTION & | T,
|  | const char | Query[],
|  | const PGSTD::string & | BaseName = `"query"`,
|  | size_type | Granularity = `100` |
| ) |  |  | `[explicit]`

Perform query and transparently fetch and cache resulting data.

Parameters:

  | T | is the transaction context in which the cachedresult lives. This will be used whenever data is fetched. Must have isolation level "serializable," otherwise a build error will be generated for the symbol error_permitted_isolation_level.
  | Query | is the SQL query that yields the desired result set.
  | BaseName | gives the initial part of the name for this cachedresult and the Cursor it uses to obtain its results.
  | Granularity | determines how large the blocks of data used internally will be; must be at least 2.

## Member Function Documentation

const tuple pqxx::cachedresult::operator[] | ( | size_type | i | ) | const

Access a tuple. Invalid index yields undefined behaviour.

Caveat: the tuple contains a reference to a result that may be destroyed by any other operation on the cachedresult, even if its constness is preserved. Therefore only use the returned tuple as a temporary, and do not try to copy-construct it, or keep references or pointers to it.

Parameters:

  | i | the number of the tuple to be accessed.

const tuple pqxx::cachedresult::at | ( | size_type | i | ) | const

Access a tuple. Throws exception if index is out of range.

If the given index is not the index of an existing row, an out_of_range error will be thrown.

Caveat: the tuple contains a reference to a result that may be destroyed by any other operation on the cachedresult, even if its constness is preserved. Therefore only use the returned tuple as a temporary, and do not try to copy-construct it, or keep references or pointers to it.

Parameters:

  | i | the number of the tuple to be accessed.

pqxx::cachedresult::size_type pqxx::cachedresult::size | ( |  | ) | const

Number of rows in result set. First call may be slow.

bool pqxx::cachedresult::empty | ( |  | ) | const

Is the result set empty, i.e. does it contain no rows? May fetch 1 block.

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

- cachedresult.h
- cachedresult.cxx