343 lines
10 KiB
Groff
343 lines
10 KiB
Groff
.\" $NetBSD: pool.9,v 1.14 1999/08/05 04:00:04 sommerfeld Exp $
|
|
.\"
|
|
.\" Copyright (c) 1997, 1998 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, 1998
|
|
.Dt POOL 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pool_create ,
|
|
.Nm pool_destroy ,
|
|
.Nm pool_get ,
|
|
.Nm pool_put ,
|
|
.Nm pool_prime ,
|
|
.Nm pool_sethiwat ,
|
|
.Nm pool_setlowat
|
|
.\".Nm POOL_STORAGE_SIZE
|
|
.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"
|
|
.Ft void
|
|
.Fn pool_sethiwat "struct pool *pp" "int n"
|
|
.Ft void
|
|
.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
|
|
.Pq Xr malloc 9 .
|
|
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.
|
|
.Ss CREATING A POOL
|
|
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.
|
|
.Ss ALLOCATING ITEMS FROM A POOL
|
|
.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 or more of of
|
|
.Dv PR_URGENT ,
|
|
.Dv PR_WAITOK
|
|
or
|
|
.Dv PR_LIMITFAIL ,
|
|
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
|
|
.Pq XXX .
|
|
.\"Undefined behaviour results if
|
|
.\".Dv PR_MALLOCOK
|
|
.\"is specified on a pool handle that was created using client-provided
|
|
.\"storage.
|
|
.\" a bunch of other flags aren't documented.
|
|
If both
|
|
.Dv PR_LIMITFAIL
|
|
and
|
|
.Dv PR_WAITOK
|
|
is specified, and the pool has reached its hard limit,
|
|
.Fn pool_get
|
|
will return
|
|
.Dv NULL
|
|
without waiting, allowing the caller to do its own garbage collection;
|
|
however, it will still wait if the pool is not yet at its hard limit.
|
|
.El
|
|
.Ss RETURNING ITEMS TO A POOL
|
|
.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 outstanding 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
|
|
.Ss PRIMING A POOL
|
|
.Fn pool_prime
|
|
adds items to the pool.
|
|
Storage space for the items is either allocated directly using
|
|
.Xr malloc 9
|
|
or given to
|
|
.Fn pool_prime
|
|
preallocated by the calling function.
|
|
.Pp
|
|
.Fn pool_prime
|
|
.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
|
|
.Ss SETTING POOL RESOURCE WATERMARKS
|
|
A pool will attempt to increase its resource usage to keep up with the demand
|
|
for its items.
|
|
Conversely,
|
|
it will return unused memory to the system should the number of accumulated
|
|
unused items in the pool exceed a programmable limit.
|
|
The limits for the minimum and maximum number of items which a pool should keep
|
|
at hand are known as the high and low
|
|
.Sy watermarks.
|
|
The functions
|
|
.Fn pool_sethiwat
|
|
and
|
|
.Fn pool_setlowat
|
|
set a pool's high and low watermarks, respectively.
|
|
.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
|
|
.Ss POTENTIAL PITFALLS
|
|
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 its internal state.
|
|
If any pool functions are called in an interrupt context,
|
|
the caller must block all interrupts that might cause the
|
|
code to be reentered.
|
|
.Ss DIAGNOSTICS
|
|
Pool usage logs can be enabled by defining the compile-time option
|
|
.Dv POOL_DIAGNOSTIC .
|
|
.\" .Sh RETURN VALUES
|
|
.\" .Sh EXAMPLES
|
|
.Sh CODE REFERENCES
|
|
The pool manager is implemented in the file
|
|
.Pa sys/kern/subr_pool.c .
|
|
.\" .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 .
|