Allocator - SeqAn API Documentation

# Class Allocator
Manager for allocated memory.

All Subcl's | MultiPoolAllocator, SimpleAllocator, SinglePoolAllocator
Defined in | <seqan/basic.h>
Signature | `template <typename TSpec> class Allocator;`

## Template Parameters

`TSpec` | The specializing type.

## Interface Function Overview

- `void allocate(allocator, data, count[, usageTag]);`
  Allocates memory from heap.
- `void clear(allocator);`
  Deallocates all memory blocks.
- `void deallocate(object, data, count[, usageTag])`
  Deallocates memory.

## Detailed Description

### Remarks

There are two reasons for using non-trivial allocators:

1. Allocators support the function clear for a fast deallocation of all allocated memory blocks.
2. Some allocators are faster in allocating an deallocating memory. Pool allocators like e.g. SinglePoolAllocator or MultiPoolAllocator speed up allocate, *, and clear for pooled memory blocks.

## Interface Functions Detail

### `void allocate(allocator, data, count[, usageTag]);`

Allocates memory from heap.

#### Parameters

`count` | Number of items that could be stored in the allocated memory. The type of the allocated items is given by the type of `data`.
`usageTag` | A tag the specifies the purpose for the allocated memory. Values: AllocatorUsageTags.
`allocator` | Allocator object. `allocator` is conceptually the "owner" of the allocated memory. Objects of all types can be used as allocators. If no special behavior is implemented, default functions allocation/deallocation are applied that uses standard `new` and `delete` operators. Types: Allocator

#### Remarks

The function allocates at least `count*sizeof(data)` bytes. The allocated memory is large enough to hold `count` objects of type `T`, where `T *` is type of `data`.

These objects are not constructed by `allocate`.

Use e.g. one of the functions valueConstruct, arrayConstruct, arrayConstructCopy or arrayFill to construct the objects. A `new` operator which is part of the C++ standard (defined in `<new>`) can also be used to construct objects at a given memory address.

#### Remarks

All allocated memory blocks should be deallocated by the corresponding function deallocate.

#### Data Races

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

### `void clear(allocator);`

Deallocates all memory blocks.

#### Parameters

`The` | allocator to clear.

#### Remarks

This function deallocates all memory block sthat were allocated using `allocate()` for `allocator`. The memory is not pooled but directly passed back to the heap manager.

#### Data Races

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

### `void deallocate(object, data, count[, usageTag])`

Deallocates memory.

#### Parameters

`object` | Allocator object.`object` is conceptually the "owner" of the allocated memory. Objects of all types can be used as allocators. If no special behavior is implemented, default functions allocation/deallocation are applied that uses standard `new` and `delete` operators. Types: Allocator
`data` | Pointer to allocated memory that was allocated by `allocate`.
`count` | Number of items that could be stored in the allocated memory.
`usageTag` | A tag the specifies the purpose for the allocated memory. Values: AllocatorUsageTags.

The values for `object`, `count` and `usageTag` should be the same that was used when `allocate` was called. The value of `data` should be the same that was returned by `allocate`.

`deallocate` does not destruct objects.

Use e.g. one of the functions valueDestruct or arrayDestruct to destruct the objects. `delete` and `delete []` operators which are part of the C++ standard (defined in `<new>`) can also be used to destruct objects at a given memory address.

#### Data Races

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

