--- /dev/null
+.\" $OpenBSD: pool.9,v 1.3 2000/04/26 21:21:38 mickey Exp $
+.\" $NetBSD: pool.9,v 1.13 1999/04/03 14:50:21 msaitoh 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
+.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 CODE REFERENCES
+The pool manager is implemented in the file
+.Pa sys/kern/subr_pool.c .
+.Sh SEE ALSO
+.Xr malloc 9 ,
+.Xr free 9
+.\" .Xr uvm 9
+.Sh BUGS
+Pool will not work with old VM and is only used by UVM.
+.Sh HISTORY
+The pool manager first appeared in
+.Nx 1.4
+and was ported to
+.Ox
+by Artur Grabowski <art@openbsd.org>.
projects / openbsd / commitdiff