Home --> Documentations --> PJLIB Reference

Modules
Fast Memory 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. More...

Modules

 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.
 

Detailed Description

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 Memory Pool

Advantages

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:

Performance

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

Caveats

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.

Using Memory Pool

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.

Create Pool Factory

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().

Create The Pool

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.

Allocate Memory as Required

Then whenever application needs to allocate dynamic memory, it would call pj_pool_alloc(), pj_pool_calloc(), or pj_pool_zalloc() to allocate memory chunks from the pool.

Destroy the Pool

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.

Destroy the Pool Factory

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.

Example

Below is a sample complete program that utilizes PJLIB's memory pool.

#include <pjlib.h>
#define THIS_FILE "pool_sample.c"
static void my_perror(const char *title, pj_status_t status)
{
char errmsg[PJ_ERR_MSG_SIZE];
pj_strerror(status, errmsg, sizeof(errmsg));
PJ_LOG(1,(THIS_FILE, "%s: %s [status=%d]", title, errmsg, status));
}
static void pool_demo_1(pj_pool_factory *pfactory)
{
unsigned i;
pj_pool_t *pool;
// Must create pool before we can allocate anything
pool = pj_pool_create(pfactory, // the factory
"pool1", // pool's name
4000, // initial size
4000, // increment size
NULL); // use default callback.
if (pool == NULL) {
my_perror("Error creating pool", PJ_ENOMEM);
return;
}
// Demo: allocate some memory chunks
for (i=0; i<1000; ++i) {
void *p;
p = pj_pool_alloc(pool, (pj_rand()+1) % 512);
// Do something with p
...
// Look! No need to free p!!
}
// Done with silly demo, must free pool to release all memory.
}
int main()
{
pj_status_t status;
// Must init PJLIB before anything else
status = pj_init();
if (status != PJ_SUCCESS) {
my_perror("Error initializing PJLIB", status);
return 1;
}
// Create the pool factory, in this case, a caching pool,
// using default pool policy.
pj_caching_pool_init(&cp, NULL, 1024*1024 );
// Do a demo
pool_demo_1(&cp.factory);
// Done with demos, destroy caching pool before exiting app.
return 0;
}

More information about pool factory, the pool object, and caching pool can be found on the Module Links below.

 


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