xref: /netbsd-src/share/man/man9/pool_cache.9 (revision a5847cc334d9a7029f6352b847e9e8d71a0f9e0c)
1.\"	$NetBSD: pool_cache.9,v 1.18 2011/06/01 20:49:22 dyoung Exp $
2.\"
3.\" Copyright (c)2003 YAMAMOTO Takashi,
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
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.
14.\"
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
25.\" SUCH DAMAGE.
26.\"
27.\" Copyright (c) 1997, 1999, 2000, 2007, 2008 The NetBSD Foundation, Inc.
28.\" All rights reserved.
29.\"
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.
33.\"
34.\" Redistribution and use in source and binary forms, with or without
35.\" modification, are permitted provided that the following conditions
36.\" are met:
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.
42.\"
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.
54.\"
55.\" ------------------------------------------------------------
56.Dd June 1, 2011
57.Dt POOL_CACHE 9
58.Os
59.\" ------------------------------------------------------------
60.Sh NAME
61.Nm pool_cache ,
62.Nm pool_cache_init ,
63.Nm pool_cache_destroy ,
64.Nm pool_cache_get_paddr ,
65.Nm pool_cache_get ,
66.Nm pool_cache_put_paddr ,
67.Nm pool_cache_put ,
68.Nm pool_cache_destruct_object ,
69.Nm pool_cache_invalidate ,
70.Nm pool_cache_sethiwat ,
71.Nm pool_cache_setlowat
72.Nd resource-pool cache manager
73.\" ------------------------------------------------------------
74.Sh SYNOPSIS
75.In sys/pool.h
76.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
77.Ft pool_cache_t
78.Fn pool_cache_init \
79"size_t size" "u_int align" "u_int align_offset" "int flags" \
80"const char *name" "struct pool_allocator *palloc" "int ipl" \
81"int (*ctor)(void *, void *, int)" "void (*dtor)(void *, void *)" "void *arg"
82.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
83.Ft void
84.Fn pool_cache_destroy \
85"pool_cache_t pc"
86.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
87.Ft void *
88.Fn pool_cache_get_paddr \
89"pool_cache_t pc" "int flags" "paddr_t *pap"
90.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
91.Ft void *
92.Fn pool_cache_get \
93"pool_cache_t pc" "int flags"
94.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
95.Ft void
96.Fn pool_cache_put_paddr \
97"pool_cache_t pc" "void *object" "paddr_t pa"
98.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
99.Ft void
100.Fn pool_cache_put \
101"pool_cache_t pc" "void *object"
102.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
103.Ft void
104.Fn pool_cache_destruct_object \
105"pool_cache_t pc" "void *object"
106.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
107.Ft void
108.Fn pool_cache_invalidate \
109"pool_cache_t pc"
110.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
111.Ft void
112.Fn pool_cache_sethiwat \
113"pool_cache_t pc" "int nitems"
114.Ft void
115.Fn pool_cache_setlowat \
116"pool_cache_t pc" "int nitems"
117.\" ------------------------------------------------------------
118.Sh DESCRIPTION
119These utility routines provide management of pools of fixed-sized
120areas of memory.
121Resource pools set aside an amount of memory for exclusive use by the resource
122pool owner.
123This can be used by applications to guarantee the availability of a minimum
124amount of memory needed to continue operation independent of the memory
125resources currently available from the system-wide memory allocator.
126.Pp
127Global and per-CPU caches of constructed objects are maintained.
128The two levels of cache work together to allow for low overhead
129allocation and release of objects, and improved L1/L2/L3 hardware
130cache locality in multiprocessor systems.
131.\" ------------------------------------------------------------
132.Sh FUNCTIONS
133.Bl -tag -width compact
134.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
135.It Fn pool_cache_init "size" "align" "align_offset" "flags" \
136"name" "palloc" "ipl"  "ctor" "dtor" "arg"
137.Pp
138Allocate and initialize a pool cache.
139The arguments are:
140.Pp
141.Bl -tag -width four
142.It Fa size
143.Pp
144Specifies the size of the memory items managed by the pool.
145.It Fa align
146.Pp
147Specifies the memory address alignment of the items returned by
148.Fn pool_cache_get .
149This argument must be a power of two.
150If zero,
151the alignment defaults to an architecture-specific natural alignment.
152.It Fa align_offset
153.Pp
154The offset within an item to which the
155.Fa align
156parameter applies.
157.It Fa flags
158.Pp
159Should be set to zero or
160.Dv PR_NOTOUCH .
161If
162.Dv PR_NOTOUCH
163is given, free items are never used to keep internal state so that
164the pool can be used for non memory backed objects.
165.It Fa name
166.Pp
167The name used to identify the object in diagnostic output.
168.It Fa palloc
169.Pp
170Should be typically be set to NULL, instructing
171.Fn pool_cache_init
172to select an appropriate back-end allocator.
173Alternate allocators can be used to partition space from arbitrary sources.
174Use of alternate allocators is not documented here as it is not a stable,
175endorsed part of the API.
176.It Fa ipl
177.Pp
178Specifies an interrupt priority level that will block all interrupt
179handlers that could potentially access the pool.
180The
181.Nm
182facility provides its own synchronization.
183The users of any given
184.Nm
185need not provide additional synchronization for access to it.
186.It Fa ctor
187.Pp
188Specifies a constructor used to initialize newly allocated objects.
189If no constructor is required, specify
190.Dv NULL .
191The first argument to
192.Fa ctor
193is
194.Fa arg ,
195the second is the new object, and the third is
196.Fa flags .
197.It Fa dtor
198.Pp
199Specifies a destructor used to destroy cached objects prior to
200their release to backing store.
201If no destructor is required, specify
202.Dv NULL .
203The first argument to
204.Fa dtor
205is
206.Fa arg ,
207and the second is the object.
208.It Fa arg
209.Pp
210This value of this argument will be passed to both the constructor
211and destructor routines.
212.El
213.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
214.It Fn pool_cache_destroy "pc"
215.Pp
216Destroy a pool cache
217.Fa pc .
218All other access to the cache must be stopped before this call
219can be made.
220.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
221.It Fn pool_cache_get_paddr "pc" "flags" "pap"
222.Pp
223Get an object from a pool cache
224.Fa pc .
225If
226.Fa pap
227is not
228.Dv NULL ,
229physical address of the object or
230.Dv POOL_PADDR_INVALID
231will be returned via it.
232.Fa flags
233will be passed to
234.Fn pool_get
235function of the backing
236.Xr pool 9
237and the object constructor specified when the pool cache is created by
238.Fn pool_cache_init .
239.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
240.It Fn pool_cache_get "pc" "flags"
241.Pp
242.Fn pool_cache_get
243is the same as
244.Fn pool_cache_get_paddr
245with
246.Dv NULL
247.Fa pap
248argument.
249It's implemented as a macro.
250.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
251.It Fn pool_cache_put_paddr "pc" "object" "pa"
252.Pp
253Put an object
254.Fa object
255back to the pool cache
256.Fa pc .
257.Fa pa
258should be physical address of the object
259.Fa object
260or
261.Dv POOL_PADDR_INVALID .
262.Fa pp .
263If the number of available items in the backing pool exceeds the maximum
264pool size set by
265.Fn pool_cache_sethiwat
266and there are no outstanding requests for pool items,
267the excess items will be returned to the system.
268.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
269.It Fn pool_cache_put "pc" "object"
270.Pp
271.Fn pool_cache_put
272is the same as
273.Fn pool_cache_put_paddr
274with
275.Dv POOL_PADDR_INVALID
276.Fa pa
277argument.
278It's implemented as a macro.
279.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
280.It Fn pool_cache_destruct_object "pc" "object"
281.Pp
282Force destruction of an object
283.Fa object
284and its release back into the pool.
285.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
286.It Fn pool_cache_invalidate "pc"
287.Pp
288Invalidate a pool cache
289.Fa pc .
290All objects in the cache will be destructed and freed back to the pool
291backing the cache.
292For pool caches that vend constructed objects, consumers of this API
293must take care to provide proper synchronization between the input to
294the constructor and cache invalidation.
295.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
296.It Fn pool_cache_sethiwat "pc" "nitems"
297.Pp
298A pool will attempt to increase its resource usage to keep up with the demand
299for its items.
300Conversely,
301it will return unused memory to the system should the number of accumulated
302unused items in the pool exceed a programmable limit.
303The limits for the minimum and maximum number of items which a pool should keep
304at hand are known as the high and low
305.Sy watermarks .
306.Pp
307The function
308.Fn pool_cache_sethiwat
309sets the backing pool's high water mark.
310As items are returned and the total number of pages in the pool is larger
311than the maximum set by this function,
312any completely unused pages are released immediately.
313If this function is not used to specify a maximum number of items,
314the pages will remain associated with the pool until the system runs low
315on memory,
316at which point the VM system will try to reclaim unused pages.
317.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
318.It Fn pool_cache_setlowat "pc" "nitems"
319.Pp
320Set the minimum number of items to keep in the pool.
321The number pages in the pool will not decrease below the required value to
322accommodate the minimum number of items specified by this function.
323.El
324.\" ------------------------------------------------------------
325.Sh CODE REFERENCES
326The
327.Nm
328subsystem is implemented within the file
329.Pa sys/kern/subr_pool.c .
330.Sh SEE ALSO
331.Xr intro 9 ,
332.Xr kmem 9 ,
333.Xr memoryallocators 9 ,
334.Xr percpu 9 ,
335.Xr pool 9
336