298 lines
8.9 KiB
Groff
298 lines
8.9 KiB
Groff
.\" $NetBSD: pool.9,v 1.39 2005/10/03 16:52:17 wiz 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 October 2, 2005
|
|
.Dt POOL 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pool_init ,
|
|
.Nm pool_destroy ,
|
|
.Nm pool_get ,
|
|
.Nm pool_put ,
|
|
.Nm pool_prime ,
|
|
.Nm pool_sethiwat ,
|
|
.Nm pool_setlowat
|
|
.Nd resource-pool manager
|
|
.Sh SYNOPSIS
|
|
.In sys/pool.h
|
|
.Ft void
|
|
.Fo pool_init
|
|
.Fa "struct pool *pp"
|
|
.Fa "size_t size"
|
|
.Fa "u_int align"
|
|
.Fa "u_int align_offset"
|
|
.Fa "int flags"
|
|
.Fa "char *wchan"
|
|
.Fa "struct pool_allocator *palloc"
|
|
.Fc
|
|
.Ft void
|
|
.Fn pool_destroy "struct pool *pp"
|
|
.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"
|
|
.Ft void
|
|
.Fn pool_sethiwat "struct pool *pp" "int n"
|
|
.Ft void
|
|
.Fn pool_setlowat "struct pool *pp" "int n"
|
|
.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 .
|
|
.Ss INITIALIZING A POOL
|
|
The function
|
|
.Fn pool_init
|
|
initializes a resource pool.
|
|
The arguments are:
|
|
.Pp
|
|
.Bl -tag -offset indent -width "align_offset"
|
|
.It Fa pp
|
|
The handle identifying the pool resource instance.
|
|
.It Fa size
|
|
Specifies the size of the memory items managed by the pool.
|
|
.It Fa align
|
|
Specifies the memory address alignment of the items returned by
|
|
.Fn pool_get .
|
|
This argument must be a power of two.
|
|
If zero,
|
|
the alignment defaults to an architecture-specific natural alignment.
|
|
.It Fa align_offset
|
|
The offset within an item to which the
|
|
.Fa align
|
|
parameter applies.
|
|
.It Fa flags
|
|
Should be set to zero or
|
|
.Dv PR_NOTOUCH .
|
|
If
|
|
.Dv PR_NOTOUCH
|
|
is given, free items are never used to keep internal state so that
|
|
the pool can be used for non memory backed objects.
|
|
.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 palloc
|
|
can be set to
|
|
.Dv NULL
|
|
or
|
|
.Dv pool_allocator_kmem ,
|
|
in which case the default kernel memory allocator will be used.
|
|
It can also be set to
|
|
.Dv pool_allocator_nointr
|
|
when the pool will never be accessed from interrupt context.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn POOL_INIT
|
|
macro can be used to both declare and initialize a resource pool.
|
|
The
|
|
.Fn POOL_INIT
|
|
macro has the same arguments as the
|
|
.Fn pool_init
|
|
function and the resource pool will be initialized automatically
|
|
during system startup.
|
|
.Ss DESTROYING A POOL
|
|
The function
|
|
.Fn pool_destroy
|
|
destroys a resource pool.
|
|
It takes a single argument
|
|
.Fa pp
|
|
identifying the pool resource instance.
|
|
.Ss ALLOCATING ITEMS FROM A POOL
|
|
.Fn pool_get
|
|
allocates an item from the pool and returns a pointer to it.
|
|
The arguments are:
|
|
.Bl -tag -offset indent -width "flags"
|
|
.It Fa pp
|
|
The handle identifying the pool resource instance.
|
|
.It Fa flags
|
|
The flags can be used to define behaviour in case the pooled resources
|
|
are depleted.
|
|
If no resources are available and
|
|
.Dv PR_NOWAIT
|
|
is given,
|
|
.Fn pool_get
|
|
returns
|
|
.Dv NULL .
|
|
If
|
|
.Dv PR_WAITOK
|
|
is given and allocation is attempted with no resources available,
|
|
the function will sleep until items are returned to the pool.
|
|
.\"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
|
|
are 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.
|
|
The arguments to
|
|
.Fn pool_put
|
|
are:
|
|
.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 allocated by using the page allocation
|
|
routine specified to
|
|
.Fn pool_create .
|
|
.Pp
|
|
The arguments to
|
|
.Fn pool_prime
|
|
are:
|
|
.Bl -tag -offset indent -width "storage"
|
|
.It Fa pp
|
|
The handle identifying the pool resource instance.
|
|
.It Fa nitems
|
|
The number of items to add to the pool.
|
|
.El
|
|
.Pp
|
|
This function may return
|
|
.Dv ENOMEM
|
|
in case the requested number of items could not be allocated.
|
|
Otherwise,
|
|
the return value is 0.
|
|
.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.
|
|
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 up-front.
|
|
.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.
|
|
Additionally, the functions
|
|
.Fn pool_init
|
|
and
|
|
.Fn pool_destroy
|
|
should never be called in interrupt context.
|
|
.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 free 9 ,
|
|
.Xr malloc 9 ,
|
|
.Xr pool_cache 9 ,
|
|
.Xr uvm 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nx
|
|
pool manager appeared in
|
|
.Nx 1.4 .
|