I've just entered a pool(9) manual page, which is duplicated below.
The accompanying code in kern/subr_pool.c is to follow shortly.
This code grew out of a private version in vm_swap.c, where it
manages a buffer pool, but it can useful as a generic utility.

Comments welcome.

-pk


POOL(9)                      NetBSD Kernel Manual                      POOL(9)

NAME
     pool create, pool destroy, pool get, pool put, pool prime - resource-pool
     manager

SYNOPSIS
     #include <sys/malloc.h>
     #include <sys/pool.h>

     struct pool *
     pool create(size t size, int nitems, char *wchan, int mtype)

     POOL INITIALIZER(pool, size, nitems, wchan, mtype)

     void *
     pool get(struct pool *pp, int flags)

     void
     pool put(struct pool *pp, void *item)

     int
     pool prime(struct pool *pp, int nitems)

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 continue opera-
     tion independent of the memory resources currently available from the
     system-wide memory allocator (malloc(9)). The pool manager can optionally
     obtain temporary memory through malloc(9) for extra pool items in case
     the number of allocations exceeds the nominal number of pool items man-
     aged by a pool resource.  This temporary memory will be automatically re-
     turned to the system at a later time.

     The function pool create() initializes a resource pool and returns a han-
     dle to it. The arguments are:

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

           nitems  specifies the number of memory items that are allocated to
                   the pool at creation time. This number may be zero, in
                   which case pool prime() must be used at a later time to add
                   items to the pool.

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

           mtype   the memory tag passed to malloc(9) when allocating memory
                   for pool items.

     If not enough memory is available to create the pool resource,
     pool create() returns NULL.

     The macro POOL INITIALIZER() can be used to initialize a statically de-
     clared pool-resource structure.  The size, nitems, wchan, and mtype argu-
     ments have the same meaning as their pool create() counterparts.

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

           pp     The handle identifying the pool resource instance.

           flags  A combination of PR MALLOCOK and PR WAITOK, that define be-
                  haviour in case the pooled resources are depleted.  If
                  PR MALLOCOK is given, an attempt will be made to allocate
                  supplemental memory by using malloc(9).  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.

     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 nominal pool size and there are no out-standing requests
     for pool items, the excess items will be returned to the system by using
     free(9).

           pp    The handle identifying the pool resource instance.

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

     pool prime() adds items to the pool.

           pp      The handle identifying the pool resource instance.

           nitems  The number of items to add to the pool. The items are allo-
                   cated by using malloc(9).  This function may return ENOMEM
                   in case the requested number of items could not be allocat-
                   ed. Otherwise, the return value is 0.

RETURN VALUES
EXAMPLES
CODE REFERENCES
     The pool manager is implemented in the file sys/kern/subr pool.c.

AUTHOR
SEE ALSO
     malloc(9),  free(9).

HISTORY
     The NetBSD pool manager appeared in

NetBSD                            Dec 4, 1997                                2