1.\" $NetBSD: pool.9,v 1.44 2011/11/14 02:38:05 jym 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 November 14, 2011 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 int 63.Fn pool_prime "struct pool *pp" "int nitems" 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.Pp 86.Bl -tag -offset indent -width "align_offset" 87.It Fa pp 88The handle identifying the pool resource instance. 89.It Fa size 90Specifies the size of the memory items managed by the pool. 91.It Fa align 92Specifies the memory address alignment of the items returned by 93.Fn pool_get . 94This argument must be a power of two. 95If zero, 96the alignment defaults to an architecture-specific natural alignment. 97.It Fa align_offset 98The offset within an item to which the 99.Fa align 100parameter applies. 101.It Fa flags 102Should be set to zero or 103.Dv PR_NOTOUCH . 104If 105.Dv PR_NOTOUCH 106is given, free items are never used to keep internal state so that 107the pool can be used for non memory backed objects. 108.It Fa wchan 109The 110.Sq wait channel 111passed on to 112.Xr cv_wait 9 113if 114.Fn pool_get 115must wait for items to be returned to the pool. 116.It Fa palloc 117Can be set to 118.Dv NULL 119or 120.Dv pool_allocator_kmem , 121in which case the default kernel memory allocator will be used. 122It can also be set to 123.Dv pool_allocator_nointr 124when the pool will never be accessed from interrupt context. 125.It Fa ipl 126Specifies an interrupt priority level that will block all interrupt 127handlers that could potentially access the pool. 128.El 129.Pp 130The 131.Fn POOL_INIT 132macro can be used to both declare and initialize a resource pool. 133The 134.Fn POOL_INIT 135macro has the same arguments as the 136.Fn pool_init 137function and the resource pool will be initialized automatically 138during system startup. 139.Ss DESTROYING A POOL 140The function 141.Fn pool_destroy 142destroys 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. 149The arguments are: 150.Bl -tag -offset indent -width "flags" 151.It Fa pp 152The handle identifying the pool resource instance. 153.It Fa flags 154The flags can be used to define behaviour in case the pooled resources 155are depleted. 156If no resources are available and 157.Dv PR_NOWAIT 158is given, 159.Fn pool_get 160returns 161.Dv NULL . 162If 163.Dv PR_WAITOK 164is given and allocation is attempted with no resources available, 165the function will sleep until items are returned to the pool. 166.\"Undefined behaviour results if 167.\".Dv PR_MALLOCOK 168.\"is specified on a pool handle that was created using client-provided 169.\"storage. 170.\" a bunch of other flags aren't documented. 171If both 172.Dv PR_LIMITFAIL 173and 174.Dv PR_WAITOK 175are specified, and the pool has reached its hard limit, 176.Fn pool_get 177will return 178.Dv NULL 179without waiting, allowing the caller to do its own garbage collection; 180however, it will still wait if the pool is not yet at its hard limit. 181.El 182.Ss RETURNING ITEMS TO A POOL 183.Fn pool_put 184returns the pool item pointed at by 185.Fa item 186to the resource pool identified by the pool handle 187.Fa pp . 188If the number of available items in the pool exceeds the maximum pool 189size set by 190.Fn pool_sethiwat 191and there are no outstanding requests for pool items, 192the excess items will be returned to the system. 193The arguments to 194.Fn pool_put 195are: 196.Bl -tag -offset indent -width "item" 197.It Fa pp 198The handle identifying the pool resource instance. 199.It Fa item 200A pointer to a pool item previously obtained by 201.Fn pool_get . 202.El 203.Ss PRIMING A POOL 204.Fn pool_prime 205adds items to the pool. 206Storage space for the items is allocated by using the page allocation 207routine specified to 208.Fn pool_create . 209.Pp 210The arguments to 211.Fn pool_prime 212are: 213.Bl -tag -offset indent -width "storage" 214.It Fa pp 215The handle identifying the pool resource instance. 216.It Fa nitems 217The number of items to add to the pool. 218.El 219.Pp 220This function may return 221.Dv ENOMEM 222in case the requested number of items could not be allocated. 223Otherwise, 224the return value is 0. 225.Ss SETTING POOL RESOURCE WATERMARKS AND LIMITS 226A pool will attempt to increase its resource usage to keep up with the demand 227for its items. 228Conversely, 229it will return unused memory to the system should the number of accumulated 230unused items in the pool exceed a programmable limit. 231.Pp 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 241The hard limit represents the maximum number of items a pool is allowed 242to allocate at any given time. 243Unless modified via 244.Fn pool_sethardlimit , 245the hard limit defaults to 246.Dv UINT_MAX . 247.Pp 248.Fn pool_sethiwat 249.Bl -tag -offset indent -width "flags" 250.It Fa pp 251The handle identifying the pool resource instance. 252.It Fa n 253The maximum number of items to keep in the pool. 254As items are returned and the total number of pages in the pool is larger 255than the maximum set by this function, 256any completely unused pages are released immediately. 257If this function is not used to specify a maximum number of items, 258the pages will remain associated with the pool until the system runs low 259on memory, 260at which point the VM system will try to reclaim unused pages. 261.El 262.Pp 263.Fn pool_setlowat 264.Bl -tag -offset indent -width "flags" 265.It Fa pp 266The handle identifying the pool resource instance. 267.It Fa n 268The minimum number of items to keep in the pool. 269The number pages in the pool will not decrease below the required value to 270accommodate the minimum number of items specified by this function. 271Unlike 272.Fn pool_prime , 273this function does not allocate the necessary memory up-front. 274.El 275.Pp 276.Fn pool_sethardlimit 277.Bl -tag -offset indent -width "flags" 278.It Fa pp 279The handle identifying the pool resource instance. 280.It Fa n 281The maximum number of items to be allocated from the pool (i.e. the 282hard limit). 283.It Fa warnmess 284The warning message that will be logged when the hard limit is reached. 285.It Fa ratecap 286The minimal interval (in seconds) after which another warning message 287is issued when the pool hits its hard limit again. 288.El 289.Ss POTENTIAL PITFALLS 290Note that undefined behaviour results when mixing the storage providing 291methods supported by the pool resource routines. 292.Pp 293The pool resource code uses a per-pool lock to protect its internal state. 294If any pool functions are called in an interrupt context, 295the caller must block all interrupts that might cause the 296code to be reentered. 297Additionally, the functions 298.Fn pool_init 299and 300.Fn pool_destroy 301should never be called in interrupt context. 302.Ss DIAGNOSTICS 303Pool usage logs can be enabled by defining the compile-time option 304.Dv POOL_DIAGNOSTIC . 305.\" .Sh RETURN VALUES 306.\" .Sh EXAMPLES 307.Sh CODE REFERENCES 308The pool manager is implemented in the file 309.Pa sys/kern/subr_pool.c . 310.\" .Sh AUTHOR 311.Sh SEE ALSO 312.Xr free 9 , 313.Xr malloc 9 , 314.Xr memoryallocators 9 , 315.Xr pool_cache 9 , 316.Xr uvm 9 317.Sh HISTORY 318The 319.Nx 320pool manager appeared in 321.Nx 1.4 . 322