1.\" 2.\" Copyright (c) 2009 3.\" The DragonFly Project. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 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 14.\" distribution. 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. 18.\" 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 30.\" SUCH DAMAGE. 31.\" 32.Dd March 9, 2009 33.Dt OBJCACHE 9 34.Os 35.Sh NAME 36.Nm objcache_create , 37.Nm objcache_create_mbacked , 38.Nm objcache_create_simple , 39.Nm objcache_destroy , 40.Nm objcache_dtor , 41.Nm objcache_get , 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 , 47.Nm objcache_put , 48.Nm objcache_reclaimlist 49.Nd "object caching facility" 50.Sh SYNOPSIS 51.In sys/objcache.h 52.Ft struct objcache * 53.Fo objcache_create 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" 59.Fa "void *privdata" 60.Fa "objcache_alloc_fn *alloc" 61.Fa "objcache_free_fn *free" 62.Fa "void *allocator_args" 63.Fc 64.Ft struct objcache * 65.Fo objcache_create_mbacked 66.Fa "malloc_type_t mtype" 67.Fa "size_t objsize" 68.Fa "int cluster_limit" 69.Fa "int mag_capacity" 70.Fa "objcache_ctor_fn *ctor" 71.Fa "objcache_dtor_fn *dtor" 72.Fa "void *privdata" 73.Fc 74.Ft struct objcache * 75.Fn objcache_create_simple "malloc_type_t mtype" "size_t objsize" 76.Ft void 77.Fn objcache_destroy "struct objcache *oc" 78.Ft void 79.Fn objcache_dtor "struct objcache *oc" "void *obj" 80.Ft void * 81.Fn objcache_get "struct objcache *oc" "int ocflags" 82.Ft void * 83.Fn objcache_malloc_alloc "void *allocator_args" "int ocflags" 84.Ft void 85.Fn objcache_malloc_free "void *obj" "void *allocator_args" 86.Ft void * 87.Fn objcache_nop_alloc "void *allocator_args" "int ocflags" 88.Ft void 89.Fn objcache_nop_free "void *obj" "void *allocator_args" 90.\" .Ft void 91.\" .Fo objcache_populate_linear 92.\" .Fa "struct objcache *oc" 93.\" .Fa "void *elts" 94.\" .Fa "int nelts" 95.\" .Fa "int size" 96.\" .Fc 97.Ft void 98.Fn objcache_put "struct objcache *oc" "void *obj" 99.Ft boolean_t 100.Fn objcache_reclaimlist "struct objcache *oc[]" "int nlist" "int ocflags" 101.Sh DESCRIPTION 102Object caching is a technique for manipulating objects that are frequently 103allocated and freed. 104The idea behind caching is to preserve the invariant portion of an object's 105initial state between uses, so it does not have to be destroyed and reborn 106every time the object is used. 107.Pp 108.Fn objcache_create 109creates a new object cache. 110It is identified by 111.Fa name , 112which is used to distinguish the object in diagnostic output. 113The 114.Fa cluster_limit 115determines the number of available magazines in the depot layer. 116It must be at least 117.Fa mag_capacity * 118ncpus * 8. 119If 0 is given, then there is no limit to the number of magazines the depot 120can have (aside from the inherent limitation imposed by the restricted nature 121of the back end allocator). 122The 123.Fa mag_capacity 124describes the capacity of the magazine, that is the largest number of objects 125it can hold. 126If set to 0, the default value is used as defined in 127.Pa sys/kern/kern_objcache.c . 128Currently, the default value is 64. 129The object caching system itself may adjust the cluster limit and/or 130magazines' capacity based on the number of available CPUs. 131.Fa ctor 132specifies a function that constructs (i.e., performs the one-time 133initialization of) an object in the cache. 134It is defined as: 135.Bd -literal 136boolean_t foo_ctor(void *obj, void *privdata, int ocflags); 137.Ed 138.Pp 139If no constructor is needed, it must be set to 140.Dv NULL . 141.Fa dtor 142specifies a deconstructor function that destroys the cached object, before it 143is released to the back end that manages the flow of real memory. 144It is defined as: 145.Bd -literal 146void foo_dtor(void *obj, void *privdata); 147.Ed 148.Pp 149If no deconstructor is needed, it must be set to 150.Dv NULL . 151The interface to underlying allocator is provided by 152.Fa alloc , 153.Fa free 154and 155.Fa allocator_args . 156It must adhere to the following form: 157.Bd -literal 158void *foo_alloc(void *allocator_args, int ocflags); 159void foo_free(void *obj, void *allocator_args); 160.Ed 161.Pp 162.Fn objcache_malloc_alloc 163and 164.Fn objcache_malloc_free 165are wrappers for 166.Xr kmalloc 9 167allocation functions. 168Whereas, 169.Fn objcache_nop_alloc 170and 171.Fn objcache_nop_free 172are wrappers for allocation policies that pre-allocate at initialization time 173instead of doing run-time allocation. 174.Pp 175.Fn objcache_create_mbacked 176creates a new object cache of size 177.Fa objsize , 178backed with a 179.Vt malloc_type_t 180argument. 181The latter is used to perform statistics in memory usage and for basic sanity 182checks. 183For the underlying allocator, 184.Xr kmalloc 9 185functions are employed. 186.Pp 187.Fn objcache_create_simple 188creates a new object cache of size 189.Fa objsize , 190backed with a 191.Vt malloc_type_t 192argument. 193The 194.Fa cluster_limit 195is set to 0 and the default value for magazines' capacity is used. 196.Fa ctor 197and 198.Fa dtor 199are set to 200.Dv NULL . 201.Fa privdata 202is set to 203.Dv NULL 204as well. 205For the underlying allocator, 206.Xr kmalloc 9 207functions are employed. 208.Pp 209.Fn objcache_get 210returns an object from the 211.Fa oc 212object cache. 213The object is in its initialized state. 214Newly allocated objects are subjected to the object cache's constructor 215function, if not 216.Dv NULL , 217prior to being returned. 218.Fa ocflags 219is only used when the depot does not have any non-empty magazines and a new 220object needs to be allocated using the back end allocator. 221In this case we cannot depend on flags such as 222.Dv M_ZERO . 223If the back end allocator fails, or if the depot's object limit has been 224reached and 225.Dv M_WAITOK 226is not specified, 227.Dv NULL 228is returned. 229.Pp 230.Fn objcache_put 231returns 232.Fa obj 233to the 234.Fa oc 235object cache. 236The object must be in its initialized state prior to this call. 237If there is no empty magazine, the object deconstructor is called and 238the object is freed. 239.Pp 240.Fn objcache_dtor 241puts 242.Fa obj 243back into the 244.Fa oc 245object cache, indicating that the object is not in any shape to be reused and 246should be deconstructed and freed immediately. 247.Pp 248.Fn objcache_reclaimlist 249iterates over the 250.Fa oclist[] 251list with 252.Fa nlist 253elements and tries to free up some memory. 254For each object cache in the reclaim list, the current per-CPU cache is tried 255first and then the full magazine depot. 256The function returns 257.Dv TRUE 258as soon as some free memory is found 259and 260.Dv FALSE 261otherwise. 262.Pp 263.Fn objcache_destroy 264destroys the 265.Fa oc 266object cache. 267The object must have no existing references. 268.\" .Pp 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 275.Ss Magazine 276A magazine is the very basic functional unit of the object caching scheme. 277The number of objects it can hold is fixed and determined by its capacity. 278The 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 281The reasoning behind per-CPU caches is to allow CPUs to perform their 282transactions (i.e., allocations, frees) in a parallel, yet lockless manner. 283.Pp 284Each CPU is given two magazines, an active and a backup. 285This is done in order to avoid a situation where a tight loop of 286two allocations followed by two frees can cause thrashing at the 287magazine boundary. 288.Pp 289If we need to add an object to the cache and the active magazine is full, 290room is searched in the backup magazine. 291If the backup has room, we swap active with backup and add the object. 292If both magazines are full, we get an empty magazine from the depot 293and move a fully loaded magazine to the depot. 294.Ss Magazine depot 295Each object cache manages a global supply of magazines, the depot, that is 296available across all CPUs. 297The depot maintains two lists of magazines. 298One for completely full and one for completely free magazines. 299The per-CPU object caches only exchange completely full or 300completely empty magazines with the depot layer. 301.Sh EXAMPLES 302.Bd -literal 303/* This is the data structure we are going to cache. */ 304struct foo { 305 int x; 306 char str[32]; 307}; 308 309MALLOC_DEFINE(M_FOOBUF, "foobuf", "Buffer to my little precious data"); 310 311struct objcache_malloc_args foo_malloc_args = { 312 sizeof(struct foo), M_FOOBUF }; 313 314struct objcache *foo_cache; 315 316/* 317 * Object cache constructor. 318 */ 319static boolean_t 320foo_cache_ctor(void *obj, void *privdata, int ocflags) 321{ 322 struct foo *myfoo = obj; 323 324 /* 325 * Do any initialization of the object here. Let's just zero out 326 * the data structure for the fun of it. 327 */ 328 bzero(myfoo, sizeof(*myfoo)); 329 330 return (TRUE); 331} 332 333/* 334 * Object cache deconstructor. 335 */ 336static void 337foo_cache_dtor(void *obj, void *privdata) 338{ 339 struct foo *myfoo = obj; 340 341 /* 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(). 344 */ 345} 346 347/* 348 * Initialize our subsystem. 349 */ 350static void 351foo_init(void) 352{ 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, 360 &foo_malloc_args); 361} 362 363/* 364 * Random function. 365 */ 366static void 367foo_random(...) 368{ 369 struct foo *myfoo; 370 371 /* Get a `foo' object from the object cache. */ 372 myfoo = objcache_get(foo_cache, M_WAITOK); 373 374 /* Do stuff with it. */ 375 /* ... */ 376 377 /* We don't need it anymore. Put it back in object cache. */ 378 objcache_put(foo_cache, myfoo); 379} 380 381/* 382 * Shutdown our subsystem. 383 */ 384static void 385foo_uninit(void) 386{ 387 /* Destroy the object cache. */ 388 objcache_destroy(foo_cache); 389} 390.Ed 391.Sh SEE ALSO 392.Xr memory 9 393.Rs 394.%A "Jeff Bonwick" 395.%T "The Slab Allocator: An Object-Caching Kernel Memory Allocator" 396.%R "USENIX Summer 1994 Technical Conference" 397.Re 398.Rs 399.%A "Jeff Bonwick" 400.%A "Jonathan Adams" 401.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources" 402.%R "USENIX 2001 Technical Conference" 403.Re 404.Sh HISTORY 405The object caching system appeared in 406.Dx 1.3 . 407.Sh AUTHORS 408The object caching system was written by 409.An -nosplit 410.An Jeffrey M. Hsu Aq Mt hsu@freebsd.org . 411This manual page was written by 412.An Stathis Kamperis Aq Mt ekamperi@gmail.com . 413