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.
-
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).
-
struct
pj_pool_factory_policy¶ - #include <pool.h>
This structure declares pool factory interface.
-
struct
pj_pool_factory¶ - #include <pool.h>
This structure contains the declaration for pool factory interface.
Forward declaration for memory pool factory.