share/man/man9/pool.9

   1 .\"     $NetBSD: pool.9,v 1.42 2007/07/25 09:14:18 pooka 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
  68 These utility routines provide management of pools of fixed-sized
  69 areas of memory.
  70 Resource pools set aside an amount of memory for exclusive use by the resource
  71 pool owner.
  72 This can be used by applications to guarantee the availability of a minimum
  73 amount of memory needed to continue operation independent of the memory
  74 resources currently available from the system-wide memory allocator
  75 .Pq Xr malloc 9 .
  76 .Ss INITIALIZING A POOL
  77 The function
  78 .Fn pool_init
  79 initializes a resource pool.
  80 The arguments are:
  81 .Pp
  82 .Bl -tag -offset indent -width "align_offset"
  83 .It Fa pp
  84 The handle identifying the pool resource instance.
  85 .It Fa size
  86 Specifies the size of the memory items managed by the pool.
  87 .It Fa align
  88 Specifies the memory address alignment of the items returned by
  89 .Fn pool_get .
  90 This argument must be a power of two.
  91 If zero,
  92 the alignment defaults to an architecture-specific natural alignment.
  93 .It Fa align_offset
  94 The offset within an item to which the
  95 .Fa align
  96 parameter applies.
  97 .It Fa flags
  98 Should be set to zero or
  99 .Dv PR_NOTOUCH .
 100 If
 101 .Dv PR_NOTOUCH
 102 is given, free items are never used to keep internal state so that
 103 the pool can be used for non memory backed objects.
 104 .It Fa wchan
 105 The
 106 .Sq wait channel
 107 passed on to
 108 .Xr cv_wait 9
 109 if
 110 .Fn pool_get
 111 must wait for items to be returned to the pool.
 112 .It Fa palloc
 113 Can be set to
 114 .Dv NULL
 115 or
 116 .Dv pool_allocator_kmem ,
 117 in which case the default kernel memory allocator will be used.
 118 It can also be set to
 119 .Dv pool_allocator_nointr
 120 when the pool will never be accessed from interrupt context.
 121 .It Fa ipl
 122 Specifies an interrupt priority level that will block all interrupt
 123 handlers that could potentially access the pool.
 124 .El
 125 .Pp
 126 The
 127 .Fn POOL_INIT
 128 macro can be used to both declare and initialize a resource pool.
 129 The
 130 .Fn POOL_INIT
 131 macro has the same arguments as the
 132 .Fn pool_init
 133 function and the resource pool will be initialized automatically
 134 during system startup.
 135 .Ss DESTROYING A POOL
 136 The function
 137 .Fn pool_destroy
 138 destroys a resource pool.
 139 It takes a single argument
 140 .Fa pp
 141 identifying the pool resource instance.
 142 .Ss ALLOCATING ITEMS FROM A POOL
 143 .Fn pool_get
 144 allocates an item from the pool and returns a pointer to it.
 145 The arguments are:
 146 .Bl -tag -offset indent -width "flags"
 147 .It Fa pp
 148 The handle identifying the pool resource instance.
 149 .It Fa flags
 150 The flags can be used to define behaviour in case the pooled resources
 151 are depleted.
 152 If no resources are available and
 153 .Dv PR_NOWAIT
 154 is given,
 155 .Fn pool_get
 156 returns
 157 .Dv NULL .
 158 If
 159 .Dv PR_WAITOK
 160 is given and allocation is attempted with no resources available,
 161 the 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.
 167 If both
 168 .Dv PR_LIMITFAIL
 169 and
 170 .Dv PR_WAITOK
 171 are specified, and the pool has reached its hard limit,
 172 .Fn pool_get
 173 will return
 174 .Dv NULL
 175 without waiting, allowing the caller to do its own garbage collection;
 176 however, 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
 180 returns the pool item pointed at by
 181 .Fa item
 182 to the resource pool identified by the pool handle
 183 .Fa pp .
 184 If the number of available items in the pool exceeds the maximum pool
 185 size set by
 186 .Fn pool_sethiwat
 187 and there are no outstanding requests for pool items,
 188 the excess items will be returned to the system.
 189 The arguments to
 190 .Fn pool_put
 191 are:
 192 .Bl -tag -offset indent -width "item"
 193 .It Fa pp
 194 The handle identifying the pool resource instance.
 195 .It Fa item
 196 A pointer to a pool item previously obtained by
 197 .Fn pool_get .
 198 .El
 199 .Ss PRIMING A POOL
 200 .Fn pool_prime
 201 adds items to the pool.
 202 Storage space for the items is allocated by using the page allocation
 203 routine specified to
 204 .Fn pool_create .
 205 .Pp
 206 The arguments to
 207 .Fn pool_prime
 208 are:
 209 .Bl -tag -offset indent -width "storage"
 210 .It Fa pp
 211 The handle identifying the pool resource instance.
 212 .It Fa nitems
 213 The number of items to add to the pool.
 214 .El
 215 .Pp
 216 This function may return
 217 .Dv ENOMEM
 218 in case the requested number of items could not be allocated.
 219 Otherwise,
 220 the return value is 0.
 221 .Ss SETTING POOL RESOURCE WATERMARKS
 222 A pool will attempt to increase its resource usage to keep up with the demand
 223 for its items.
 224 Conversely,
 225 it will return unused memory to the system should the number of accumulated
 226 unused items in the pool exceed a programmable limit.
 227 The limits for the minimum and maximum number of items which a pool should keep
 228 at hand are known as the high and low
 229 .Sy watermarks .
 230 The functions
 231 .Fn pool_sethiwat
 232 and
 233 .Fn pool_setlowat
 234 set 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
 239 The handle identifying the pool resource instance.
 240 .It Fa n
 241 The maximum number of items to keep in the pool.
 242 As items are returned and the total number of pages in the pool is larger
 243 than the maximum set by this function,
 244 any completely unused pages are released immediately.
 245 If this function is not used to specify a maximum number of items,
 246 the pages will remain associated with the pool until the system runs low
 247 on memory,
 248 at 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
 254 The handle identifying the pool resource instance.
 255 .It Fa n
 256 The minimum number of items to keep in the pool.
 257 The number pages in the pool will not decrease below the required value to
 258 accommodate the minimum number of items specified by this function.
 259 Unlike
 260 .Fn pool_prime ,
 261 this function does not allocate the necessary memory up-front.
 262 .El
 263 .Ss POTENTIAL PITFALLS
 264 Note that undefined behaviour results when mixing the storage providing
 265 methods supported by the pool resource routines.
 266 .Pp
 267 The pool resource code uses a per-pool lock to protect its internal state.
 268 If any pool functions are called in an interrupt context,
 269 the caller must block all interrupts that might cause the
 270 code to be reentered.
 271 Additionally, the functions
 272 .Fn pool_init
 273 and
 274 .Fn pool_destroy
 275 should never be called in interrupt context.
 276 .Ss DIAGNOSTICS
 277 Pool 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
 282 The 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
 292 The
 293 .Nx
 294 pool manager appeared in
 295 .Nx 1.4 .