1.\" $OpenBSD: pool.9,v 1.24 2003/06/06 20:56:32 jmc Exp $ 2.\" $NetBSD: pool.9,v 1.18 2001/06/21 11:59:01 wiz Exp $ 3.\" 4.\" Copyright (c) 1997, 1998 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Paul Kranenburg. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd July 23, 1998 39.Dt POOL 9 40.Os 41.Sh NAME 42.Nm pool_init , 43.Nm pool_destroy , 44.Nm pool_get , 45.Nm pool_put , 46.Nm pool_prime , 47.Nm pool_sethiwat , 48.Nm pool_setlowat 49.Nd resource-pool manager 50.Sh SYNOPSIS 51.Fd #include <sys/pool.h> 52.Ft void 53.Fo pool_init 54.Fa "struct pool *pool" 55.Fa "size_t size" 56.Fa "u_int align" 57.Fa "u_int align_offset" 58.Fa "int flags" 59.Fa "char *wmesg" 60.Fa "struct pool_allocator *palloc" 61.Fc 62.Ft void 63.Fo pool_destroy 64.Fa "struct pool *pp" 65.Fc 66.Ft void 67.Fo pool_set_drain_hook 68.Fa "struct pool *pp" 69.Fa "void (*fun)(void *, int)" 70.Fa "void *arg" 71.Fc 72.Ft void * 73.Fn pool_get "struct pool *pp" "int flags" 74.Ft void 75.Fn pool_put "struct pool *pp" "void *item" 76.Ft int 77.Fn pool_prime "struct pool *pp" "int nitems" "caddr_t storage" 78.Ft void 79.Fn pool_sethiwat "struct pool *pp" "int n" 80.Ft void 81.Fn pool_setlowat "struct pool *pp" "int n" 82.Ft int 83.Fo pool_sethardlimit 84.Fa "struct pool *pp" 85.Fa "int n" 86.Fa "const char *warnmess" 87.Fa "int ratecap" 88.Fc 89.Sh DESCRIPTION 90These utility routines provide management of pools of fixed-sized 91areas of memory. 92Resource pools set aside an amount of memory for exclusive use by the resource 93pool owner. 94This can be used by applications to guarantee the availability of a minimum 95amount of memory needed to continue operation independent of the memory 96resources currently available from the system-wide memory allocator 97.Pq Xr malloc 9 . 98The pool manager obtains memory by using the special-purpose memory 99allocator 100.Fn palloc 101passed to 102.Fn pool_init , 103for extra pool items in case the number of allocations exceeds 104the nominal number of pool items managed by a pool resource. 105This temporary memory will be automatically returned to the system 106at a later time. 107.Ss CREATING A POOL 108The function 109.Fn pool_init 110initializes a resource pool. 111The arguments are: 112.Pp 113.Bl -tag -offset indent -width "align_offset" 114.It Fa pool 115Specifies the pool storage to be initialized. 116.It Fa size 117Specifies the size of the memory items managed by the pool. 118.It Fa align 119Specifies the memory address alignment of the items returned by 120.Fn pool_get . 121This argument must be a power of two. 122If zero, 123the alignment defaults to an architecture-specific natural alignment. 124.It Fa align_offset 125The offset within an item to which the 126.Fa align 127parameter applies. 128.It Fa flags 129Specifies various flags set on the pool at creation time. 130.It Fa wmesg 131The message passed on to 132.Xr tsleep 9 133if 134.Fn pool_get 135must wait for items to be returned to the pool. 136.It Fa palloc 137The back-end allocator used to manage the memory for the pool. 138.Fn palloc 139may be 140.Dv NULL , 141in which case the pool manager uses the 142.Em pool_allocator_kmem 143allocator which uses 144.Xr uvm_km_kmemalloc 9 145and 146.Xr uvm_km_free 9 147to allocate and release memory using the 148.Em kmem_map 149.Po 150see 151.Xr uvm 9 152.Pc . 153It is recommended to set this to 154.Em pool_allocator_nointr 155if the pool will never be accessed in interrupt context, since that 156allocator is much more efficient. 157.El 158.Ss DESTROYING A POOL 159The 160.Fn pool_destroy 161function destroys a resource pool. 162It takes a single argument 163.Fa pp 164identifying the pool resource instance. 165.Ss SETTING DRAIN CALLBACK 166The 167.Fn pool_set_drain_hook 168function can be used to specify a function that will be called when 169memory is running low. 170The callback 171.Fa fun 172will be called with the arguments 173.Fa arg 174which is the third argument to 175.Fn pool_set_drain_hook 176and 177.Fa flags 178which will have 179.Dv PR_WAITOK 180set if the drain hook is allowed to sleep. 181.Ss ALLOCATING ITEMS FROM A POOL 182.Fn pool_get 183allocates an item from the pool and returns a pointer to it. 184.Bl -tag -offset indent -width "flags" 185.It Fa pp 186The handle identifying the pool resource instance. 187.It Fa flags 188One or more of 189.Dv PR_URGENT , 190.Dv PR_WAITOK 191or 192.Dv PR_LIMITFAIL , 193that define behaviour in case the pooled resources are depleted. 194If no resources are available and 195.Dv PR_WAITOK 196is given, 197this function will wait until items are returned to the pool. 198Otherwise 199.Fn pool_get 200returns 201.Dv NULL . 202If 203.Dv PR_URGENT 204is specified and no items are available and 205.Fn palloc 206cannot allocate a new page, 207the system will panic 208.Pq XXX . 209.\"Undefined behaviour results if 210.\".Dv PR_MALLOCOK 211.\"is specified on a pool handle that was created using client-provided 212.\"storage. 213.\" a bunch of other flags aren't documented. 214If both 215.Dv PR_LIMITFAIL 216and 217.Dv PR_WAITOK 218are specified, and the pool has reached its hard limit, 219.Fn pool_get 220will return 221.Dv NULL 222without waiting, allowing the caller to do its own garbage collection; 223however, it will still wait if the pool is not yet at its hard limit. 224.El 225.Ss RETURNING ITEMS TO A POOL 226.Fn pool_put 227returns the pool item pointed at by 228.Fa item 229to the resource pool identified by the pool handle 230.Fa pp . 231If the number of available items in the pool exceeds the maximum pool 232size set by 233.Fn pool_sethiwat 234and there are no outstanding requests for pool items, 235the excess items will be returned to the system by calling 236.Fn prelease . 237.Bl -tag -offset indent -width "item" 238.It Fa pp 239The handle identifying the pool resource instance. 240.It Fa item 241A pointer to a pool item previously obtained by 242.Fn pool_get . 243.El 244.Ss PRIMING A POOL 245.Fn pool_prime 246adds items to the pool. 247Storage space for the items is either allocated by using the page allocation 248routine specified to 249.Fn pool_init , 250or provided to 251.Fn pool_prime 252by the caller through the 253.Fa storage 254parameter. 255.Pp 256.Fn pool_prime 257.Bl -tag -offset indent -width "nitems" 258.It Fa pp 259The handle identifying the pool resource instance. 260.It Fa nitems 261The number of items to add to the pool. 262.It Fa storage 263Optional pre-allocated storage. 264.El 265.Pp 266This function may return 267.Dv ENOMEM 268in case the requested number of items could not be allocated. 269Otherwise, 270the return value is 0. 271.Ss SETTING POOL RESOURCE WATERMARKS 272A pool will attempt to increase its resource usage to keep up with the demand 273for its items. 274Conversely, 275it will return unused memory to the system should the number of accumulated 276unused items in the pool exceed a programmable limit. 277The limits for the minimum and maximum number of items which a pool should keep 278at hand are known as the high and low 279.Sy watermarks . 280The functions 281.Fn pool_sethiwat 282and 283.Fn pool_setlowat 284set a pool's high and low watermarks, respectively. 285.Pp 286.Fn pool_sethiwat 287.Bl -tag -offset indent -width "flags" 288.It Fa pp 289The handle identifying the pool resource instance. 290.It Fa n 291The maximum number of items to keep in the pool. 292As items are returned and the total number of pages in the pool is larger 293than the maximum set by this function, 294any completely unused pages are released immediately 295.Pq by calling Fn prelease . 296If this function is not used to specify a maximum number of items, 297the pages will remain associated with the pool until the system runs low 298on memory, 299at which point the VM system will try to reclaim unused pages. 300.El 301.Pp 302.Fn pool_setlowat 303.Bl -tag -offset indent -width "flags" 304.It Fa pp 305The handle identifying the pool resource instance. 306.It Fa n 307The minimum number of items to keep in the pool. 308The number of pages in the pool will not decrease below the required value to 309accommodate the minimum number of items specified by this function. 310Unlike 311.Fn pool_prime , 312this function does not allocate the necessary memory up-front. 313.El 314.Ss SETTING HARD LIMITS 315The function 316.Fn pool_sethardlimit 317sets a hard limit on the pool to 318.Fa n 319items. 320If the hard limit is reached 321.Fa warnmess 322will be printed to the console, but no more than every 323.Fa ratecap 324seconds. 325Upon successful completion, a value of 0 is returned. 326The value EINVAL is returned when the current size of the pool 327already exceeds the requested hard limit. 328.Ss POTENTIAL PITFALLS 329Note that undefined behaviour results when mixing the storage providing 330methods supported by the pool resource routines. 331.Pp 332The pool resource code uses a per-pool lock to protect its internal state. 333If any pool functions are called in an interrupt context, 334the caller must block all interrupts that might cause the 335code to be reentered. 336.Ss DIAGNOSTICS 337Pool usage logs can be enabled by defining the compile-time option 338.Dv POOL_DIAGNOSTIC . 339.Ss DEBUGGING 340To debug a misbehaving pool, a kernel can be compiled with the 341.Dv MALLOC_DEBUG 342option and memory debugging on pools can be enabled with the 343.Dv PR_DEBUG 344flag passed in the 345.Fa flags 346argument in the call to 347.Fn pool_init . 348See 349.Xr malloc 9 350for more information about 351.Dv MALLOC_DEBUG . 352.Sh CODE REFERENCES 353The pool manager is implemented in the file 354.Pa sys/kern/subr_pool.c . 355.Sh SEE ALSO 356.Xr free 9 , 357.Xr malloc 9 , 358.Xr uvm 9 359.Sh HISTORY 360The pool manager first appeared in 361.Nx 1.4 362and was ported to 363.Ox 364by 365.An Artur Grabowski Aq art@openbsd.org . 366