2 .\" Copyright (c) 2009 Hudson River Trading LLC
3 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
4 .\" All rights reserved.
6 .\" Copyright (c) 2019 The FreeBSD Foundation, Inc.
8 .\" Parts of this documentation was written by
9 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
10 .\" from the FreeBSD Foundation.
12 .\" Redistribution and use in source and binary forms, with or without
13 .\" modification, are permitted provided that the following conditions
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.
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
41 .Nm refcount_acquire ,
43 .Nd manage a simple reference counter
48 .Fn refcount_init "volatile u_int *count" "u_int value"
50 .Fn refcount_load "volatile u_int *count"
52 .Fn refcount_acquire "volatile u_int *count"
54 .Fn refcount_acquire_checked "volatile u_int *count"
56 .Fn refcount_acquire_if_not_zero "volatile u_int *count"
58 .Fn refcount_release "volatile u_int *count"
60 .Fn refcount_release_if_last "volatile u_int *count"
62 .Fn refcount_release_if_not_last "volatile u_int *count"
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
70 Usually the counter is used to manage the lifetime of an object and is
71 stored as a member of the object.
73 Currently all functions are implemented as static inline.
77 function is used to set the initial value of the counter to
79 It is normally used when creating a reference-counted object.
83 function returns a snapshot of the counter value.
84 This value may immediately become out-of-date in the absence of external
87 should be used instead of relying on the properties of the
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.
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.
102 .Fn refcount_acquire_checked
103 variant performs the same operation as
104 .Fn refcount_acquire ,
105 but additionally checks that the
107 value does not overflow as result of the operation.
110 if the reference was sucessfully obtained, and
112 if it was not, due to the overflow.
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.
121 must be already greater than zero for the function to succeed, in which
122 case the return value is
130 function is used to release an existing reference.
131 The function returns true if the reference being released was
133 otherwise, it returns false.
136 .Fn refcount_release_if_last
138 .Fn refcount_release_if_not_last
139 functions are variants of
141 which only drop the reference when it is or is not the last reference,
144 .Fn refcount_release_if_last
149 is equal to one, in which case it is decremented to zero.
152 is not modified and the function returns
155 .Fn refcount_release_if_not_last
160 is greater than one, in which case
165 is equal to one, the reference is not released and the function returns
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.
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
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
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
191 function returns true when releasing the last reference and false when
192 releasing any other reference.
194 These functions were introduced in