1.\" $OpenBSD: pool.9,v 1.54 2016/09/15 06:11:14 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.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: September 15 2016 $ 32.Dt POOL_INIT 9 33.Os 34.Sh NAME 35.Nm pool_init , 36.Nm pool_destroy , 37.Nm pool_get , 38.Nm pool_put , 39.Nm pool_prime , 40.Nm pool_sethiwat , 41.Nm pool_setlowat , 42.Nm pool_sethardlimit 43.Nd resource-pool manager 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/pool.h 47.Ft void 48.Fo pool_init 49.Fa "struct pool *pool" 50.Fa "size_t size" 51.Fa "u_int align" 52.Fa "int ipl" 53.Fa "int flags" 54.Fa "const char *wmesg" 55.Fa "struct pool_allocator *palloc" 56.Fc 57.Ft void 58.Fo pool_destroy 59.Fa "struct pool *pp" 60.Fc 61.Ft void * 62.Fn pool_get "struct pool *pp" "int flags" 63.Ft void 64.Fn pool_put "struct pool *pp" "void *item" 65.Ft int 66.Fn pool_prime "struct pool *pp" "int nitems" 67.Ft void 68.Fn pool_sethiwat "struct pool *pp" "int n" 69.Ft void 70.Fn pool_setlowat "struct pool *pp" "int n" 71.Ft int 72.Fo pool_sethardlimit 73.Fa "struct pool *pp" 74.Fa "unsigned n" 75.Fa "const char *warnmess" 76.Fa "int ratecap" 77.Fc 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 obtains memory by using the special-purpose memory 88allocator 89.Fa palloc 90passed to 91.Fn pool_init , 92for extra pool items in case the number of allocations exceeds 93the nominal number of pool items managed by a pool resource. 94This temporary memory will be automatically returned to the system 95at a later time. 96.Ss CREATING A POOL 97The function 98.Fn pool_init 99initializes a resource pool. 100The arguments are: 101.Bl -tag -offset indent -width "align_offset" 102.It Fa pool 103Specifies the pool storage to be initialized. 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 an architecture-specific natural alignment. 112.It Fa ipl 113The interrupt protection level used to protect the pool's internals, 114and at what level the pool can be safely used. 115See 116.Xr spl 9 117for a list of the IPLs. 118.It Fa flags 119Specifies various flags set on the pool at creation time. 120.It Fa wmesg 121The message passed on to 122.Xr tsleep 9 123if 124.Fn pool_get 125must wait for items to be returned to the pool. 126.It Fa palloc 127The back-end allocator used to manage the memory for the pool. 128.Fa palloc 129may be 130.Dv NULL , 131in which case the pool manager chooses an appropriate back-end allocator. 132If the 133.Dv PR_WAITOK 134flag has been specified, this allocator may not be interrupt safe. 135It is recommended to specify this flag if the pool will never be 136accessed in interrupt context. 137.El 138.Ss DESTROYING A POOL 139The 140.Fn pool_destroy 141function destroys 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. 148.Bl -tag -offset indent -width "flags" 149.It Fa pp 150The handle identifying the pool resource instance. 151.It Fa flags 152One or more flags. 153Either 154.Dv PR_WAITOK 155or 156.Dv PR_NOWAIT 157must be specified 158to define behaviour in case the pooled resources are depleted. 159If no resources are available and 160.Dv PR_NOWAIT 161was specified, 162this function returns 163.Dv NULL . 164If 165.Dv PR_WAITOK 166was specified 167but 168.Dv PR_LIMITFAIL 169was not, 170.Fn pool_get 171will wait until items are returned to the pool. 172If both 173.Dv PR_WAITOK 174and 175.Dv PR_LIMITFAIL 176were specified, and the pool has reached its hard limit, 177.Fn pool_get 178will return 179.Dv NULL 180without waiting, allowing the caller to do its own garbage collection; 181however, it will still wait if the pool is not yet at its hard limit. 182If 183.Dv PR_ZERO 184was specified and an item has been successfully allocated, it is zeroed before 185being returned to the caller. 186.El 187.Ss RETURNING ITEMS TO A POOL 188.Fn pool_put 189returns the pool item pointed at by 190.Fa item 191to the resource pool identified by the pool handle 192.Fa pp . 193If the number of available items in the pool exceeds the maximum pool 194size set by 195.Fn pool_sethiwat 196and there are no outstanding requests for pool items, 197the excess items will be returned to the system if possible. 198.Bl -tag -offset indent -width "item" 199.It Fa pp 200The handle identifying the pool resource instance. 201.It Fa item 202A pointer to a pool item previously obtained by 203.Fn pool_get . 204.El 205.Pp 206If a non-interrupt safe allocator has been selected by passing the 207.Dv PR_WAITOK 208flag to 209.Fn pmap_init , 210.Fn pool_put 211may sleep when completely unused pages are released. 212.Ss PRIMING A POOL 213.Fn pool_prime 214adds items to the pool. 215Storage space for the items is allocated by using the page allocation 216routine specified to 217.Fn pool_init . 218.Pp 219.Fn pool_prime 220.Bl -tag -offset indent -width "nitems" 221.It Fa pp 222The handle identifying the pool resource instance. 223.It Fa nitems 224The number of items to add to the pool. 225.El 226.Ss SETTING POOL RESOURCE WATERMARKS 227A pool will attempt to increase its resource usage to keep up with the demand 228for its items. 229Conversely, 230it will return unused memory to the system should the number of accumulated 231unused items in the pool exceed a programmable limit. 232The limits for the minimum and maximum number of items which a pool should keep 233at hand are known as the high and low 234.Sy watermarks . 235The functions 236.Fn pool_sethiwat 237and 238.Fn pool_setlowat 239set a pool's high and low watermarks, respectively. 240.Pp 241.Fn pool_sethiwat 242.Bl -tag -offset indent -width "flags" 243.It Fa pp 244The handle identifying the pool resource instance. 245.It Fa n 246The maximum number of items to keep in the pool. 247As items are returned and the total number of pages in the pool is larger 248than the maximum set by this function, 249any completely unused pages are released immediately. 250If this function is not used to specify a maximum number of items, 251the pages will remain associated with the pool until the system runs low 252on memory, 253at which point the VM system will try to reclaim unused pages. 254.El 255.Pp 256.Fn pool_setlowat 257.Bl -tag -offset indent -width "flags" 258.It Fa pp 259The handle identifying the pool resource instance. 260.It Fa n 261The minimum number of items to keep in the pool. 262The number of pages in the pool will not decrease below the required value to 263accommodate the minimum number of items specified by this function. 264Unlike 265.Fn pool_prime , 266this function does not allocate the necessary memory up-front. 267.El 268.Ss SETTING HARD LIMITS 269The function 270.Fn pool_sethardlimit 271sets a hard limit on the pool to 272.Fa n 273items. 274If the hard limit is reached 275.Fa warnmess 276will be printed to the console, but no more than every 277.Fa ratecap 278seconds. 279Upon successful completion, a value of 0 is returned. 280The value EINVAL is returned when the current size of the pool 281already exceeds the requested hard limit. 282.Ss POTENTIAL PITFALLS 283Note that undefined behaviour results when mixing the storage providing 284methods supported by the pool resource routines. 285.Pp 286The pool resource code uses a per-pool lock to protect its internal state. 287If any pool functions are called in an interrupt context, 288the caller must block all interrupts that might cause the 289code to be reentered. 290.Sh CONTEXT 291.Fn pool_init , 292.Fn pool_destroy , 293.Fn pool_prime , 294.Fn pool_sethiwat , 295.Fn pool_setlowat , 296and 297.Fn pool_sethardlimit 298can be called during autoconf or from process context. 299.Pp 300.Fn pool_get 301and 302.Fn pool_put 303can be called during autoconf or from process context. 304If the pool has been initialised with an interrupt safe pool allocator 305they can also be called from interrupt context at or below the 306interrupt level specified by a call to 307.Fn pool_init . 308.Sh RETURN VALUES 309.Fn pool_get 310will return a pointer to an item allocated from the pool. 311If 312.Dv PR_NOWAIT 313or 314.Dv PR_LIMITFAIL 315were passed as flags to the pool it may return 316.Dv NULL 317if there are no resources available or if the pool hard limit has been reached, 318respectively. 319.Pp 320.Fn pool_prime 321will return 322.Dv ENOMEM 323if the requested number of items could not be allocated. 324Otherwise, the return value is 0. 325.Pp 326.Fn pool_sethardlimit 327will return 328.Dv EINVAL 329if the current size of the pool exceeds the requested hard limit. 330Otherwise, the return value is 0. 331.Sh CODE REFERENCES 332The pool manager is implemented in the file 333.Pa sys/kern/subr_pool.c . 334.Sh SEE ALSO 335.Xr free 9 , 336.Xr malloc 9 , 337.Xr spl 9 , 338.Xr uvm 9 339.Sh HISTORY 340The pool manager first appeared in 341.Nx 1.4 342and was ported to 343.Ox 344by 345.An Artur Grabowski Aq Mt art@openbsd.org . 346