Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pool(3m)		     MBA Library Functions		      pool(3m)

NAME
       pool - A	container for recycleable objects.

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);
       int pool_destroy(struct pool *p);
       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);
       int pool_del(struct pool	*p);
       int pool_clean(struct pool *p);

       void *pool_get(struct pool *p);
       int pool_release(struct pool *p,	void *data);
       unsigned	int pool_size(struct pool *p);
       unsigned	int pool_unused(struct pool *p);
       void pool_iterate(void *p, iter_t *iter);
       void *pool_next(void *p,	iter_t *iter);

DESCRIPTION
       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  ob-
       jects  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.

       create 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 allo-
	      cator 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  con-
	      text  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  be-
	      fore being returned from the pool_get functionbut	only if	it was
	      previously retrieved and released. Unlike	the object_new and ob-
	      ject_del	parameters, object_rst may be NULL to indicate that it
	      is not necessary to reset	objects.

       destroy
	      The pool_destroy function	deletes	all unused objects in the pool
	      and frees	the bitmap backing the pool.

       new    The  pool_new  function allocates	memory and initializes it with
	      the pool_create function.

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

       clean  The  pool_clean  function	 destroys all unused data items	in the
	      pool with	the data_del function specified	with pool_create.

       get    The pool_get function searches the pool p	for an unused data ob-
	      ject  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  cre-
	      ate a new	data object which is then added	to the pool. If	an ex-
	      isting 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.

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

       size   The pool_size function returns the total number of data  objects
	      that  consititute	the pool regardless of how many	object are be-
	      ing used or not being unused. This number	is equal to the	number
	      of  times	new_data_fn has	been called (barring memory allocation
	      failures).

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

       iterate,	next
	      Enumerate	each data object in the	pool. The  pool_iterate	 func-
	      tion  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 enumer-
	      ation  cycle they	may or may not be included in the current set.
	      Elements are not returned	in any particular order.

RETURNS
       create The pool_create function returns -1 and sets errno to an appror-
	      iate value if the	operation failed or 0 if the pool was success-
	      fully initialized.

       destroy
	      The pool_destroy function	returns	-1 and sets errno to an	appro-
	      riate  value  if	the operation failed or	0 if the pool was suc-
	      cessfully	destroyed.

       new    The pool_new function returns a new pool object with no objects.

       clean  The pool_clean function returns -1 and sets errno	to an approri-
	      ate  value  if  the operation failed or 0	if all unused data ob-
	      jects were successfully destroyed.

       get    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  oc-
	      curs  errno  will	be set to an approriate	value and NULL will be
	      returned.

       release
	      The pool_release function	returns	-1 and sets errno to an	appro-
	      riate  value  if	the p parameter	is NULL	or if the data pointer
	      was not derived from this	pool. If the data object was  success-
	      fully  released  back  into  the pool or if it is	NULL, 0	is re-
	      turned to	indicate success.

       next   The pool_next function returns the next member in	 the  pool  or
	      NULL if all members have been enumerated.

libmba-0.9.1			 Apr 29, 2005			      pool(3m)

NAME | SYNOPSIS | DESCRIPTION | RETURNS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pool&sektion=3&manpath=FreeBSD+8.2-RELEASE+and+Ports>

home | help