Copyright (c) 1997 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Paul Kranenburg.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
must display the following acknowledgement:
This product includes software developed by the NetBSD
Foundation, Inc. and its contributors.
4. Neither the name of The NetBSD Foundation nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd December 4, 1997 .Dt POOL 9 .Os NetBSD .Sh NAME .Nm pool_create , .Nm pool_destroy , .Nm pool_get , .Nm pool_put , .Nm pool_prime .Nd resource-pool manager .Sh SYNOPSIS .Fd #include <sys/malloc.h> .Fd #include <sys/pool.h> .Ft struct pool * .Fn pool_create "size_t size" "int nitems" "char *wchan" "int mtype" "caddr_t storage" .Ft void * .Fn pool_get "struct pool *pp" "int flags" .Ft void .Fn pool_put "struct pool *pp" "void *item" .Ft int .Fn pool_prime "struct pool *pp" "int nitems" "caddr_t storage" .Fn POOL_STORAGE_SIZE "size" "nitems" .Sh 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 operation independent of the memory resources currently available from the system-wide memory allocator
o .Xr malloc 9
c . The pool manager can optionally obtain temporary memory through .Xr malloc 9 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.
p The function .Fn pool_create initializes a resource pool and returns a handle to it. The arguments are:
p l -tag -offset indent -width "nitems" t Fa size specifies the size of the memory items managed by the pool. t Fa nitems specifies the number of memory items that are allocated to the pool at creation time. This number may be zero, in which case .Fn pool_prime must be used at a later time to add items to the pool. t Fa wchan the .Sq wait channel passed on to .Xr tsleep 9 if .Fn pool_get must wait for items to be returned to the pool. t Fa mtype the memory tag passed to .Xr malloc 9 when allocating memory for pool items. t Fa storage Optional storage provided by the caller to use in lieu of .Xr malloc 9 for both the pool handle and all pool items. .El
p If not enough memory is available to create the pool resource, .Fn pool_create returns .Dv NULL . If the .Fa storage parameter is used, the client is responsible for providing enough storage to accommodate the number of pool items specified by .Fa nitems , as well as the space required by the pool's administrative overhead
q i.e. the pool handle . The macro .Fn POOL_STORAGE_SIZE "size" "nitems" can be used to determine the amount of storage needed to setup a pool, given the size and number of the pool items.
p .Fn pool_get allocates an item from the pool and returns a pointer to it. l -tag -offset indent -width "flags" t Fa pp The handle identifying the pool resource instance. t Fa flags A combination of .Dv PR_MALLOCOK and .Dv PR_WAITOK , that define behaviour in case the pooled resources are depleted. If .Dv PR_MALLOCOK is given, an attempt will be made to allocate supplemental memory by using .Xr malloc 9 . If no resources are available and .Dv PR_WAITOK is given, this function will wait until items are returned to the pool, otherwise .Fn pool_get returns .Dv NULL . Undefined behaviour results if .Dv PR_MALLOCOK is specified on a pool handle that was created using client-provided storage. .El
p .Fn pool_put returns the pool item pointed at by .Fa item to the resource pool identified by the pool handle .Fa 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 .Xr free 9 . l -tag -offset indent -width "item" t Fa pp The handle identifying the pool resource instance. t Fa item A pointer to a pool item previously obtained by .Fn pool_get . .El
p .Fn pool_prime adds items to the pool. l -tag -offset indent -width "nitems" t Fa pp The handle identifying the pool resource instance. t Fa nitems The number of items to add to the pool. Storage for the pool items can be passed in the .Fa storage argument. If this parameter is .Dv NULL , the items are allocated by using .Xr malloc 9 . This function may return .Dv ENOMEM in case the requested number of items could not be allocated. Otherwise, the return value is 0. .El
p Note that undefined behaviour results when mixing the storage providing methods supported by the pool resource routines. .Sh RETURN VALUES .Sh EXAMPLES .Sh CODE REFERENCES
p The pool manager is implemented in the file .Nm sys/kern/subr_pool.c .
p .Sh AUTHOR .Sh SEE ALSO .Xr malloc 9 , .Xr free 9 . .Sh HISTORY The .Nx pool manager appeared in .Nx 1.4 .
Indexes created Thu Oct 23 18:09:57 GMT 2025