Home --> Documentations --> PJLIB Reference
Memory pools allow dynamic memory allocation comparable to malloc or the new in operator C++. Those implementations are not desirable for very high performance applications or real-time systems, because of the performance bottlenecks and it suffers from fragmentation issue. More...
|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. |
|Pool Factory and Policy|
|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. |
|Caching Pool Factory|
|Caching pool is one sample implementation of pool factory where the factory can reuse memory to create a pool. Application defines what the maximum memory the factory can hold, and when a pool is released the factory decides whether to destroy the pool or to keep it for future use. If the total amount of memory in the internal cache is still within the limit, the factory will keep the pool in the internal cache, otherwise the pool will be destroyed, thus releasing the memory back to the system. |
|Stack/Buffer Based Memory Pool Allocator|
|Stack/buffer based pool. |
Memory pools allow dynamic memory allocation comparable to malloc or the new in operator C++. Those implementations are not desirable for very high performance applications or real-time systems, because of the performance bottlenecks and it suffers from fragmentation issue.
PJLIB's pool has many advantages over traditional malloc/new operator and over other memory pool implementations, because:
Even more, PJLIB's memory pool provides some additional usability and flexibility for applications:
The result of PJLIB's memory design and careful implementation is a memory allocation strategy that can speed-up the memory allocations and deallocations by up to 30 times compared to standard malloc()/free() (more than 150 million allocations per second on a P4/3.0GHz Linux machine).
(Note: your mileage may vary, of course. You can see how much PJLIB's pool improves the performance over malloc()/free() in your target system by running pjlib-test application).
There are some caveats though!
When creating pool, PJLIB requires applications to specify the initial pool size, and as soon as the pool is created, PJLIB allocates memory from the system by that size. Application designers MUST choose the initial pool size carefully, since choosing too big value will result in wasting system's memory.
But the pool can grow. Application designer can specify how the pool will grow in size, by specifying the size increment when creating the pool.
The pool, however, cannot shrink! Since there is no function to deallocate memory chunks, there is no way for the pool to release back unused memory to the system. Application designers must be aware that constant memory allocations from pool that has infinite life-time may cause the memory usage of the application to grow over time.
This section describes how to use PJLIB's memory pool framework. As we hope the readers will witness, PJLIB's memory pool API is quite straightforward.
First, application needs to initialize a pool factory (this normally only needs to be done once in one application). PJLIB provides a pool factory implementation called caching pool (see Caching Pool Factory), and it is initialized by calling pj_caching_pool_init().
Then application creates the pool object itself with pj_pool_create(), specifying among other thing the pool factory where the pool should be created from, the pool name, initial size, and increment/expansion size.
When application has finished with the pool, it should call pj_pool_release() to release the pool object back to the factory. Depending on the types of the factory, this may release the memory back to the operating system.
And finally, before application quites, it should deinitialize the pool factory, to make sure that all memory blocks allocated by the factory are released back to the operating system. After this, of course no more memory pool allocation can be requested.
Below is a sample complete program that utilizes PJLIB's memory pool.
More information about pool factory, the pool object, and caching pool can be found on the Module Links below.