Group PJ_POOL_FACTORY

group PJ_POOL_FACTORY

A pool object must be created through a factory. A factory not only provides generic interface functions to create and release pool, but also provides strategy to manage the life time of pools. One sample implementation, pj_caching_pool, can be set to keep the pools released by application for future use as long as the total memory is below the limit.

// PJ_POOL

The pool factory interface declared in PJLIB is designed to be extensible. Application can define its own strategy by creating it’s own pool factory implementation, and this strategy can be used even by existing library without recompilation.

Pool Factory Interface

The pool factory defines the following interface:

  • policy: the memory pool factory policy.

  • create_pool(): create a new memory pool.

  • release_pool(): release memory pool back to factory.

Pool Factory Policy.

A pool factory only defines functions to create and release pool and how to manage pools, but the rest of the functionalities are controlled by policy. A pool policy defines:

  • how memory block is allocated and deallocated (the default implementation allocates and deallocate memory by calling malloc() and free()).

  • callback to be called when memory allocation inside a pool fails (the default implementation will throw PJ_NO_MEMORY_EXCEPTION exception).

  • concurrency when creating and releasing pool from/to the factory.

A pool factory can be given different policy during creation to make it behave differently. For example, caching pool factory can be configured to allocate and deallocate from a static/contiguous/preallocated memory instead of using malloc()/free().

What strategy/factory and what policy to use is not defined by PJLIB, but instead is left to application to make use whichever is most efficient for itself.

The pool factory policy controls the behaviour of memory factories, and defines the following interface:

  • block_alloc(): allocate memory block from backend memory mgmt/system.

  • block_free(): free memory block back to backend memory mgmt/system.

Functions

int pj_NO_MEMORY_EXCEPTION(void)

Get PJ_NO_MEMORY_EXCEPTION constant.

const pj_pool_factory_policy *pj_pool_factory_get_default_policy(void)

Get the default pool factory policy.

Returns:

the pool policy.

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

This function is intended to be used by pool factory implementors.

Parameters:

  • factory – Pool factory.

  • name – Pool name.

  • initial_size – Initial size.

  • increment_size – Increment size.

  • callback – Callback.

Returns:

The pool object, or NULL.

void pj_pool_init_int(pj_pool_t *pool, const char *name, pj_size_t increment_size, pj_pool_callback *callback)

This function is intended to be used by pool factory implementors.

Parameters:

  • pool – The pool.

  • name – Pool name.

  • increment_size – Increment size.

  • callback – Callback function.

void pj_pool_destroy_int(pj_pool_t *pool)

This function is intended to be used by pool factory implementors.

Parameters:

pool – The memory pool.

void pj_pool_factory_dump(pj_pool_factory *pf, pj_bool_t detail)

Dump pool factory state.

Parameters:

  • pf – The pool factory.

  • detail – Detail state required.

Variables

int PJ_NO_MEMORY_EXCEPTION

This constant denotes the exception number that will be thrown by default memory factory policy when memory allocation fails.

See also

pj_NO_MEMORY_EXCEPTION()

pj_pool_factory_policy pj_pool_factory_default_policy

This global variable points to default memory pool factory policy. The behaviour of the default policy is:

  • block allocation and deallocation use malloc() and free().

  • callback will raise PJ_NO_MEMORY_EXCEPTION exception.

  • access to pool factory is not serialized (i.e. not thread safe).

See also

pj_pool_factory_get_default_policy

struct pj_pool_factory_policy
#include <pool.h>

This structure declares pool factory interface.

Public Members

void *(*block_alloc)(pj_pool_factory *factory, pj_size_t size)

Allocate memory block (for use by pool). This function is called by memory pool to allocate memory block.

Param factory:

Pool factory.

Param size:

The size of memory block to allocate.

Return:

Memory block.

void (*block_free)(pj_pool_factory *factory, void *mem, pj_size_t size)

Free memory block.

Param factory:

Pool factory.

Param mem:

Memory block previously allocated by block_alloc().

Param size:

The size of memory block.

pj_pool_callback *callback

Default callback to be called when memory allocation fails.

unsigned flags

Option flags.

struct pj_pool_factory
#include <pool.h>

This structure contains the declaration for pool factory interface.

Forward declaration for memory pool factory.

Public Members

pj_pool_factory_policy policy

Memory pool policy.

pj_pool_t *(*create_pool)(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.

Param factory:

The pool factory.

Param 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.

Param 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.

Param 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 20 bytes (equal to sizeof(pj_pool_block)) to store some administrative info.

Param callback:

Cllback to be called when error occurs in the pool. Note that when an error occurs during pool creation, the callback itself is not called. Instead, NULL will be returned.

Return:

the memory pool, or NULL.

void (*release_pool)(pj_pool_factory *factory, pj_pool_t *pool)

Release the pool to the pool factory.

Param factory:

The pool factory.

Param pool:

The pool to be released.

void (*dump_status)(pj_pool_factory *factory, pj_bool_t detail)

Dump pool status to log.

Param factory:

The pool factory.

pj_bool_t (*on_block_alloc)(pj_pool_factory *factory, pj_size_t size)

This is optional callback to be called by allocation policy when it allocates a new memory block. The factory may use this callback for example to keep track of the total number of memory blocks currently allocated by applications.

Param factory:

The pool factory.

Param size:

Size requested by application.

Return:

MUST return PJ_TRUE, otherwise the block allocation is cancelled.

void (*on_block_free)(pj_pool_factory *factory, pj_size_t size)

This is optional callback to be called by allocation policy when it frees memory block. The factory may use this callback for example to keep track of the total number of memory blocks currently allocated by applications.

Param factory:

The pool factory.

Param size:

Size freed.