Pool resource utility docs.
This commit is contained in:
pk
parent
eee2902993
commit
c9552d7f64
|
|
@ -0,0 +1,188 @@
|
|||
.\" $NetBSD: pool.9,v 1.1 1997/12/13 23:45:07 pk 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 Dec 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"
|
||||
.Fn POOL_INITIALIZER "pool" "size" "nitems" "wchan" "mtype"
|
||||
.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"
|
||||
.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.
|
||||
.El
|
||||
.Pp
|
||||
If not enough memory is available to create the pool resource,
|
||||
.Fn pool_create
|
||||
returns
|
||||
.Dv NULL .
|
||||
.Pp
|
||||
The macro
|
||||
.Fn POOL_INITIALIZER
|
||||
can be used to initialize a statically declared pool-resource structure.
|
||||
The
|
||||
.Fa size ,
|
||||
.Fa nitems ,
|
||||
.Fa wchan ,
|
||||
and
|
||||
.Fa mtype
|
||||
arguments have the same meaning as their
|
||||
.Fn pool_create
|
||||
counterparts.
|
||||
.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 .
|
||||
.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. 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
|
||||
.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 NetBSD pool manager appeared in
|
||||
.Nx 1.3a .
|
||||
Loading…
Reference in New Issue