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

Example 5. A Pool of Buffers
The following example illustrates how to use pool(3m) and allocator(3m) to create a pool of reusable buffers.


  struct pool bufferpool;
  
  if (pool_create(&bufferpool, 100,
  		(new_fn)allocator_new, (del_fn)allocator_free, NULL,
  		al, 4096, 0, NULL) == -1) {
  	perror("failed to create buffer pool");
  	return -1;
  }

The pool will create at most 100 buffers of 4096 bytes each allocated from the allocator identified by the al parameter.

12.1. Memory management functions

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

The pool_create function
Synopsis


  #include <mba/pool.h>
  int pool_create(struct pool *p,
           unsigned int max_size,
           new_fn object_new,
           del_fn object_del,
           rst_fn object_rst,
           void *context,
           size_t size,
           int flags,
           struct allocator *al);

Description
The pool_create function initializes the pool object p. The pool will limit the number of objects created through the pool to max_size. If max_size is 0 or greater than POOL_SIZE_MAX the pool will accept no more than POOL_SIZE_MAX elements. The allocator al will be used to allocate all memory for the pool itself (but not objects created by the pool).

The remaining parameters are used to create and destroy objects managed by the pool. The object_new function will be called with the context, size, and flags parameters to create new objects for the pool. The object_del function will called with the context parameter to delete objects when the pool is destroyed, cleaned, and possibly if an error occurs attempting to allocate storage for an object. The object_rst function will be called with the context parameter and a target object to reset it before being returned from the pool_get function but only if it was previously retrieved and released. Unlike the object_new and object_del parameters, object_rst may be NULL to indicate that it is not necessary to reset objects.
Returns
The pool_create function returns -1 and sets errno to an approriate value if the operation failed or 0 if the pool was successfully initialized.

The pool_destroy function
Synopsis


  #include <mba/pool.h>
  int pool_destroy(struct pool *p);

Description
The pool_destroy function deletes all unused objects in the pool and frees the bitmap backing the pool.
Returns
The pool_destroy function returns -1 and sets errno to an approriate value if the operation failed or 0 if the pool was successfully destroyed.

The pool_new function
Synopsis


  #include <mba/pool.h>
  struct pool *pool_new(unsigned int max_size,
           new_fn object_new,
           del_fn object_del,
           rst_fn object_rst,
           void *context,
           size_t size,
           int flags,
           struct allocator *al);

Description
The pool_new function allocates memory and initializes it with the pool_create function.
Returns
The pool_new function returns a new pool object with no objects.

The pool_del function
Synopsis


  #include <mba/pool.h>
  int pool_del(struct pool *p);

Description
The pool_del function destroys the pool p with the pool_destroy function and frees p itself.

The pool_clean function
Synopsis


  #include <mba/pool.h>
  int pool_clean(struct pool *p);

Description
The pool_clean function destroys all unused data items in the pool with the data_del function specified with pool_create.
Returns
The pool_clean function returns -1 and sets errno to an approriate value if the operation failed or 0 if all unused data objects were successfully destroyed.

12.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. If an existing element in the pool is being reused and the rst_fn was provided when the pool was constructed the object will first be reset with this function.
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. If the data pointer is NULL or was not derived from p the pool is not modified.
Returns
The pool_release function returns -1 and sets errno to an approriate value if the p parameter is NULL or if the data pointer was not derived from this pool. If the data object was successfully released back into the pool or if it is NULL, 0 is returned to indicate success.

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.