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

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 flags. Either PR_WAITOK or
PR_NOWAIT must be specified to define behaviour in
case the pooled resources are depleted. If no resources are available and
PR_NOWAIT was specified, this function returns
NULL. If PR_WAITOK was
specified but PR_LIMITFAIL was not,
pool_get() will wait until items are returned to
the pool. If both PR_WAITOK and
PR_LIMITFAIL were 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. If PR_ZERO was specified
and an item has been successfully allocated, it is zeroed before being
returned to the caller.

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 if possible.

pp

The handle identifying the pool resource instance.

item

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

If a non-interrupt safe allocator has been selected by passing the
PR_WAITOK flag to
pmap_init(), pool_put() may
sleep when completely unused pages are released.

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.

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

pool_setlowat()

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.

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

The pool resource code uses a per-pool lock to protect 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
reentered.

pool_init(), pool_destroy(),
pool_prime(), pool_sethiwat(),
pool_setlowat(), and
pool_sethardlimit() can be called during autoconf or
from process context.

pool_get() and
pool_put() can be called during autoconf or from
process context. If the pool has been initialised with an interrupt safe
pool allocator they can also be called from interrupt context at or below
the interrupt level specified by a call to
pool_init().

pool_get() will return a pointer to an item allocated
from the pool. If PR_NOWAIT or
PR_LIMITFAIL were passed as flags to the pool it may
return NULL if there are no resources available or if
the pool hard limit has been reached, respectively.

pool_prime() will return
ENOMEM if the requested number of items could not be
allocated. Otherwise, the return value is 0.

pool_sethardlimit() will return
EINVAL if the current size of the pool exceeds the
requested hard limit. Otherwise, the return value is 0.