share/man/man9/kref.9

   1 .\"
   2 .\" Copyright (c) 2010, The DragonFly Project.
   3 .\"
   4 .\" This software is derived from software contributed to the DragonFly Project
   5 .\" by Venkatesh Srinivas <me@endeavour.zapto.org>.
   6 .\"
   7 .\" Permission to use, copy, modify, or distribute this software for any
   8 .\" purpose with or without fee is hereby granted, provided that the above
   9 .\" copyright notice and this permission notice appear in all copies.
  10 .\"
  11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  12 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  13 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  14 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR OTHER DAMAGES
  15 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN
  16 .\" ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF
  17 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd December 21, 2010
  20 .Dt KREF 9
  21 .Os
  22 .Sh NAME
  23 .Nm kref_init ,
  24 .Nm kref_inc ,
  25 .Nm kref_dec
  26 .Nd lightweight reference counts
  27 .Sh SYNOPSIS
  28 .In sys/ref.h
  29 .Ft void
  30 .Fn kref_init "struct kref *ref" "int count"
  31 .Ft void
  32 .Fn kref_inc "struct kref *ref"
  33 .Ft int
  34 .Fn kref_dec "struct kref *ref" "void (*deconstruct)(void *, void *)" \
  35 "void *priv1" "void *priv2"
  36 .Sh DESCRIPTION
  37 .Pp
  38 Kref is a lightweight reference counting system applicable to many dynamically
  39 allocated structures. The space overhead of a reference count is only one
  40 machine word.
  41 .Pp
  42 The
  43 .Fn kref_init
  44 function initializes a reference to the value
  45 .Fa count .
  46 .Pp
  47 The
  48 .Fn kref_inc
  49 function increments a reference atomically with respect to preemption and to
  50 concurrent
  51 .Fn kref_inc
  52 calls.
  53 .Pp
  54 The
  55 .Fn kref_dec
  56 function decrements a reference atomically with respect to preemption and to
  57 concurrent
  58 .Fn kref_dec
  59 calls. If the reference transitions from 1 to 0, the
  60 .Fa deconstruct
  61 function is called with
  62 .Fa priv1
  63 and
  64 .Fa priv2
  65 as arguments. The
  66 .Fa deconstruct
  67 argument may be NULL.
  68 .Fn kref_dec
  69 returns 0 if it sees a 1 to 0 transition, 1 otherwise.
  70 .Sh NOTES
  71 .Pp
  72 An object cannot synchronize its own visibility. Therefore care must be taken
  73 when interleaving calls to kref_inc and kref_dec; higher level synchronization
  74 is often required.
  75 .Sh EXAMPLE
  76 Simple use of kref with a
  77 .Xr kmalloc 9
  78 allocated structure:
  79 .Bd -literal
  80 struct interesting {
  81         int ctr;
  82         struct kref ref;
  83 };
  84
  85 struct interesting *thing = kmalloc(sizeof(struct interesting), M_DEVBUF);
  86 /* Setup reference to 1 */
  87 kref_init(&thing->ref, 1);
  88
  89 /* 1 -> 2 transition */
  90 kref_inc(&thing->ref);
  91
  92 /* 2 -> 1 transition ; don't call deconstruct (kfree) */
  93 kref_dec(&thing->ref, kfree, thing, M_DEVBUF);
  94
  95 /* 1 -> 0 transition, so call kfree to release thing */
  96 kref_dec(&thing->ref, kfree, thing, M_DEVBUF);
  97 .Ed
  98 .Sh FILES
  99 The kref implementation is in
 100 .Pa /sys/kern/kern_ref.c .
 101 .Sh HISTORY
 102 kref first appeared in
 103 .Dx 2.9 .