1.\" $NetBSD: pool.9,v 1.26 2002/11/12 15:45:42 minoura 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 July 20, 2001 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.Fd #include \*[Lt]sys/pool.h\*[Gt] 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 nitems" 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 a 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 nitems 104Specifies the number of memory items that are allocated to 105the pool at creation time. 106This number may be zero, 107in which case 108.Fn pool_prime 109can be used at a later time to add permanent items to the pool. 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.Ss DESTROYING A POOL 129The function 130.Fn pool_destroy 131destroys a resource pool. 132It takes a single argument 133.Fa pp 134identifying the pool resource instance. 135.Ss ALLOCATING ITEMS FROM A POOL 136.Fn pool_get 137allocates an item from the pool and returns a pointer to it. 138The arguments are: 139.Bl -tag -offset indent -width "flags" 140.It Fa pp 141The handle identifying the pool resource instance. 142.It Fa flags 143One or more of 144.Dv PR_URGENT , 145.Dv PR_WAITOK 146or 147.Dv PR_LIMITFAIL , 148that define behaviour in case the pooled resources are depleted. 149If no resources are available and 150.Dv PR_WAITOK 151is given, 152this function will wait until items are returned to the pool. 153Otherwise 154.Fn pool_get 155returns 156.Dv NULL . 157If 158.Dv PR_URGENT 159is specified and no items are available and 160.Fn palloc 161cannot allocate a new page, 162the system will panic 163.Pq XXX . 164.\"Undefined behaviour results if 165.\".Dv PR_MALLOCOK 166.\"is specified on a pool handle that was created using client-provided 167.\"storage. 168.\" a bunch of other flags aren't documented. 169If both 170.Dv PR_LIMITFAIL 171and 172.Dv PR_WAITOK 173is specified, and the pool has reached its hard limit, 174.Fn pool_get 175will return 176.Dv NULL 177without waiting, allowing the caller to do its own garbage collection; 178however, it will still wait if the pool is not yet at its hard limit. 179.El 180.Ss RETURNING ITEMS TO A POOL 181.Fn pool_put 182returns the pool item pointed at by 183.Fa item 184to the resource pool identified by the pool handle 185.Fa pp . 186If the number of available items in the pool exceeds the maximum pool 187size set by 188.Fn pool_sethiwat 189and there are no outstanding requests for pool items, 190the excess items will be returned to the system. 191The arguments to 192.Fn pool_put 193are: 194.Bl -tag -offset indent -width "item" 195.It Fa pp 196The handle identifying the pool resource instance. 197.It Fa item 198A pointer to a pool item previously obtained by 199.Fn pool_get . 200.El 201.Ss PRIMING A POOL 202.Fn pool_prime 203adds items to the pool. 204Storage space for the items is either allocated by using the page allocation 205routine specified to 206.Fn pool_create , 207or provided to 208.Fn pool_prime 209by the caller through the 210.Fa storage 211parameter. 212.Pp 213The arguments to 214.Fn pool_prime 215are: 216.Bl -tag -offset indent -width "storage" 217.It Fa pp 218The handle identifying the pool resource instance. 219.It Fa nitems 220The number of items to add to the pool. 221.It Fa storage 222Optional pre-allocated storage. 223.El 224.Pp 225This function may return 226.Dv ENOMEM 227in case the requested number of items could not be allocated. 228Otherwise, 229the return value is 0. 230.Ss SETTING POOL RESOURCE WATERMARKS 231A pool will attempt to increase its resource usage to keep up with the demand 232for its items. 233Conversely, 234it will return unused memory to the system should the number of accumulated 235unused items in the pool exceed a programmable limit. 236The limits for the minimum and maximum number of items which a pool should keep 237at hand are known as the high and low 238.Sy watermarks . 239The functions 240.Fn pool_sethiwat 241and 242.Fn pool_setlowat 243set a pool's high and low watermarks, respectively. 244.Pp 245.Fn pool_sethiwat 246.Bl -tag -offset indent -width "flags" 247.It Fa pp 248The handle identifying the pool resource instance. 249.It Fa n 250The maximum number of items to keep in the pool. 251As items are returned and the total number of pages in the pool is larger 252than the maximum set by this function, 253any completely unused pages are released immediately. 254If this function is not used to specify a maximum number of items, 255the pages will remain associated with the pool until the system runs low 256on memory, 257at which point the VM system will try to reclaim unused pages. 258.El 259.Pp 260.Fn pool_setlowat 261.Bl -tag -offset indent -width "flags" 262.It Fa pp 263The handle identifying the pool resource instance. 264.It Fa n 265The minimum number of items to keep in the pool. 266The number pages in the pool will not decrease below the required value to 267accommodate the minimum number of items specified by this function. 268Unlike 269.Fn pool_prime , 270this function does not allocate the necessary memory up-front. 271.El 272.Ss POTENTIAL PITFALLS 273Note that undefined behaviour results when mixing the storage providing 274methods supported by the pool resource routines. 275.Pp 276The pool resource code uses a per-pool lock to protect its internal state. 277If any pool functions are called in an interrupt context, 278the caller must block all interrupts that might cause the 279code to be reentered. 280.Ss DIAGNOSTICS 281Pool usage logs can be enabled by defining the compile-time option 282.Dv POOL_DIAGNOSTIC . 283.\" .Sh RETURN VALUES 284.\" .Sh EXAMPLES 285.Sh CODE REFERENCES 286The pool manager is implemented in the file 287.Pa sys/kern/subr_pool.c . 288.\" .Sh AUTHOR 289.Sh SEE ALSO 290.Xr free 9 , 291.Xr malloc 9 , 292.Xr uvm 9 293.Sh HISTORY 294The 295.Nx 296pool manager appeared in 297.Nx 1.4 . 298