Memory Pool Object

The memory pool is an opaque object created by pool factory. Application uses this object to request a memory chunk, by calling pj_pool_alloc(), pj_pool_calloc(), or pj_pool_zalloc(). When the application has finished using the pool, it must call pj_pool_release() to free all the chunks previously allocated and release the pool back to the factory. More...

Data Structures
struct	pj_pool_block
struct	pj_pool_t

Macros
#define	PJ_POOL_SIZE   (sizeof(struct pj_pool_t))
#define	PJ_POOL_ALIGNMENT   4
#define	PJ_POOL_ALLOC_T(pool, type)    ((type*)pj_pool_alloc(pool, sizeof(type)))
#define	PJ_POOL_ZALLOC_T(pool, type)    ((type*)pj_pool_zalloc(pool, sizeof(type)))

Typedefs
typedef void	pj_pool_callback(pj_pool_t *pool, pj_size_t size)

Functions
pj_pool_t *	pj_pool_create (pj_pool_factory *factory, const char *name, pj_size_t initial_size, pj_size_t increment_size, pj_pool_callback *callback)
void	pj_pool_release (pj_pool_t *pool)
void	pj_pool_safe_release (pj_pool_t **ppool)
void	pj_pool_secure_release (pj_pool_t **ppool)
const char *	pj_pool_getobjname (const pj_pool_t *pool)
void	pj_pool_reset (pj_pool_t *pool)
pj_size_t	pj_pool_get_capacity (pj_pool_t *pool)
pj_size_t	pj_pool_get_used_size (pj_pool_t *pool)
void *	pj_pool_alloc (pj_pool_t *pool, pj_size_t size)
void *	pj_pool_calloc (pj_pool_t *pool, pj_size_t count, pj_size_t elem)
void *	pj_pool_zalloc (pj_pool_t *pool, pj_size_t size)
void *	pj_pool_alloc_from_block (pj_pool_block *block, pj_size_t size)
void *	pj_pool_allocate_find (pj_pool_t *pool, pj_size_t size)

Detailed Description

The memory pool is an opaque object created by pool factory. Application uses this object to request a memory chunk, by calling pj_pool_alloc(), pj_pool_calloc(), or pj_pool_zalloc(). When the application has finished using the pool, it must call pj_pool_release() to free all the chunks previously allocated and release the pool back to the factory.

A memory pool is initialized with an initial amount of memory, which is called a block. Pool can be configured to dynamically allocate more memory blocks when it runs out of memory.

The pool doesn't keep track of individual memory allocations by user, and the user doesn't have to free these indidual allocations. This makes memory allocation simple and very fast. All the memory allocated from the pool will be destroyed when the pool itself is destroyed.

More on Threading Policies

• By design, memory allocation from a pool is not thread safe. We assumed that a pool will be owned by an object, and thread safety should be handled by that object. Thus these functions are not thread safe:
  • pj_pool_alloc,
  • pj_pool_calloc,
  • and other pool statistic functions.
• Threading in the pool factory is decided by the policy set for the factory when it was created.

Examples

For some sample codes on how to use the pool, please see:

• Test: Pool

Macro Definition Documentation

PJ_POOL_ALIGNMENT

#define PJ_POOL_ALIGNMENT   4

Pool memory alignment (must be power of 2).

PJ_POOL_ALLOC_T

#define PJ_POOL_ALLOC_T	(		pool,
			type
	)		((type*)pj_pool_alloc(pool, sizeof(type)))

This macro allocates memory from the pool and returns the instance of the specified type. It provides a stricker type safety than pj_pool_alloc() since the return value of this macro will be type-casted to the specified type.

Parameters

pool	The pool
type	The type of object to be allocated

Returns

Memory buffer of the specified type.

PJ_POOL_SIZE

#define PJ_POOL_SIZE   (sizeof(struct pj_pool_t))

Guidance on how much memory required for initial pool administrative data.

PJ_POOL_ZALLOC_T

#define PJ_POOL_ZALLOC_T	(		pool,
			type
	)		((type*)pj_pool_zalloc(pool, sizeof(type)))

This macro allocates memory from the pool, zeroes the buffer, and returns the instance of the specified type. It provides a stricker type safety than pj_pool_zalloc() since the return value of this macro will be type-casted to the specified type.

Parameters

pool	The pool
type	The type of object to be allocated

Returns

Memory buffer of the specified type.

Typedef Documentation

pj_pool_callback

typedef void pj_pool_callback(pj_pool_t *pool, pj_size_t size)

