10. Pool

The pool(3m) module provides a container that will manage a reuseable pool of data objects. If the data objects are costly to create (e.g. a database connection) and can be reused in a different context the object can be released back to the pool for retrival at a later point without creating and destroying objects frequently. The number of data objects in a pool is limited to POOL_SIZE_MAX defined in the pool(3m) header file. This limit is 2040 by default which will create a bitmap of 256 bytes. Memory to store data pointers will increase dynamically as more space is required.

10.1. Memory management functions

These functions should be used to create and destroy pool objects.

The pool_new function
Synopsis

#include <mba/pool.h> struct pool *pool_new(unsigned int max_size, void *(*new_data_fn)(void *), void *arg, void (*free_data_fn)(void *));
Description
The pool_new function creates a new empty pool object that will accept no more than max_size elements. The max_size parameter is limited to POOL_SIZE_MAX. If max_size is 0 or greater than POOL_SIZE_MAX the pool will accept no more than POOL_SIZE_MAX elements. The new_data_fn function will be called with arg as a parameter to create a new data objects when necessary. The free_data_fn function is called for each member in the pool when the pool is deleted. It may also be called if the pool was successfull in creating a data object but failed to store it due to a memory allocation failure.
Returns
The pool_new function returns a new pool object that initially contains no memebers.

The pool_del function
Synopsis

#include <mba/pool.h> void pool_del(void *p);
Description
The pool_del function calls the free_data_fn function on each element in the pool and frees any resources allocated with pool_new.

10.2. Pool management functions

The pool_get function
Synopsis

#include <mba/pool.h> void *pool_get(struct pool *p);
Description
The pool_get function searches the pool p for an unused data object or creates a new data object if necessary. In either case, the data object is returned. More specifically, if there are no data objects in the pool or if all data objects in the pool are currently being used the new_data_fn function is called to create a new data object which is then added to the pool.
Returns
The pool_get function returns a data object from the pool. If the max_size limit is reached, errno is set to ERANGE and NULL is returned. If the new_data_fn returns NULL or if an error occurs errno will be set to an approriate value and NULL will be returned.

The pool_release function
Synopsis

#include <mba/pool.h> int pool_release(struct pool *p, void *data);
Description
The pool_release function releases the data pointer data back into the pool p.
Returns
The pool_release function returns -1 and sets errno to an approriate value if the operation failed or 0 if the data object was successfully released back into the pool.

The pool_size function
Synopsis

#include <mba/pool.h> unsigned int pool_size(struct pool *p);
Description
The pool_size function returns the total number of data objects that consititute the pool regardless of how many object are being used or not being unused. This number is equal to the number of times new_data_fn has been called (barring memory allocation failures).

The pool_unused function
Synopsis

#include <mba/pool.h> unsigned int pool_unused(struct pool *p);
Description
The pool_unused function returns the number of data objects that are currently not being used. The number of objects currently in use is pool_size minus pool_unused.

The pool_iterate function
Synopsis

#include <mba/pool.h> void pool_iterate(void *p, iter_t *iter);
Description
Enumerate each data object in the pool. The pool_iterate function initializes the iter object to the beginning of the pool. With each subsequent call to pool_next a pointer to each element is returned or NULL is returned to indicate all elements have been enumerated. All elements are enumerated regardless of wheather or not they are currently attributed as being used or unused. If data objects are added to the pool during one enumeration cycle they may or may not be included in the current set. Elements are not returned in any particular order.

The pool_next function
Synopsis

#include <mba/pool.h> void *pool_next(void *p, iter_t *iter);
Returns
The pool_next function returns the next member in the pool or NULL if all members have been enumerated.


Copyright 2002 Michael B. Allen <mballen@erols.com>