1.\" $OpenBSD: pool.9,v 1.52 2016/04/21 04:09:28 mlarkin 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: April 21 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_setipl , 41.Nm pool_sethiwat , 42.Nm pool_setlowat , 43.Nm pool_sethardlimit 44.Nd resource-pool manager 45.Sh SYNOPSIS 46.In sys/types.h 47.In sys/pool.h 48.Ft void 49.Fo pool_init 50.Fa "struct pool *pool" 51.Fa "size_t size" 52.Fa "u_int align" 53.Fa "u_int align_offset" 54.Fa "int flags" 55.Fa "const char *wmesg" 56.Fa "struct pool_allocator *palloc" 57.Fc 58.Ft void 59.Fo pool_destroy 60.Fa "struct pool *pp" 61.Fc 62.Ft void * 63.Fn pool_get "struct pool *pp" "int flags" 64.Ft void 65.Fn pool_put "struct pool *pp" "void *item" 66.Ft int 67.Fn pool_prime "struct pool *pp" "int nitems" 68.Ft void 69.Fn pool_setipl "struct pool *pp" "int ipl" 70.Ft void 71.Fn pool_sethiwat "struct pool *pp" "int n" 72.Ft void 73.Fn pool_setlowat "struct pool *pp" "int n" 74.Ft int 75.Fo pool_sethardlimit 76.Fa "struct pool *pp" 77.Fa "unsigned n" 78.Fa "const char *warnmess" 79.Fa "int ratecap" 80.Fc 81.Sh DESCRIPTION 82These utility routines provide management of pools of fixed-sized 83areas of memory. 84Resource pools set aside an amount of memory for exclusive use by the resource 85pool owner. 86This can be used by applications to guarantee the availability of a minimum 87amount of memory needed to continue operation independent of the memory 88resources currently available from the system-wide memory allocator 89.Pq Xr malloc 9 . 90The pool manager obtains memory by using the special-purpose memory 91allocator 92.Fa palloc 93passed to 94.Fn pool_init , 95for extra pool items in case the number of allocations exceeds 96the nominal number of pool items managed by a pool resource. 97This temporary memory will be automatically returned to the system 98at a later time. 99.Ss CREATING A POOL 100The function 101.Fn pool_init 102initializes a resource pool. 103The arguments are: 104.Bl -tag -offset indent -width "align_offset" 105.It Fa pool 106Specifies the pool storage to be initialized. 107.It Fa size 108Specifies the size of the memory items managed by the pool. 109.It Fa align 110Specifies the memory address alignment of the items returned by 111.Fn pool_get . 112This argument must be a power of two. 113If zero, 114the alignment defaults to an architecture-specific natural alignment. 115.It Fa align_offset 116The offset within an item to which the 117.Fa align 118parameter applies. 119.It Fa flags 120Specifies various flags set on the pool at creation time. 121.It Fa wmesg 122The message passed on to 123.Xr tsleep 9 124if 125.Fn pool_get 126must wait for items to be returned to the pool. 127.It Fa palloc 128The back-end allocator used to manage the memory for the pool. 129.Fa palloc 130may be 131.Dv NULL , 132in which case the pool manager chooses an appropriate back-end allocator. 133If the 134.Dv PR_WAITOK 135flag has been specified, this allocator may not be interrupt safe. 136It is recommended to specify this flag if the pool will never be 137accessed in interrupt context. 138.El 139.Ss DESTROYING A POOL 140The 141.Fn pool_destroy 142function destroys a resource pool. 143It takes a single argument 144.Fa pp 145identifying the pool resource instance. 146.Ss ALLOCATING ITEMS FROM A POOL 147.Fn pool_get 148allocates an item from the pool and returns a pointer to it. 149.Bl -tag -offset indent -width "flags" 150.It Fa pp 151The handle identifying the pool resource instance. 152.It Fa flags 153One or more flags. 154Either 155.Dv PR_WAITOK 156or 157.Dv PR_NOWAIT 158must be specified 159to define behaviour in case the pooled resources are depleted. 160If no resources are available and 161.Dv PR_NOWAIT 162was specified, 163this function returns 164.Dv NULL . 165If 166.Dv PR_WAITOK 167was specified 168but 169.Dv PR_LIMITFAIL 170was not, 171.Fn pool_get 172will wait until items are returned to the pool. 173If both 174.Dv PR_WAITOK 175and 176.Dv PR_LIMITFAIL 177were specified, and the pool has reached its hard limit, 178.Fn pool_get 179will return 180.Dv NULL 181without waiting, allowing the caller to do its own garbage collection; 182however, it will still wait if the pool is not yet at its hard limit. 183If 184.Dv PR_ZERO 185was specified and an item has been successfully allocated, it is zeroed before 186being returned to the caller. 187.El 188.Ss RETURNING ITEMS TO A POOL 189.Fn pool_put 190returns the pool item pointed at by 191.Fa item 192to the resource pool identified by the pool handle 193.Fa pp . 194If the number of available items in the pool exceeds the maximum pool 195size set by 196.Fn pool_sethiwat 197and there are no outstanding requests for pool items, 198the excess items will be returned to the system if possible. 199.Bl -tag -offset indent -width "item" 200.It Fa pp 201The handle identifying the pool resource instance. 202.It Fa item 203A pointer to a pool item previously obtained by 204.Fn pool_get . 205.El 206.Pp 207If a non-interrupt safe allocator has been selected by passing the 208.Dv PR_WAITOK 209flag to 210.Fn pmap_init , 211.Fn pool_put 212may sleep when completely unused pages are released. 213.Ss PRIMING A POOL 214.Fn pool_prime 215adds items to the pool. 216Storage space for the items is allocated by using the page allocation 217routine specified to 218.Fn pool_init . 219.Pp 220.Fn pool_prime 221.Bl -tag -offset indent -width "nitems" 222.It Fa pp 223The handle identifying the pool resource instance. 224.It Fa nitems 225The number of items to add to the pool. 226.El 227.Ss SETTING POOL RESOURCE WATERMARKS 228A pool will attempt to increase its resource usage to keep up with the demand 229for its items. 230Conversely, 231it will return unused memory to the system should the number of accumulated 232unused items in the pool exceed a programmable limit. 233The limits for the minimum and maximum number of items which a pool should keep 234at hand are known as the high and low 235.Sy watermarks . 236The functions 237.Fn pool_sethiwat 238and 239.Fn pool_setlowat 240set a pool's high and low watermarks, respectively. 241.Pp 242.Fn pool_sethiwat 243.Bl -tag -offset indent -width "flags" 244.It Fa pp 245The handle identifying the pool resource instance. 246.It Fa n 247The maximum number of items to keep in the pool. 248As items are returned and the total number of pages in the pool is larger 249than the maximum set by this function, 250any completely unused pages are released immediately. 251If this function is not used to specify a maximum number of items, 252the pages will remain associated with the pool until the system runs low 253on memory, 254at which point the VM system will try to reclaim unused pages. 255.El 256.Pp 257.Fn pool_setlowat 258.Bl -tag -offset indent -width "flags" 259.It Fa pp 260The handle identifying the pool resource instance. 261.It Fa n 262The minimum number of items to keep in the pool. 263The number of pages in the pool will not decrease below the required value to 264accommodate the minimum number of items specified by this function. 265Unlike 266.Fn pool_prime , 267this function does not allocate the necessary memory up-front. 268.El 269.Ss SETTING THE PROTECTION LEVEL 270The 271.Fn pool_setipl 272function is used to specify the interrupt protection level at which the pool 273can be safely used. 274.Pp 275.Fn pool_setipl 276.Bl -tag -offset indent -width "flags" 277.It Fa pp 278The handle identifying the pool resource instance. 279.It Fa ipl 280The interrupt protection level used to protect the pool's internals. 281See 282.Xr spl 9 283for a list of the IPLs. 284.El 285.Ss SETTING HARD LIMITS 286The function 287.Fn pool_sethardlimit 288sets a hard limit on the pool to 289.Fa n 290items. 291If the hard limit is reached 292.Fa warnmess 293will be printed to the console, but no more than every 294.Fa ratecap 295seconds. 296Upon successful completion, a value of 0 is returned. 297The value EINVAL is returned when the current size of the pool 298already exceeds the requested hard limit. 299.Ss POTENTIAL PITFALLS 300Note that undefined behaviour results when mixing the storage providing 301methods supported by the pool resource routines. 302.Pp 303The pool resource code uses a per-pool lock to protect its internal state. 304If any pool functions are called in an interrupt context, 305the caller must block all interrupts that might cause the 306code to be reentered. 307.Sh CONTEXT 308.Fn pool_init , 309.Fn pool_destroy , 310.Fn pool_prime , 311.Fn pool_setipl , 312.Fn pool_sethiwat , 313.Fn pool_setlowat , 314and 315.Fn pool_sethardlimit 316can be called during autoconf or from process context. 317.Pp 318.Fn pool_get 319and 320.Fn pool_put 321can be called during autoconf or from process context. 322If the pool has been initialised with an interrupt safe pool allocator 323they can also be called from interrupt context at or below the 324interrupt level specified by a call to 325.Fn pool_setipl . 326.Sh RETURN VALUES 327.Fn pool_get 328will return a pointer to an item allocated from the pool. 329If 330.Dv PR_NOWAIT 331or 332.Dv PR_LIMITFAIL 333were passed as flags to the pool it may return 334.Dv NULL 335if there are no resources available or if the pool hard limit has been reached, 336respectively. 337.Pp 338.Fn pool_prime 339will return 340.Dv ENOMEM 341if the requested number of items could not be allocated. 342Otherwise, the return value is 0. 343.Pp 344.Fn pool_sethardlimit 345will return 346.Dv EINVAL 347if the current size of the pool exceeds the requested hard limit. 348Otherwise, the return value is 0. 349.Sh CODE REFERENCES 350The pool manager is implemented in the file 351.Pa sys/kern/subr_pool.c . 352.Sh SEE ALSO 353.Xr free 9 , 354.Xr malloc 9 , 355.Xr spl 9 , 356.Xr uvm 9 357.Sh HISTORY 358The pool manager first appeared in 359.Nx 1.4 360and was ported to 361.Ox 362by 363.An Artur Grabowski Aq Mt art@openbsd.org . 364