Movatterモバイル変換

cc [flag … ]file…-lumem [library … ] #include <umem.h>umem_cache_t *umem_cache_create(char *debug_name,size_tbufsize,size_talign,umem_constructor_t *constructor,umem_destructor_t *destructor,umem_reclaim_t *reclaim,void *callback_data,vmem_t *source,intcflags);

voidumem_cache_destroy(umem_cache_t *cache);

void *umem_cache_alloc(umem_cache_t *cache,intflags);

voidumem_cache_free(umem_cache_t *cache,void *buffer);

Description

These functions create, destroy, and use an “object cache” An objectcache is a collection of buffers of a single size, with optionalcontent caching enabled by the use of callbacks (seeCache Callbacks). Objectcaches are MT-Safe. Multiple allocations and freeing of memory from different threads canproceed simultaneously. Object caches are faster and use less space perbuffer thanmalloc(3MALLOC) andumem_alloc(3MALLOC). For more information about object caching,see “The Slab Allocator: An Object-Caching Kernel Memory Allocator” and “Magazines and vmem:Extending the Slab Allocator to Many CPUs and Arbitrary Resources”.

Theumem_cache_create() function creates object caches. Once a cache has been created,objects can be requested from and returned to the cache usingumem_cache_alloc()andumem_cache_free(), respectively. A cache with no outstanding buffers can be destroyed withumem_cache_destroy().

Creating and Destroying Caches

Theumem_cache_create() function creates a cache of objects and takes as argumentsthe following:

debug_name: A human-readable name for debugging purposes.
bufsize: The size, in bytes, of the buffers in this cache.
align: The minimum alignment required for buffers in this cache. This parameter must be a power of 2. If 0, it is replaced with the minimum required alignment for the current architecture.
constructor: The callback to construct an object.
destructor: The callback to destroy an object.
reclaim: The callback to reclaim objects.
callback_data: An opaque pointer passed to the callbacks.
source: This parameter must beNULL.
cflags: This parameter must be either 0 orUMC_NODEBUG. IfUMC_NODEBUG, all debugging features are disabled for this cache. Seeumem_debug(3MALLOC).

Each cache can have up to three associated callbacks:

int constructor(void *buffer, void *callback_data, int flags);void destructor(void *buffer, void *callback_data);void reclaim(void *callback_data);

Thecallback_data argument is always equal to the value passed toumem_cache_create(),thereby allowing a client to use the same callback functions for multiplecaches, but with customized behavior.

The reclaim callback is called when the umem function is requesting morememory from the operating system. This callback can be used by clientswho retain objects longer than they are strictly needed (for example, cachingnon-active state). A typical reclaim callback might return to the cache tenper cent of the unneeded buffers.

The constructor and destructor callbacks enable the management of buffers with theconstructed state. The constructor takes as arguments a buffer with undefined contents,some callback data, and the flags to use for any allocations. Thiscallback should transform the buffer into the constructed state.

The destructor callback takes as an argument a constructed object and preparesit for return to the general pool of memory. The destructorshould undo any state that the constructor created. For debugging, thedestructor can also check that the buffer is in the constructed state,to catch incorrectly freed buffers. Seeumem_debug(3MALLOC) for further information on debuggingsupport.

Theumem_cache_destroy() function destroys an object cache. If the cache has anyoutstanding allocations, the behavior is undefined.

Allocating Objects

Theumem_cache_alloc() function takes as arguments:

cache: a cache pointer
flags: flags that determine the behavior ifumem_cache_alloc() is unable to fulfill the allocation request

If successful,umem_cache_alloc() returns a pointer to the beginning of an objectofbufsize length.

There are three cases to consider:

A new buffer needed to be allocated. If the cache was created with a constructor, it is applied to the buffer and the resulting object is returned.
The object cache was able to use a previously freed buffer. If the cache was created with a constructor, the object is returned unchanged from when it was freed.
The allocation of a new buffer failed. Theflags argument determines the behavior:
UMEM_DEFAULT
Theumem_cache_alloc() function returnsNULL if the allocation fails.
UMEM_NOFAIL
Theumem_cache_alloc() function cannot returnNULL. A callback is used to determine what action occurs. Seeumem_alloc(3MALLOC) for more information.

Freeing Objects

Theumem_cache_free() function takes as arguments:

cache: a cache pointer
buf: a pointer previously returned fromumem_cache_alloc(). This argument must not beNULL.

If the cache was created with a constructor callback, the object mustbe returned to the constructed state before it is freed.

Undefined behavior results if an object is freed multiple times, if anobject is modified after it is freed, or if an object isfreed to a cache other than the one from which it wasallocated.

Caches with Constructors

When a constructor callback is in use, there is essentially a contractbetween the cache and its clients. The cache guarantees that allobjects returned fromumem_cache_alloc() will be in the constructed state, and theclient guarantees that it will return the object to the constructed state beforehanding it toumem_cache_free().

Return Values

Upon failure, theumem_cache_create() function returns a null pointer.

Errors

Theumem_cache_create() function will fail if:

EAGAIN: There is not enough memory available to allocate the cache data structure.
EINVAL: Thedebug_name argument isNULL, thealign argument is not a power of two or is larger than the system pagesize, or thebufsize argument is 0.
ENOMEM: Thelibumem library could not be initialized, or thebufsize argument is too large and its use would cause integer overflow to occur.

Examples

Example 1 Use a fixed-size structure with no constructor callback.

#include <umem.h>typedef struct my_obj {     long my_data1;} my_obj_t;/* * my_objs can be freed at any time.  The contents of * my_data1 is undefined at allocation time. */umem_cache_t *my_obj_cache;...my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t),    0, NULL, NULL, NULL, NULL, NULL, 0);...my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT);.../* use cur */...umem_cache_free(my_obj_cache, cur);...

