1.\" $NetBSD: pool.9,v 1.36 2005/02/02 17:13:08 wiz Exp $ 2.\" 3.\" Copyright (c) 1997, 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd January 2, 2005 38.Dt POOL 9 39.Os 40.Sh NAME 41.Nm pool_init , 42.Nm pool_destroy , 43.Nm pool_get , 44.Nm pool_put , 45.Nm pool_prime , 46.Nm pool_sethiwat , 47.Nm pool_setlowat 48.Nd resource-pool manager 49.Sh SYNOPSIS 50.In sys/pool.h 51.Ft void 52.Fo pool_init 53.Fa "struct pool *pp" 54.Fa "size_t size" 55.Fa "u_int align" 56.Fa "u_int align_offset" 57.Fa "int flags" 58.Fa "char *wchan" 59.Fa "struct pool_allocator *palloc" 60.Fc 61.Ft void 62.Fn pool_destroy "struct pool *pp" 63.Ft void * 64.Fn pool_get "struct pool *pp" "int flags" 65.Ft void 66.Fn pool_put "struct pool *pp" "void *item" 67.Ft int 68.Fn pool_prime "struct pool *pp" "int nitems" "caddr_t storage" 69.Ft void 70.Fn pool_sethiwat "struct pool *pp" "int n" 71.Ft void 72.Fn pool_setlowat "struct pool *pp" "int n" 73.Sh DESCRIPTION 74These utility routines provide management of pools of fixed-sized 75areas of memory. 76Resource pools set aside an amount of memory for exclusive use by the resource 77pool owner. 78This can be used by applications to guarantee the availability of a minimum 79amount of memory needed to continue operation independent of the memory 80resources currently available from the system-wide memory allocator 81.Pq Xr malloc 9 . 82.Ss INITIALIZING A POOL 83The function 84.Fn pool_init 85initializes a resource pool. 86The arguments are: 87.Pp 88.Bl -tag -offset indent -width "align_offset" 89.It Fa pp 90The handle identifying the pool resource instance. 91.It Fa size 92Specifies the size of the memory items managed by the pool. 93.It Fa align 94Specifies the memory address alignment of the items returned by 95.Fn pool_get . 96This argument must be a power of two. 97If zero, 98the alignment defaults to an architecture-specific natural alignment. 99.It Fa align_offset 100The offset within an item to which the 101.Fa align 102parameter applies. 103.It Fa flags 104Should be set to zero or 105.Dv PR_NOTOUCH . 106If 107.Dv PR_NOTOUCH 108is given, free items are never used to keep internal state so that 109the pool can be used for non memory backed objects. 110.It Fa wchan 111The 112.Sq wait channel 113passed on to 114.Xr tsleep 9 115if 116.Fn pool_get 117must wait for items to be returned to the pool. 118.It Fa palloc 119can be set to 120.Dv NULL 121or 122.Dv pool_allocator_kmem , 123in which case the default kernel memory allocator will be used. 124It can also be set to 125.Dv pool_allocator_nointr 126when the pool will never be accessed from interrupt context. 127.El 128.Pp 129The 130.Fn POOL_INIT 131macro can be used to both declare and initialize a resource pool. 132The 133.Fn POOL_INIT 134macro has the same arguments as the 135.Fn pool_init 136function and the resource pool will be initialized automatically 137during system startup. 138.Ss DESTROYING A POOL 139The function 140.Fn pool_destroy 141destroys a resource pool. 142It takes a single argument 143.Fa pp 144identifying the pool resource instance. 145.Ss ALLOCATING ITEMS FROM A POOL 146.Fn pool_get 147allocates an item from the pool and returns a pointer to it. 148The arguments are: 149.Bl -tag -offset indent -width "flags" 150.It Fa pp 151The handle identifying the pool resource instance. 152.It Fa flags 153The flags can be used to define behaviour in case the pooled resources 154are depleted. 155If no resources are available and 156.Dv PR_NOWAIT 157is given, 158.Fn pool_get 159returns 160.Dv NULL . 161If 162.Dv PR_WAITOK 163is given and allocation is attempted with no resources available, 164the function will sleep until items are returned to the pool. 165.\"Undefined behaviour results if 166.\".Dv PR_MALLOCOK 167.\"is specified on a pool handle that was created using client-provided 168.\"storage. 169.\" a bunch of other flags aren't documented. 170If both 171.Dv PR_LIMITFAIL 172and 173.Dv PR_WAITOK 174are specified, and the pool has reached its hard limit, 175.Fn pool_get 176will return 177.Dv NULL 178without waiting, allowing the caller to do its own garbage collection; 179however, it will still wait if the pool is not yet at its hard limit. 180.El 181.Ss RETURNING ITEMS TO A POOL 182.Fn pool_put 183returns the pool item pointed at by 184.Fa item 185to the resource pool identified by the pool handle 186.Fa pp . 187If the number of available items in the pool exceeds the maximum pool 188size set by 189.Fn pool_sethiwat 190and there are no outstanding requests for pool items, 191the excess items will be returned to the system. 192The arguments to 193.Fn pool_put 194are: 195.Bl -tag -offset indent -width "item" 196.It Fa pp 197The handle identifying the pool resource instance. 198.It Fa item 199A pointer to a pool item previously obtained by 200.Fn pool_get . 201.El 202.Ss PRIMING A POOL 203.Fn pool_prime 204adds items to the pool. 205Storage space for the items is either allocated by using the page allocation 206routine specified to 207.Fn pool_create , 208or provided to 209.Fn pool_prime 210by the caller through the 211.Fa storage 212parameter. 213.Pp 214The arguments to 215.Fn pool_prime 216are: 217.Bl -tag -offset indent -width "storage" 218.It Fa pp 219The handle identifying the pool resource instance. 220.It Fa nitems 221The number of items to add to the pool. 222.It Fa storage 223Optional pre-allocated storage. 224.El 225.Pp 226This function may return 227.Dv ENOMEM 228in case the requested number of items could not be allocated. 229Otherwise, 230the return value is 0. 231.Ss SETTING POOL RESOURCE WATERMARKS 232A pool will attempt to increase its resource usage to keep up with the demand 233for its items. 234Conversely, 235it will return unused memory to the system should the number of accumulated 236unused items in the pool exceed a programmable limit. 237The limits for the minimum and maximum number of items which a pool should keep 238at hand are known as the high and low 239.Sy watermarks . 240The functions 241.Fn pool_sethiwat 242and 243.Fn pool_setlowat 244set a pool's high and low watermarks, respectively. 245.Pp 246.Fn pool_sethiwat 247.Bl -tag -offset indent -width "flags" 248.It Fa pp 249The handle identifying the pool resource instance. 250.It Fa n 251The maximum number of items to keep in the pool. 252As items are returned and the total number of pages in the pool is larger 253than the maximum set by this function, 254any completely unused pages are released immediately. 255If this function is not used to specify a maximum number of items, 256the pages will remain associated with the pool until the system runs low 257on memory, 258at which point the VM system will try to reclaim unused pages. 259.El 260.Pp 261.Fn pool_setlowat 262.Bl -tag -offset indent -width "flags" 263.It Fa pp 264The handle identifying the pool resource instance. 265.It Fa n 266The minimum number of items to keep in the pool. 267The number pages in the pool will not decrease below the required value to 268accommodate the minimum number of items specified by this function. 269Unlike 270.Fn pool_prime , 271this function does not allocate the necessary memory up-front. 272.El 273.Ss POTENTIAL PITFALLS 274Note that undefined behaviour results when mixing the storage providing 275methods supported by the pool resource routines. 276.Pp 277The pool resource code uses a per-pool lock to protect its internal state. 278If any pool functions are called in an interrupt context, 279the caller must block all interrupts that might cause the 280code to be reentered. 281Additionally, the functions 282.Fn pool_init 283and 284.Fn pool_destroy 285should never be called in interrupt context. 286.Ss DIAGNOSTICS 287Pool usage logs can be enabled by defining the compile-time option 288.Dv POOL_DIAGNOSTIC . 289.\" .Sh RETURN VALUES 290.\" .Sh EXAMPLES 291.Sh CODE REFERENCES 292The pool manager is implemented in the file 293.Pa sys/kern/subr_pool.c . 294.\" .Sh AUTHOR 295.Sh SEE ALSO 296.Xr free 9 , 297.Xr malloc 9 , 298.Xr uvm 9 299.Sh HISTORY 300The 301.Nx 302pool manager appeared in 303.Nx 1.4 . 304