## Public API Reference

- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# csBlockAllocator< T, BlockPolicy > Class Template Reference

This class implements a memory allocator which can efficiently allocate objects that all have the same size. More...

`#include <csutil/blockallocator.h>`

List of all members.

## Public Member Functions

T * | Alloc ()
| Allocate a new object.
void | Compact ()
| Compact the block allocator so that all blocks that are completely unused are removed.
| csBlockAllocator (size_t nelem=32, bool warn_unfreed=false)
| Construct a new block allocator.
void | Empty ()
| Destroy all objects allocated by the pool.
void | Free (T *p)
| Deallocate an object.
size_t | GetBlockElements () const
| Query number of elements per block.
| ~csBlockAllocator ()
| Destroy all allocated objects and release memory.

## Protected Member Functions

uint8 * | AllocBlock () const
| Allocate a block and initialize its free-node chain.
void | DestroyObject (T *p, bool warn=false) const
| Destroy an object, optionally warning if pedanticism is desired.
void | DisposeAll (bool warn_unfreed)
| Destroys all living objects and releases all memory allocated by the pool.
size_t | FindBlock (void const *m) const
| Find the memory block which contains the given memory.
void | FreeBlock (uint8 *p) const
| Dispose of a block.
csBitArray | GetAllocationMap () const
| Get a usage mask showing all used (1's) and free (0's) nodes in the entire allocator.

## Static Protected Member Functions

static int | FuzzyCmp (uint8 *const &block, BlockKey const &k)
| Comparison function for FindBlock() which does a "fuzzy" search given an arbitrary address.

## Protected Attributes

csArray< uint8 * > | blocks
size_t | blocksize
size_t | elsize
FreeNode * | freenode
bool | insideDisposeAll
bool | pedantic
size_t | size

## Classes

struct | BlockKey
struct | FreeNode

## Detailed Description

### template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
class csBlockAllocator< T, BlockPolicy >

This class implements a memory allocator which can efficiently allocate objects that all have the same size.

It has no memory overhead per allocation (unless the objects are smaller than sizeof(void*) bytes) and is extremely fast, both for Alloc() and Free(). The only restriction is that any specific allocator can be used for just one type of object (the type for which the template is instantiated).

Remarks:
  The objects are properly constructed and destructed.

  Assumes that the class `T` with which the template is instantiated has a default (zero-argument) constructor. Alloc() uses this constructor to initialize each vended object.

  Defining the macro CS_BLOCKALLOC_DEBUG will cause freed objects to be overwritten with '0xfb' bytes. This can be useful to track use of already freed objects, as they can be more easily recognized (as some members will be likely bogus.)

See also:
  csArray

  csMemoryPool

Definition at line 155 of file blockallocator.h.

## Constructor & Destructor Documentation

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
csBlockAllocator< T, BlockPolicy >::csBlockAllocator | ( | size_t | nelem = `32`,
|  | bool | warn_unfreed = `false`
| ) | `[inline]`

Construct a new block allocator.

Parameters:

  | nelem | Number of elements to store in each allocation unit.
  | warn_unfreed | If true, in debug mode warn about objects not explicitly released via Free().

Remarks:
  Bigger values for `nelem` will improve allocation performance, but at the cost of having some potential waste if you do not add `nelem` elements to each pool. For instance, if `nelem` is 50 but you only add 3 elements to the pool, then the space for the remaining 47 elements, though allocated, will remain unused (until you add more elements).

  If use use csBlockAllocator as a convenient and lightweight garbage collection facility (for which it is well-suited), and expect it to dispose of allocated objects when the pool itself is destroyed, then set `warn_unfreed` to false. On the other hand, if you use csBlockAllocator only as a fast allocator but intend to manage each object's life time manually, then you may want to set `warn_unfreed` to true in order to receive diagnostics about objects which you have forgotten to release explicitly via manual invocation of Free().

Definition at line 312 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
csBlockAllocator< T, BlockPolicy >::~csBlockAllocator | ( |  | ) | `[inline]`

| Destroy all allocated objects and release memory. Definition at line 324 of file blockallocator.h.

## Member Function Documentation

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
T* csBlockAllocator< T, BlockPolicy >::Alloc | ( |  | ) | `[inline]`

| Allocate a new object. Its default (no-argument) constructor is invoked. Definition at line 387 of file blockallocator.h. Referenced by csShaderVarBlockAlloc::Alloc(), and csRedBlackTree< csRedBlackTreePayload< K, T > >::RecursiveInsert().

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
uint8* csBlockAllocator< T, BlockPolicy >::AllocBlock | ( |  | ) | const`[inline, protected]`

Allocate a block and initialize its free-node chain.

Returns:
  The returned address is both the reference to the overall block, and the address of the first free node in the chain.

Definition at line 207 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
void csBlockAllocator< T, BlockPolicy >::Compact | ( |  | ) | `[inline]`

| Compact the block allocator so that all blocks that are completely unused are removed. The blocks that still contain elements are not touched. Definition at line 343 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
void csBlockAllocator< T, BlockPolicy >::DestroyObject | ( | T * | p,
|  | bool | warn = `false`
| ) | const`[inline, protected]`

| Destroy an object, optionally warning if pedanticism is desired. Definition at line 235 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
void csBlockAllocator< T, BlockPolicy >::DisposeAll | ( | bool | warn_unfreed | ) | `[inline, protected]`

Destroys all living objects and releases all memory allocated by the pool.

Parameters:

  | warn_unfreed | If true, in debug mode warn about objects not explicitly released via Free().

Definition at line 273 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
void csBlockAllocator< T, BlockPolicy >::Empty | ( |  | ) | `[inline]`

Destroy all objects allocated by the pool.

Remarks:
  All pointers returned by Alloc() are invalidated. It is safe to perform new allocations from the pool after invoking Empty().

Definition at line 334 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
size_t csBlockAllocator< T, BlockPolicy >::FindBlock | ( | void const * | m | ) | const`[inline, protected]`

| Find the memory block which contains the given memory. Definition at line 196 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
void csBlockAllocator< T, BlockPolicy >::Free | ( | T * | p | ) | `[inline]`

| Deallocate an object. It is safe to provide a null pointer. Definition at line 409 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
void csBlockAllocator< T, BlockPolicy >::FreeBlock | ( | uint8 * | p | ) | const`[inline, protected]`

| Dispose of a block. Definition at line 227 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
static int csBlockAllocator< T, BlockPolicy >::FuzzyCmp | ( | uint8 *const & | block,
|  | BlockKey const & | k
| ) | `[inline, static, protected]`

| Comparison function for FindBlock() which does a "fuzzy" search given an arbitrary address. It checks if the address falls somewhere within a block rather than checking if the address exactly matches the start of the block (which is the only information recorded in blocks[] array). Definition at line 188 of file blockallocator.h. Referenced by csBlockAllocator< csBSPTree >::FindBlock().

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
csBitArray csBlockAllocator< T, BlockPolicy >::GetAllocationMap | ( |  | ) | const`[inline, protected]`

| Get a usage mask showing all used (1's) and free (0's) nodes in the entire allocator. Definition at line 254 of file blockallocator.h.

template<class T, class BlockPolicy = csBlockAllocatorNormalBlockPolicy>
size_t csBlockAllocator< T, BlockPolicy >::GetBlockElements | ( |  | ) | const`[inline]`

| Query number of elements per block. Definition at line 421 of file blockallocator.h.

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

- csutil/blockallocator.h