2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH UMEM_CACHE_CREATE 3MALLOC "Mar 24, 2008"
8 umem_cache_create, umem_cache_destroy, umem_cache_alloc, umem_cache_free \-
9 allocation cache manipulation
13 cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary \&.\|.\|.\fR ]
16 \fBumem_cache_t *\fR\fBumem_cache_create\fR(\fBchar *\fR\fIdebug_name\fR, \fBsize_t\fR \fIbufsize\fR,
17 \fBsize_t\fR \fIalign\fR, \fBumem_constructor_t *\fR\fIconstructor\fR,
18 \fBumem_destructor_t *\fR\fIdestructor\fR, \fBumem_reclaim_t *\fR\fIreclaim\fR,
19 \fBvoid *\fR\fIcallback_data\fR, \fBvmem_t *\fR\fIsource\fR, \fBint\fR \fIcflags\fR);
24 \fBvoid\fR \fBumem_cache_destroy\fR(\fBumem_cache_t *\fR\fIcache\fR);
29 \fBvoid *\fR\fBumem_cache_alloc\fR(\fBumem_cache_t *\fR\fIcache\fR, \fBint\fR \fIflags\fR);
34 \fBvoid\fR \fBumem_cache_free\fR(\fBumem_cache_t *\fR\fIcache\fR, \fBvoid *\fR\fIbuffer\fR);
40 These functions create, destroy, and use an "object cache" An object cache is
41 a collection of buffers of a single size, with optional content caching enabled
42 by the use of callbacks (see \fBCache Callbacks\fR). Object caches are
43 MT-Safe. Multiple allocations and freeing of memory from different threads can
44 proceed simultaneously. Object caches are faster and use less space per buffer
45 than \fBmalloc\fR(3MALLOC) and \fBumem_alloc\fR(3MALLOC). For more information
46 about object caching, see "The Slab Allocator: An Object-Caching Kernel Memory
47 Allocator" and "Magazines and vmem: Extending the Slab Allocator to Many CPUs
48 and Arbitrary Resources".
51 The \fBumem_cache_create()\fR function creates object caches. Once a cache has
52 been created, objects can be requested from and returned to the cache using
53 \fBumem_cache_alloc()\fR and \fBumem_cache_free()\fR, respectively. A cache
54 with no outstanding buffers can be destroyed with \fBumem_cache_destroy()\fR.
55 .SS "Creating and Destroying Caches"
58 The \fBumem_cache_create()\fR function creates a cache of objects and takes as
59 arguments the following:
63 \fB\fIdebug_name\fR\fR
66 A human-readable name for debugging purposes.
75 The size, in bytes, of the buffers in this cache.
84 The minimum alignment required for buffers in this cache. This parameter must
85 be a power of 2. If 0, it is replaced with the minimum required alignment for
86 the current architecture.
92 \fB\fIconstructor\fR\fR
95 The callback to construct an object.
101 \fB\fIdestructor\fR\fR
104 The callback to destroy an object.
113 The callback to reclaim objects.
119 \fB\fIcallback_data\fR\fR
122 An opaque pointer passed to the callbacks.
131 This parameter must be \fINULL\fR.
140 This parameter must be either 0 or \fBUMC_NODEBUG\fR. If \fBUMC_NODEBUG\fR, all
141 debugging features are disabled for this cache. See \fBumem_debug\fR(3MALLOC).
146 Each cache can have up to three associated callbacks:
150 int constructor(void *buffer, void *callback_data, int flags);
151 void destructor(void *buffer, void *callback_data);
152 void reclaim(void *callback_data);
158 The \fIcallback_data\fR argument is always equal to the value passed to
159 \fBumem_cache_create()\fR, thereby allowing a client to use the same callback
160 functions for multiple caches, but with customized behavior.
163 The reclaim callback is called when the umem function is requesting more memory
164 from the operating system. This callback can be used by clients who retain
165 objects longer than they are strictly needed (for example, caching non-active
166 state). A typical reclaim callback might return to the cache ten per cent of
167 the unneeded buffers.
170 The constructor and destructor callbacks enable the management of buffers with
171 the constructed state. The constructor takes as arguments a buffer with
172 undefined contents, some callback data, and the flags to use for any
173 allocations. This callback should transform the buffer into the constructed
177 The destructor callback takes as an argument a constructed object and prepares
178 it for return to the general pool of memory. The destructor should undo any
179 state that the constructor created. For debugging, the destructor can also
180 check that the buffer is in the constructed state, to catch incorrectly freed
181 buffers. See \fBumem_debug\fR(3MALLOC) for further information on debugging
185 The \fBumem_cache_destroy()\fR function destroys an object cache. If the cache
186 has any outstanding allocations, the behavior is undefined.
187 .SS "Allocating Objects"
190 The \fBumem_cache_alloc()\fR function takes as arguments:
206 flags that determine the behavior if \fBumem_cache_alloc()\fR is unable to
207 fulfill the allocation request
212 If successful, \fBumem_cache_alloc()\fR returns a pointer to the beginning of
213 an object of \fIbufsize\fR length.
216 There are three cases to consider:
221 A new buffer needed to be allocated. If the cache was created with a
222 constructor, it is applied to the buffer and the resulting object is returned.
228 The object cache was able to use a previously freed buffer. If the cache was
229 created with a constructor, the object is returned unchanged from when it was
236 The allocation of a new buffer failed. The \fIflags\fR argument determines the
243 \fB\fBUMEM_DEFAULT\fR\fR
246 The \fBumem_cache_alloc()\fR function returns \fINULL\fR if the allocation
253 \fB\fBUMEM_NOFAIL\fR\fR
256 The \fBumem_cache_alloc()\fR function cannot return \fINULL\fR. A callback is
257 used to determine what action occurs. See \fBumem_alloc\fR(3MALLOC) for more
264 .SS "Freeing Objects"
267 The \fBumem_cache_free()\fR function takes as arguments:
283 a pointer previously returned from \fBumem_cache_alloc()\fR. This argument must
289 If the cache was created with a constructor callback, the object must be
290 returned to the constructed state before it is freed.
293 Undefined behavior results if an object is freed multiple times, if an object
294 is modified after it is freed, or if an object is freed to a cache other than
295 the one from which it was allocated.
296 .SS "Caches with Constructors"
299 When a constructor callback is in use, there is essentially a contract between
300 the cache and its clients. The cache guarantees that all objects returned from
301 \fBumem_cache_alloc()\fR will be in the constructed state, and the client
302 guarantees that it will return the object to the constructed state before
303 handing it to \fBumem_cache_free()\fR.
307 Upon failure, the \fBumem_cache_create()\fR function returns a null pointer.
311 The \fBumem_cache_create()\fR function will fail if:
318 There is not enough memory available to allocate the cache data structure.
327 The \fIdebug_name\fR argument is \fINULL\fR, the \fIalign\fR argument is not a
328 power of two or is larger than the system pagesize, or the \fIbufsize\fR
338 The \fBlibumem\fR library could not be initialized, or the \fIbufsize\fR
339 argument is too large and its use would cause integer overflow to occur.
344 \fBExample 1 \fRUse a fixed-size structure with no constructor callback.
350 typedef struct my_obj {
355 * my_objs can be freed at any time. The contents of
356 * my_data1 is undefined at allocation time.
359 umem_cache_t *my_obj_cache;
362 my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t),
363 0, NULL, NULL, NULL, NULL, NULL, 0);
365 my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT);
369 umem_cache_free(my_obj_cache, cur);
375 \fBExample 2 \fRUse an object with a mutex.
382 typedef struct my_obj {
388 * my_objs can only be freed when my_mutex is unlocked.
391 my_obj_constructor(void *buf, void *ignored, int flags)
393 my_obj_t *myobj = buf;
395 (void) mutex_init(&my_obj->my_mutex, USYNC_THREAD, NULL);
401 my_obj_destructor(void *buf, void *ignored)
403 my_obj_t *myobj = buf;
405 (void) mutex_destroy(&my_obj->my_mutex);
408 umem_cache_t *my_obj_cache;
411 my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t),
412 0, my_obj_constructor, my_obj_destructor, NULL, NULL,
415 my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT);
416 cur->my_data = 0; /* cannot assume anything about my_data */
418 umem_cache_free(my_obj_cache, cur);
424 \fBExample 3 \fRUse a more complex object with a mutex.
432 typedef struct my_obj {
435 struct bar *my_barlist;
436 unsigned my_refcount;
440 * my_objs can only be freed when my_barlist == NULL,
441 * my_refcount == 0, there are no waiters on my_cv, and
442 * my_mutex is unlocked.
446 my_obj_constructor(void *buf, void *ignored, int flags)
448 my_obj_t *myobj = buf;
450 (void) mutex_init(&my_obj->my_mutex, USYNC_THREAD, NULL);
451 (void) cond_init(&my_obj->my_cv, USYNC_THREAD, NULL);
452 myobj->my_barlist = NULL;
453 myobj->my_refcount = 0;
459 my_obj_destructor(void *buf, void *ignored)
461 my_obj_t *myobj = buf;
463 assert(myobj->my_refcount == 0);
464 assert(myobj->my_barlist == NULL);
465 (void) cond_destroy(&my_obj->my_cv);
466 (void) mutex_destroy(&my_obj->my_mutex);
469 umem_cache_t *my_obj_cache;
472 my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t),
473 0, my_obj_constructor, my_obj_destructor, NULL, NULL,
476 my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT);
480 umem_cache_free(my_obj_cache, cur);
486 \fBExample 4 \fRUse objects with a subordinate buffer while reusing callbacks.
493 typedef struct my_obj {
499 * my_size and the my_buffer pointer should never be changed
503 my_obj_constructor(void *buf, void *arg, int flags)
505 size_t sz = (size_t)arg;
507 my_obj_t *myobj = buf;
509 if ((myobj->my_buffer = umem_alloc(sz, flags)) == NULL)
518 my_obj_destructor(void *buf, void *arg)
520 size_t sz = (size_t)arg;
522 my_obj_t *myobj = buf;
524 assert(sz == buf->my_size);
525 umem_free(myobj->my_buffer, sz);
529 umem_cache_t *my_obj_4k_cache;
530 umem_cache_t *my_obj_8k_cache;
532 my_obj_cache_4k = umem_cache_create("my_obj_4k", sizeof (my_obj_t),
533 0, my_obj_constructor, my_obj_destructor, NULL,
534 (void *)4096, NULL, 0);
536 my_obj_cache_8k = umem_cache_create("my_obj_8k", sizeof (my_obj_t),
537 0, my_obj_constructor, my_obj_destructor, NULL,
538 (void *)8192, NULL, 0);
540 my_obj_t *my_obj_4k = umem_cache_alloc(my_obj_4k_cache,
542 my_obj_t *my_obj_8k = umem_cache_alloc(my_obj_8k_cache,
544 /* no assumptions should be made about the contents
547 /* make sure to return them to the correct cache */
548 umem_cache_free(my_obj_4k_cache, my_obj_4k);
549 umem_cache_free(my_obj_8k_cache, my_obj_8k);
556 See the \fBEXAMPLES\fR section of \fBumem_alloc\fR(3MALLOC) for examples
557 involving the \fBUMEM_NOFAIL\fR flag.
561 See \fBattributes\fR(5) for descriptions of the following attributes:
569 ATTRIBUTE TYPE ATTRIBUTE VALUE
571 Interface Stability Committed
579 \fBsetcontext\fR(2), \fBatexit\fR(3C), \fBlibumem\fR(3LIB), \fBlongjmp\fR(3C),
580 \fBswapcontext\fR(3C), \fBthr_exit\fR(3C), \fBumem_alloc\fR(3MALLOC),
581 \fBumem_debug\fR(3MALLOC), \fBattributes\fR(5)
584 Bonwick, Jeff, "The Slab Allocator: An Object-Caching Kernel Memory Allocator",
585 Proceedings of the Summer 1994 Usenix Conference.
588 Bonwick, Jeff and Jonathan Adams, "Magazines and vmem: Extending the Slab
589 Allocator to Many CPUs and Arbitrary Resources", Proceedings of the Summer 2001
594 Any of the following can cause undefined results:
599 Destroying a cache that has outstanding allocated buffers.
605 Using a cache after it has been destroyed.
611 Calling \fBumem_cache_free()\fR on the same buffer multiple times.
617 Passing a \fINULL\fR pointer to \fBumem_cache_free()\fR.
623 Writing past the end of a buffer.
629 Reading from or writing to a buffer after it has been freed.
635 Performing \fBUMEM_NOFAIL\fR allocations from an \fBatexit\fR(3C) handler.
639 Per-cache callbacks can be called from a variety of contexts. The use of
640 functions that modify the active context, such as \fBsetcontext\fR(2),
641 \fBswapcontext\fR(3C), and \fBthr_exit\fR(3C), or functions that are unsafe for
642 use in multithreaded applications, such as \fBlongjmp\fR(3C) and
643 \fBsiglongjmp\fR(3C), result in undefined behavior.
646 A constructor callback that performs allocations must pass its \fIflags\fR
647 argument unchanged to \fBumem_alloc\fR(3MALLOC) and \fBumem_cache_alloc()\fR.
648 Any allocations made with a different flags argument results in undefined
649 behavior. The constructor must correctly handle the failure of any allocations
654 Object caches make the following guarantees about objects:
659 If the cache has a constructor callback, it is applied to every object before
660 it is returned from \fBumem_cache_alloc()\fR for the first time.
666 If the cache has a constructor callback, an object passed to
667 \fBumem_cache_free()\fR and later returned from \fBumem_cache_alloc()\fR is not
668 modified between the two events.
674 If the cache has a destructor, it is applied to all objects before their
675 underlying storage is returned.
679 No other guarantees are made. In particular, even if there are buffers recently
680 freed to the cache, \fBumem_cache_alloc()\fR can fail.