300 lines
9.0 KiB
Groff
300 lines
9.0 KiB
Groff
.\" $NetBSD: pool.9,v 1.6 1998/07/29 22:10:47 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 July 23, 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/pool.h>
|
|
.Ft struct pool *
|
|
.\" too many arguments for a single .Fn
|
|
.Fo pool_create
|
|
.Fa "size_t size"
|
|
.Fa "u_int align"
|
|
.Fa "u_int align_offset"
|
|
.Fa "int nitems"
|
|
.Fa "char *wchan"
|
|
.Fa "u_int pagesz"
|
|
.Fa "void *(*palloc)(unsigned long sz, int flags, int tag)"
|
|
.Fa "void (*prelease)(void *v, unsigned long sz, int tag)"
|
|
.Fa "int mtag"
|
|
.Fc
|
|
.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_sethiwat "struct pool *pp" "int n"
|
|
.Fn pool_setlowat "struct pool *pp" "int n"
|
|
.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 by calling the
|
|
.Fn palloc
|
|
function passed to
|
|
.Fn pool_create ,
|
|
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 "prelease"
|
|
.It Fa size
|
|
specifies the size of the memory items managed by the pool.
|
|
.It Fa align
|
|
Specifies the memory address aligment of the items returned by
|
|
.Fn pool_get .
|
|
This argument must be a power of two. If zero, the alignment defaults
|
|
to a architecture-specific natural aligment.
|
|
.It Fa align_offset
|
|
The offset within an item to which the
|
|
.Fa align
|
|
parameter applies.
|
|
.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
|
|
can be used at a later time to add permanent 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 pagesz
|
|
The unit which is used to allocate additional memory to the pool.
|
|
It must be a power of two.
|
|
.It Fa palloc
|
|
is called to add additional memory if the pool is depleted. It returns
|
|
.Fa pagesz
|
|
aligned memory. The argument
|
|
.Fa sz
|
|
will be a multiple of
|
|
.Fa pagesz .
|
|
.It Fa prelease
|
|
is called to release pages back to the system.
|
|
.Fn palloc
|
|
and
|
|
.Fn prelease
|
|
may be
|
|
.Dv NULL ,
|
|
in which case the pool manager uses
|
|
.Xr uvm_km_kmemalloc 9
|
|
and
|
|
.Xr uvm_km_free 9
|
|
to allocate and release memory using the
|
|
.Em kernel_map
|
|
.Po see
|
|
.Xr UVM 9
|
|
.Pc .
|
|
.It Fa mtag
|
|
the memory tag passed to
|
|
.Fn palloc
|
|
and
|
|
.Fn prelease
|
|
when allocating or releasing memory pages.
|
|
.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
|
|
One of
|
|
.Dv PR_URGENT
|
|
or
|
|
.Dv PR_WAITOK ,
|
|
that define behaviour in case the pooled resources are depleted.
|
|
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 .
|
|
If
|
|
.Dv PR_URGENT
|
|
is specified and no items are available and
|
|
.Fn palloc
|
|
cannot allocate a new page, the system will panic (XXX).
|
|
.\"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 maximum pool
|
|
size set by
|
|
.Fn pool_sethiwat
|
|
and there are no out-standing requests for pool items, the excess
|
|
items will be returned to the system by calling
|
|
.Fn prelease .
|
|
.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
|
|
.Fn pool_sethiwat
|
|
.Bl -tag -offset indent -width "flags"
|
|
.It Fa pp
|
|
The handle identifying the pool resource instance.
|
|
.It Fa 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
|
|
.Pq by calling Fn prelease .
|
|
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.
|
|
.El
|
|
|
|
.Pp
|
|
.Fn pool_setlowat
|
|
.Bl -tag -offset indent -width "flags"
|
|
.It Fa pp
|
|
The handle identifying the pool resource instance.
|
|
.It Fa n
|
|
The minimum number of items to keep in the pool. The number pages
|
|
in the pool will not decrease below the required value to accommodate
|
|
the minimum number of items specified by this function.
|
|
Unlike
|
|
.Fn pool_prime ,
|
|
this function does not allocate the necessary memory upfront.
|
|
.El
|
|
|
|
.Pp
|
|
Note that undefined behaviour results when mixing the storage providing
|
|
methods supported by the pool resource routines.
|
|
.Pp
|
|
The pool resource code uses a per-pool lock to protect the internal state.
|
|
If a pool is used from an interrupt context, the caller is responsible
|
|
for blocking interrupts appropriately.
|
|
.Pp
|
|
Pool usage logs can be enabled by defining the compile-time option
|
|
.Dv POOL_DIAGNOSTIC .
|
|
.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 .
|
|
.Xr uvm 9 .
|
|
.Sh HISTORY
|
|
The
|
|
.Nx
|
|
pool manager appeared in
|
|
.Nx 1.4 .
|