diff options
Diffstat (limited to 'static/netbsd/man9/pool.9')
| -rw-r--r-- | static/netbsd/man9/pool.9 | 322 |
1 files changed, 322 insertions, 0 deletions
diff --git a/static/netbsd/man9/pool.9 b/static/netbsd/man9/pool.9 new file mode 100644 index 00000000..7572c3e7 --- /dev/null +++ b/static/netbsd/man9/pool.9 @@ -0,0 +1,322 @@ +.\" $NetBSD: pool.9,v 1.50 2021/12/22 17:28:17 thorpej Exp $ +.\" +.\" Copyright (c) 1997, 1998, 2007 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. +.\" +.\" 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 April 12, 2020 +.Dt POOL 9 +.Os +.Sh NAME +.Nm pool_init , +.Nm pool_destroy , +.Nm pool_get , +.Nm pool_put , +.Nm pool_prime , +.Nm pool_sethiwat , +.Nm pool_setlowat , +.Nm pool_sethardlimit +.Nd resource-pool manager +.Sh SYNOPSIS +.In sys/pool.h +.Ft void +.Fo pool_init +.Fa "struct pool *pp" +.Fa "size_t size" +.Fa "u_int align" +.Fa "u_int align_offset" +.Fa "int flags" +.Fa "const char *wchan" +.Fa "struct pool_allocator *palloc" +.Fa "int ipl" +.Fc +.Ft void +.Fn pool_destroy "struct pool *pp" +.Ft void * +.Fn pool_get "struct pool *pp" "int flags" +.Ft void +.Fn pool_put "struct pool *pp" "void *item" +.Ft void +.Fn pool_prime "struct pool *pp" "int n" +.Ft void +.Fn pool_sethiwat "struct pool *pp" "int n" +.Ft void +.Fn pool_setlowat "struct pool *pp" "int n" +.Ft void +.Fn pool_sethardlimit "struct pool *pp" "int n" \ +"const char *warnmess" "int ratecap" +.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 . +.Ss INITIALIZING A POOL +The function +.Fn pool_init +initializes a resource pool. +The arguments are: +.Bl -tag -offset indent -width "align_offset" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa size +Specifies the size of the memory items managed by the pool. +.It Fa align +Specifies the memory address alignment of the items returned by +.Fn pool_get . +This argument must be a power of two. +If zero, +the alignment defaults to an architecture-specific natural alignment. +.It Fa align_offset +The offset within an item to which the +.Fa align +parameter applies. +.It Fa flags +Should be set to zero, +.Dv PR_NOTOUCH , +or +.Dv PR_PSERIALIZE . +If +.Dv PR_NOTOUCH +is given, free items are never used to keep internal state so that +the pool can be used for non memory backed objects. +If +.Dv PR_PSERIALIZE +is given, then the allocator guarantees that a passive serialization +barrier equivalent to +.Dq xc_barrier(0) +will be performed before the object's backing store is returned to +the system. +.Dv PR_PSERIALIZE +implies +.Dv PR_NOTOUCH . +Because of the guarantees provided by +.Dv PR_PSERIALIZE , +objects muste never be freed to a pool using this option from either +hard or soft interrupt context, as doing so may block. +.It Fa wchan +The +.Sq wait channel +passed on to +.Xr cv_wait 9 +if +.Fn pool_get +must wait for items to be returned to the pool. +.It Fa palloc +Can be set to +.Dv NULL +or +.Dv pool_allocator_kmem , +in which case the default kernel memory allocator will be used. +It can also be set to +.Dv pool_allocator_nointr +when the pool will never be accessed from interrupt context. +.It Fa ipl +Specifies an interrupt priority level that will block all interrupt +handlers that could potentially access the pool. +.El +.Ss DESTROYING A POOL +The function +.Fn pool_destroy +destroys a resource pool. +It takes a single argument +.Fa pp +identifying the pool resource instance. +.Ss ALLOCATING ITEMS FROM A POOL +.Fn pool_get +allocates an item from the pool and returns a pointer to it. +The arguments are: +.Bl -tag -offset indent -width "flags" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa flags +The flags can be used to define behaviour in case the pooled resources +are depleted. +If no resources are available and +.Dv PR_NOWAIT +is given, +.Fn pool_get +returns +.Dv NULL . +If +.Dv PR_WAITOK +is given and allocation is attempted with no resources available, +the function will sleep until items are returned to the pool. +.\"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 +are 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. +If the +.Dv PR_ZERO +flag is specified, then the memory returned will be zeroed first using +.Xr memset 3 . +.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. +The arguments to +.Fn pool_put +are: +.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 SETTING POOL RESOURCE WATERMARKS AND LIMITS +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. +.Pp +The targets for the minimum and maximum number of free items which a pool should +try to keep available 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 +The limits for the minimum and maximum number of total items (both free and +allocated) that the pool can have at any time are specified by the functions +.Fn pool_prime +and +.Fn pool_sethardlimit , +respectively. +The defaults for these limits are +.Dv 0 +and +.Dv UINT_MAX , +respectively. +Changing these limits will cause memory to be immediately allocated to the pool +or freed from the pool as needed. +.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 free items to keep in the pool. +As items are returned and the total number of free items in the pool is larger +than the maximum set by this function, +any completely unused pages are released immediately. +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 free items to keep in the pool. +When the number of free items in the pool drops below this threshold, +a non-blocking attempt is made to allocate memory for more items. +The number of free items is not guaranteed to remain above this threshold. +.El +.Pp +.Fn pool_sethardlimit +.Bl -tag -offset indent -width "flags" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa n +The maximum number of total items in the pool (i.e. the hard limit). +.It Fa warnmess +The warning message that will be logged when the hard limit is reached. +.It Fa ratecap +The minimal interval (in seconds) after which another warning message +is issued when the pool hits its hard limit again. +.El +.Pp +.Fn pool_prime +.Bl -tag -offset indent -width "storage" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa n +The minimum number of total items for the pool. +If the current number of total items is less than the new minimum then new items +are allocated with blocking allocations. +.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. +Additionally, the functions +.Fn pool_init +and +.Fn pool_destroy +should never be called in interrupt context. +.Ss DIAGNOSTICS +Pool usage logs can be enabled by defining the compile-time option +.Dv POOL_DIAGNOSTIC . +.\" .Sh RETURN VALUES +.\" .Sh EXAMPLES +.Sh CODE REFERENCES +The pool manager is implemented in the file +.Pa sys/kern/subr_pool.c . +.\" .Sh AUTHOR +.Sh SEE ALSO +.Xr free 9 , +.Xr malloc 9 , +.Xr memoryallocators 9 , +.Xr pool_cache 9 , +.Xr uvm 9 +.Sh HISTORY +The +.Nx +pool manager appeared in +.Nx 1.4 . |