Pool Factory and Policy [Fast Memory Pool]

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

Data Structures
struct	pj_pool_factory_policy
struct	pj_pool_factory
Functions
int	pj_NO_MEMORY_EXCEPTION (void)
const pj_pool_factory_policy *	pj_pool_factory_get_default_policy (void)
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)
void	pj_pool_init_int (pj_pool_t *pool, const char *name, pj_size_t increment_size, pj_pool_callback *callback)
void	pj_pool_destroy_int (pj_pool_t *pool)
void	pj_pool_factory_dump (pj_pool_factory *pf, pj_bool_t detail)
Variables
int	PJ_NO_MEMORY_EXCEPTION
pj_pool_factory_policy	pj_pool_factory_default_policy

---

Detailed Description

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.

---

Function Documentation

int pj_NO_MEMORY_EXCEPTION

(

void

)

Get PJ_NO_MEMORY_EXCEPTION constant.

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

const pj_pool_factory_policy* pj_pool_factory_get_default_policy

(

void

)

Get the default pool factory policy.

Returns:

the pool policy.

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.

---

Variable Documentation

int PJ_NO_MEMORY_EXCEPTION

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

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