From a2a4c3cced0c9f01a1e432b21172022c2e999de6 Mon Sep 17 00:00:00 2001 From: Artur Grabowski Date: Sat, 23 Jun 2001 16:40:17 +0000 Subject: reflect reality. Parts from NetBSD --- share/man/man9/pool.9 | 67 ++++++++++++++++++++------------------------------- 1 file changed, 26 insertions(+), 41 deletions(-) (limited to 'share/man/man9/pool.9') diff --git a/share/man/man9/pool.9 b/share/man/man9/pool.9 index 6c5d8f3f7a9..4347286560c 100644 --- a/share/man/man9/pool.9 +++ b/share/man/man9/pool.9 @@ -1,5 +1,5 @@ -.\" $OpenBSD: pool.9,v 1.11 2001/05/28 05:37:28 angelos Exp $ -.\" $NetBSD: pool.9,v 1.13 1999/04/03 14:50:21 msaitoh Exp $ +.\" $OpenBSD: pool.9,v 1.12 2001/06/23 16:40:16 art Exp $ +.\" $NetBSD: pool.9,v 1.18 2001/06/21 11:59:01 wiz Exp $ .\" .\" Copyright (c) 1997, 1998 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -39,7 +39,7 @@ .Dt POOL 9 .Os .Sh NAME -.Nm pool_create , +.Nm pool_init , .Nm pool_destroy , .Nm pool_get , .Nm pool_put , @@ -49,9 +49,9 @@ .Nd resource-pool manager .Sh SYNOPSIS .Fd #include -.Ft struct pool * -.\" too many arguments for a single .Fn -.Fo pool_create +.Ft void +.Fo pool_init +.Fa "struct pool *pool" .Fa "size_t size" .Fa "u_int align" .Fa "u_int align_offset" @@ -85,18 +85,20 @@ resources currently available from the system-wide memory allocator The pool manager can optionally obtain temporary memory by calling the .Fn palloc function passed to -.Fn pool_create , +.Fn pool_init , 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. +.Fn pool_init +initializes a resource pool. The arguments are: .Pp .Bl -tag -offset indent -width "prelease" +.It Fa pool +Specifies the pool storage to be initialized. .It Fa size Specifies the size of the memory items managed by the pool. .It Fa align @@ -129,12 +131,12 @@ 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 +It must return .Fa pagesz aligned memory. The argument .Fa sz -will be a multiple of +shall be a multiple of .Fa pagesz . .It Fa prelease is called to release pages back to the system. @@ -150,7 +152,7 @@ and to allocate and release memory using the .Em kernel_map .Po see -.Xr UVM 9 +.Xr uvm 9 .Pc . .It Fa mtag The memory tag passed to @@ -158,24 +160,8 @@ The memory tag passed to 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, @@ -246,11 +232,14 @@ A pointer to a pool item previously obtained by .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 +Storage space for the items is either allocated by using the page allocation +routine specified to +.Fn pool_init , +or provided to .Fn pool_prime -preallocated by the calling function. +by the caller through the +.Fa storage +parameter. .Pp .Fn pool_prime .Bl -tag -offset indent -width "nitems" @@ -258,19 +247,15 @@ preallocated by the calling function. 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 . +.It Fa storage +Optional pre-allocated storage. +.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. -.El .Ss SETTING POOL RESOURCE WATERMARKS A pool will attempt to increase its resource usage to keep up with the demand for its items. @@ -279,7 +264,7 @@ 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. +.Sy watermarks . The functions .Fn pool_sethiwat and -- cgit v1.2.3