205 lines
6.5 KiB
Groff
205 lines
6.5 KiB
Groff
.\" $NetBSD: pool.9,v 1.5 1998/04/22 07:14:33 ross Exp $
|
|
.\"
|
|
.\" 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
|
|
.Po
|
|
.Xr malloc 9
|
|
.Pc .
|
|
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.
|
|
.Pp
|
|
The function
|
|
.Fn pool_create
|
|
initializes a resource pool and returns a handle to it. The
|
|
arguments are:
|
|
.Pp
|
|
.Bl -tag -offset indent -width "nitems"
|
|
.It Fa size
|
|
specifies the size of the memory items managed by the pool.
|
|
.It 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.
|
|
.It 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.
|
|
.It Fa mtype
|
|
the memory tag passed to
|
|
.Xr malloc 9
|
|
when allocating memory for pool items.
|
|
.It 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
|
|
.Pp
|
|
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
|
|
.Pq 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.
|
|
.Pp
|
|
.Fn pool_get
|
|
allocates an item from the pool and returns a pointer to it.
|
|
.Bl -tag -offset indent -width "flags"
|
|
.It Fa pp
|
|
The handle identifying the pool resource instance.
|
|
.It 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
|
|
.Pp
|
|
.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 .
|
|
.Bl -tag -offset indent -width "item"
|
|
.It Fa pp
|
|
The handle identifying the pool resource instance.
|
|
.It Fa item
|
|
A pointer to a pool item previously obtained by
|
|
.Fn pool_get .
|
|
.El
|
|
.Pp
|
|
.Fn pool_prime
|
|
adds items to the pool.
|
|
.Bl -tag -offset indent -width "nitems"
|
|
.It Fa pp
|
|
The handle identifying the pool resource instance.
|
|
.It 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
|
|
.Pp
|
|
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
|
|
.Pp
|
|
The pool manager is implemented in the file
|
|
.Nm sys/kern/subr_pool.c .
|
|
.Pp
|
|
.Sh AUTHOR
|
|
.Sh SEE ALSO
|
|
.Xr malloc 9 ,
|
|
.Xr free 9 .
|
|
.Sh HISTORY
|
|
The
|
|
.Nx
|
|
pool manager appeared in
|
|
.Nx 1.4 .
|