Pool - SeqAn API Documentation

# Class Pool
Pools are push- and pop-passive pipeline modules.

All Subcl's | MapperConfig, MapperConfigSize, MapperSpec, PoolConfig, PoolConfigSize, PoolSpec, SorterConfig, SorterConfigSize, SorterSpec
Defined in | <seqan/pipe.h>
Signature | `template <typename TValue[, typename TSpec]> class Pool;`

## Template Parameters

`TSpec` | The specializing type. Default: PoolSpec<>, see PoolSpec.
`TValue` | The value type, that is the type of the stream elements.

## Interface Function Overview

- `void assign(target, source);`
  Assigns one object to another object.
- `bool atEnd(pool);`
  Check whether the Pool object is at end.
- `bool beginRead(pool);`
  Initiates a read process.
- `bool beginWrite(pool);`
  Initiates a write process.
- `void clear(pool);`
  Remove all elements from the pool.
- `bool endRead(pool);`
  Terminates a read process.
- `bool endWrite(pool);`
  Terminates a write process.
- `TReference front(pool);`
  Return reference to the first element.
- `TSize length(pool);`
  Length of the pool.
- `void pop(pool[, ref]);`
  Pops the first element of the remaining stream.
- `void push(pool, val);`
  Appends an item at the end of an input stream.
- `void resize(pool, len);`
  Resize a pool.

## Detailed Description

Use Value to get the output type of a given Pipe (returns `Value<TInput>::Type` by default).

Use Size to get the size type of a given Pipe (returns `Size<TInput>::Type` by default).

## Interface Functions Detail

### `void assign(target, source);`

Assigns one object to another object.

#### Parameters

`target` | Reference to assign to.
`source` | Value to assign.

Assign value of source to target.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool atEnd(pool);`

Check whether the Pool object is at end.

#### Parameters

`pool` | The Pool object to query.

#### Returns

`bool` | true in case of the pool being at the end, false otherwise.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool beginRead(pool);`

Initiates a read process.

#### Parameters

`pool` | A pool module.

#### Returns

`bool` | true on success, false on failure.

A read process must be terminated with endRead. Nested read processes are not allowed.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### See Also

- endRead

### `bool beginWrite(pool);`

Initiates a write process.

#### Parameters

`pool` | A pool module.

#### Returns

`bool` | `true` on success, false on failure.

`beginWrite` prepares a pool for succeeding writes.

A write process must be terminated with endWrite. Nested write processes are not allowed.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### See Also

- endWrite

### `void clear(pool);`

Remove all elements from the pool.

#### Parameters

`pool` | Pool to clear.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool endRead(pool);`

Terminates a read process.

#### Parameters

`pool` | A pool module.

#### Returns

`bool` | true on success, false on failure.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### See Also

- beginRead

### `bool endWrite(pool);`

Terminates a write process.

#### Parameters

`pool` | A push-passive pipeline module.

#### Returns

`bool` | true on success, false on failure.

`endWrite` closes the input stream and frees resources possibly allocated by beginWrite

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### See Also

- beginWrite

### `TReference front(pool);`

Return reference to the first element.

#### Parameters

`pool` | The pool to get the first element of.

#### Returns

`TReference` | A reference to the first element of `seq`.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TSize length(pool);`

Length of the pool.

#### Parameters

`pool` | The Pool to query for its size.

#### Returns

`TSize` | The number of elements in the pool.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void pop(pool[, ref]);`

Pops the first element of the remaining stream.

#### Parameters

`pool` | A pop-passive pipeline module.
`ref` | Reference to the result. Result type is `Value<TObject>::Type` for `object` type `TObject`. Returns the first element of the remaining input stream.

In contrast to Pool#front this function also steps one element further.

Pool#front or Pool#pop can only be called within a read process surrounded by beginRead and endRead.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void push(pool, val);`

Appends an item at the end of an input stream.

#### Parameters

`pool` | A pool module.
`val` | Item to be pushed.

