kmem_cache_destroy(9F) (man pages section 9: DDI and DKI Kernel Functions)

man pages section 9: DDI and DKI Kernel Functions

kmem_cache_destroy(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>

name

bufsize

align

constructor

destructor

reclaim

private

vmp

cflags

cp

kmflag

cp

obj

constructor

buf

un

kmflags

destructor

buf

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: Determines whether caller can sleep for memory. Possible 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. Possible 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:

frequently allocated and freed, and
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 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 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 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 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 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 more expensive 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, respectively.

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 attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving