share/man/man9/refcount.9

   1 .\"
   2 .\" Copyright (c) 2009 Hudson River Trading LLC
   3 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Copyright (c) 2019 The FreeBSD Foundation, Inc.
   7 .\"
   8 .\" Parts of this documentation was written by
   9 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
  10 .\" from the FreeBSD Foundation.
  11 .\"
  12 .\" Redistribution and use in source and binary forms, with or without
  13 .\" modification, are permitted provided that the following conditions
  14 .\" are met:
  15 .\" 1. Redistributions of source code must retain the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer.
  17 .\" 2. Redistributions in binary form must reproduce the above copyright
  18 .\"    notice, this list of conditions and the following disclaimer in the
  19 .\"    documentation and/or other materials provided with the distribution.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd November 2, 2020
  36 .Dt REFCOUNT 9
  37 .Os
  38 .Sh NAME
  39 .Nm refcount ,
  40 .Nm refcount_init ,
  41 .Nm refcount_acquire ,
  42 .Nm refcount_release
  43 .Nd manage a simple reference counter
  44 .Sh SYNOPSIS
  45 .In sys/param.h
  46 .In sys/refcount.h
  47 .Ft void
  48 .Fn refcount_init "volatile u_int *count" "u_int value"
  49 .Ft u_int
  50 .Fn refcount_load "volatile u_int *count"
  51 .Ft void
  52 .Fn refcount_acquire "volatile u_int *count"
  53 .Ft bool
  54 .Fn refcount_acquire_checked "volatile u_int *count"
  55 .Ft bool
  56 .Fn refcount_acquire_if_not_zero "volatile u_int *count"
  57 .Ft bool
  58 .Fn refcount_release "volatile u_int *count"
  59 .Ft bool
  60 .Fn refcount_release_if_last "volatile u_int *count"
  61 .Ft bool
  62 .Fn refcount_release_if_not_last "volatile u_int *count"
  63 .Sh DESCRIPTION
  64 The
  65 .Nm
  66 functions provide an API to manage a simple reference counter.
  67 The caller provides the storage for the counter in an unsigned integer.
  68 A pointer to this integer is passed via
  69 .Fa count .
  70 Usually the counter is used to manage the lifetime of an object and is
  71 stored as a member of the object.
  72 .Pp
  73 Currently all functions are implemented as static inline.
  74 .Pp
  75 The
  76 .Fn refcount_init
  77 function is used to set the initial value of the counter to
  78 .Fa value .
  79 It is normally used when creating a reference-counted object.
  80 .Pp
  81 The
  82 .Fn refcount_load
  83 function returns a snapshot of the counter value.
  84 This value may immediately become out-of-date in the absence of external
  85 synchronization.
  86 .Fn refcount_load
  87 should be used instead of relying on the properties of the
  88 .Vt volatile
  89 qualifier.
  90 .Pp
  91 The
  92 .Fn refcount_acquire
  93 function is used to acquire a new reference.
  94 The caller is responsible for ensuring that it holds a valid reference
  95 while obtaining a new reference.
  96 For example,
  97 if an object is stored on a list and the list holds a reference on the
  98 object, then holding a lock that protects the list provides sufficient
  99 protection for acquiring a new reference.
 100 .Pp
 101 The
 102 .Fn refcount_acquire_checked
 103 variant performs the same operation as
 104 .Fn refcount_acquire ,
 105 but additionally checks that the
 106 .Fa count
 107 value does not overflow as result of the operation.
 108 It returns
 109 .Dv true
 110 if the reference was sucessfully obtained, and
 111 .Dv false
 112 if it was not, due to the overflow.
 113 .Pp
 114 The
 115 .Fn refcount_acquire_if_not_zero
 116 function is yet another variant of
 117 .Fn refcount_acquire ,
 118 which only obtains the reference when some reference already exists.
 119 In other words,
 120 .Fa *count
 121 must be already greater than zero for the function to succeed, in which
 122 case the return value is
 123 .Dv true ,
 124 otherwise
 125 .Dv false
 126 is returned.
 127 .Pp
 128 The
 129 .Fn refcount_release
 130 function is used to release an existing reference.
 131 The function returns true if the reference being released was
 132 the last reference;
 133 otherwise, it returns false.
 134 .Pp
 135 The
 136 .Fn refcount_release_if_last
 137 and
 138 .Fn refcount_release_if_not_last
 139 functions are variants of
 140 .Fn refcount_release
 141 which only drop the reference when it is or is not the last reference,
 142 respectively.
 143 In other words,
 144 .Fn refcount_release_if_last
 145 returns
 146 .Dv true
 147 when
 148 .Fa *count
 149 is equal to one, in which case it is decremented to zero.
 150 Otherwise,
 151 .Fa *count
 152 is not modified and the function returns
 153 .Dv false .
 154 Similarly,
 155 .Fn refcount_release_if_not_last
 156 returns
 157 .Dv true
 158 when
 159 .Fa *count
 160 is greater than one, in which case
 161 .Fa *count
 162 is decremented.
 163 Otherwise, if
 164 .Fa *count
 165 is equal to one, the reference is not released and the function returns
 166 .Dv false .
 167 .Pp
 168 Note that these routines do not provide any inter-CPU synchronization or
 169 data protection for managing the counter.
 170 The caller is responsible for any additional synchronization needed by
 171 consumers of any containing objects.
 172 In addition,
 173 the caller is also responsible for managing the life cycle of any containing
 174 objects including explicitly releasing any resources when the last reference
 175 is released.
 176 .Pp
 177 The
 178 .Fn refcount_release
 179 unconditionally executes a release fence (see
 180 .Xr atomic 9 ) before releasing the reference, which
 181 synchronizes with an acquire fence executed right before
 182 returning the
 183 .Dv true
 184 value.
 185 This ensures that the destructor, supposedly executed by the caller after
 186 the last reference was dropped, sees all updates done during the lifetime
 187 of the object.
 188 .Sh RETURN VALUES
 189 The
 190 .Nm refcount_release
 191 function returns true when releasing the last reference and false when
 192 releasing any other reference.
 193 .Sh HISTORY
 194 These functions were introduced in
 195 .Fx 6.0 .