share/man/man9/objcache.9

   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_limit0"
  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
 102 Object caching is a technique for manipulating objects that are frequently
 103 allocated and freed.
 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.
 107 .Pp
 108 .Fn objcache_create
 109 creates a new object cache.
 110 It is identified by
 111 .Fa name ,
 112 which is used to distinguish the object in diagnostic output.
 113 The
 114 .Fa cluster_limit0
 115 determines the number of available magazines in the depot layer.
 116 It must be at least
 117 .Fa mag_capacity *
 118 ncpus * 8.
 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).
 122 The
 123 .Fa mag_capacity
 124 describes the capacity of the magazine, that is the largest number of objects
 125 it can hold.
 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.
 131 .Fa ctor
 132 specifies a function that constructs (i.e., performs the one-time
 133 initialization of) an object in the cache.
 134 It is defined as:
 135 .Bd -literal
 136 boolean_t foo_ctor(void *obj, void *privdata, int ocflags);
 137 .Ed
 138 .Pp
 139 If no constructor is needed, it must be set to
 140 .Dv NULL .
 141 .Fa dtor
 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.
 144 It is defined as:
 145 .Bd -literal
 146 void foo_dtor(void *obj, void *privdata);
 147 .Ed
 148 .Pp
 149 If no deconstructor is needed, it must be set to
 150 .Dv NULL .
 151 The interface to underlying allocator is provided by
 152 .Fa alloc ,
 153 .Fa free
 154 and
 155 .Fa allocator_args .
 156 It must adhere to the following form:
 157 .Bd -literal
 158 void *foo_alloc(void *allocator_args, int ocflags);
 159 void foo_free(void *obj, void *allocator_args);
 160 .Ed
 161 .Pp
 162 .Fn objcache_malloc_alloc
 163 and
 164 .Fn objcache_malloc_free
 165 are wrappers for
 166 .Xr kmalloc 9
 167 allocation functions.
 168 Whereas,
 169 .Fn objcache_nop_alloc
 170 and
 171 .Fn objcache_nop_free
 172 are wrappers for allocation policies that pre-allocate at initialization time
 173 instead of doing run-time allocation.
 174 .Pp
 175 .Fn objcache_create_mbacked
 176 creates a new object cache of size
 177 .Fa objsize ,
 178 backed with a
 179 .Vt malloc_type_t
 180 argument.
 181 The latter is used to perform statistics in memory usage and for basic sanity
 182 checks.
 183 For the underlying allocator,
 184 .Xr kmalloc 9
 185 functions are employed.
 186 .Pp
 187 .Fn objcache_create_simple
 188 creates a new object cache of size
 189 .Fa objsize ,
 190 backed with a
 191 .Vt malloc_type_t
 192 argument.
 193 The
 194 .Fa cluster_limit0
 195 is set to 0 and the default value for magazines' capacity is used.
 196 .Fa ctor
 197 and
 198 .Fa dtor
 199 are set to
 200 .Dv NULL .
 201 .Fa privdata
 202 is  set to
 203 .Dv NULL
 204 as well.
 205 For the underlying allocator,
 206 .Xr kmalloc 9
 207 functions are employed.
 208 .Pp
 209 .Fn objcache_get
 210 returns an object from the
 211 .Fa oc
 212 object cache.
 213 The object is in its initialized state.
 214 Newly allocated objects are subjected to the object cache's constructor
 215 function, if not
 216 .Dv NULL ,
 217 prior to being returned.
 218 .Fa ocflags
 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
 222 .Dv M_ZERO .
 223 If the back end allocator fails, or if the depot's object limit has been
 224 reached and
 225 .Dv M_WAITOK
 226 is not specified,
 227 .Dv NULL
 228 is returned.
 229 .Pp
 230 .Fn objcache_put
 231 returns
 232 .Fa obj
 233 to the
 234 .Fa oc
 235 object cache.
 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
 238 the object is freed.
 239 .Pp
 240 .Fn objcache_dtor
 241 puts
 242 .Fa obj
 243 back into the
 244 .Fa oc
 245 object cache, indicating that the object is not in any shape to be reused and
 246 should be deconstructed and freed immediately.
 247 .Pp
 248 .Fn objcache_reclaimlist
 249 iterates over the
 250 .Fa oclist[]
 251 list with
 252 .Fa nlist
 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.
 256 The function returns
 257 .Dv TRUE
 258 as soon as some free memory is found
 259 and
 260 .Dv FALSE
 261 otherwise.
 262 .Pp
 263 .Fn objcache_destroy
 264 destroys the
 265 .Fa oc
 266 object cache.
 267 The 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
 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.
 283 .Pp
 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
 287 magazine boundary.
 288 .Pp
 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.
 294 .Ss Magazine 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.
 301 .Sh EXAMPLES
 302 .Bd -literal
 303 /* This is the data structure we are going to cache. */
 304 struct foo {
 305         int x;
 306         char str[32];
 307 };
 308
 309 MALLOC_DEFINE(M_FOOBUF, "foobuf", "Buffer to my little precious data");
 310
 311 struct objcache_malloc_args foo_malloc_args = {
 312         sizeof(struct foo), M_FOOBUF };
 313
 314 struct objcache *foo_cache;
 315
 316 /*
 317  * Object cache constructor.
 318  */
 319 static boolean_t
 320 foo_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  */
 336 static void
 337 foo_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  */
 350 static void
 351 foo_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  */
 366 static void
 367 foo_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  */
 384 static void
 385 foo_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
 405 The object caching system appeared in
 406 .Dx 1.3 .
 407 .Sh AUTHORS
 408 The object caching system was written by
 409 .An -nosplit
 410 .An "Jeffrey M. Hsu" Aq "hsu@freebsd.org" .
 411 This manual page was written by
 412 .An "Stathis Kamperis" Aq "ekamperi@gmail.com" .