CrystalSpace

Public API Reference

Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

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

uint8AllocBlock () 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
FreeNodefreenode
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 154 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 311 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 323 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 386 of file blockallocator.h.

Referenced by csShaderVarBlockAlloc::Alloc(), csTree< T >::csTree(), csRedBlackTree< csRedBlackTreePayload< K, T > >::RecursiveCopy(), 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 206 of file blockallocator.h.

Referenced by csBlockAllocator< csBSPTree >::Alloc().

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 342 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 234 of file blockallocator.h.

Referenced by csBlockAllocator< csBSPTree >::DisposeAll(), and csBlockAllocator< csBSPTree >::Free().

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 272 of file blockallocator.h.

Referenced by csBlockAllocator< csBSPTree >::Empty(), and csBlockAllocator< csBSPTree >::~csBlockAllocator().

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 333 of file blockallocator.h.

Referenced by csRedBlackTree< csRedBlackTreePayload< K, T > >::DeleteAll().

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 195 of file blockallocator.h.

Referenced by csBlockAllocator< csBSPTree >::Free(), and csBlockAllocator< csBSPTree >::GetAllocationMap().

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 408 of file blockallocator.h.

Referenced by csTree< T >::Delete(), and csRedBlackTree< csRedBlackTreePayload< K, T > >::DeleteNode().

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

Dispose of a block.

Definition at line 226 of file blockallocator.h.

Referenced by csBlockAllocator< csBSPTree >::Compact(), and csBlockAllocator< csBSPTree >::DisposeAll().

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 187 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 253 of file blockallocator.h.

Referenced by csBlockAllocator< csBSPTree >::Compact(), and csBlockAllocator< csBSPTree >::DisposeAll().

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

Query number of elements per block.

Definition at line 420 of file blockallocator.h.


The documentation for this class was generated from the following file:
Generated for Crystal Space by doxygen 1.4.4