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