POOL(9)                NetBSD Kernel Developer's Manual                POOL(9)

NAME
     pool_init, pool_destroy, pool_get, pool_put, pool_prime, pool_sethiwat,
     pool_setlowat, pool_sethardlimit -- resource-pool manager

SYNOPSIS
     #include <sys/pool.h>

     void
     pool_init(struct pool *pp, size_t size, u_int align, u_int align_offset,
         int flags, const char *wchan, struct pool_allocator *palloc,
         int ipl);

     void
     pool_destroy(struct pool *pp);

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

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

     int
     pool_prime(struct pool *pp, int nitems);

     void
     pool_sethiwat(struct pool *pp, int n);

     void
     pool_setlowat(struct pool *pp, int n);

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

DESCRIPTION
     These utility routines provide management of pools of fixed-sized areas
     of memory.  Resource pools set aside an amount of memory for exclusive
     use by the resource pool owner.  This can be used by applications to
     guarantee the availability of a minimum amount of memory needed to con-
     tinue operation independent of the memory resources currently available
     from the system-wide memory allocator (malloc(9)).

   INITIALIZING A POOL
     The function pool_init() initializes a resource pool.  The arguments are:

           pp            The handle identifying the pool resource instance.

           size          Specifies the size of the memory items managed by the
                         pool.

           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 parame-
                         ter applies.

           flags         Should be set to zero or PR_NOTOUCH.  If PR_NOTOUCH
                         is given, free items are never used to keep internal
                         state so that the pool can be used for non memory
                         backed objects.

           wchan         The `wait channel' passed on to cv_wait(9) if
                         pool_get() must wait for items to be returned to the
                         pool.

           palloc        Can be set to NULL or pool_allocator_kmem, in which
                         case the default kernel memory allocator will be
                         used.  It can also be set to pool_allocator_nointr
                         when the pool will never be accessed from interrupt
                         context.

           ipl           Specifies an interrupt priority level that will block
                         all interrupt handlers that could potentially access
                         the pool.

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

                       ALLOCATING ITEMS FROM A POOL
                         pool_get() allocates an item from the pool and
                         returns a pointer to it.  The arguments are:

                               pp     The handle identifying the pool resource
                                      instance.

                               flags  The flags can be used to define behav-
                                      iour in case the pooled resources are
                                      depleted.  If no resources are available
                                      and PR_NOWAIT is given, pool_get()
                                      returns NULL.  If PR_WAITOK is given and
                                      allocation is attempted with no
                                      resources available, the function will
                                      sleep until items are returned to the
                                      pool.  If both PR_LIMITFAIL and
                                      PR_WAITOK are specified, and the pool
                                      has reached its hard limit, pool_get()
                                      will return NULL without waiting, allow-
                                      ing 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
                         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.  The
                         arguments to pool_put() are:

                               pp    The handle identifying the pool resource
                                     instance.

                               item  A pointer to a pool item previously
                                     obtained by pool_get().

                       PRIMING A POOL
                         pool_prime() adds items to the pool.  Storage space
                         for the items is allocated by using the page alloca-
                         tion routine specified to pool_create().

                         The arguments to pool_prime() are:

                               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.

                       SETTING POOL RESOURCE WATERMARKS AND LIMITS
                         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.

                         The hard limit represents the maximum number of items
                         a pool is allowed to allocate at any given time.
                         Unless modified via pool_sethardlimit(), the hard
                         limit defaults to UINT_MAX.

                         pool_sethiwat()

                               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.  If this func-
                                      tion is not used to specify a maximum
                                      number of items, the pages will remain
                                      associated with the pool until the sys-
                                      tem runs low on memory, at which point
                                      the VM system will try to reclaim unused
                                      pages.

                         pool_setlowat()

                               pp     The handle identifying the pool resource
                                      instance.

                               n      The minimum number of items to keep in
                                      the pool.  The number 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.

                         pool_sethardlimit()

                               pp     The handle identifying the pool resource
                                      instance.

                               n      The maximum number of items to be allo-
                                      cated from the pool (i.e. the hard
                                      limit).

                               warnmess
                                      The warning message that will be logged
                                      when the hard limit is reached.

                               ratecap
                                      The minimal interval (in seconds) after
                                      which another warning message is issued
                                      when the pool hits its hard limit again.

                       POTENTIAL PITFALLS
                         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 pro-
                         tect its internal state.  If any pool functions are
                         called in an interrupt context, the caller must block
                         all interrupts that might cause the code to be reen-
                         tered.  Additionally, the functions pool_init() and
                         pool_destroy() should never be called in interrupt
                         context.

                       DIAGNOSTICS
                         Pool usage logs can be enabled by defining the com-
                         pile-time option POOL_DIAGNOSTIC.

CODE REFERENCES
     The pool manager is implemented in the file sys/kern/subr_pool.c.

SEE ALSO
     free(9), malloc(9), memoryallocators(9), pool_cache(9), uvm(9)

HISTORY
     The NetBSD pool manager appeared in NetBSD 1.4.

NetBSD 7.0                      August 15, 2015                     NetBSD 7.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2015 Modified for NetBSD by Kimmo Suominen