Example 2 Use an object with a mutex.

#define _REENTRANT#include <synch.h>#include <umem.h> typedef struct my_obj {          mutex_t my_mutex;          long my_data;} my_obj_t; /* * my_objs can only be freed when my_mutex is unlocked. */intmy_obj_constructor(void *buf, void *ignored, int flags){          my_obj_t *myobj = buf;           (void) mutex_init(&my_obj->my_mutex, USYNC_THREAD, NULL);           return (0);} voidmy_obj_destructor(void *buf, void *ignored){          my_obj_t *myobj = buf;           (void) mutex_destroy(&my_obj->my_mutex);} umem_cache_t *my_obj_cache; ...my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t),    0, my_obj_constructor, my_obj_destructor, NULL, NULL,         NULL, 0);...my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT);cur->my_data = 0;       /* cannot assume anything about my_data */...umem_cache_free(my_obj_cache, cur);...

Example 3 Use a more complex object with a mutex.

#define _REENTRANT#include <assert.h>#include <synch.h>#include <umem.h>typedef struct my_obj {          mutex_t my_mutex;          cond_t my_cv;          struct bar *my_barlist;          unsigned my_refcount;} my_obj_t;/* * my_objs can only be freed when my_barlist == NULL, * my_refcount == 0, there are no waiters on my_cv, and * my_mutex is unlocked. */intmy_obj_constructor(void *buf, void *ignored, int flags){          my_obj_t *myobj = buf;          (void) mutex_init(&my_obj->my_mutex, USYNC_THREAD, NULL);          (void) cond_init(&my_obj->my_cv, USYNC_THREAD, NULL);          myobj->my_barlist = NULL;          myobj->my_refcount = 0;          return (0);}voidmy_obj_destructor(void *buf, void *ignored){          my_obj_t *myobj = buf;          assert(myobj->my_refcount == 0);          assert(myobj->my_barlist == NULL);          (void) cond_destroy(&my_obj->my_cv);          (void) mutex_destroy(&my_obj->my_mutex);}umem_cache_t *my_obj_cache;...my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t),    0, my_obj_constructor, my_obj_destructor, NULL, NULL,         NULL, 0);...my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT);.../* use cur */...umem_cache_free(my_obj_cache, cur);...

Example 4 Use objects with a subordinate buffer while reusing callbacks.

#include assert.h>#include umem.h>typedef struct my_obj {          char *my_buffer;          size_t my_size;} my_obj_t; /* * my_size and the my_buffer pointer should never be changed */ intmy_obj_constructor(void *buf, void *arg, int flags){          size_t sz = (size_t)arg;           my_obj_t *myobj = buf;           if ((myobj->my_buffer = umem_alloc(sz, flags)) == NULL)                return (1);           my_size = sz;           return (0);} voidmy_obj_destructor(void *buf, void *arg){          size_t sz = (size_t)arg;           my_obj_t *myobj = buf;           assert(sz == buf->my_size);          umem_free(myobj->my_buffer, sz);} ...umem_cache_t *my_obj_4k_cache;umem_cache_t *my_obj_8k_cache;...my_obj_cache_4k = umem_cache_create("my_obj_4k", sizeof (my_obj_t),         0, my_obj_constructor, my_obj_destructor, NULL,          (void *)4096, NULL, 0); my_obj_cache_8k = umem_cache_create("my_obj_8k", sizeof (my_obj_t),         0, my_obj_constructor, my_obj_destructor, NULL,          (void *)8192, NULL, 0);...my_obj_t *my_obj_4k = umem_cache_alloc(my_obj_4k_cache,         UMEM_DEFAULT);my_obj_t *my_obj_8k = umem_cache_alloc(my_obj_8k_cache,         UMEM_DEFAULT);/* no assumptions should be made about the contents of the buffers */.../* make sure to return them to the correct cache */umem_cache_free(my_obj_4k_cache, my_obj_4k);umem_cache_free(my_obj_8k_cache, my_obj_8k);...

See theEXAMPLES section ofumem_alloc(3MALLOC) for examples involving theUMEM_NOFAIL flag.

Attributes

Seeattributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed
MT-Level	MT-Safe

Warnings

Any of the following can cause undefined results:

Destroying a cache that has outstanding allocated buffers.
Using a cache after it has been destroyed.
Callingumem_cache_free() on the same buffer multiple times.
Passing aNULL pointer toumem_cache_free().
Writing past the end of a buffer.
Reading from or writing to a buffer after it has been freed.
PerformingUMEM_NOFAIL allocations from anatexit(3C) handler.

Per-cache callbacks can be called from a variety of contexts. The useof functions that modify the active context, such assetcontext(2),swapcontext(3C), andthr_exit(3C), or functions that are unsafe for use in multithreaded applications, such aslongjmp(3C) andsiglongjmp(3C), result in undefined behavior.

A constructor callback that performs allocations must pass itsflags argument unchangedtoumem_alloc(3MALLOC) andumem_cache_alloc(). Any allocations made with a different flags argumentresults in undefined behavior. The constructor must correctly handle the failureof any allocations it makes.

Notes

Object caches make the following guarantees about objects:

If the cache has a constructor callback, it is applied to every object before it is returned fromumem_cache_alloc() for the first time.
If the cache has a constructor callback, an object passed toumem_cache_free() and later returned fromumem_cache_alloc() is not modified between the two events.
If the cache has a destructor, it is applied to all objects before their underlying storage is returned.

No other guarantees are made. In particular, even if there are buffersrecently freed to the cache,umem_cache_alloc() can fail.

Skip Navigation Links
Exit Print View
	man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library

Movatterモバイル変換

umem_cache_create

, umem_cache_destroy

, umem_cache_alloc

, umem_cache_free

Synopsis