BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJLIB Reference

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_policypj_pool_factory_get_default_policy (void)
 
pj_pool_tpj_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

◆ pj_NO_MEMORY_EXCEPTION()

int pj_NO_MEMORY_EXCEPTION ( void  )

Get PJ_NO_MEMORY_EXCEPTION constant.

◆ pj_pool_create_int()

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
factoryPool factory.
namePool name.
initial_sizeInitial size.
increment_sizeIncrement size.
callbackCallback.
Returns
The pool object, or NULL.

◆ pj_pool_destroy_int()

void pj_pool_destroy_int ( pj_pool_t pool)

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

Parameters
poolThe memory pool.

◆ pj_pool_factory_dump()

void pj_pool_factory_dump ( pj_pool_factory pf,
pj_bool_t  detail 
)

Dump pool factory state.

Parameters
pfThe pool factory.
detailDetail state required.

References pj_pool_factory::dump_status.

◆ pj_pool_factory_get_default_policy()

const pj_pool_factory_policy* pj_pool_factory_get_default_policy ( void  )

Get the default pool factory policy.

Returns
the pool policy.

◆ pj_pool_init_int()

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
poolThe pool.
namePool name.
increment_sizeIncrement size.
callbackCallback function.

Variable Documentation

◆ PJ_NO_MEMORY_EXCEPTION

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_default_policy

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

 


PJLIB Open Source, high performance, small footprint, and very very portable framework
Copyright (C) 2006-2009 Teluu Inc.