#### Dox Sources

    /*!
     * @class Allocator
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Manager for allocated memory.
     *
     * @signature template <typename TSpec> class Allocator;
     *
     * @tparam TSpec The specializing type.
     *
     * @section Remarks
     *
     * There are two reasons for using non-trivial allocators:
     *
     * <ol> <li>Allocators support the function @link Allocator#clear @endlink for a
     * fast deallocation of all allocated memory blocks.</li> <li>Some allocators
     * are faster in allocating an deallocating memory. Pool allocators like e.g.
     * @link SinglePoolAllocator @endlink or @link MultiPoolAllocator @endlink speed
     * up @link Allocator#allocate @endlink, @link Allocator#deallocate * @endlink,
     * and @link Allocator#clear @endlink for pooled memory blocks.</li> </ol>
     *
     * @fn Allocator#clear
     *
     * @brief Deallocates all memory blocks.
     *
     * @signature void clear(allocator);
     *
     * @param[in,out] The allocator to clear.
     *
     * @section Remarks
     *
     * This function deallocates all memory block sthat were allocated using
     * <tt>allocate()</tt> for <tt>allocator</tt>. The memory is not pooled but
     * directly passed back to the heap manager.
     *
     * @fn Allocator#allocate
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Allocates memory from heap.
     *
     * @signature void allocate(allocator, data, count[, usageTag]);
     *
     * @param[in] count Number of items that could be stored in the allocated
     *                  memory. The type of the allocated items is given by the type
     *                  of <tt>data</tt>.
     * @param[in] usageTag A tag the specifies the purpose for the allocated memory.
     *                     Values: @link AllocatorUsageTags @endlink.
     * @param[in,out] allocator Allocator object. <tt>allocator</tt> is conceptually
     *                          the "owner" of the allocated memory. Objects of all
     *                          types can be used as allocators. If no special
     *                          behavior is implemented, default functions
     *                          allocation/deallocation are applied that uses
     *                          standard <tt>new</tt> and <tt>delete</tt> operators.
     *                          Types: Allocator
     *
     * @section Remarks
     *
     * The function allocates at least <tt>count*sizeof(data)</tt> bytes. The
     * allocated memory is large enough to hold <tt>count</tt> objects of type
     * <tt>T</tt>, where <tt>T *</tt> is type of <tt>data</tt>.
     *
     * These objects are not constructed by <tt>allocate</tt>.
     *
     * Use e.g. one of the functions @link valueConstruct @endlink, @link
     * arrayConstruct @endlink, @link arrayConstructCopy @endlink or @link arrayFill
     * @endlink to construct the objects. A <tt>new</tt> operator which is part of
     * the C++ standard (defined in <tt>&lt;new&gt;</tt>) can also be used to
     * construct objects at a given memory address.
     *
     * @section Remarks
     *
     * All allocated memory blocks should be deallocated by the corresponding
     * function @link Allocator#deallocate @endlink.
     *
     * @fn Allocator#deallocate
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Deallocates memory.
     *
     * @signature void deallocate(object, data, count[, usageTag])
     *
     * @param[in,out] object Allocator object.<tt>object</tt> is conceptually the
     *                       "owner" of the allocated memory. Objects of all types
     *                       can be used as allocators. If no special behavior is
     *                       implemented, default functions allocation/deallocation
     *                       are applied that uses standard <tt>new</tt> and
     *                       <tt>delete</tt> operators. Types: Allocator
     * @param[out] data Pointer to allocated memory that was allocated by
     *                  <tt>allocate</tt>.
     * @param[in] count Number of items that could be stored in the allocated
     *                  memory.
     * @param[in] usageTag A tag the specifies the purpose for the allocated memory.
     *                     Values: @link AllocatorUsageTags @endlink.
     *
     * The values for <tt>object</tt>, <tt>count</tt> and <tt>usageTag</tt> should
     * be the same that was used when <tt>allocate</tt> was called. The value of
     * <tt>data</tt> should be the same that was returned by <tt>allocate</tt>.
     *
     * <tt>deallocate</tt> does not destruct objects.
     *
     * Use e.g. one of the functions @link valueDestruct @endlink or @link
     * arrayDestruct @endlink to destruct the objects. <tt>delete</tt> and
     * <tt>delete []</tt> operators which are part of the C++ standard (defined in
     * <tt>&lt;new&gt;</tt>) can also be used to destruct objects at a given memory
     * address.
     */