The new memory resource pool scheme.

share/man/man9/pool.9

@@ -1,4 +1,4 @@
-.\"	$NetBSD: pool.9,v 1.5 1998/04/22 07:14:33 ross Exp $
+.\"	$NetBSD: pool.9,v 1.6 1998/07/29 22:10:47 pk Exp $
 .\"
 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -34,7 +34,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 4, 1997
+.Dd July 23, 1997
 .Dt POOL 9
 .Os NetBSD
 .Sh NAME
@@ -45,16 +45,28 @@
 .Nm pool_prime
 .Nd resource-pool manager
 .Sh SYNOPSIS
-.Fd #include <sys/malloc.h>
 .Fd #include <sys/pool.h>
 .Ft struct pool *
-.Fn pool_create "size_t size" "int nitems" "char *wchan" "int mtype" "caddr_t storage"
+.\" 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"
+.Fn pool_sethiwat "struct pool *pp" "int n"
+.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
@@ -66,8 +78,10 @@ currently available from the system-wide memory allocator
 .Po
 .Xr malloc 9
 .Pc .
-The pool manager can optionally obtain temporary memory through
-.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
@@ -78,14 +92,23 @@ The function
 initializes a resource pool and returns a handle to it. The
 arguments are:
 .Pp
-.Bl -tag -offset indent -width "nitems"
+.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
-must be used at a later time to add items to the pool.
+can be used at a later time to add permanent items to the pool.
 .It Fa wchan
 the
 .Sq wait channel
@@ -94,10 +117,38 @@ passed on to
 if
 .Fn pool_get
 must wait for items to be returned to the pool.
-.It Fa mtype
+.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
-.Xr malloc 9
-when allocating memory for pool items.
+.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
@@ -115,26 +166,23 @@ 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.
+.\"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.
 .Pp
+
 .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
-A combination of
-.Dv PR_MALLOCOK
-and
+One of
+.Dv PR_URGENT
+or
 .Dv PR_WAITOK ,
 that define behaviour in case the pooled resources are depleted.
-If
-.Dv PR_MALLOCOK
-is given, an attempt will be made to allocate supplemental memory by using
-.Xr malloc 9 .
 If no resources are available and
 .Dv PR_WAITOK
 is given, this function will wait until items are returned to the pool,
@@ -142,21 +190,29 @@ otherwise
 .Fn pool_get
 returns
 .Dv NULL .
-Undefined behaviour results if
-.Dv PR_MALLOCOK
-is specified on a pool handle that was created using client-provided
-storage.
+If
+.Dv PR_URGENT
+is specified and no items are available and
+.Fn palloc
+cannot allocate a new page, the system will panic (XXX).
+.\"Undefined behaviour results if
+.\".Dv PR_MALLOCOK
+.\"is specified on a pool handle that was created using client-provided
+.\"storage.
 .El
+
 .Pp
 .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 nominal pool
-size and there are no out-standing requests for pool items, the excess
-items will be returned to the system by using
-.Xr free 9 .
+If the number of available items in the pool exceeds the maximum pool
+size set by
+.Fn pool_sethiwat
+and there are no out-standing 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.
@@ -164,6 +220,7 @@ The handle identifying the pool resource instance.
 A pointer to a pool item previously obtained by
 .Fn pool_get .
 .El
+
 .Pp
 .Fn pool_prime
 adds items to the pool.
@@ -183,9 +240,46 @@ This function may return
 in case the requested number of items could not be allocated. Otherwise,
 the return value is 0.
 .El
+
+.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
+
 .Pp
 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 the internal state.
+If a pool is used from an interrupt context, the caller is responsible
+for blocking interrupts appropriately.
+.Pp
+Pool usage logs can be enabled by defining the compile-time option
+.Dv POOL_DIAGNOSTIC .
 .Sh RETURN VALUES
 .Sh EXAMPLES
 .Sh CODE REFERENCES
@@ -197,6 +291,7 @@ The pool manager is implemented in the file
 .Sh SEE ALSO
 .Xr malloc 9 ,
 .Xr free 9 .
+.Xr uvm 9 .
 .Sh HISTORY
 The
 .Nx