1.\" $NetBSD: pool.9,v 1.43 2008/04/30 13:10:58 martin 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 July 25, 2007 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.Nd resource-pool manager 42.Sh SYNOPSIS 43.In sys/pool.h 44.Ft void 45.Fo pool_init 46.Fa "struct pool *pp" 47.Fa "size_t size" 48.Fa "u_int align" 49.Fa "u_int align_offset" 50.Fa "int flags" 51.Fa "const char *wchan" 52.Fa "struct pool_allocator *palloc" 53.Fa "int ipl" 54.Fc 55.Ft void 56.Fn pool_destroy "struct pool *pp" 57.Ft void * 58.Fn pool_get "struct pool *pp" "int flags" 59.Ft void 60.Fn pool_put "struct pool *pp" "void *item" 61.Ft int 62.Fn pool_prime "struct pool *pp" "int nitems" 63.Ft void 64.Fn pool_sethiwat "struct pool *pp" "int n" 65.Ft void 66.Fn pool_setlowat "struct pool *pp" "int n" 67.Sh DESCRIPTION 68These utility routines provide management of pools of fixed-sized 69areas of memory. 70Resource pools set aside an amount of memory for exclusive use by the resource 71pool owner. 72This can be used by applications to guarantee the availability of a minimum 73amount of memory needed to continue operation independent of the memory 74resources currently available from the system-wide memory allocator 75.Pq Xr malloc 9 . 76.Ss INITIALIZING A POOL 77The function 78.Fn pool_init 79initializes a resource pool. 80The arguments are: 81.Pp 82.Bl -tag -offset indent -width "align_offset" 83.It Fa pp 84The handle identifying the pool resource instance. 85.It Fa size 86Specifies the size of the memory items managed by the pool. 87.It Fa align 88Specifies the memory address alignment of the items returned by 89.Fn pool_get . 90This argument must be a power of two. 91If zero, 92the alignment defaults to an architecture-specific natural alignment. 93.It Fa align_offset 94The offset within an item to which the 95.Fa align 96parameter applies. 97.It Fa flags 98Should be set to zero or 99.Dv PR_NOTOUCH . 100If 101.Dv PR_NOTOUCH 102is given, free items are never used to keep internal state so that 103the pool can be used for non memory backed objects. 104.It Fa wchan 105The 106.Sq wait channel 107passed on to 108.Xr cv_wait 9 109if 110.Fn pool_get 111must wait for items to be returned to the pool. 112.It Fa palloc 113Can be set to 114.Dv NULL 115or 116.Dv pool_allocator_kmem , 117in which case the default kernel memory allocator will be used. 118It can also be set to 119.Dv pool_allocator_nointr 120when the pool will never be accessed from interrupt context. 121.It Fa ipl 122Specifies an interrupt priority level that will block all interrupt 123handlers that could potentially access the pool. 124.El 125.Pp 126The 127.Fn POOL_INIT 128macro can be used to both declare and initialize a resource pool. 129The 130.Fn POOL_INIT 131macro has the same arguments as the 132.Fn pool_init 133function and the resource pool will be initialized automatically 134during system startup. 135.Ss DESTROYING A POOL 136The function 137.Fn pool_destroy 138destroys a resource pool. 139It takes a single argument 140.Fa pp 141identifying the pool resource instance. 142.Ss ALLOCATING ITEMS FROM A POOL 143.Fn pool_get 144allocates an item from the pool and returns a pointer to it. 145The arguments are: 146.Bl -tag -offset indent -width "flags" 147.It Fa pp 148The handle identifying the pool resource instance. 149.It Fa flags 150The flags can be used to define behaviour in case the pooled resources 151are depleted. 152If no resources are available and 153.Dv PR_NOWAIT 154is given, 155.Fn pool_get 156returns 157.Dv NULL . 158If 159.Dv PR_WAITOK 160is given and allocation is attempted with no resources available, 161the function will sleep until items are returned to the pool. 162.\"Undefined behaviour results if 163.\".Dv PR_MALLOCOK 164.\"is specified on a pool handle that was created using client-provided 165.\"storage. 166.\" a bunch of other flags aren't documented. 167If both 168.Dv PR_LIMITFAIL 169and 170.Dv PR_WAITOK 171are specified, and the pool has reached its hard limit, 172.Fn pool_get 173will return 174.Dv NULL 175without waiting, allowing the caller to do its own garbage collection; 176however, it will still wait if the pool is not yet at its hard limit. 177.El 178.Ss RETURNING ITEMS TO A POOL 179.Fn pool_put 180returns the pool item pointed at by 181.Fa item 182to the resource pool identified by the pool handle 183.Fa pp . 184If the number of available items in the pool exceeds the maximum pool 185size set by 186.Fn pool_sethiwat 187and there are no outstanding requests for pool items, 188the excess items will be returned to the system. 189The arguments to 190.Fn pool_put 191are: 192.Bl -tag -offset indent -width "item" 193.It Fa pp 194The handle identifying the pool resource instance. 195.It Fa item 196A pointer to a pool item previously obtained by 197.Fn pool_get . 198.El 199.Ss PRIMING A POOL 200.Fn pool_prime 201adds items to the pool. 202Storage space for the items is allocated by using the page allocation 203routine specified to 204.Fn pool_create . 205.Pp 206The arguments to 207.Fn pool_prime 208are: 209.Bl -tag -offset indent -width "storage" 210.It Fa pp 211The handle identifying the pool resource instance. 212.It Fa nitems 213The number of items to add to the pool. 214.El 215.Pp 216This function may return 217.Dv ENOMEM 218in case the requested number of items could not be allocated. 219Otherwise, 220the return value is 0. 221.Ss SETTING POOL RESOURCE WATERMARKS 222A pool will attempt to increase its resource usage to keep up with the demand 223for its items. 224Conversely, 225it will return unused memory to the system should the number of accumulated 226unused items in the pool exceed a programmable limit. 227The limits for the minimum and maximum number of items which a pool should keep 228at hand are known as the high and low 229.Sy watermarks . 230The functions 231.Fn pool_sethiwat 232and 233.Fn pool_setlowat 234set a pool's high and low watermarks, respectively. 235.Pp 236.Fn pool_sethiwat 237.Bl -tag -offset indent -width "flags" 238.It Fa pp 239The handle identifying the pool resource instance. 240.It Fa n 241The maximum number of items to keep in the pool. 242As items are returned and the total number of pages in the pool is larger 243than the maximum set by this function, 244any completely unused pages are released immediately. 245If this function is not used to specify a maximum number of items, 246the pages will remain associated with the pool until the system runs low 247on memory, 248at which point the VM system will try to reclaim unused pages. 249.El 250.Pp 251.Fn pool_setlowat 252.Bl -tag -offset indent -width "flags" 253.It Fa pp 254The handle identifying the pool resource instance. 255.It Fa n 256The minimum number of items to keep in the pool. 257The number pages in the pool will not decrease below the required value to 258accommodate the minimum number of items specified by this function. 259Unlike 260.Fn pool_prime , 261this function does not allocate the necessary memory up-front. 262.El 263.Ss POTENTIAL PITFALLS 264Note that undefined behaviour results when mixing the storage providing 265methods supported by the pool resource routines. 266.Pp 267The pool resource code uses a per-pool lock to protect its internal state. 268If any pool functions are called in an interrupt context, 269the caller must block all interrupts that might cause the 270code to be reentered. 271Additionally, the functions 272.Fn pool_init 273and 274.Fn pool_destroy 275should never be called in interrupt context. 276.Ss DIAGNOSTICS 277Pool usage logs can be enabled by defining the compile-time option 278.Dv POOL_DIAGNOSTIC . 279.\" .Sh RETURN VALUES 280.\" .Sh EXAMPLES 281.Sh CODE REFERENCES 282The pool manager is implemented in the file 283.Pa sys/kern/subr_pool.c . 284.\" .Sh AUTHOR 285.Sh SEE ALSO 286.Xr free 9 , 287.Xr malloc 9 , 288.Xr memoryallocators 9 , 289.Xr pool_cache 9 , 290.Xr uvm 9 291.Sh HISTORY 292The 293.Nx 294pool manager appeared in 295.Nx 1.4 . 296