*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> pool (9)              



NAME    [Toc]    [Back]

     pool_init,  pool_destroy,  pool_get,  pool_put,  pool_prime,
     pool_setlowat,      pool_cache_init,     pool_cache_destroy,
     pool_cache_put,                  pool_cache_destruct_object,
pool_cache_invalidate - resource-pool

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <sys/pool.h>

     pool_init(struct pool *pool, size_t size, u_int align,
             u_int align_offset, int flags, const char *wmesg,
             struct pool_allocator *palloc);

     pool_destroy(struct pool *pp);

     pool_set_drain_hook(struct  pool  *pp,  void  (*fun)(void *,
             void *arg);

     void *
     pool_get(struct pool *pp, int flags);

     pool_put(struct pool *pp, void *item);

     pool_prime(struct pool *pp, int nitems);

     pool_sethiwat(struct pool *pp, int n);

     pool_setlowat(struct pool *pp, int n);

     pool_sethardlimit(struct pool *pp, unsigned  n,  const  char
             int ratecap);

     pool_cache_init(struct pool_cache *pc, struct pool *pp,
             int  (*ctor)(void *, void *, int), void (*dtor)(void
*, void *),
             void *arg);

     pool_cache_destroy(struct pool_cache *pc);

     void *
     pool_cache_get(struct pool_cache *pc, int flags);

     pool_cache_put(struct pool_cache *pc, void *object);

     pool_cache_destruct_object(struct   pool_cache   *pc,   void

     pool_cache_invalidate(struct pool_cache *pc);

DESCRIPTION    [Toc]    [Back]

     These utility routines provide management of pools of fixedsized areas
     of memory.  Resource pools set aside an amount of memory for
     use  by the resource pool owner.  This can be used by applications to
     guarantee the availability of a  minimum  amount  of  memory
needed to continue
 operation independent of the memory resources currently available
     from the system-wide memory allocator (malloc(9)).  The pool
manager obtains
  memory  by using the special-purpose memory allocator
     passed to pool_init(), for extra pool items in case the number of allocations
  exceeds the nominal number of pool items managed by a
pool resource.
  This temporary memory  will  be  automatically  returned to the system
 at a later time.

   CREATING A POOL    [Toc]    [Back]
     The  function  pool_init() initializes a resource pool.  The
arguments are:

           pool          Specifies the pool storage  to  be  initialized.

           size           Specifies  the size of the memory items
managed by the

           align         Specifies the memory  address  alignment
of the items
                         returned  by  pool_get().  This argument
must be a power
 of two.  If zero, the  alignment  defaults to an architecture-specific
 natural alignment.

           align_offset   The  offset within an item to which the
align parameter

           flags         Specifies various flags set on the  pool
at creation

           wmesg          The  message  passed on to tsleep(9) if
pool_get() must
                         wait for items to  be  returned  to  the

           palloc         The  back-end  allocator used to manage
the memory for
                         the pool.   palloc()  may  be  NULL,  in
which case the
                         pool        manager       uses       the
pool_allocator_kmem allocator
                         which   uses   uvm_km_kmemalloc(9)   and
uvm_km_free(9) to
                         allocate  and  release  memory using the
kmem_map (see
                         uvm(9)).  It is recommended to set  this
                         pool_allocator_nointr  if  the pool will
never be accessed
 in interrupt context, since  that
allocator is
                         much more efficient.

   DESTROYING A POOL    [Toc]    [Back]
     The  pool_destroy()  function  destroys a resource pool.  It
takes a single
     argument pp identifying the pool resource instance.

   SETTING DRAIN CALLBACK    [Toc]    [Back]
     The pool_set_drain_hook() function can be used to specify  a
function that
     will be called when memory is running low.  The callback fun
will be
     called with the arguments arg which is the third argument to
     pool_set_drain_hook()  and  flags  which will have PR_WAITOK
set if the
     drain hook is allowed to sleep.

     pool_get() allocates an item from the  pool  and  returns  a
pointer to it.

           pp      The  handle  identifying the pool resource instance.

           flags  One or more of PR_URGENT, PR_WAITOK or  PR_LIMITFAIL, that
                  define  behaviour  in case the pooled resources
are depleted.
                  If no resources are available and PR_WAITOK  is
given, this
                  function  will wait until items are returned to
the pool.
                  Otherwise pool_get() returns NULL.   If  PR_URGENT is specified
  and  no  items are available and palloc()
cannot allocate
                  a new page, the system will  panic  (XXX).   If
                  PR_LIMITFAIL  and  PR_WAITOK are specified, and
the pool has
                  reached its hard limit, pool_get() will  return
NULL without
                  waiting,  allowing  the  caller  to  do its own
garbage collection;
 however, it will still wait if  the  pool
is not yet at
                  its hard limit.

   RETURNING ITEMS TO A POOL    [Toc]    [Back]
     pool_put()  returns  the pool item pointed at by item to the
resource pool
     identified by the pool handle pp.  If the number  of  available items in
     the   pool   exceeds   the   maximum   pool   size   set  by
pool_sethiwat() and there
     are no outstanding requests for pool items, the excess items
will be returned
 to the system by calling prelease().

           pp     The  handle  identifying  the pool resource instance.

           item  A pointer to a pool item previously obtained  by

   PRIMING A POOL    [Toc]    [Back]
     pool_prime()  adds items to the pool.  Storage space for the
items is allocated
 by using the page allocation  routine  specified  to


           pp       The  handle identifying the pool resource instance.

           nitems  The number of items to add to the pool.

     This function may return ENOMEM in case the requested number
of items
     could not be allocated.  Otherwise, the return value is 0.

     A  pool  will attempt to increase its resource usage to keep
up with the
     demand for its items.  Conversely,  it  will  return  unused
memory to the
     system  should the number of accumulated unused items in the
pool exceed a
     programmable limit.  The limits for the minimum and  maximum
number of
     items which a pool should keep at hand are known as the high
and low
     watermarks.     The    functions     pool_sethiwat()     and
pool_setlowat() set a
     pool's high and low watermarks, respectively.


           pp      The  handle  identifying the pool resource instance.

           n      The maximum number of  items  to  keep  in  the
pool.  As items
                  are  returned  and the total number of pages in
the pool is
                  larger than the maximum set by  this  function,
any completely
                  unused pages are released immediately (by calling
                  prelease()).  If this function is not  used  to
specify a maximum
 number of items, the pages will remain associated with
                  the pool until the system runs low  on  memory,
at which point
                  the VM system will try to reclaim unused pages.


           pp     The handle identifying the  pool  resource  instance.

           n       The  minimum  number  of  items to keep in the
pool.  The number
                  of pages in the pool will  not  decrease  below
the required
                  value  to  accommodate  the  minimum  number of
items specified
                  by this function.   Unlike  pool_prime(),  this
function does
                  not allocate the necessary memory up-front.

   SETTING HARD LIMITS    [Toc]    [Back]
     The  function  pool_sethardlimit()  sets a hard limit on the
pool to n
     items.  If the hard limit is reached warnmess will be printed to the console,
 but no more than every ratecap seconds.  Upon successful completion,
 a value of 0 is returned.  The  value  EINVAL  is  returned when the
     current  size of the pool already exceeds the requested hard

   POTENTIAL PITFALLS    [Toc]    [Back]
     Note that undefined behaviour results when mixing the  storage providing
     methods supported by the pool resource routines.

     The  pool  resource code uses a per-pool lock to protect its
     state.  If any pool functions are  called  in  an  interrupt
context, the
     caller  must  block all interrupts that might cause the code
to be reentered.

   POOL CACHES    [Toc]    [Back]
     Another set of functions are available as extensions to  the
pool manager.
     The pool cache functions automatically call constructors and
     when objects are allocated from the pool or returned to  it.
They have
     similar semantics as the other pool functions.  The pp argument to
     pool_cache_init() must already be initialized.

     Objects are not immediately deconstructed when put into  the
pool cache.
     Instead,  they  are maintained for future allocations.  When
the system determines
 that memory needs to be reclaimed, then the  deconstructor is
     called  on  each  free object and it is placed back into the
pool.  The ctor
     and dtor functions are passed arg and a pointer to  the  object, in that
     order.   The  ctor  is  also  passed the same flags that are
passed to
     pool_cache_get().  The pool_cache_destruct_object() function
     and puts an object back into the pool immediately.
     pool_cache_invalidate()  deconstructs all cached objects and
     their memory.

     Pool caches are also commonly referred to as a slab  allocator.

   DIAGNOSTICS    [Toc]    [Back]
     Pool  usage logs can be enabled by defining the compile-time

   DEBUGGING    [Toc]    [Back]
     To debug a misbehaving pool, a kernel can be  compiled  with
     MALLOC_DEBUG option and memory debugging on pools can be enabled with the
     PR_DEBUG flag passed in the flags argument in  the  call  to
     See malloc(9) for more information about MALLOC_DEBUG.

CODE REFERENCES    [Toc]    [Back]

     The    pool    manager    is   implemented   in   the   file

SEE ALSO    [Toc]    [Back]

     free(9), malloc(9), uvm(9)

HISTORY    [Toc]    [Back]

     The pool manager first appeared in NetBSD 1.4 and was ported
to OpenBSD
     by Artur Grabowski <art@openbsd.org>.

OpenBSD      3.6                           July      23,     1998
[ Back ]
 Similar pages
Name OS Title
miser IRIX Miser resource manager
sharemgr IRIX shared resource manager
miser IRIX The Miser Resource Manager
XmRepTypeInstallTearOffModelConvert HP-UX A representation type manager function that installs the resource converter for XmNtearOffModel.
XmRepTypeInstallTearOffModelConverter Tru64 A representation type manager function that installs the resource converter for XmNtearOffModel.
XmRepTypeInstallTearOffModelConverter IRIX A representation type manager function that installs the resource converter for XmNtearOffModel.
XmRepTypeRegister IRIX A representation type manager function that registers a representation type resource
XmRepTypeRegister Tru64 A representation type manager function that registers a representation type resource
XmRepTypeRegister HP-UX A representation type manager function that registers a representation type resource
rad_get_num Tru64 Query resource complements of a Resource Affinity Domain (libnuma)
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service