1 | /* grefcount.c: Reference counting |
2 | * |
3 | * Copyright 2018 Emmanuele Bassi |
4 | * |
5 | * This library is free software; you can redistribute it and/or |
6 | * modify it under the terms of the GNU Lesser General Public |
7 | * License as published by the Free Software Foundation; either |
8 | * version 2.1 of the License, or (at your option) any later version. |
9 | * |
10 | * This library is distributed in the hope that it will be useful, |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | * Lesser General Public License for more details. |
14 | * |
15 | * You should have received a copy of the GNU Lesser General Public |
16 | * License along with this library; if not, see <http://www.gnu.org/licenses/>. |
17 | */ |
18 | |
19 | /** |
20 | * SECTION:refcount |
21 | * @Title: Reference counting |
22 | * @Short_description: Reference counting types and functions |
23 | * |
24 | * Reference counting is a garbage collection mechanism that is based on |
25 | * assigning a counter to a data type, or any memory area; the counter is |
26 | * increased whenever a new reference to that data type is acquired, and |
27 | * decreased whenever the reference is released. Once the last reference |
28 | * is released, the resources associated to that data type are freed. |
29 | * |
30 | * GLib uses reference counting in many of its data types, and provides |
31 | * the #grefcount and #gatomicrefcount types to implement safe and atomic |
32 | * reference counting semantics in new data types. |
33 | * |
34 | * It is important to note that #grefcount and #gatomicrefcount should be |
35 | * considered completely opaque types; you should always use the provided |
36 | * API to increase and decrease the counters, and you should never check |
37 | * their content directly, or compare their content with other values. |
38 | * |
39 | * Since: 2.58 |
40 | */ |
41 | |
42 | #include "config.h" |
43 | |
44 | #include "grefcount.h" |
45 | |
46 | #include "gatomic.h" |
47 | #include "gmessages.h" |
48 | |
49 | /** |
50 | * grefcount: |
51 | * |
52 | * A type for implementing non-atomic reference count semantics. |
53 | * |
54 | * Use g_ref_count_init() to initialize it; g_ref_count_inc() to |
55 | * increase the counter, and g_ref_count_dec() to decrease it. |
56 | * |
57 | * It is safe to use #grefcount only if you're expecting to operate |
58 | * on the reference counter from a single thread. It is entirely up |
59 | * to you to ensure that all reference count changes happen in the |
60 | * same thread. |
61 | * |
62 | * See also: #gatomicrefcount |
63 | * |
64 | * Since: 2.58 |
65 | */ |
66 | |
67 | /** |
68 | * gatomicrefcount: |
69 | * |
70 | * A type for implementing atomic reference count semantics. |
71 | * |
72 | * Use g_atomic_ref_count_init() to initialize it; g_atomic_ref_count_inc() |
73 | * to increase the counter, and g_atomic_ref_count_dec() to decrease it. |
74 | * |
75 | * It is safe to use #gatomicrefcount if you're expecting to operate on the |
76 | * reference counter from multiple threads. |
77 | * |
78 | * See also: #grefcount |
79 | * |
80 | * Since: 2.58 |
81 | */ |
82 | |
83 | /** |
84 | * g_ref_count_init: |
85 | * @rc: the address of a reference count variable |
86 | * |
87 | * Initializes a reference count variable. |
88 | * |
89 | * Since: 2.58 |
90 | */ |
91 | void |
92 | (g_ref_count_init) (grefcount *rc) |
93 | { |
94 | g_return_if_fail (rc != NULL); |
95 | |
96 | /* Non-atomic refcounting is implemented using the negative range |
97 | * of signed integers: |
98 | * |
99 | * G_MININT Z¯< 0 > Z⁺ G_MAXINT |
100 | * |----------------------------|----------------------------| |
101 | * |
102 | * Acquiring a reference moves us towards MININT, and releasing a |
103 | * reference moves us towards 0. |
104 | */ |
105 | *rc = -1; |
106 | } |
107 | |
108 | /** |
109 | * g_ref_count_inc: |
110 | * @rc: the address of a reference count variable |
111 | * |
112 | * Increases the reference count. |
113 | * |
114 | * Since: 2.58 |
115 | */ |
116 | void |
117 | (g_ref_count_inc) (grefcount *rc) |
118 | { |
119 | grefcount rrc; |
120 | |
121 | g_return_if_fail (rc != NULL); |
122 | |
123 | rrc = *rc; |
124 | |
125 | g_return_if_fail (rrc < 0); |
126 | |
127 | /* Check for saturation */ |
128 | if (rrc == G_MININT) |
129 | { |
130 | g_critical ("Reference count %p has reached saturation" , rc); |
131 | return; |
132 | } |
133 | |
134 | rrc -= 1; |
135 | |
136 | *rc = rrc; |
137 | } |
138 | |
139 | /** |
140 | * g_ref_count_dec: |
141 | * @rc: the address of a reference count variable |
142 | * |
143 | * Decreases the reference count. |
144 | * |
145 | * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise |
146 | * |
147 | * Since: 2.58 |
148 | */ |
149 | gboolean |
150 | (g_ref_count_dec) (grefcount *rc) |
151 | { |
152 | grefcount rrc; |
153 | |
154 | g_return_val_if_fail (rc != NULL, FALSE); |
155 | |
156 | rrc = *rc; |
157 | |
158 | g_return_val_if_fail (rrc < 0, FALSE); |
159 | |
160 | rrc += 1; |
161 | if (rrc == 0) |
162 | return TRUE; |
163 | |
164 | *rc = rrc; |
165 | |
166 | return FALSE; |
167 | } |
168 | |
169 | /** |
170 | * g_ref_count_compare: |
171 | * @rc: the address of a reference count variable |
172 | * @val: the value to compare |
173 | * |
174 | * Compares the current value of @rc with @val. |
175 | * |
176 | * Returns: %TRUE if the reference count is the same |
177 | * as the given value |
178 | * |
179 | * Since: 2.58 |
180 | */ |
181 | gboolean |
182 | (g_ref_count_compare) (grefcount *rc, |
183 | gint val) |
184 | { |
185 | grefcount rrc; |
186 | |
187 | g_return_val_if_fail (rc != NULL, FALSE); |
188 | g_return_val_if_fail (val >= 0, FALSE); |
189 | |
190 | rrc = *rc; |
191 | |
192 | if (val == G_MAXINT) |
193 | return rrc == G_MININT; |
194 | |
195 | return rrc == -val; |
196 | } |
197 | |
198 | /** |
199 | * g_atomic_ref_count_init: |
200 | * @arc: the address of an atomic reference count variable |
201 | * |
202 | * Initializes a reference count variable. |
203 | * |
204 | * Since: 2.58 |
205 | */ |
206 | void |
207 | (g_atomic_ref_count_init) (gatomicrefcount *arc) |
208 | { |
209 | g_return_if_fail (arc != NULL); |
210 | |
211 | /* Atomic refcounting is implemented using the positive range |
212 | * of signed integers: |
213 | * |
214 | * G_MININT Z¯< 0 > Z⁺ G_MAXINT |
215 | * |----------------------------|----------------------------| |
216 | * |
217 | * Acquiring a reference moves us towards MAXINT, and releasing a |
218 | * reference moves us towards 0. |
219 | */ |
220 | *arc = 1; |
221 | } |
222 | |
223 | /** |
224 | * g_atomic_ref_count_inc: |
225 | * @arc: the address of an atomic reference count variable |
226 | * |
227 | * Atomically increases the reference count. |
228 | * |
229 | * Since: 2.58 |
230 | */ |
231 | void |
232 | (g_atomic_ref_count_inc) (gatomicrefcount *arc) |
233 | { |
234 | g_return_if_fail (arc != NULL); |
235 | g_return_if_fail (g_atomic_int_get (arc) > 0); |
236 | |
237 | if (g_atomic_int_get (arc) == G_MAXINT) |
238 | { |
239 | g_critical ("Reference count has reached saturation" ); |
240 | return; |
241 | } |
242 | |
243 | g_atomic_int_inc (arc); |
244 | } |
245 | |
246 | /** |
247 | * g_atomic_ref_count_dec: |
248 | * @arc: the address of an atomic reference count variable |
249 | * |
250 | * Atomically decreases the reference count. |
251 | * |
252 | * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise |
253 | * |
254 | * Since: 2.58 |
255 | */ |
256 | gboolean |
257 | (g_atomic_ref_count_dec) (gatomicrefcount *arc) |
258 | { |
259 | g_return_val_if_fail (arc != NULL, FALSE); |
260 | g_return_val_if_fail (g_atomic_int_get (arc) > 0, FALSE); |
261 | |
262 | return g_atomic_int_dec_and_test (arc); |
263 | } |
264 | |
265 | /** |
266 | * g_atomic_ref_count_compare: |
267 | * @arc: the address of an atomic reference count variable |
268 | * @val: the value to compare |
269 | * |
270 | * Atomically compares the current value of @arc with @val. |
271 | * |
272 | * Returns: %TRUE if the reference count is the same |
273 | * as the given value |
274 | * |
275 | * Since: 2.58 |
276 | */ |
277 | gboolean |
278 | (g_atomic_ref_count_compare) (gatomicrefcount *arc, |
279 | gint val) |
280 | { |
281 | g_return_val_if_fail (arc != NULL, FALSE); |
282 | g_return_val_if_fail (val >= 0, FALSE); |
283 | |
284 | return g_atomic_int_get (arc) == val; |
285 | } |
286 | |