CrystalSpace

Public API Reference

csMemoryPool Class Reference
[Containers]

A quick-allocation pool for storage of arbitrary data. More...

#include <csutil/mempool.h>

Inherited by TEventMemPool.

List of all members.

Public Member Functions

void * Alloc (size_t)
 Allocate the specified number of bytes.
 csMemoryPool (size_t gran=4096)
 Construct a new memory pool.
void Empty ()
 Release all memory allocated by the pool.
char const * Store (char const *)
 Store a null-terminated C-string.
void const * Store (void const *, size_t)
 Store a copy of a block of memory of the indicated size.
 ~csMemoryPool ()
 Destroy the memory pool, freeing all allocated storage.

Detailed Description

A quick-allocation pool for storage of arbitrary data.

Pointers to allocations made from the pool are guaranteed to remain valid as long as the pool is alive; the pool contents are never relocated. All individually allocated memory chunks are freed when the pool itself is destroyed. This memory management scheme is suitable for algorithms which need to allocate and manipulate many chunks of memory in a non-linear fashion where the life-time of each memory chunk is not predictable. Rather than complicating the algorithm by having it carefully track each memory chunk to determine when it would be safe to dispose of the memory, it can instead create a csMemoryPool at the start, and destroy the pool at the end. During processing, it can allocate memory chunks from the pool as needed, and simply forget about them when no longer needed, knowing that they will be freed en-masse when the pool itself is disposed. This is often a cheaper, simpler, and faster alternative to reference-counting or automatic garbage collection.

See also:
csBlockAllocator
csArray

Definition at line 54 of file mempool.h.


Constructor & Destructor Documentation

csMemoryPool::csMemoryPool ( size_t  gran = 4096  )  [inline]

Construct a new memory pool.

If a size is provided, it is taken as a recommendation in bytes of the granularity of the internal allocations made by the pool, but is not a hard limit. Client allocations from the pool can be both smaller and larger than this number. A larger number will result in fewer interactions with the system heap (which translates to better performance), but at the cost of potential unused but allocated space. A smaller number translates to a greater number of interactions with the system heap (which is slow), but means less potential wasted memory.

Definition at line 79 of file mempool.h.

csMemoryPool::~csMemoryPool (  )  [inline]

Destroy the memory pool, freeing all allocated storage.

Definition at line 81 of file mempool.h.


Member Function Documentation

void* csMemoryPool::Alloc ( size_t   ) 

Allocate the specified number of bytes.

Returns:
A pointer to the allocated memory.
Remarks:
The allocated space is not initialized in any way (it is not even zeroed); the caller is responsible for populating the allocated space.
The specified size must be greater than zero.
void csMemoryPool::Empty (  ) 

Release all memory allocated by the pool.

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

Store a null-terminated C-string.

Returns:
A pointer to the stored copy.
Remarks:
It is safe to store a zero-length string. A null pointer is treated like a zero-length string.
void const* csMemoryPool::Store ( void const *  ,
size_t   
)

Store a copy of a block of memory of the indicated size.

Returns:
A pointer to the stored copy.
Remarks:
The specified size must be greater than zero.

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

Generated for Crystal Space 2.1 by doxygen 1.6.1