3 .\" The DragonFly Project. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" 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
13 .\" the documentation and/or other materials provided with the
15 .\" 3. Neither the name of The DragonFly Project nor the names of its
16 .\" contributors may be used to endorse or promote products derived
17 .\" from this software without specific, prior written permission.
19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .Nm objcache_create_mbacked ,
38 .Nm objcache_create_simple ,
39 .Nm objcache_destroy ,
42 .Nm objcache_malloc_alloc ,
43 .Nm objcache_malloc_free ,
44 .Nm objcache_nop_alloc ,
45 .Nm objcache_nop_free ,
46 .\" .Nm objcache_populate_linear ,
48 .Nm objcache_reclaimlist
49 .Nd "object caching facility"
54 .Fa "const char *name"
55 .Fa "int cluster_limit"
56 .Fa "int mag_capacity"
57 .Fa "objcache_ctor_fn *ctor"
58 .Fa "objcache_dtor_fn *dtor"
60 .Fa "objcache_alloc_fn *alloc"
61 .Fa "objcache_free_fn *free"
62 .Fa "void *allocator_args"
65 .Fo objcache_create_mbacked
66 .Fa "malloc_type_t mtype"
68 .Fa "int cluster_limit"
69 .Fa "int mag_capacity"
70 .Fa "objcache_ctor_fn *ctor"
71 .Fa "objcache_dtor_fn *dtor"
75 .Fn objcache_create_simple "malloc_type_t mtype" "size_t objsize"
77 .Fn objcache_destroy "struct objcache *oc"
79 .Fn objcache_dtor "struct objcache *oc" "void *obj"
81 .Fn objcache_get "struct objcache *oc" "int ocflags"
83 .Fn objcache_malloc_alloc "void *allocator_args" "int ocflags"
85 .Fn objcache_malloc_free "void *obj" "void *allocator_args"
87 .Fn objcache_nop_alloc "void *allocator_args" "int ocflags"
89 .Fn objcache_nop_free "void *obj" "void *allocator_args"
91 .\" .Fo objcache_populate_linear
92 .\" .Fa "struct objcache *oc"
98 .Fn objcache_put "struct objcache *oc" "void *obj"
100 .Fn objcache_reclaimlist "struct objcache *oc[]" "int nlist" "int ocflags"
102 Object caching is a technique for manipulating objects that are frequently
104 The idea behind caching is to preserve the invariant portion of an object's
105 initial state between uses, so it does not have to be destroyed and reborn
106 every time the object is used.
109 creates a new object cache.
112 which is used to distinguish the object in diagnostic output.
115 determines the number of available magazines in the depot layer.
119 If 0 is given, then there is no limit to the number of magazines the depot
120 can have (aside from the inherent limitation imposed by the restricted nature
121 of the back end allocator).
124 describes the capacity of the magazine, that is the largest number of objects
126 If set to 0, the default value is used as defined in
127 .Pa sys/kern/kern_objcache.c .
128 Currently, the default value is 64.
129 The object caching system itself may adjust the cluster limit and/or
130 magazines' capacity based on the number of available CPUs.
132 specifies a function that constructs (i.e., performs the one-time
133 initialization of) an object in the cache.
136 boolean_t foo_ctor(void *obj, void *privdata, int ocflags);
139 If no constructor is needed, it must be set to
142 specifies a deconstructor function that destroys the cached object, before it
143 is released to the back end that manages the flow of real memory.
146 void foo_dtor(void *obj, void *privdata);
149 If no deconstructor is needed, it must be set to
151 The interface to underlying allocator is provided by
156 It must adhere to the following form:
158 void *foo_alloc(void *allocator_args, int ocflags);
159 void foo_free(void *obj, void *allocator_args);
162 .Fn objcache_malloc_alloc
164 .Fn objcache_malloc_free
167 allocation functions.
169 .Fn objcache_nop_alloc
171 .Fn objcache_nop_free
172 are wrappers for allocation policies that pre-allocate at initialization time
173 instead of doing run-time allocation.
175 .Fn objcache_create_mbacked
176 creates a new object cache of size
181 The latter is used to perform statistics in memory usage and for basic sanity
183 For the underlying allocator,
185 functions are employed.
187 .Fn objcache_create_simple
188 creates a new object cache of size
195 is set to 0 and the default value for magazines' capacity is used.
205 For the underlying allocator,
207 functions are employed.
210 returns an object from the
213 The object is in its initialized state.
214 Newly allocated objects are subjected to the object cache's constructor
217 prior to being returned.
219 is only used when the depot does not have any non-empty magazines and a new
220 object needs to be allocated using the back end allocator.
221 In this case we cannot depend on flags such as
223 If the back end allocator fails, or if the depot's object limit has been
236 The object must be in its initialized state prior to this call.
237 If there is no empty magazine, the object deconstructor is called and
245 object cache, indicating that the object is not in any shape to be reused and
246 should be deconstructed and freed immediately.
248 .Fn objcache_reclaimlist
253 elements and tries to free up some memory.
254 For each object cache in the reclaim list, the current per-CPU cache is tried
255 first and then the full magazine depot.
258 as soon as some free memory is found
267 The object must have no existing references.
269 .\" .Fn objcache_populate_linear
270 .\" populates the per-cluster depot with elements from a linear block of memory.
271 .\" Must be called for individually for each cluster.
272 .\" Populated depots should not be destroyed.
273 .\" Currently this function is unimplemented.
274 .Sh IMPLEMENTATION NOTES
276 A magazine is the very basic functional unit of the object caching scheme.
277 The number of objects it can hold is fixed and determined by its capacity.
278 The term magazine is used as an analogy with automatic weapon
279 (a firearm that can fire several rounds without reloading).
280 .Ss Per-CPU object cache
281 The reasoning behind per-CPU caches is to allow CPUs to perform their
282 transactions (i.e., allocations, frees) in a parallel, yet lockless manner.
284 Each CPU is given two magazines, an active and a backup.
285 This is done in order to avoid a situation where a tight loop of
286 two allocations followed by two frees can cause thrashing at the
289 If we need to add an object to the cache and the active magazine is full,
290 room is searched in the backup magazine.
291 If the backup has room, we swap active with backup and add the object.
292 If both magazines are full, we get an empty magazine from the depot
293 and move a fully loaded magazine to the depot.
295 Each object cache manages a global supply of magazines, the depot, that is
296 available across all CPUs.
297 The depot maintains two lists of magazines.
298 One for completely full and one for completely free magazines.
299 The per-CPU object caches only exchange completely full or
300 completely empty magazines with the depot layer.
303 /* This is the data structure we are going to cache. */
309 MALLOC_DEFINE(M_FOOBUF, "foobuf", "Buffer to my little precious data");
311 struct objcache_malloc_args foo_malloc_args = {
312 sizeof(struct foo), M_FOOBUF };
314 struct objcache *foo_cache;
317 * Object cache constructor.
320 foo_cache_ctor(void *obj, void *privdata, int ocflags)
322 struct foo *myfoo = obj;
325 * Do any initialization of the object here. Let's just zero out
326 * the data structure for the fun of it.
328 bzero(myfoo, sizeof(*myfoo));
334 * Object cache deconstructor.
337 foo_cache_dtor(void *obj, void *privdata)
339 struct foo *myfoo = obj;
342 * Do any clean up here. E.g., if you have kmalloc'ed() inside
343 * the constructor, this is the right place and time to kfree().
348 * Initialize our subsystem.
353 /* Create the object cache. */
354 foo_cache = objcache_create("foo",
355 0, /* infinite depot's capacity */
356 0, /* default magazine's capacity */
357 foo_ctor, foo_dtor, NULL,
358 objcache_malloc_alloc,
359 objcache_malloc_free,
371 /* Get a `foo' object from the object cache. */
372 myfoo = objcache_get(foo_cache, M_WAITOK);
374 /* Do stuff with it. */
377 /* We don't need it anymore. Put it back in object cache. */
378 objcache_put(foo_cache, myfoo);
382 * Shutdown our subsystem.
387 /* Destroy the object cache. */
388 objcache_destroy(foo_cache);
395 .%T "The Slab Allocator: An Object-Caching Kernel Memory Allocator"
396 .%R "USENIX Summer 1994 Technical Conference"
401 .%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources"
402 .%R "USENIX 2001 Technical Conference"
405 The object caching system appeared in
408 The object caching system was written by
410 .An Jeffrey M. Hsu Aq Mt hsu@freebsd.org .
411 This manual page was written by
412 .An Stathis Kamperis Aq Mt ekamperi@gmail.com .