#include "libut/ut.h"
void UT_mem_pool_create(char *name, int buf_size, int exhaust_incr);
This function is used to define a memory pool. Usually, memory pools are defined
at program initialization after calling UT_init(3). The new pool is identified
by the given name; this string will be copied and silently truncated if too
long. The pool will contain buffers (units of allocation) each of size
buf_size bytes. The exhaust_incr parameter specifies the minimum number of
buffers that are allocated whenever the pool requires more memory. (I.e., a
UT_buf_alloc(3) request for fewer than exhaust_incr buffers will cause
exhaust_incr buffers to be allocated if the pool's existing buffers cannot
satisfy the request). The excess buffers are kept to satisfy future requests.
When the pool is defined, a pre-allocation of exhaust_incr buffers is made.
UT_buf_alloc(3) and UT_buf_free(3) are used to allocate and
free buffers from the pool. The advantage of using these functions over
malloc(3) and free(3) is the visibility into memory usage provided by the mem
control port command.
The typical usage of this function is to define a pool for each type of structure that the program relies on.
UT_mem_pool_create( "xyz", sizeof(struct xyz), 10 );
The mem control port command reports memory usage statistics for each pool. This command displays memory usage both in terms of buffers and kilobytes for each pool. It can also report on number of buffers allocated and freed since the pool was defined. The latter usage helps to expose memory leaks.
Do not be concerned about choosing an optimal exhaust_incr value. Its purpose is mainly to reduce calls internal calls to malloc(3). A good rule of thumb is to choose a power of ten: 1, 10, 100, 1000, etc, that most closely resembles the number of buffers you typically plan to request at once, or that most closely resembles a multiple of the total number of buffers you need in the program.
UT_buf_alloc(3), UT_buf_free(3)
Troy D. Hanson <thanson@users.sourceforge.net>