kmem_cache_create(9F) Kernel Functions for Drivers kmem_cache_create(9F)NAME
kmem_cache_create, kmem_cache_alloc, kmem_cache_free,
kmem_cache_destroy - kernel memory cache allocator operations
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, intkmflag);
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 follows:
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 Possible flags are:
KM_SLEEP Allow sleeping (blocking) until memory is
available.
KM_NOSLEEP Return NULL immediately if memory is not
available.
KM_PUSHPAGE Allow the allocation to use reserved mem‐
ory.
*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_cre‐
ate(); it is typically a pointer to the soft-state
structure.
int kmflags Propagated kmflag values.
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_cre‐
ate(); it is typically a pointer to the soft-state struc‐
ture.
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 pre‐
serve the invariant portion of an object's initial state, or con‐
structed state, between uses, so it does not have to be destroyed and
re-created every time the object is used. For example, an object con‐
taining a mutex only needs to have mutex_init() applied once, the first
time the object is allocated. The object can then be freed and reallo‐
cated many times without incurring the expense of mutex_destroy() and
mutex_init() each time. An object's embedded locks, condition vari‐
ables, 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 destructor convert plain memory into objects
and back again; constructor can fail if it needs to allocate memory but
cannot. 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 debug‐
ging, 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 has either KM_SLEEP or KM_NOSLEEP set,
indicating whether it is acceptable to wait for memory if none is cur‐
rently available.
A small pool of reserved memory is available to allow the system to
progress toward the goal of freeing additional memory while in a low
memory situation. The KM_PUSHPAGE flag enables use of this reserved
memory pool on an allocation. This flag can be used by drivers that
implement strategy(9E) on memory allocations associated with a single
I/O operation. The driver guarantees that the I/O operation will com‐
plete (or timeout) and, on completion, that the memory will be
returned. The KM_PUSHPAGE flag should be used only in
kmem_cache_alloc() calls. All allocations from a given cache should be
consistent in their use of the flag. A driver that adheres to these
restrictions can guarantee progress in a low memory situation without
resorting to complex private allocation and queuing schemes. If
KM_PUSHPAGE is specified, KM_SLEEP can also be used without causing
deadlock.
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 constructor 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 interrupt con‐
text.
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 out‐
standing 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 allocated 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 but expensive overhead. All of this
overhead (that is, everything other than use foo above) can be elimi‐
nated by object caching.
int
foo_constructor(void *buf, void *arg, int tags)
{
struct foo *foo = buf;
mutex_init(&foo->foo_lock, ...);
cv_init(&foo->foo_cv, ...);
foo->foo_refcnt = 0;
foo->foo_barlist = NULL;
return (0);
}
void
foo_destructor(void *buf, void *arg)
{
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, respectively.
RETURN VALUES
If successful, the constructor function must return 0. If KM_NOSLEEP is
set and memory cannot be allocated without sleeping, the constructor
must return -1.
kmem_cache_create() returns a pointer to the allocated cache. If the
name parameter contains non-alphanumeric characters, kmem_cache_cre‐
ate() 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 attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOcondvar(9F), kmem_alloc(9F), mutex(9F), kstat(9S)
The Slab Allocator: An Object-Caching Kernel Memory Allocator, Bonwick,
J.; USENIX Summer 1994 Technical Conference (1994).
SunOS 5.10 14 Jan 2003 kmem_cache_create(9F)
