pool manipulation routines; second take

2 files changed, 347 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 1afd14ae1cd..a26fedb7a89 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.19 2000/04/26 20:44:50 mickey Exp $
+#	$OpenBSD: Makefile,v 1.20 2000/04/26 21:21:38 mickey Exp $
 #       $NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -6,7 +6,7 @@
 MAN=	boot.9 copy.9 ctxsw.9 disk.9 disklabel.9 doshutdownhooks.9 \
 	fetch.9 fork1.9 \
 	extent.9 hz.9 hzto.9 intro.9 inittodr.9 log.9 kthread.9 \
-	malloc.9 md5.9 microtime.9 panic.9 pfind.9 printf.9 \
+	malloc.9 md5.9 microtime.9 panic.9 pfind.9 pool.9 printf.9 \
 	psignal.9 ratecheck.9 resettodr.9 \
 	random.9 shutdownhook_establish.9 sleep.9 spl.9 store.9 style.9 \
 	time.9 timeout.9 vm_allocate.9 vm_map_copy.9 vm_deallocate.9 \
@@ -32,6 +32,9 @@ MLINKS+=kthread.9 kthread_create.9 kthread.9 kthread_exit.9 \
 MLINKS+=log.9 addlog.9
 MLINKS+=md5.9 MD5Init.9 md5.9 MD5Transform.9
 MLINKS+=pfind.9 pgfind.9
+MLINKS+=pool.9 pool_create.9 pool.9 pool_destroy.9 pool.9 pool_get.9 \
+	pool.9 pool_put.9 pool.9 pool_prime.9 pool.9 pool_sethiwat.9 \
+	pool.9 pool_setlowat.9
 MLINKS+=printf.9 sprintf.9 printf.9 vprintf.9 printf.9 uprintf.9 \
 	printf.9 ttyprintf.9 printf.9 db_printf.9
 MLINKS+=psignal.9 pgsignal.9 psignal.9 gsignal.9
diff --git a/share/man/man9/pool.9 b/share/man/man9/pool.9
new file mode 100644
index 00000000000..edd2fca4a3c
--- /dev/null
+++ b/share/man/man9/pool.9
@@ -0,0 +1,342 @@
+.\"	$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>.