1.\" $OpenBSD: pool.9,v 1.57 2019/12/06 19:15:16 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: December 6 2019 $ 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 119The bitwise OR of zero or more of the following values: 120.Pp 121.Bl -tag -width "PR_WAITOK" -offset indent -compact 122.It Dv PR_WAITOK 123The pool doesn't need to be interrupt safe. 124It is recommended to specify this flag if the pool will never be 125accessed in interrupt context. 126.It Dv PR_RWLOCK 127The pool will use an 128.Xr rwlock 9 129instead of a 130.Xr mutex 9 131for exclusion. 132Requires 133.Dv PR_WAITOK 134to be specified as well, both to 135.Fn pool_init 136and on all 137.Fn pool_get 138calls on this pool. 139.El 140.It Fa wmesg 141The message passed on to 142.Xr tsleep 9 143if 144.Fn pool_get 145must wait for items to be returned to the pool. 146.It Fa palloc 147The back-end allocator used to manage the memory for the pool. 148.Fa palloc 149may be 150.Dv NULL , 151in which case the pool manager chooses an appropriate back-end allocator. 152.El 153.Ss DESTROYING A POOL 154The 155.Fn pool_destroy 156function destroys a resource pool. 157It takes a single argument 158.Fa pp 159identifying the pool resource instance. 160.Ss ALLOCATING ITEMS FROM A POOL 161.Fn pool_get 162allocates an item from the pool and returns a pointer to it. 163.Bl -tag -offset indent -width "flags" 164.It Fa pp 165The handle identifying the pool resource instance. 166.It Fa flags 167One or more flags. 168Either 169.Dv PR_WAITOK 170or 171.Dv PR_NOWAIT 172must be specified 173to define behaviour in case the pooled resources are depleted. 174If no resources are available and 175.Dv PR_NOWAIT 176was specified, 177this function returns 178.Dv NULL . 179If 180.Dv PR_WAITOK 181was specified 182but 183.Dv PR_LIMITFAIL 184was not, 185.Fn pool_get 186will wait until items are returned to the pool. 187If both 188.Dv PR_WAITOK 189and 190.Dv PR_LIMITFAIL 191were specified, and the pool has reached its hard limit, 192.Fn pool_get 193will return 194.Dv NULL 195without waiting, allowing the caller to do its own garbage collection; 196however, it will still wait if the pool is not yet at its hard limit. 197If 198.Dv PR_ZERO 199was specified and an item has been successfully allocated, it is zeroed before 200being returned to the caller. 201.El 202.Ss RETURNING ITEMS TO A POOL 203.Fn pool_put 204returns the pool item pointed at by 205.Fa item 206to the resource pool identified by the pool handle 207.Fa pp . 208If the number of available items in the pool exceeds the maximum pool 209size set by 210.Fn pool_sethiwat 211and there are no outstanding requests for pool items, 212the excess items will be returned to the system if possible. 213.Bl -tag -offset indent -width "item" 214.It Fa pp 215The handle identifying the pool resource instance. 216.It Fa item 217A pointer to a pool item previously obtained by 218.Fn pool_get . 219.El 220.Pp 221If a non-interrupt safe allocator has been selected by passing the 222.Dv PR_WAITOK 223flag to 224.Fn pmap_init , 225.Fn pool_put 226may sleep when completely unused pages are released. 227.Ss PRIMING A POOL 228.Fn pool_prime 229adds items to the pool. 230Storage space for the items is allocated by using the page allocation 231routine specified to 232.Fn pool_init . 233.Pp 234.Fn pool_prime 235.Bl -tag -offset indent -width "nitems" 236.It Fa pp 237The handle identifying the pool resource instance. 238.It Fa nitems 239The number of items to add to the pool. 240.El 241.Ss SETTING POOL RESOURCE WATERMARKS 242A pool will attempt to increase its resource usage to keep up with the demand 243for its items. 244Conversely, 245it will return unused memory to the system should the number of accumulated 246unused items in the pool exceed a programmable limit. 247The limits for the minimum and maximum number of items which a pool should keep 248at hand are known as the high and low 249.Sy watermarks . 250The functions 251.Fn pool_sethiwat 252and 253.Fn pool_setlowat 254set a pool's high and low watermarks, respectively. 255.Pp 256.Fn pool_sethiwat 257.Bl -tag -offset indent -width "flags" 258.It Fa pp 259The handle identifying the pool resource instance. 260.It Fa n 261The maximum number of items to keep in the pool. 262As items are returned and the total number of pages in the pool is larger 263than the maximum set by this function, 264any completely unused pages are released immediately. 265If this function is not used to specify a maximum number of items, 266the pages will remain associated with the pool until the system runs low 267on memory, 268at which point the VM system will try to reclaim unused pages. 269.El 270.Pp 271.Fn pool_setlowat 272.Bl -tag -offset indent -width "flags" 273.It Fa pp 274The handle identifying the pool resource instance. 275.It Fa n 276The minimum number of items to keep in the pool. 277The number of pages in the pool will not decrease below the required value to 278accommodate the minimum number of items specified by this function. 279Unlike 280.Fn pool_prime , 281this function does not allocate the necessary memory up-front. 282.El 283.Ss SETTING HARD LIMITS 284The function 285.Fn pool_sethardlimit 286sets a hard limit on the pool to 287.Fa n 288items. 289If the hard limit is reached 290.Fa warnmess 291will be printed to the console, but no more than every 292.Fa ratecap 293seconds. 294Upon successful completion, a value of 0 is returned. 295The value EINVAL is returned when the current size of the pool 296already exceeds the requested hard limit. 297.Ss POTENTIAL PITFALLS 298Note that undefined behaviour results when mixing the storage providing 299methods supported by the pool resource routines. 300.Pp 301The pool resource code uses a per-pool lock to protect its internal state. 302If any pool functions are called in an interrupt context, 303the caller must block all interrupts that might cause the 304code to be reentered. 305.Sh CONTEXT 306.Fn pool_init , 307.Fn pool_destroy , 308.Fn pool_prime , 309.Fn pool_sethiwat , 310.Fn pool_setlowat , 311and 312.Fn pool_sethardlimit 313can be called during autoconf or from process context. 314.Pp 315.Fn pool_get 316and 317.Fn pool_put 318can be called during autoconf or from process context. 319If the pool has been initialised with an interrupt safe pool allocator 320they can also be called from interrupt context at or below the 321interrupt level specified by a call to 322.Fn pool_init . 323.Sh RETURN VALUES 324.Fn pool_get 325will return a pointer to an item allocated from the pool. 326If 327.Dv PR_NOWAIT 328or 329.Dv PR_LIMITFAIL 330were passed as flags to the pool it may return 331.Dv NULL 332if there are no resources available or if the pool hard limit has been reached, 333respectively. 334.Pp 335.Fn pool_prime 336will return 337.Dv ENOMEM 338if the requested number of items could not be allocated. 339Otherwise, the return value is 0. 340.Pp 341.Fn pool_sethardlimit 342will return 343.Dv EINVAL 344if the current size of the pool exceeds the requested hard limit. 345Otherwise, the return value is 0. 346.Sh CODE REFERENCES 347The pool manager is implemented in the file 348.Pa sys/kern/subr_pool.c . 349.Sh SEE ALSO 350.Xr free 9 , 351.Xr malloc 9 , 352.Xr mutex 9 , 353.Xr rwlock 9 , 354.Xr spl 9 , 355.Xr uvm_init 9 356.Sh HISTORY 357The pool manager first appeared in 358.Nx 1.4 359and was ported to 360.Ox 361by 362.An Artur Grabowski Aq Mt art@openbsd.org . 363