From 8a51851605feebf1c06f16ece4962cbdd4e9f7ee Mon Sep 17 00:00:00 2001 From: mickey Date: Wed, 26 Apr 2000 21:21:38 +0000 Subject: [PATCH] pool manipulation routines; second take --- share/man/man9/Makefile | 7 +- share/man/man9/pool.9 | 342 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 347 insertions(+), 2 deletions(-) create mode 100644 share/man/man9/pool.9 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 +.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 . -- 2.20.1