1.\" $NetBSD: pool.9,v 1.50 2021/12/22 17:28:17 thorpej Exp $ 2.\" 3.\" Copyright (c) 1997, 1998, 2007 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 12, 2020 31.Dt POOL 9 32.Os 33.Sh NAME 34.Nm pool_init , 35.Nm pool_destroy , 36.Nm pool_get , 37.Nm pool_put , 38.Nm pool_prime , 39.Nm pool_sethiwat , 40.Nm pool_setlowat , 41.Nm pool_sethardlimit 42.Nd resource-pool manager 43.Sh SYNOPSIS 44.In sys/pool.h 45.Ft void 46.Fo pool_init 47.Fa "struct pool *pp" 48.Fa "size_t size" 49.Fa "u_int align" 50.Fa "u_int align_offset" 51.Fa "int flags" 52.Fa "const char *wchan" 53.Fa "struct pool_allocator *palloc" 54.Fa "int ipl" 55.Fc 56.Ft void 57.Fn pool_destroy "struct pool *pp" 58.Ft void * 59.Fn pool_get "struct pool *pp" "int flags" 60.Ft void 61.Fn pool_put "struct pool *pp" "void *item" 62.Ft void 63.Fn pool_prime "struct pool *pp" "int n" 64.Ft void 65.Fn pool_sethiwat "struct pool *pp" "int n" 66.Ft void 67.Fn pool_setlowat "struct pool *pp" "int n" 68.Ft void 69.Fn pool_sethardlimit "struct pool *pp" "int n" \ 70"const char *warnmess" "int ratecap" 71.Sh DESCRIPTION 72These utility routines provide management of pools of fixed-sized 73areas of memory. 74Resource pools set aside an amount of memory for exclusive use by the resource 75pool owner. 76This can be used by applications to guarantee the availability of a minimum 77amount of memory needed to continue operation independent of the memory 78resources currently available from the system-wide memory allocator 79.Pq Xr malloc 9 . 80.Ss INITIALIZING A POOL 81The function 82.Fn pool_init 83initializes a resource pool. 84The arguments are: 85.Bl -tag -offset indent -width "align_offset" 86.It Fa pp 87The handle identifying the pool resource instance. 88.It Fa size 89Specifies the size of the memory items managed by the pool. 90.It Fa align 91Specifies the memory address alignment of the items returned by 92.Fn pool_get . 93This argument must be a power of two. 94If zero, 95the alignment defaults to an architecture-specific natural alignment. 96.It Fa align_offset 97The offset within an item to which the 98.Fa align 99parameter applies. 100.It Fa flags 101Should be set to zero, 102.Dv PR_NOTOUCH , 103or 104.Dv PR_PSERIALIZE . 105If 106.Dv PR_NOTOUCH 107is given, free items are never used to keep internal state so that 108the pool can be used for non memory backed objects. 109If 110.Dv PR_PSERIALIZE 111is given, then the allocator guarantees that a passive serialization 112barrier equivalent to 113.Dq xc_barrier(0) 114will be performed before the object's backing store is returned to 115the system. 116.Dv PR_PSERIALIZE 117implies 118.Dv PR_NOTOUCH . 119Because of the guarantees provided by 120.Dv PR_PSERIALIZE , 121objects muste never be freed to a pool using this option from either 122hard or soft interrupt context, as doing so may block. 123.It Fa wchan 124The 125.Sq wait channel 126passed on to 127.Xr cv_wait 9 128if 129.Fn pool_get 130must wait for items to be returned to the pool. 131.It Fa palloc 132Can be set to 133.Dv NULL 134or 135.Dv pool_allocator_kmem , 136in which case the default kernel memory allocator will be used. 137It can also be set to 138.Dv pool_allocator_nointr 139when the pool will never be accessed from interrupt context. 140.It Fa ipl 141Specifies an interrupt priority level that will block all interrupt 142handlers that could potentially access the pool. 143.El 144.Ss DESTROYING A POOL 145The function 146.Fn pool_destroy 147destroys a resource pool. 148It takes a single argument 149.Fa pp 150identifying the pool resource instance. 151.Ss ALLOCATING ITEMS FROM A POOL 152.Fn pool_get 153allocates an item from the pool and returns a pointer to it. 154The arguments are: 155.Bl -tag -offset indent -width "flags" 156.It Fa pp 157The handle identifying the pool resource instance. 158.It Fa flags 159The flags can be used to define behaviour in case the pooled resources 160are depleted. 161If no resources are available and 162.Dv PR_NOWAIT 163is given, 164.Fn pool_get 165returns 166.Dv NULL . 167If 168.Dv PR_WAITOK 169is given and allocation is attempted with no resources available, 170the function will sleep until items are returned to the pool. 171.\"Undefined behaviour results if 172.\".Dv PR_MALLOCOK 173.\"is specified on a pool handle that was created using client-provided 174.\"storage. 175.\" a bunch of other flags aren't documented. 176If both 177.Dv PR_LIMITFAIL 178and 179.Dv PR_WAITOK 180are specified, and the pool has reached its hard limit, 181.Fn pool_get 182will return 183.Dv NULL 184without waiting, allowing the caller to do its own garbage collection; 185however, it will still wait if the pool is not yet at its hard limit. 186If the 187.Dv PR_ZERO 188flag is specified, then the memory returned will be zeroed first using 189.Xr memset 3 . 190.El 191.Ss RETURNING ITEMS TO A POOL 192.Fn pool_put 193returns the pool item pointed at by 194.Fa item 195to the resource pool identified by the pool handle 196.Fa pp . 197If the number of available items in the pool exceeds the maximum pool 198size set by 199.Fn pool_sethiwat 200and there are no outstanding requests for pool items, 201the excess items will be returned to the system. 202The arguments to 203.Fn pool_put 204are: 205.Bl -tag -offset indent -width "item" 206.It Fa pp 207The handle identifying the pool resource instance. 208.It Fa item 209A pointer to a pool item previously obtained by 210.Fn pool_get . 211.El 212.Ss SETTING POOL RESOURCE WATERMARKS AND LIMITS 213A pool will attempt to increase its resource usage to keep up with the demand 214for its items. 215Conversely, 216it will return unused memory to the system should the number of accumulated 217unused items in the pool exceed a programmable limit. 218.Pp 219The targets for the minimum and maximum number of free items which a pool should 220try to keep available are known as the high and low 221.Sy watermarks . 222The functions 223.Fn pool_sethiwat 224and 225.Fn pool_setlowat 226set a pool's high and low watermarks, respectively. 227.Pp 228The limits for the minimum and maximum number of total items (both free and 229allocated) that the pool can have at any time are specified by the functions 230.Fn pool_prime 231and 232.Fn pool_sethardlimit , 233respectively. 234The defaults for these limits are 235.Dv 0 236and 237.Dv UINT_MAX , 238respectively. 239Changing these limits will cause memory to be immediately allocated to the pool 240or freed from the pool as needed. 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 free items to keep in the pool. 248As items are returned and the total number of free items 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 free items to keep in the pool. 263When the number of free items in the pool drops below this threshold, 264a non-blocking attempt is made to allocate memory for more items. 265The number of free items is not guaranteed to remain above this threshold. 266.El 267.Pp 268.Fn pool_sethardlimit 269.Bl -tag -offset indent -width "flags" 270.It Fa pp 271The handle identifying the pool resource instance. 272.It Fa n 273The maximum number of total items in the pool (i.e. the hard limit). 274.It Fa warnmess 275The warning message that will be logged when the hard limit is reached. 276.It Fa ratecap 277The minimal interval (in seconds) after which another warning message 278is issued when the pool hits its hard limit again. 279.El 280.Pp 281.Fn pool_prime 282.Bl -tag -offset indent -width "storage" 283.It Fa pp 284The handle identifying the pool resource instance. 285.It Fa n 286The minimum number of total items for the pool. 287If the current number of total items is less than the new minimum then new items 288are allocated with blocking allocations. 289.El 290.Ss POTENTIAL PITFALLS 291Note that undefined behaviour results when mixing the storage providing 292methods supported by the pool resource routines. 293.Pp 294The pool resource code uses a per-pool lock to protect its internal state. 295If any pool functions are called in an interrupt context, 296the caller must block all interrupts that might cause the 297code to be reentered. 298Additionally, the functions 299.Fn pool_init 300and 301.Fn pool_destroy 302should never be called in interrupt context. 303.Ss DIAGNOSTICS 304Pool usage logs can be enabled by defining the compile-time option 305.Dv POOL_DIAGNOSTIC . 306.\" .Sh RETURN VALUES 307.\" .Sh EXAMPLES 308.Sh CODE REFERENCES 309The pool manager is implemented in the file 310.Pa sys/kern/subr_pool.c . 311.\" .Sh AUTHOR 312.Sh SEE ALSO 313.Xr free 9 , 314.Xr malloc 9 , 315.Xr memoryallocators 9 , 316.Xr pool_cache 9 , 317.Xr uvm 9 318.Sh HISTORY 319The 320.Nx 321pool manager appeared in 322.Nx 1.4 . 323