The function `push` can only be called within a write process surrounded by beginWrite and endWrite.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void resize(pool, len);`

Resize a pool.

#### Parameters

`pool` | Pool to resize.
`len` | Length to resize `pool` to.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### Dox Sources

    /*!
     * @class Pool
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Pools are push- and pop-passive pipeline modules.
     *
     * @signature template <typename TValue[, typename TSpec]> class Pool;
     *
     * @tparam TSpec The specializing type. Default: PoolSpec&lt;&gt;, see PoolSpec.
     * @tparam TValue The value type, that is the type of the stream elements.
     *
     * Use Value to get the output type of a given Pipe (returns
     * <tt>Value&lt;TInput&gt;::Type</tt> by default).
     *
     * Use Size to get the size type of a given Pipe (returns
     * <tt>Size&lt;TInput&gt;::Type</tt> by default).
     *
     * @fn Pool#clear
     *
     * @brief Remove all elements from the pool.
     *
     * @signature void clear(pool);
     *
     * @param[in,out] pool Pool to clear.
     *
     * @fn Pool#length
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Length of the pool.
     *
     * @signature TSize length(pool);
     *
     * @param[in] pool The Pool to query for its size.
     *
     * @return TSize The number of elements in the pool.
     *
     * @fn Pool#resize
     *
     * @brief Resize a pool.
     *
     * @signature void resize(pool, len);
     *
     * @param[in,out] pool Pool to resize.
     * @param[in] len Length to resize <tt>pool</tt> to.
     *
     * @fn Pool#front
     *
     * @brief Return reference to the first element.
     *
     * @signature TReference front(pool);
     *
     * @param[in] pool The pool to get the first element of.
     *
     * @return TReference A reference to the first element of <tt>seq</tt>.
     *
     * @fn Pool#pop
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Pops the first element of the remaining stream.
     *
     * @signature void pop(pool[, ref]);
     *
     * @param[in,out] pool A pop-passive pipeline module.
     * @param[out] ref Reference to the result. Result type is
     *                 <tt>Value&lt;TObject&gt;::Type</tt> for <tt>object</tt> type
     *                 <tt>TObject</tt>. Returns the first element of the remaining
     *                 input stream.
     *
     * In contrast to Pool#front this function also steps one element further.
     *
     * Pool#front or Pool#pop can only be called within a read process surrounded by
     * beginRead and endRead.
     *
     * @fn Pool#push
     *
     * @brief Appends an item at the end of an input stream.
     *
     * @signature void push(pool, val);
     *
     * @param[in,out] pool A pool module.
     * @param[in] val Item to be pushed.
     *
     * The function <tt>push</tt> can only be called within a write process
     * surrounded by beginWrite and endWrite.
     *
     * @fn Pool#beginWrite
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Initiates a write process.
     *
     * @signature bool beginWrite(pool);
     *
     * @param[in,out] pool A pool module.
     *
     * @return bool <tt>true</tt> on success, false on failure.
     *
     * <tt>beginWrite</tt> prepares a pool for succeeding writes.
     *
     * A write process must be terminated with endWrite. Nested write processes are
     * not allowed.
     *
     * @see Pool#endWrite
     *
     * @fn Pool#endWrite
     *
     * @brief Terminates a write process.
     *
     * @signature bool endWrite(pool);
     *
     * @param[in,out] pool A push-passive pipeline module.
     *
     * @return bool true on success, false on failure.
     *
     * <tt>endWrite</tt> closes the input stream and frees resources possibly
     * allocated by beginWrite
     *
     * @see Pool#beginWrite
     *
     * @fn Pool#atEnd
     *
     * @brief Check whether the @link Pool @endlink object is at end.
     *
     * @signature bool atEnd(pool);
     *
     * @param[in] pool The @link Pool @endlink object to query.
     *
     * @return bool true in case of the pool being at the end, false otherwise.
     *
     * @fn Pool#beginRead
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Initiates a read process.
     *
     * @signature bool beginRead(pool);
     *
     * @param[in,out] pool A pool module.
     *
     * @return bool true on success, false on failure.
     *
     * A read process must be terminated with endRead. Nested read processes are not
     * allowed.
     *
     * @see Pool#endRead
     *
     * @fn Pool#endRead
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Terminates a read process.
     *
     * @signature bool endRead(pool);
     *
     * @param[in,out] pool A pool module.
     *
     * @return bool true on success, false on failure.
     *
     * @see Pool#beginRead
     *
     * @fn Pool#assign
     *
     * @headerfile <seqan/pipe.h>
     *
     * @brief Assigns one object to another object.
     *
     * @signature void assign(target, source);
     *
     * @param[out] target Reference to assign to.
     * @param[in] source Value to assign.
     *
     * Assign value of source to target.
     */