.\" .\" Copyright 2002 Michael B. Allen .\" .TH pool 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions" .SH NAME pool \- A container for recycleable objects. .SH SYNOPSIS .nf .B #include .sp .BI "int pool_create(struct pool *" p ", .BI " unsigned int " max_size ", .BI " new_fn " object_new ", .BI " del_fn " object_del ", .BI " rst_fn " object_rst ", .BI " void *" context ", .BI " size_t " size ", .BI " int " flags ", .BI " struct allocator *" al "); .br .BI "int pool_destroy(struct pool *" p "); .br .BI "struct pool *pool_new(unsigned int " max_size ", .BI " new_fn " object_new ", .BI " del_fn " object_del ", .BI " rst_fn " object_rst ", .BI " void *" context ", .BI " size_t " size ", .BI " int " flags ", .BI " struct allocator *" al "); .br .BI "int pool_del(struct pool *" p "); .br .BI "int pool_clean(struct pool *" p "); .br .sp .BI "void *pool_get(struct pool *" p "); .br .BI "int pool_release(struct pool *" p ", void *" data "); .br .BI "unsigned int pool_size(struct pool *" p "); .br .BI "unsigned int pool_unused(struct pool *" p "); .br .BI "void pool_iterate(void *" p ", iter_t *" iter "); .br .BI "void *pool_next(void *" p ", iter_t *" iter "); .br .fi .SH DESCRIPTION The .BR "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 .I POOL_SIZE_MAX defined in the .BR "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. .PP .TP .B create The .B pool_create function initializes the pool object .IR "p" . The pool will limit the number of objects created through the pool to .IR "max_size" . If .I max_size is 0 or greater than .I POOL_SIZE_MAX the pool will accept no more than .I POOL_SIZE_MAX elements. The allocator .I al will be used to allocate all memory for the pool itself (but not objects created by the pool). .sp The remaining parameters are used to create and destroy objects managed by the pool. The .I object_new function will be called with the .IR "context" , .IR "size" , and .I flags parameters to create new objects for the pool. The .I object_del function will called with the .I 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 .I object_rst function will be called with the .I context parameter and a target object to reset it before being returned from the .B pool_get functionbut only if it was previously retrieved and released. Unlike the .I object_new and .I object_del parameters, .I object_rst may be .B NULL to indicate that it is not necessary to reset objects. .TP .B destroy The .B pool_destroy function deletes all unused objects in the pool and frees the bitmap backing the pool. .TP .B new The .B pool_new function allocates memory and initializes it with the .B pool_create function. .TP .B del The .B pool_del function destroys the .B pool .I p with the .B pool_destroy function and frees .I p itself. .TP .B clean The .B pool_clean function destroys all unused data items in the pool with the .I data_del function specified with .BR "pool_create" . .TP .B get The .B pool_get function searches the pool .I 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 .I 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 .B rst_fn was provided when the pool was constructed the object will first be reset with this function. .TP .B release The .B pool_release function releases the data pointer .I data back into the pool .IR "p" . If the .I data pointer is .B NULL or was not derived from .I p the pool is not modified. .TP .B size The .B 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 .I new_data_fn has been called (barring memory allocation failures). .TP .B unused The .B pool_unused function returns the number of data objects that are currently not being used. The number of objects currently in use is .I pool_size minus .IR "pool_unused" . .TP .B iterate\fR, \fBnext Enumerate each data object in the pool. The .I pool_iterate function initializes the .I iter object to the beginning of the pool. With each subsequent call to .I pool_next a pointer to each element is returned or .I 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. .SH RETURNS .TP .B create The .B pool_create function returns -1 and sets .I errno to an approriate value if the operation failed or 0 if the pool was successfully initialized. .TP .B destroy The .B pool_destroy function returns -1 and sets .I errno to an approriate value if the operation failed or 0 if the pool was successfully destroyed. .TP .B new The .B pool_new function returns a new .B pool object with no objects. .TP .B clean The .B pool_clean function returns -1 and sets .I errno to an approriate value if the operation failed or 0 if all unused data objects were successfully destroyed. .TP .B get The .B pool_get function returns a data object from the pool. If the .I max_size limit is reached, .I errno is set to .B ERANGE and .I NULL is returned. If the .I new_data_fn returns .I NULL or if an error occurs .I errno will be set to an approriate value and .I NULL will be returned. .TP .B release The .B pool_release function returns -1 and sets .I errno to an approriate value if the .I p parameter is .B NULL or if the .I data pointer was not derived from this pool. If the .I data object was successfully released back into the pool or if it is .IR "NULL" , 0 is returned to indicate success. .TP .B next The .B pool_next function returns the next member in the pool or .I NULL if all members have been enumerated.