kmem_cache_create(9F)
NAME
kmem_cache_create, kmem_cache_alloc, kmem_cache_free,
kmem_cache_destroy - kernel memory cache allocator opera-
tions
SYNOPSIS
#include <sys/types.h>
#include <sys/kmem.h>
kmem_cache_t *kmem_cache_create(char *name, size_t bufsize,
size_t align, int (*constructor)(void *, void *, int), void
(*destructor)(void *, void *), void (*reclaim)(void *), void
*private, void *vmp, int cflags);
void kmem_cache_destroy(kmem_cache_t *cp);
void *kmem_cache_alloc(kmem_cache_t *cp, int kmflag);
void kmem_cache_free(kmem_cache_t *cp, void *obj);
[Synopsis for callback functions:]
int (*constructor)(void *buf, void *un, int kmflags);
void (*destructor)(void *buf, void *un);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)
PARAMETERS
The parameters for the kmem_cache_* functions are as fol-
lows:
name Descriptive name of a kstat(9S) structure of class
kmem_cache. Only alphanumeric characters can be used
in name.
bufsize
Size of the objects it manages.
align Required object alignment.
constructor
Pointer to an object constructor function. Parameters
are defined below.
destructor
Pointer to an object destructor function. Parameters
are defined below.
reclaim
Drivers should pass NULL.
private
Pass-through argument for constructor/destructor.
vmp Drivers should pass NULL.
cflags
Drivers must pass 0.
kmflag
Determines whether caller can sleep for memory. Possi-
ble flags are KM_SLEEP to allow sleeping until memory
is available, or KM_NOSLEEP to return NULL immediately
if memory is not available.
*obj Pointer to the object allocated by kmem_cache_alloc().
The parameters for the callback constructor function are as
follows:
void *buf
Pointer to the object to be constructed.
void *un
The private parameter from the call to
kmem_cache_create(); it is typically a pointer to the
soft-state structure.
int kmflags
Determines whether caller can sleep for memory. Possi-
ble flags are KM_SLEEP to allow sleeping until memory
is available, or KM_NOSLEEP to return NULL immediately
if memory is not available.
The parameters for the callback destructor function are as
follows:
void *buf
Pointer to the object to be deconstructed.
void *un
The private parameter from the call to
kmem_cache_create(); it is typically a pointer to the
soft-state structure.
DESCRIPTION
In many cases, the cost of initializing and destroying an
object exceeds the cost of allocating and freeing memory for
it. The functions described here address this condition.
Object caching is a technique for dealing with objects that
are:
o frequently allocated and freed, and
o have setup and initialization costs.
The idea is to allow the allocator and its clients to
cooperate to preserve the invariant portion of an object's
initial state, or constructed state, between uses, so it
does not have to be destroyed and re-created every time the
object is used. For example, an object containing a mutex
only needs to have mutex_init() applied once, the first time
the object is allocated. The object can then be freed and
reallocated many times without incurring the expense of
mutex_destroy() and mutex_init() each time. An object's
embedded locks, condition variables, reference counts, lists
of other objects, and read-only data all generally qualify
as constructed state. The essential requirement is that the
client must free the object (using kmem_cache_free()) in its
constructed state. The allocator cannot enforce this, so
programming errors will lead to hard-to-find bugs.
A driver should call kmem_cache_create() at the time of
_init(9E) or attach(9E), and call the corresponding
kmem_cache_destroy() at the time of _fini(9E) or detach(9E).
kmem_cache_create() creates a cache of objects, each of size
size bytes, aligned on an align boundary. Drivers not
requiring a specific alignment can pass 0. name identifies
the cache for statistics and debugging. constructor and des-
tructor convert plain memory into objects and back again;
constructor can fail if it needs to allocate memory but can-
not. private is a parameter passed to the constructor and
destructor callbacks to support parameterized caches (for
example, a pointer to an instance of the driver's soft-state
structure). To facilitate debugging, kmem_cache_create()
creates a kstat(9S) structure of class kmem_cache and name
name. It returns an opaque pointer to the object cache.
kmem_cache_alloc() gets an object from the cache. The object
will be in its constructed state. kmflag is either KM_SLEEP
or KM_NOSLEEP, indicating whether it is acceptable to wait
for memory if none is currently available.
kmem_cache_free() returns an object to the cache. The object
must be in its constructed state.
kmem_cache_destroy() destroys the cache and releases all
associated resources. All allocated objects must have been
previously freed.
CONTEXT
Constructors can be invoked during any call to
kmem_cache_alloc(), and will run in that context. Similarly,
destructors can be invoked during any call to
kmem_cache_free(), and can also be invoked during
kmem_cache_destroy(). Therefore, the functions that a con-
structor or destructor invokes must be appropriate in that
context.
kmem_cache_create() and kmem_cache_destroy() must not be
called from interrupt context.
kmem_cache_alloc() can be called from interrupt context only
if the KM_NOSLEEP flag is set. It can be called from user or
kernel context with any valid flag.
kmem_cache_free() can be called from user, kernel, or inter-
rupt context.
EXAMPLES
Example 1: Object Caching
Consider the following data structure:
struct foo {
kmutex_t foo_lock;
kcondvar_t foo_cv;
struct bar *foo_barlist;
int foo_refcnt;
};
Assume that a foo structure cannot be freed until there are
no outstanding references to it (foo_refcnt == 0) and all of
its pending bar events (whatever they are) have completed
(foo_barlist == NULL). The life cycle of a dynamically allo-
cated foo would be something like this:
foo = kmem_alloc(sizeof (struct foo), KM_SLEEP);
mutex_init(&foo->foo_lock, ...);
cv_init(&foo->foo_cv, ...);
foo->foo_refcnt = 0;
foo->foo_barlist = NULL;
use foo;
ASSERT(foo->foo_barlist == NULL);
ASSERT(foo->foo_refcnt == 0);
cv_destroy(&foo->foo_cv);
mutex_destroy(&foo->foo_lock);
kmem_free(foo);
Notice that between each use of a foo object we perform a
sequence of operations that constitutes nothing more expen-
sive overhead. All of this overhead (that is, everything
other than use foo above) can be eliminated by object
caching.
int
foo_constructor(void *buf, void *arg, int size)
{
struct foo *foo = buf;
mutex_init(&foo->foo_lock, ...);
cv_init(&foo->foo_cv, ...);
foo->foo_refcnt = 0;
foo->foo_barlist = NULL;
}
void
foo_destructor(void *buf, void *arg, int size)
{
struct foo *foo = buf;
ASSERT(foo->foo_barlist == NULL);
ASSERT(foo->foo_refcnt == 0);
cv_destroy(&foo->foo_cv);
mutex_destroy(&foo->foo_lock);
}
un = ddi_get_soft_state(foo_softc, instance);
(void) snprintf(buf, KSTAT_STRLEN, "foo%d_cache",
ddi_get_instance(dip));
foo_cache = kmem_cache_create(buf,
sizeof (struct foo), 0,
foo_constructor, foo_destructor,
NULL, un, 0);
To allocate, use, and free a foo object:
foo = kmem_cache_alloc(foo_cache, KM_SLEEP);
use foo;
kmem_cache_free(foo_cache, foo);
This makes foo allocation fast, because the allocator will
usually do nothing more than fetch an already-constructed
foo from the cache. foo_constructor and foo_destructor will
be invoked only to populate and drain the cache, respec-
tively.
RETURN VALUES
If successful, the constructor function must return a
pointer to the allocated object. If KM_NOSLEEP is set and
memory cannot be allocated without sleeping, the constructor
must return NULL.
kmem_cache_create() returns a pointer to the allocated
cache. If the name parameter contains non-alphanumeric
characters, kmem_cache_create() returns NULL.
If successful, kmem_cache_alloc() returns a pointer to the
allocated object. If KM_NOSLEEP is set and memory cannot be
allocated without sleeping, kmem_cache_alloc() returns NULL.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Evolving |
|_____________________________|_____________________________|
SEE ALSO
condvar(9F), kmem_alloc(9F), mutex(9F), kstat(9S)
Writing Device Drivers
The Slab Allocator: An Object-Caching Kernel Memory Alloca-
tor, Bonwick, J.; USENIX Summer 1994 Technical Conference
(1994).
Man(1) output converted with
man2html