1 .\" $NetBSD: pool_cache.9,v 1.11 2009/10/08 21:54:45 jym Exp $
3 .\" Copyright (c)2003 YAMAMOTO Takashi,
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" Copyright (c) 1997, 1999, 2000, 2007, 2008 The NetBSD Foundation, Inc.
28 .\" All rights reserved.
30 .\" This code is derived from software contributed to The NetBSD Foundation
31 .\" by Paul Kranenburg; by Jason R. Thorpe of the Numerical Aerospace
32 .\" Simulation Facility, NASA Ames Research Center, and by Andrew Doran.
34 .\" Redistribution and use in source and binary forms, with or without
35 .\" modification, are permitted provided that the following conditions
37 .\" 1. Redistributions of source code must retain the above copyright
38 .\" notice, this list of conditions and the following disclaimer.
39 .\" 2. Redistributions in binary form must reproduce the above copyright
40 .\" notice, this list of conditions and the following disclaimer in the
41 .\" documentation and/or other materials provided with the distribution.
43 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
44 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
45 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
46 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
47 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
48 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
49 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
50 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
51 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
52 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
53 .\" POSSIBILITY OF SUCH DAMAGE.
55 .\" ------------------------------------------------------------
59 .\" ------------------------------------------------------------
63 .Nm pool_cache_destroy ,
64 .Nm pool_cache_get_paddr ,
66 .Nm pool_cache_put_paddr ,
68 .Nm pool_cache_destruct_object ,
69 .Nm pool_cache_invalidate ,
70 .Nm pool_cache_invalidate_local ,
71 .Nm pool_cache_sethiwat ,
72 .Nm pool_cache_setlowat
73 .Nd resource-pool cache manager
74 .\" ------------------------------------------------------------
77 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
80 "size_t size" "u_int align" "u_int align_offset" "int flags" \
81 "const char *name" "struct pool_allocator *palloc" "int ipl" \
82 "int (*ctor)(void *, void *, int)" "void (*dtor)(void *, void *)" "void *arg"
83 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
85 .Fn pool_cache_destroy \
87 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
89 .Fn pool_cache_get_paddr \
90 "pool_cache_t pc" "int flags" "paddr_t *pap"
91 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
94 "pool_cache_t pc" "int flags"
95 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
97 .Fn pool_cache_put_paddr \
98 "pool_cache_t pc" "void *object" "paddr_t pa"
99 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
102 "pool_cache_t pc" "void *object"
103 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
105 .Fn pool_cache_destruct_object \
106 "pool_cache_t pc" "void *object"
107 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
109 .Fn pool_cache_invalidate \
112 .Fn pool_cache_invalidate_local \
114 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
116 .Fn pool_cache_sethiwat \
117 "pool_cache_t pc" "int nitems"
119 .Fn pool_cache_setlowat \
120 "pool_cache_t pc" "int nitems"
121 .\" ------------------------------------------------------------
123 These utility routines provide management of pools of fixed-sized
125 Resource pools set aside an amount of memory for exclusive use by the resource
127 This can be used by applications to guarantee the availability of a minimum
128 amount of memory needed to continue operation independent of the memory
129 resources currently available from the system-wide memory allocator.
131 Global and per-CPU caches of constructed objects are maintained.
132 The two levels of cache work together to allow for low overhead
133 allocation and release of objects, and improved L1/L2/L3 hardware
134 cache locality in multiprocessor systems.
135 .\" ------------------------------------------------------------
137 .Bl -tag -width compact
138 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
139 .It Fn pool_cache_init "pc" "pp" "ctor" "dtor" "arg"
141 Allocate and initialize a pool cache.
147 Specifies the size of the memory items managed by the pool.
150 Specifies the memory address alignment of the items returned by
152 This argument must be a power of two.
154 the alignment defaults to an architecture-specific natural alignment.
157 The offset within an item to which the
162 Should be set to zero or
166 is given, free items are never used to keep internal state so that
167 the pool can be used for non memory backed objects.
170 The name used to identify the object in diagnostic output.
173 Should be typically be set to NULL, instructing
175 to select an appropriate back-end allocator.
176 Alternate allocators can be used to partition space from arbitrary sources.
177 Use of alternate allocators is not documented here as it is not a stable,
178 endorsed part of the API.
181 Specifies an interrupt priority level that will block all interrupt
182 handlers that could potentially access the pool.
185 facility provides its own synchronization.
186 The users of any given
188 need not provide additional synchronization for access to it.
191 Specifies a constructor used to initialize newly allocated objects.
192 If no constructor is required, specify
196 Specifies a destructor used to destroy cached objects prior to
197 their release to backing store.
198 If no destructor is required, specify
202 This value of this argument will be passed to both the constructor
203 and destructor routines.
205 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
206 .It Fn pool_cache_destroy "pc"
210 All other access to the cache must be stopped before this call
212 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
213 .It Fn pool_cache_get_paddr "pc" "flags" "pap"
215 Get an object from a pool cache
221 physical address of the object or
222 .Dv POOL_PADDR_INVALID
223 will be returned via it.
227 function of the backing
229 and the object constructor specified when the pool cache is created by
230 .Fn pool_cache_init .
231 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
232 .It Fn pool_cache_get "pc" "flags"
236 .Fn pool_cache_get_paddr
241 It's implemented as a macro.
242 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
243 .It Fn pool_cache_put_paddr "pc" "object" "pa"
247 back to the pool cache
250 should be physical address of the object
253 .Dv POOL_PADDR_INVALID .
255 If the number of available items in the backing pool exceeds the maximum
257 .Fn pool_cache_sethiwat
258 and there are no outstanding requests for pool items,
259 the excess items will be returned to the system.
260 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
261 .It Fn pool_cache_put "pc" "object"
265 .Fn pool_cache_put_paddr
267 .Dv POOL_PADDR_INVALID
270 It's implemented as a macro.
271 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
272 .It Fn pool_cache_destruct_object "pc" "object"
274 Force destruction of an object
276 and its release back into the pool.
277 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
278 .It Fn pool_cache_invalidate "pc"
280 Invalidate a pool cache
282 Destruct and release all objects in the global cache.
283 Per-CPU caches will not be invalidated by this call, meaning that it
284 is still possible to allocate "stale" items from the cache.
285 If relevant, the user must check for this condition when allocating
287 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
288 .It Fn pool_cache_invalidate_local "pc"
290 Invalidate local, current CPU pool cache
292 Destruct and release all objects in the local, current CPU cache.
293 Only the Per-CPU caches associated to the current CPU calling the routine
294 will be invalidated, meaning that stale items can still be allocated from
295 other CPUs or the global cache.
296 It is the caller's responsibility to ensure that such conditions do
298 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
299 .It Fn pool_cache_sethiwat "pc" "nitems"
301 A pool will attempt to increase its resource usage to keep up with the demand
304 it will return unused memory to the system should the number of accumulated
305 unused items in the pool exceed a programmable limit.
306 The limits for the minimum and maximum number of items which a pool should keep
307 at hand are known as the high and low
311 .Fn pool_cache_sethiwat
312 sets the backing pool's high water mark.
313 As items are returned and the total number of pages in the pool is larger
314 than the maximum set by this function,
315 any completely unused pages are released immediately.
316 If this function is not used to specify a maximum number of items,
317 the pages will remain associated with the pool until the system runs low
319 at which point the VM system will try to reclaim unused pages.
320 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
321 .It Fn pool_cache_setlowat "pc" "nitems"
323 Set the minimum number of items to keep in the pool.
324 The number pages in the pool will not decrease below the required value to
325 accommodate the minimum number of items specified by this function.
327 .\" ------------------------------------------------------------
329 This section describes places within the
331 source tree where actual code implementing the
335 All pathnames are relative to
340 subsystem is implemented within the file
341 .Pa sys/kern/subr_pool.c .
345 .Xr memoryallocators 9 ,