1.\" $NetBSD: pool.9,v 1.21 2002/02/13 08:18:49 ross 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.\".Nm POOL_STORAGE_SIZE 49.Nd resource-pool manager 50.Sh SYNOPSIS 51.Fd #include \*[Lt]sys/pool.h\*[Gt] 52.Ft void 53.Fo pool_init 54.Fa "struct pool *" 55.Fa "size_t size" 56.Fa "u_int align" 57.Fa "u_int align_offset" 58.Fa "int nitems" 59.Fa "char *wchan" 60.Fa "u_int pagesz" 61.Fa "void *(*palloc)(unsigned long sz, int flags, int tag)" 62.Fa "void (*prelease)(void *v, unsigned long sz, int tag)" 63.Fa "int mtag" 64.Fc 65.Ft void 66.Fn pool_destroy "struct pool *pp" 67.Ft void * 68.Fn pool_get "struct pool *pp" "int flags" 69.Ft void 70.Fn pool_put "struct pool *pp" "void *item" 71.Ft int 72.Fn pool_prime "struct pool *pp" "int nitems" "caddr_t storage" 73.Ft void 74.Fn pool_sethiwat "struct pool *pp" "int n" 75.Ft void 76.Fn pool_setlowat "struct pool *pp" "int n" 77.Fn POOL_STORAGE_SIZE "size" "nitems" 78.Sh DESCRIPTION 79These utility routines provide management of pools of fixed-sized 80areas of memory. 81Resource pools set aside an amount of memory for exclusive use by the resource 82pool owner. 83This can be used by applications to guarantee the availability of a minimum 84amount of memory needed to continue operation independent of the memory 85resources currently available from the system-wide memory allocator 86.Pq Xr malloc 9 . 87The pool manager can optionally obtain temporary memory by calling the 88.Fn palloc 89function passed to 90.Fn pool_init , 91for extra pool items in case the number of allocations exceeds 92the nominal number of pool items managed by a pool resource. 93This temporary memory will be automatically returned to the system 94at a later time. 95.Ss INITIALIZING A POOL 96The function 97.Fn pool_init 98initializes a resource pool. 99The arguments are: 100.Pp 101.Bl -tag -offset indent -width "prelease" 102.It Fa pp 103The handle identifying the pool resource instance. 104.It Fa size 105Specifies the size of the memory items managed by the pool. 106.It Fa align 107Specifies the memory address alignment of the items returned by 108.Fn pool_get . 109This argument must be a power of two. 110If zero, 111the alignment defaults to a architecture-specific natural alignment. 112.It Fa align_offset 113The offset within an item to which the 114.Fa align 115parameter applies. 116.It Fa nitems 117Specifies the number of memory items that are allocated to 118the pool at creation time. 119This number may be zero, 120in which case 121.Fn pool_prime 122can be used at a later time to add permanent items to the pool. 123.It Fa wchan 124The 125.Sq wait channel 126passed on to 127.Xr tsleep 9 128if 129.Fn pool_get 130must wait for items to be returned to the pool. 131.It Fa pagesz 132The unit which is used to allocate additional memory to the pool. 133It must be a power of two. 134.It Fa palloc 135is called to add additional memory if the pool is depleted. 136It must return 137.Fa pagesz 138aligned memory. 139The argument 140.Fa sz 141shall be a multiple of 142.Fa pagesz . 143.It Fa prelease 144is called to release pages back to the system. 145.Fn palloc 146and 147.Fn prelease 148may be 149.Dv NULL , 150in which case the pool manager uses 151.Xr uvm_km_kmemalloc 9 152and 153.Xr uvm_km_free 9 154to allocate and release memory using the 155.Em kernel_map 156.Po 157see 158.Xr uvm 9 159.Pc . 160.It Fa mtag 161The memory tag passed to 162.Fn palloc 163and 164.Fn prelease 165when allocating or releasing memory pages. 166.El 167.Pp 168.\"The macro 169.\".Fn POOL_STORAGE_SIZE "size" "nitems" 170.\"can be used to determine the amount of storage needed to setup a pool, 171.\"given the size and number of the pool items. 172.Ss DESTROYING A POOL 173The function 174.Fn pool_destroy 175destroys a resource pool. It takes a single argument 176.Fa pp 177identifying the pool resource instance. 178.Ss ALLOCATING ITEMS FROM A POOL 179.Fn pool_get 180allocates an item from the pool and returns a pointer to it. 181The arguments are: 182.Bl -tag -offset indent -width "flags" 183.It Fa pp 184The handle identifying the pool resource instance. 185.It Fa flags 186One or more of of 187.Dv PR_URGENT , 188.Dv PR_WAITOK 189or 190.Dv PR_LIMITFAIL , 191that define behaviour in case the pooled resources are depleted. 192If no resources are available and 193.Dv PR_WAITOK 194is given, 195this function will wait until items are returned to the pool. 196Otherwise 197.Fn pool_get 198returns 199.Dv NULL . 200If 201.Dv PR_URGENT 202is specified and no items are available and 203.Fn palloc 204cannot allocate a new page, 205the system will panic 206.Pq XXX . 207.\"Undefined behaviour results if 208.\".Dv PR_MALLOCOK 209.\"is specified on a pool handle that was created using client-provided 210.\"storage. 211.\" a bunch of other flags aren't documented. 212If both 213.Dv PR_LIMITFAIL 214and 215.Dv PR_WAITOK 216is specified, and the pool has reached its hard limit, 217.Fn pool_get 218will return 219.Dv NULL 220without waiting, allowing the caller to do its own garbage collection; 221however, it will still wait if the pool is not yet at its hard limit. 222.El 223.Ss RETURNING ITEMS TO A POOL 224.Fn pool_put 225returns the pool item pointed at by 226.Fa item 227to the resource pool identified by the pool handle 228.Fa pp . 229If the number of available items in the pool exceeds the maximum pool 230size set by 231.Fn pool_sethiwat 232and there are no outstanding requests for pool items, 233the excess items will be returned to the system by calling 234.Fn prelease . 235The arguments to 236.Fn pool_put 237are: 238.Bl -tag -offset indent -width "item" 239.It Fa pp 240The handle identifying the pool resource instance. 241.It Fa item 242A pointer to a pool item previously obtained by 243.Fn pool_get . 244.El 245.Ss PRIMING A POOL 246.Fn pool_prime 247adds items to the pool. 248Storage space for the items is either allocated by using the page allocation 249routine specified to 250.Fn pool_create , 251or provided to 252.Fn pool_prime 253by the caller through the 254.Fa storage 255parameter. 256.Pp 257The arguments to 258.Fn pool_prime 259are: 260.Bl -tag -offset indent -width "nitems" 261.It Fa pp 262The handle identifying the pool resource instance. 263.It Fa nitems 264The number of items to add to the pool. 265.It Fa storage 266Optional pre-allocated storage. 267.El 268.Pp 269This function may return 270.Dv ENOMEM 271in case the requested number of items could not be allocated. 272Otherwise, 273the return value is 0. 274.Ss SETTING POOL RESOURCE WATERMARKS 275A pool will attempt to increase its resource usage to keep up with the demand 276for its items. 277Conversely, 278it will return unused memory to the system should the number of accumulated 279unused items in the pool exceed a programmable limit. 280The limits for the minimum and maximum number of items which a pool should keep 281at hand are known as the high and low 282.Sy watermarks . 283The functions 284.Fn pool_sethiwat 285and 286.Fn pool_setlowat 287set a pool's high and low watermarks, respectively. 288.Pp 289.Fn pool_sethiwat 290.Bl -tag -offset indent -width "flags" 291.It Fa pp 292The handle identifying the pool resource instance. 293.It Fa n 294The maximum number of items to keep in the pool. 295As items are returned and the total number of pages in the pool is larger 296than the maximum set by this function, 297any completely unused pages are released immediately 298.Pq by calling Fn prelease . 299If this function is not used to specify a maximum number of items, 300the pages will remain associated with the pool until the system runs low 301on memory, 302at which point the VM system will try to reclaim unused pages. 303.El 304.Pp 305.Fn pool_setlowat 306.Bl -tag -offset indent -width "flags" 307.It Fa pp 308The handle identifying the pool resource instance. 309.It Fa n 310The minimum number of items to keep in the pool. 311The number pages in the pool will not decrease below the required value to 312accommodate the minimum number of items specified by this function. 313Unlike 314.Fn pool_prime , 315this function does not allocate the necessary memory up-front. 316.El 317.Ss POTENTIAL PITFALLS 318Note that undefined behaviour results when mixing the storage providing 319methods supported by the pool resource routines. 320.Pp 321The pool resource code uses a per-pool lock to protect its internal state. 322If any pool functions are called in an interrupt context, 323the caller must block all interrupts that might cause the 324code to be reentered. 325.Ss DIAGNOSTICS 326Pool usage logs can be enabled by defining the compile-time option 327.Dv POOL_DIAGNOSTIC . 328.\" .Sh RETURN VALUES 329.\" .Sh EXAMPLES 330.Sh CODE REFERENCES 331The pool manager is implemented in the file 332.Pa sys/kern/subr_pool.c . 333.\" .Sh AUTHOR 334.Sh SEE ALSO 335.Xr free 9 , 336.Xr malloc 9 , 337.Xr uvm 9 338.Sh HISTORY 339The 340.Nx 341pool manager appeared in 342.Nx 1.4 . 343