kmem_cache_destroy man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

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 ALSO
       condvar(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)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net