/*!
* @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<>, 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<TInput>::Type</tt> by default).
*
* Use Size to get the size type of a given Pipe (returns
* <tt>Size<TInput>::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<TObject>::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.
*/