kmem_cache_alloc(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, 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  fol-
     lows:

     name           Descriptive name of a kstat(9S) structure  of
                    class  kmem_cache.  Only alphanumeric charac-
                    ters 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 memory.

     *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    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_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 has either KM_SLEEP
     or KM_NOSLEEP set, indicating whether it  is  acceptable  to
     wait for memory if none is currently 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 opera-
     tion. 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  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 but expen-
     sive overhead. All of this  overhead  (that  is,  everything
     other  than use foo above) can be eliminated by object cach-
     ing.

       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, respec-
     tively.

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 char-
     acters, 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)

     The Slab Allocator: An Object-Caching Kernel Memory  Alloca-
     tor,  Bonwick,  J.;  USENIX Summer 1994 Technical Conference
     (1994).