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_acquire "volatile u_int *count"
52 .Fn refcount_acquire_checked "volatile u_int *count"
54 .Fn refcount_acquire_if_not_zero "volatile u_int *count"
56 .Fn refcount_release "volatile u_int *count"
58 .Fn refcount_release_if_not_last "volatile u_int *count"
62 functions provide an API to manage a simple reference counter.
63 The caller provides the storage for the counter in an unsigned integer.
64 A pointer to this integer is passed via
66 Usually the counter is used to manage the lifetime of an object and is
67 stored as a member of the object.
69 Currently all functions are implemented as static inline.
73 function is used to set the initial value of the counter to
75 It is normally used when creating a reference-counted object.
79 function is used to acquire a new reference.
80 The caller is responsible for ensuring that it holds a valid reference
81 while obtaining a new reference.
83 if an object is stored on a list and the list holds a reference on the
84 object, then holding a lock that protects the list provides sufficient
85 protection for acquiring a new reference.
88 .Fn refcount_acquire_checked
89 variant performs the same operation as
90 .Fn refcount_acquire ,
91 but additionally checks that the
93 value does not overflow as result of the operation.
96 if the reference was sucessfully obtained, and
98 if it was not, due to the overflow.
101 .Fn refcount_acquire_if_not_zero
102 function is yet another variant of
103 .Fn refcount_acquire ,
104 which only obtains the reference when some reference already exists.
107 must be already greater than zero for the function to succeed, in which
108 case the return value is
116 function is used to release an existing reference.
117 The function returns true if the reference being released was
119 otherwise, it returns false.
122 .Fn refcount_release_if_not_last
125 which only drops the reference when it is not the last reference.
126 In other words, the function returns
130 is greater than one, in which case
131 .Fa *count is decremented.
134 is equal to one, the reference is not released and the function returns
137 Note that these routines do not provide any inter-CPU synchronization or
138 data protection for managing the counter.
139 The caller is responsible for any additional synchronization needed by
140 consumers of any containing objects.
142 the caller is also responsible for managing the life cycle of any containing
143 objects including explicitly releasing any resources when the last reference
148 unconditionally executes a release fence (see
149 .Xr atomic 9 ) before releasing the reference, which
150 synchronizes with an acquire fence executed right before
154 This ensures that the destructor, supposedly executed by the caller after
155 the last reference was dropped, sees all updates done during the lifetime
160 function returns true when releasing the last reference and false when
161 releasing any other reference.
163 These functions were introduced in