The type for function to receive callback from the pool when it is unable to allocate memory. The elegant way to handle this condition is to throw exception, and this is what is expected by most of this library components.

Function Documentation

pj_pool_alloc()

void * pj_pool_alloc	(	pj_pool_t *	pool,
		pj_size_t	size
	)

Allocate storage with the specified size from the pool. If there's no storage available in the pool, then the pool can allocate more blocks if the increment size is larger than the requested size.

Parameters

pool	the pool.
size	the requested size.

Returns

pointer to the allocated memory.

See also

PJ_POOL_ALLOC_T

pj_pool_alloc_from_block()

void * pj_pool_alloc_from_block	(	pj_pool_block *	block,
		pj_size_t	size
	)

Internal function

pj_pool_allocate_find()

void * pj_pool_allocate_find	(	pj_pool_t *	pool,
		pj_size_t	size
	)

Internal function

pj_pool_calloc()

void * pj_pool_calloc	(	pj_pool_t *	pool,
		pj_size_t	count,
		pj_size_t	elem
	)

Allocate storage from the pool, and initialize it to zero. This function behaves like pj_pool_alloc(), except that the storage will be initialized to zero.

Parameters

pool	the pool.
count	the number of elements in the array.
elem	the size of individual element.

Returns

pointer to the allocated memory.

Referenced by pj_pool_zalloc().

pj_pool_create()

pj_pool_t * pj_pool_create	(	pj_pool_factory *	factory,
		const char *	name,
		pj_size_t	initial_size,
		pj_size_t	increment_size,
		pj_pool_callback *	callback
	)

Create a new pool from the pool factory. This wrapper will call create_pool member of the pool factory.

Parameters

factory	The pool factory.
name	The name to be assigned to the pool. The name should not be longer than PJ_MAX_OBJ_NAME (32 chars), or otherwise it will be truncated.
initial_size	The size of initial memory blocks taken by the pool. Note that the pool will take 68+20 bytes for administrative area from this block.
increment_size	the size of each additional blocks to be allocated when the pool is running out of memory. If user requests memory which is larger than this size, then an error occurs. Note that each time a pool allocates additional block, it needs PJ_POOL_SIZE more to store some administrative info.
callback	Callback to be called when error occurs in the pool. If this value is NULL, then the callback from pool factory policy will be used. Note that when an error occurs during pool creation, the callback itself is not called. Instead, NULL will be returned.

Returns

The memory pool, or NULL.

pj_pool_get_capacity()

pj_size_t pj_pool_get_capacity

(

pj_pool_t *

pool

)

Get the pool capacity, that is, the system storage that have been allocated by the pool, and have been used/will be used to allocate user requests. There's no guarantee that the returned value represent a single contiguous block, because the capacity may be spread in several blocks.

Parameters

pool

the pool.

Returns

the capacity.

pj_pool_get_used_size()

pj_size_t pj_pool_get_used_size

(

pj_pool_t *

pool

)

Get the total size of user allocation request.

Parameters

pool

the pool.

Returns

the total size.

pj_pool_getobjname()

const char * pj_pool_getobjname

(

const pj_pool_t *

pool

)

Get pool object name.

Parameters

pool

the pool.

Returns

pool name as NULL terminated string.

pj_pool_release()

void pj_pool_release

(

pj_pool_t *

pool

)

Release the pool back to pool factory.

Parameters

pool	Memory pool.

pj_pool_reset()

void pj_pool_reset

(

pj_pool_t *

pool

)

Reset the pool to its state when it was initialized. This means that if additional blocks have been allocated during runtime, then they will be freed. Only the original block allocated during initialization is retained. This function will also reset the internal counters, such as pool capacity and used size.

Parameters

pool

the pool.

pj_pool_safe_release()

void pj_pool_safe_release

(

pj_pool_t **

ppool

)

Release the pool back to pool factory and set the pool pointer to zero.

Parameters

ppool

Pointer to memory pool.

pj_pool_secure_release()

void pj_pool_secure_release

(

pj_pool_t **

ppool

)

Release the pool back to pool factory and set the pool pointer to zero. The memory pool content will be wiped out first before released.

Parameters

ppool

Pointer to memory pool.

pj_pool_zalloc()

void * pj_pool_zalloc	(	pj_pool_t *	pool,
		pj_size_t	size
	)

Allocate storage from the pool and initialize it to zero.

Parameters

pool	The pool.
size	The size to be allocated.

Returns

Pointer to the allocated memory.

See also

PJ_POOL_ZALLOC_T

References pj_pool_calloc().