/usr/local/include/glib-2.0/glib/gthread.h
Line | Count | Source (jump to first uncovered line) |
1 | | /* GLIB - Library of useful routines for C programming |
2 | | * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald |
3 | | * |
4 | | * SPDX-License-Identifier: LGPL-2.1-or-later |
5 | | * |
6 | | * This library is free software; you can redistribute it and/or |
7 | | * modify it under the terms of the GNU Lesser General Public |
8 | | * License as published by the Free Software Foundation; either |
9 | | * version 2.1 of the License, or (at your option) any later version. |
10 | | * |
11 | | * This library is distributed in the hope that it will be useful, but |
12 | | * WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | | * Lesser General Public License for more details. |
15 | | * |
16 | | * You should have received a copy of the GNU Lesser General Public |
17 | | * License along with this library; if not, see <http://www.gnu.org/licenses/>. |
18 | | */ |
19 | | |
20 | | /* |
21 | | * Modified by the GLib Team and others 1997-2000. See the AUTHORS |
22 | | * file for a list of people on the GLib Team. See the ChangeLog |
23 | | * files for a list of changes. These files are distributed with |
24 | | * GLib at ftp://ftp.gtk.org/pub/gtk/. |
25 | | */ |
26 | | |
27 | | #ifndef __G_THREAD_H__ |
28 | | #define __G_THREAD_H__ |
29 | | |
30 | | #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) |
31 | | #error "Only <glib.h> can be included directly." |
32 | | #endif |
33 | | |
34 | | #include <glib/gatomic.h> |
35 | | #include <glib/gerror.h> |
36 | | #include <glib/gutils.h> |
37 | | |
38 | | G_BEGIN_DECLS |
39 | | |
40 | | #define G_THREAD_ERROR g_thread_error_quark () |
41 | | GLIB_AVAILABLE_IN_ALL |
42 | | GQuark g_thread_error_quark (void); |
43 | | |
44 | | typedef enum |
45 | | { |
46 | | G_THREAD_ERROR_AGAIN /* Resource temporarily unavailable */ |
47 | | } GThreadError; |
48 | | |
49 | | typedef gpointer (*GThreadFunc) (gpointer data); |
50 | | |
51 | | typedef struct _GThread GThread; |
52 | | |
53 | | typedef union _GMutex GMutex; |
54 | | typedef struct _GRecMutex GRecMutex; |
55 | | typedef struct _GRWLock GRWLock; |
56 | | typedef struct _GCond GCond; |
57 | | typedef struct _GPrivate GPrivate; |
58 | | typedef struct _GOnce GOnce; |
59 | | |
60 | | union _GMutex |
61 | | { |
62 | | /*< private >*/ |
63 | | gpointer p; |
64 | | guint i[2]; |
65 | | }; |
66 | | |
67 | | struct _GRWLock |
68 | | { |
69 | | /*< private >*/ |
70 | | gpointer p; |
71 | | guint i[2]; |
72 | | }; |
73 | | |
74 | | struct _GCond |
75 | | { |
76 | | /*< private >*/ |
77 | | gpointer p; |
78 | | guint i[2]; |
79 | | }; |
80 | | |
81 | | struct _GRecMutex |
82 | | { |
83 | | /*< private >*/ |
84 | | gpointer p; |
85 | | guint i[2]; |
86 | | }; |
87 | | |
88 | | #define G_PRIVATE_INIT(notify) { NULL, (notify), { NULL, NULL } } |
89 | | struct _GPrivate |
90 | | { |
91 | | /*< private >*/ |
92 | | gpointer p; |
93 | | GDestroyNotify notify; |
94 | | gpointer future[2]; |
95 | | }; |
96 | | |
97 | | typedef enum |
98 | | { |
99 | | G_ONCE_STATUS_NOTCALLED, |
100 | | G_ONCE_STATUS_PROGRESS, |
101 | | G_ONCE_STATUS_READY |
102 | | } GOnceStatus; |
103 | | |
104 | | #define G_ONCE_INIT { G_ONCE_STATUS_NOTCALLED, NULL } |
105 | | struct _GOnce |
106 | | { |
107 | | volatile GOnceStatus status; |
108 | | volatile gpointer retval; |
109 | | }; |
110 | | |
111 | | #define G_LOCK_NAME(name) g__ ## name ## _lock |
112 | | #define G_LOCK_DEFINE_STATIC(name) static G_LOCK_DEFINE (name) |
113 | | #define G_LOCK_DEFINE(name) GMutex G_LOCK_NAME (name) |
114 | | #define G_LOCK_EXTERN(name) extern GMutex G_LOCK_NAME (name) |
115 | | |
116 | | #ifdef G_DEBUG_LOCKS |
117 | | # define G_LOCK(name) G_STMT_START{ \ |
118 | | g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ |
119 | | "file %s: line %d (%s): locking: %s ", \ |
120 | | __FILE__, __LINE__, G_STRFUNC, \ |
121 | | #name); \ |
122 | | g_mutex_lock (&G_LOCK_NAME (name)); \ |
123 | | }G_STMT_END |
124 | | # define G_UNLOCK(name) G_STMT_START{ \ |
125 | | g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ |
126 | | "file %s: line %d (%s): unlocking: %s ", \ |
127 | | __FILE__, __LINE__, G_STRFUNC, \ |
128 | | #name); \ |
129 | | g_mutex_unlock (&G_LOCK_NAME (name)); \ |
130 | | }G_STMT_END |
131 | | # define G_TRYLOCK(name) \ |
132 | | (g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ |
133 | | "file %s: line %d (%s): try locking: %s ", \ |
134 | | __FILE__, __LINE__, G_STRFUNC, \ |
135 | | #name), g_mutex_trylock (&G_LOCK_NAME (name))) |
136 | | #else /* !G_DEBUG_LOCKS */ |
137 | | # define G_LOCK(name) g_mutex_lock (&G_LOCK_NAME (name)) |
138 | | # define G_UNLOCK(name) g_mutex_unlock (&G_LOCK_NAME (name)) |
139 | | # define G_TRYLOCK(name) g_mutex_trylock (&G_LOCK_NAME (name)) |
140 | | #endif /* !G_DEBUG_LOCKS */ |
141 | | |
142 | | #ifdef g_autoptr |
143 | | #define G_AUTO_LOCK(name) G_MUTEX_AUTO_LOCK (&G_LOCK_NAME (name), g__##name##_locker) |
144 | | #endif /* g_autoptr */ |
145 | | |
146 | | GLIB_AVAILABLE_IN_2_32 |
147 | | GThread * g_thread_ref (GThread *thread); |
148 | | GLIB_AVAILABLE_IN_2_32 |
149 | | void g_thread_unref (GThread *thread); |
150 | | GLIB_AVAILABLE_IN_2_32 |
151 | | GThread * g_thread_new (const gchar *name, |
152 | | GThreadFunc func, |
153 | | gpointer data); |
154 | | GLIB_AVAILABLE_IN_2_32 |
155 | | GThread * g_thread_try_new (const gchar *name, |
156 | | GThreadFunc func, |
157 | | gpointer data, |
158 | | GError **error); |
159 | | GLIB_AVAILABLE_IN_ALL |
160 | | GThread * g_thread_self (void); |
161 | | G_NORETURN GLIB_AVAILABLE_IN_ALL |
162 | | void g_thread_exit (gpointer retval); |
163 | | GLIB_AVAILABLE_IN_ALL |
164 | | gpointer g_thread_join (GThread *thread); |
165 | | GLIB_AVAILABLE_IN_ALL |
166 | | void g_thread_yield (void); |
167 | | |
168 | | GLIB_AVAILABLE_IN_2_84 |
169 | | const char * g_thread_get_name (GThread *thread); |
170 | | |
171 | | GLIB_AVAILABLE_IN_2_32 |
172 | | void g_mutex_init (GMutex *mutex); |
173 | | GLIB_AVAILABLE_IN_2_32 |
174 | | void g_mutex_clear (GMutex *mutex); |
175 | | GLIB_AVAILABLE_IN_ALL |
176 | | void g_mutex_lock (GMutex *mutex); |
177 | | GLIB_AVAILABLE_IN_ALL |
178 | | gboolean g_mutex_trylock (GMutex *mutex); |
179 | | GLIB_AVAILABLE_IN_ALL |
180 | | void g_mutex_unlock (GMutex *mutex); |
181 | | |
182 | | GLIB_AVAILABLE_IN_2_32 |
183 | | void g_rw_lock_init (GRWLock *rw_lock); |
184 | | GLIB_AVAILABLE_IN_2_32 |
185 | | void g_rw_lock_clear (GRWLock *rw_lock); |
186 | | GLIB_AVAILABLE_IN_2_32 |
187 | | void g_rw_lock_writer_lock (GRWLock *rw_lock); |
188 | | GLIB_AVAILABLE_IN_2_32 |
189 | | gboolean g_rw_lock_writer_trylock (GRWLock *rw_lock); |
190 | | GLIB_AVAILABLE_IN_2_32 |
191 | | void g_rw_lock_writer_unlock (GRWLock *rw_lock); |
192 | | GLIB_AVAILABLE_IN_2_32 |
193 | | void g_rw_lock_reader_lock (GRWLock *rw_lock); |
194 | | GLIB_AVAILABLE_IN_2_32 |
195 | | gboolean g_rw_lock_reader_trylock (GRWLock *rw_lock); |
196 | | GLIB_AVAILABLE_IN_2_32 |
197 | | void g_rw_lock_reader_unlock (GRWLock *rw_lock); |
198 | | |
199 | | GLIB_AVAILABLE_IN_2_32 |
200 | | void g_rec_mutex_init (GRecMutex *rec_mutex); |
201 | | GLIB_AVAILABLE_IN_2_32 |
202 | | void g_rec_mutex_clear (GRecMutex *rec_mutex); |
203 | | GLIB_AVAILABLE_IN_2_32 |
204 | | void g_rec_mutex_lock (GRecMutex *rec_mutex); |
205 | | GLIB_AVAILABLE_IN_2_32 |
206 | | gboolean g_rec_mutex_trylock (GRecMutex *rec_mutex); |
207 | | GLIB_AVAILABLE_IN_2_32 |
208 | | void g_rec_mutex_unlock (GRecMutex *rec_mutex); |
209 | | |
210 | | GLIB_AVAILABLE_IN_2_32 |
211 | | void g_cond_init (GCond *cond); |
212 | | GLIB_AVAILABLE_IN_2_32 |
213 | | void g_cond_clear (GCond *cond); |
214 | | GLIB_AVAILABLE_IN_ALL |
215 | | void g_cond_wait (GCond *cond, |
216 | | GMutex *mutex); |
217 | | GLIB_AVAILABLE_IN_ALL |
218 | | void g_cond_signal (GCond *cond); |
219 | | GLIB_AVAILABLE_IN_ALL |
220 | | void g_cond_broadcast (GCond *cond); |
221 | | GLIB_AVAILABLE_IN_2_32 |
222 | | gboolean g_cond_wait_until (GCond *cond, |
223 | | GMutex *mutex, |
224 | | gint64 end_time); |
225 | | |
226 | | GLIB_AVAILABLE_IN_ALL |
227 | | gpointer g_private_get (GPrivate *key); |
228 | | GLIB_AVAILABLE_IN_ALL |
229 | | void g_private_set (GPrivate *key, |
230 | | gpointer value); |
231 | | GLIB_AVAILABLE_IN_2_32 |
232 | | void g_private_replace (GPrivate *key, |
233 | | gpointer value); |
234 | | |
235 | | GLIB_AVAILABLE_IN_ALL |
236 | | gpointer g_once_impl (GOnce *once, |
237 | | GThreadFunc func, |
238 | | gpointer arg); |
239 | | GLIB_AVAILABLE_IN_ALL |
240 | | gboolean g_once_init_enter (volatile void *location); |
241 | | GLIB_AVAILABLE_IN_ALL |
242 | | void g_once_init_leave (volatile void *location, |
243 | | gsize result); |
244 | | |
245 | | GLIB_AVAILABLE_IN_2_80 |
246 | | gboolean g_once_init_enter_pointer (void *location); |
247 | | GLIB_AVAILABLE_IN_2_80 |
248 | | void g_once_init_leave_pointer (void *location, |
249 | | gpointer result); |
250 | | |
251 | | /* Use C11-style atomic extensions to check the fast path for status=ready. If |
252 | | * they are not available, fall back to using a mutex and condition variable in |
253 | | * g_once_impl(). |
254 | | * |
255 | | * On the C11-style codepath, only the load of once->status needs to be atomic, |
256 | | * as the writes to it and once->retval in g_once_impl() are related by a |
257 | | * happens-before relation. Release-acquire semantics are defined such that any |
258 | | * atomic/non-atomic write which happens-before a store/release is guaranteed to |
259 | | * be seen by the load/acquire of the same atomic variable. */ |
260 | | #if defined(G_ATOMIC_LOCK_FREE) && defined(__GCC_HAVE_SYNC_COMPARE_AND_SWAP_4) && defined(__ATOMIC_SEQ_CST) |
261 | | # define g_once(once, func, arg) \ |
262 | | ((__atomic_load_n (&(once)->status, __ATOMIC_ACQUIRE) == G_ONCE_STATUS_READY) ? \ |
263 | | (once)->retval : \ |
264 | | g_once_impl ((once), (func), (arg))) |
265 | | #else |
266 | | # define g_once(once, func, arg) g_once_impl ((once), (func), (arg)) |
267 | | #endif |
268 | | |
269 | | #ifdef __GNUC__ |
270 | | # define g_once_init_enter(location) \ |
271 | | (G_GNUC_EXTENSION ({ \ |
272 | | G_STATIC_ASSERT (sizeof *(location) == sizeof (gpointer)); \ |
273 | | (void) (0 ? (gpointer) *(location) : NULL); \ |
274 | | (!g_atomic_pointer_get (location) && \ |
275 | | g_once_init_enter (location)); \ |
276 | | })) |
277 | | # define g_once_init_leave(location, result) \ |
278 | | (G_GNUC_EXTENSION ({ \ |
279 | | G_STATIC_ASSERT (sizeof *(location) == sizeof (gpointer)); \ |
280 | | 0 ? (void) (*(location) = (result)) : (void) 0; \ |
281 | | g_once_init_leave ((location), (gsize) (result)); \ |
282 | | })) |
283 | | # define g_once_init_enter_pointer(location) \ |
284 | | (G_GNUC_EXTENSION ({ \ |
285 | | G_STATIC_ASSERT (sizeof *(location) == sizeof (gpointer)); \ |
286 | | (void) (0 ? (gpointer) * (location) : NULL); \ |
287 | | (!g_atomic_pointer_get (location) && \ |
288 | | g_once_init_enter_pointer (location)); \ |
289 | | })) GLIB_AVAILABLE_MACRO_IN_2_80 |
290 | | # define g_once_init_leave_pointer(location, result) \ |
291 | | (G_GNUC_EXTENSION ({ \ |
292 | | G_STATIC_ASSERT (sizeof *(location) == sizeof (gpointer)); \ |
293 | | 0 ? (void) (*(location) = (result)) : (void) 0; \ |
294 | | g_once_init_leave_pointer ((location), (gpointer) (guintptr) (result)); \ |
295 | | })) GLIB_AVAILABLE_MACRO_IN_2_80 |
296 | | #else |
297 | | # define g_once_init_enter(location) \ |
298 | | (g_once_init_enter((location))) |
299 | | # define g_once_init_leave(location, result) \ |
300 | | (g_once_init_leave((location), (gsize) (result))) |
301 | | # define g_once_init_enter_pointer(location) \ |
302 | | (g_once_init_enter_pointer((location))) \ |
303 | | GLIB_AVAILABLE_MACRO_IN_2_80 |
304 | | # define g_once_init_leave_pointer(location, result) \ |
305 | | (g_once_init_leave_pointer((location), (gpointer) (guintptr) (result))) \ |
306 | | GLIB_AVAILABLE_MACRO_IN_2_80 |
307 | | #endif |
308 | | |
309 | | GLIB_AVAILABLE_IN_2_36 |
310 | | guint g_get_num_processors (void); |
311 | | |
312 | | /** |
313 | | * GMutexLocker: |
314 | | * |
315 | | * Opaque type. See g_mutex_locker_new() for details. |
316 | | * Since: 2.44 |
317 | | */ |
318 | | typedef void GMutexLocker; |
319 | | |
320 | | /** |
321 | | * g_mutex_locker_new: |
322 | | * @mutex: a mutex to lock |
323 | | * |
324 | | * Lock @mutex and return a new #GMutexLocker. Unlock with |
325 | | * g_mutex_locker_free(). Using g_mutex_unlock() on @mutex |
326 | | * while a #GMutexLocker exists can lead to undefined behaviour. |
327 | | * |
328 | | * No allocation is performed, it is equivalent to a g_mutex_lock() call. |
329 | | * |
330 | | * This is intended to be used with g_autoptr(). Note that g_autoptr() |
331 | | * is only available when using GCC or clang, so the following example |
332 | | * will only work with those compilers: |
333 | | * |[ |
334 | | * typedef struct |
335 | | * { |
336 | | * ... |
337 | | * GMutex mutex; |
338 | | * ... |
339 | | * } MyObject; |
340 | | * |
341 | | * static void |
342 | | * my_object_do_stuff (MyObject *self) |
343 | | * { |
344 | | * g_autoptr(GMutexLocker) locker = g_mutex_locker_new (&self->mutex); |
345 | | * |
346 | | * // Code with mutex locked here |
347 | | * |
348 | | * if (condition) |
349 | | * // No need to unlock |
350 | | * return; |
351 | | * |
352 | | * // Optionally early unlock |
353 | | * g_clear_pointer (&locker, g_mutex_locker_free); |
354 | | * |
355 | | * // Code with mutex unlocked here |
356 | | * } |
357 | | * ]| |
358 | | * |
359 | | * Note that it is common for the declared variable to not be used in the scope, |
360 | | * which causes some compilers to warn. That can be avoided by using |
361 | | * `G_GNUC_UNUSED` or, since 2.80, [func@GLib.MUTEX_AUTO_LOCK]. |
362 | | * |
363 | | * Returns: a #GMutexLocker |
364 | | * Since: 2.44 |
365 | | */ |
366 | | GLIB_AVAILABLE_STATIC_INLINE_IN_2_44 |
367 | | static inline GMutexLocker * |
368 | | g_mutex_locker_new (GMutex *mutex) |
369 | 0 | { |
370 | 0 | g_mutex_lock (mutex); |
371 | 0 | return (GMutexLocker *) mutex; |
372 | 0 | } |
373 | | |
374 | | /** |
375 | | * g_mutex_locker_free: |
376 | | * @locker: a GMutexLocker |
377 | | * |
378 | | * Unlock @locker's mutex. See g_mutex_locker_new() for details. |
379 | | * |
380 | | * No memory is freed, it is equivalent to a g_mutex_unlock() call. |
381 | | * |
382 | | * Since: 2.44 |
383 | | */ |
384 | | GLIB_AVAILABLE_STATIC_INLINE_IN_2_44 |
385 | | static inline void |
386 | | g_mutex_locker_free (GMutexLocker *locker) |
387 | 0 | { |
388 | 0 | g_mutex_unlock ((GMutex *) locker); |
389 | 0 | } |
390 | | |
391 | | /** |
392 | | * G_MUTEX_AUTO_LOCK: |
393 | | * @mutex: a [type@GLib.Mutex] |
394 | | * @var: a variable name to be declared |
395 | | * |
396 | | * Declare a [type@GLib.MutexLocker] variable with `g_autoptr()` and lock the |
397 | | * mutex. The mutex will be unlocked automatically when leaving the scope. The |
398 | | * variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is |
399 | | * not used in the scope. |
400 | | * |
401 | | * This feature is only supported on GCC and clang. This macro is not defined on |
402 | | * other compilers and should not be used in programs that are intended to be |
403 | | * portable to those compilers. |
404 | | * |
405 | | * Note that this should be used in a place where it is allowed to declare a |
406 | | * variable, which could be before any statement in the case |
407 | | * `-Wdeclaration-after-statement` is used, or C standard prior to C99. |
408 | | * |
409 | | * ```c |
410 | | * { |
411 | | * G_MUTEX_AUTO_LOCK (&obj->mutex, locker); |
412 | | * |
413 | | * obj->stuff_with_lock (); |
414 | | * if (condition) |
415 | | * { |
416 | | * // No need to unlock |
417 | | * return; |
418 | | * } |
419 | | * |
420 | | * // Unlock before end of scope |
421 | | * g_clear_pointer (&locker, g_mutex_locker_free); |
422 | | * obj->stuff_without_lock (); |
423 | | * } |
424 | | * ``` |
425 | | * |
426 | | * Since: 2.80.0 |
427 | | */ |
428 | | #ifdef g_autoptr |
429 | | #define G_MUTEX_AUTO_LOCK(mutex, var) \ |
430 | | GLIB_AVAILABLE_MACRO_IN_2_80 g_autoptr (GMutexLocker) \ |
431 | | G_GNUC_UNUSED var = g_mutex_locker_new (mutex) |
432 | | #endif /* g_autoptr */ |
433 | | |
434 | | /** |
435 | | * GRecMutexLocker: |
436 | | * |
437 | | * Opaque type. See g_rec_mutex_locker_new() for details. |
438 | | * Since: 2.60 |
439 | | */ |
440 | | typedef void GRecMutexLocker; |
441 | | |
442 | | /** |
443 | | * g_rec_mutex_locker_new: |
444 | | * @rec_mutex: a recursive mutex to lock |
445 | | * |
446 | | * Lock @rec_mutex and return a new #GRecMutexLocker. Unlock with |
447 | | * g_rec_mutex_locker_free(). Using g_rec_mutex_unlock() on @rec_mutex |
448 | | * while a #GRecMutexLocker exists can lead to undefined behaviour. |
449 | | * |
450 | | * No allocation is performed, it is equivalent to a g_rec_mutex_lock() call. |
451 | | * |
452 | | * This is intended to be used with g_autoptr(). Note that g_autoptr() |
453 | | * is only available when using GCC or clang, so the following example |
454 | | * will only work with those compilers: |
455 | | * |[ |
456 | | * typedef struct |
457 | | * { |
458 | | * ... |
459 | | * GRecMutex rec_mutex; |
460 | | * ... |
461 | | * } MyObject; |
462 | | * |
463 | | * static void |
464 | | * my_object_do_stuff (MyObject *self) |
465 | | * { |
466 | | * g_autoptr(GRecMutexLocker) locker = g_rec_mutex_locker_new (&self->rec_mutex); |
467 | | * |
468 | | * // Code with rec_mutex locked here |
469 | | * |
470 | | * if (condition) |
471 | | * // No need to unlock |
472 | | * return; |
473 | | * |
474 | | * // Optionally early unlock |
475 | | * g_clear_pointer (&locker, g_rec_mutex_locker_free); |
476 | | * |
477 | | * // Code with rec_mutex unlocked here |
478 | | * } |
479 | | * ]| |
480 | | * |
481 | | * Note that it is common for the declared variable to not be used in the scope, |
482 | | * which causes some compilers to warn. That can be avoided by using |
483 | | * `G_GNUC_UNUSED` or, since 2.80, [func@GLib.REC_MUTEX_AUTO_LOCK]. |
484 | | * |
485 | | * Returns: a #GRecMutexLocker |
486 | | * Since: 2.60 |
487 | | */ |
488 | | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
489 | | GLIB_AVAILABLE_STATIC_INLINE_IN_2_60 |
490 | | static inline GRecMutexLocker * |
491 | | g_rec_mutex_locker_new (GRecMutex *rec_mutex) |
492 | 0 | { |
493 | 0 | g_rec_mutex_lock (rec_mutex); |
494 | 0 | return (GRecMutexLocker *) rec_mutex; |
495 | 0 | } |
496 | | G_GNUC_END_IGNORE_DEPRECATIONS |
497 | | |
498 | | /** |
499 | | * g_rec_mutex_locker_free: |
500 | | * @locker: a GRecMutexLocker |
501 | | * |
502 | | * Unlock @locker's recursive mutex. See g_rec_mutex_locker_new() for details. |
503 | | * |
504 | | * No memory is freed, it is equivalent to a g_rec_mutex_unlock() call. |
505 | | * |
506 | | * Since: 2.60 |
507 | | */ |
508 | | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
509 | | GLIB_AVAILABLE_STATIC_INLINE_IN_2_60 |
510 | | static inline void |
511 | | g_rec_mutex_locker_free (GRecMutexLocker *locker) |
512 | 0 | { |
513 | 0 | g_rec_mutex_unlock ((GRecMutex *) locker); |
514 | 0 | } |
515 | | G_GNUC_END_IGNORE_DEPRECATIONS |
516 | | |
517 | | /** |
518 | | * G_REC_MUTEX_AUTO_LOCK: |
519 | | * @mutex: a [type@GLib.RecMutex] |
520 | | * @var: a variable name to be declared |
521 | | * |
522 | | * Declare a [type@GLib.RecMutexLocker] variable with `g_autoptr()` and lock the |
523 | | * mutex. The mutex will be unlocked automatically when leaving the scope. The |
524 | | * variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is |
525 | | * not used in the scope. |
526 | | * |
527 | | * This feature is only supported on GCC and clang. This macro is not defined on |
528 | | * other compilers and should not be used in programs that are intended to be |
529 | | * portable to those compilers. |
530 | | * |
531 | | * Note that this should be used in a place where it is allowed to declare a |
532 | | * variable, which could be before any statement in the case |
533 | | * `-Wdeclaration-after-statement` is used, or C standard prior to C99. |
534 | | * |
535 | | * ```c |
536 | | * { |
537 | | * G_REC_MUTEX_AUTO_LOCK (&obj->rec_mutex, locker); |
538 | | * |
539 | | * obj->stuff_with_lock (); |
540 | | * if (condition) |
541 | | * { |
542 | | * // No need to unlock |
543 | | * return; |
544 | | * } |
545 | | * |
546 | | * // Unlock before end of scope |
547 | | * g_clear_pointer (&locker, g_rec_mutex_locker_free); |
548 | | * obj->stuff_without_lock (); |
549 | | * } |
550 | | * ``` |
551 | | * |
552 | | * Since: 2.80.0 |
553 | | */ |
554 | | #ifdef g_autoptr |
555 | | #define G_REC_MUTEX_AUTO_LOCK(mutex, var) \ |
556 | | GLIB_AVAILABLE_MACRO_IN_2_80 g_autoptr (GRecMutexLocker) \ |
557 | | G_GNUC_UNUSED var = g_rec_mutex_locker_new (mutex) |
558 | | #endif /* g_autoptr */ |
559 | | |
560 | | /** |
561 | | * GRWLockWriterLocker: |
562 | | * |
563 | | * Opaque type. See g_rw_lock_writer_locker_new() for details. |
564 | | * Since: 2.62 |
565 | | */ |
566 | | typedef void GRWLockWriterLocker; |
567 | | |
568 | | /** |
569 | | * g_rw_lock_writer_locker_new: |
570 | | * @rw_lock: a #GRWLock |
571 | | * |
572 | | * Obtain a write lock on @rw_lock and return a new #GRWLockWriterLocker. |
573 | | * Unlock with g_rw_lock_writer_locker_free(). Using g_rw_lock_writer_unlock() |
574 | | * on @rw_lock while a #GRWLockWriterLocker exists can lead to undefined |
575 | | * behaviour. |
576 | | * |
577 | | * No allocation is performed, it is equivalent to a g_rw_lock_writer_lock() call. |
578 | | * |
579 | | * This is intended to be used with g_autoptr(). Note that g_autoptr() |
580 | | * is only available when using GCC or clang, so the following example |
581 | | * will only work with those compilers: |
582 | | * |[ |
583 | | * typedef struct |
584 | | * { |
585 | | * ... |
586 | | * GRWLock rw_lock; |
587 | | * GPtrArray *array; |
588 | | * ... |
589 | | * } MyObject; |
590 | | * |
591 | | * static gchar * |
592 | | * my_object_get_data (MyObject *self, guint index) |
593 | | * { |
594 | | * g_autoptr(GRWLockReaderLocker) locker = g_rw_lock_reader_locker_new (&self->rw_lock); |
595 | | * |
596 | | * // Code with a read lock obtained on rw_lock here |
597 | | * |
598 | | * if (self->array == NULL) |
599 | | * // No need to unlock |
600 | | * return NULL; |
601 | | * |
602 | | * if (index < self->array->len) |
603 | | * // No need to unlock |
604 | | * return g_ptr_array_index (self->array, index); |
605 | | * |
606 | | * // Optionally early unlock |
607 | | * g_clear_pointer (&locker, g_rw_lock_reader_locker_free); |
608 | | * |
609 | | * // Code with rw_lock unlocked here |
610 | | * return NULL; |
611 | | * } |
612 | | * |
613 | | * static void |
614 | | * my_object_set_data (MyObject *self, guint index, gpointer data) |
615 | | * { |
616 | | * g_autoptr(GRWLockWriterLocker) locker = g_rw_lock_writer_locker_new (&self->rw_lock); |
617 | | * |
618 | | * // Code with a write lock obtained on rw_lock here |
619 | | * |
620 | | * if (self->array == NULL) |
621 | | * self->array = g_ptr_array_new (); |
622 | | * |
623 | | * if (condition) |
624 | | * // No need to unlock |
625 | | * return; |
626 | | * |
627 | | * if (index >= self->array->len) |
628 | | * g_ptr_array_set_size (self->array, index+1); |
629 | | * g_ptr_array_index (self->array, index) = data; |
630 | | * |
631 | | * // Optionally early unlock |
632 | | * g_clear_pointer (&locker, g_rw_lock_writer_locker_free); |
633 | | * |
634 | | * // Code with rw_lock unlocked here |
635 | | * } |
636 | | * ]| |
637 | | * |
638 | | * Note that it is common for the declared variable to not be used in the scope, |
639 | | * which causes some compilers to warn. That can be avoided by using |
640 | | * `G_GNUC_UNUSED` or, since 2.80, [func@GLib.RW_LOCK_WRITER_AUTO_LOCK]. |
641 | | * |
642 | | * Returns: a #GRWLockWriterLocker |
643 | | * Since: 2.62 |
644 | | */ |
645 | | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
646 | | GLIB_AVAILABLE_STATIC_INLINE_IN_2_62 |
647 | | static inline GRWLockWriterLocker * |
648 | | g_rw_lock_writer_locker_new (GRWLock *rw_lock) |
649 | 0 | { |
650 | 0 | g_rw_lock_writer_lock (rw_lock); |
651 | 0 | return (GRWLockWriterLocker *) rw_lock; |
652 | 0 | } |
653 | | G_GNUC_END_IGNORE_DEPRECATIONS |
654 | | |
655 | | /** |
656 | | * g_rw_lock_writer_locker_free: |
657 | | * @locker: a GRWLockWriterLocker |
658 | | * |
659 | | * Release a write lock on @locker's read-write lock. See |
660 | | * g_rw_lock_writer_locker_new() for details. |
661 | | * |
662 | | * No memory is freed, it is equivalent to a g_rw_lock_writer_unlock() call. |
663 | | * |
664 | | * Since: 2.62 |
665 | | */ |
666 | | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
667 | | GLIB_AVAILABLE_STATIC_INLINE_IN_2_62 |
668 | | static inline void |
669 | | g_rw_lock_writer_locker_free (GRWLockWriterLocker *locker) |
670 | 0 | { |
671 | 0 | g_rw_lock_writer_unlock ((GRWLock *) locker); |
672 | 0 | } |
673 | | G_GNUC_END_IGNORE_DEPRECATIONS |
674 | | |
675 | | /** |
676 | | * G_RW_LOCK_WRITER_AUTO_LOCK: |
677 | | * @mutex: a [type@GLib.RWLock] |
678 | | * @var: a variable name to be declared |
679 | | * |
680 | | * Declare a [type@GLib.RWLockWriterLocker] variable with `g_autoptr()` and lock |
681 | | * for writing. The mutex will be unlocked automatically when leaving the scope. |
682 | | * The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it |
683 | | * is not used in the scope. |
684 | | * |
685 | | * This feature is only supported on GCC and clang. This macro is not defined on |
686 | | * other compilers and should not be used in programs that are intended to be |
687 | | * portable to those compilers. |
688 | | * |
689 | | * Note that this should be used in a place where it is allowed to declare a |
690 | | * variable, which could be before any statement in the case |
691 | | * `-Wdeclaration-after-statement` is used, or C standard prior to C99. |
692 | | * |
693 | | * ```c |
694 | | * { |
695 | | * G_RW_LOCK_WRITER_AUTO_LOCK (&obj->rw_lock, locker); |
696 | | * |
697 | | * obj->stuff_with_lock (); |
698 | | * if (condition) |
699 | | * { |
700 | | * // No need to unlock |
701 | | * return; |
702 | | * } |
703 | | * |
704 | | * // Unlock before end of scope |
705 | | * g_clear_pointer (&locker, g_rw_lock_writer_locker_free); |
706 | | * obj->stuff_without_lock (); |
707 | | * } |
708 | | * ``` |
709 | | * |
710 | | * Since: 2.80.0 |
711 | | */ |
712 | | #ifdef g_autoptr |
713 | | #define G_RW_LOCK_WRITER_AUTO_LOCK(mutex, var) \ |
714 | | GLIB_AVAILABLE_MACRO_IN_2_80 g_autoptr (GRWLockWriterLocker) \ |
715 | | G_GNUC_UNUSED var = g_rw_lock_writer_locker_new (mutex) |
716 | | #endif /* g_autoptr */ |
717 | | |
718 | | /** |
719 | | * GRWLockReaderLocker: |
720 | | * |
721 | | * Opaque type. See g_rw_lock_reader_locker_new() for details. |
722 | | * Since: 2.62 |
723 | | */ |
724 | | typedef void GRWLockReaderLocker; |
725 | | |
726 | | /** |
727 | | * g_rw_lock_reader_locker_new: |
728 | | * @rw_lock: a #GRWLock |
729 | | * |
730 | | * Obtain a read lock on @rw_lock and return a new #GRWLockReaderLocker. |
731 | | * Unlock with g_rw_lock_reader_locker_free(). Using g_rw_lock_reader_unlock() |
732 | | * on @rw_lock while a #GRWLockReaderLocker exists can lead to undefined |
733 | | * behaviour. |
734 | | * |
735 | | * No allocation is performed, it is equivalent to a g_rw_lock_reader_lock() call. |
736 | | * |
737 | | * This is intended to be used with g_autoptr(). For a code sample, see |
738 | | * g_rw_lock_writer_locker_new(). |
739 | | * |
740 | | * Returns: a #GRWLockReaderLocker |
741 | | * Since: 2.62 |
742 | | */ |
743 | | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
744 | | GLIB_AVAILABLE_STATIC_INLINE_IN_2_62 |
745 | | static inline GRWLockReaderLocker * |
746 | | g_rw_lock_reader_locker_new (GRWLock *rw_lock) |
747 | 0 | { |
748 | 0 | g_rw_lock_reader_lock (rw_lock); |
749 | 0 | return (GRWLockReaderLocker *) rw_lock; |
750 | 0 | } |
751 | | G_GNUC_END_IGNORE_DEPRECATIONS |
752 | | |
753 | | /** |
754 | | * g_rw_lock_reader_locker_free: |
755 | | * @locker: a GRWLockReaderLocker |
756 | | * |
757 | | * Release a read lock on @locker's read-write lock. See |
758 | | * g_rw_lock_reader_locker_new() for details. |
759 | | * |
760 | | * No memory is freed, it is equivalent to a g_rw_lock_reader_unlock() call. |
761 | | * |
762 | | * Since: 2.62 |
763 | | */ |
764 | | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
765 | | GLIB_AVAILABLE_STATIC_INLINE_IN_2_62 |
766 | | static inline void |
767 | | g_rw_lock_reader_locker_free (GRWLockReaderLocker *locker) |
768 | 0 | { |
769 | 0 | g_rw_lock_reader_unlock ((GRWLock *) locker); |
770 | 0 | } |
771 | | G_GNUC_END_IGNORE_DEPRECATIONS |
772 | | |
773 | | /** |
774 | | * G_RW_LOCK_READER_AUTO_LOCK: |
775 | | * @mutex: a [type@GLib.RWLock] |
776 | | * @var: a variable name to be declared |
777 | | * |
778 | | * Declare a [type@GLib.RWLockReaderLocker] variable with `g_autoptr()` and lock |
779 | | * for reading. The mutex will be unlocked automatically when leaving the scope. |
780 | | * The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it |
781 | | * is not used in the scope. |
782 | | * |
783 | | * This feature is only supported on GCC and clang. This macro is not defined on |
784 | | * other compilers and should not be used in programs that are intended to be |
785 | | * portable to those compilers. |
786 | | * |
787 | | * Note that this should be used in a place where it is allowed to declare a |
788 | | * variable, which could be before any statement in the case |
789 | | * `-Wdeclaration-after-statement` is used, or C standard prior to C99. |
790 | | * |
791 | | * ```c |
792 | | * { |
793 | | * G_RW_LOCK_READER_AUTO_LOCK (&obj->rw_lock, locker); |
794 | | * |
795 | | * obj->stuff_with_lock (); |
796 | | * if (condition) |
797 | | * { |
798 | | * // No need to unlock |
799 | | * return; |
800 | | * } |
801 | | * |
802 | | * // Unlock before end of scope |
803 | | * g_clear_pointer (&locker, g_rw_lock_reader_locker_free); |
804 | | * obj->stuff_without_lock (); |
805 | | * } |
806 | | * ``` |
807 | | * |
808 | | * Since: 2.80.0 |
809 | | */ |
810 | | #ifdef g_autoptr |
811 | | #define G_RW_LOCK_READER_AUTO_LOCK(mutex, var) \ |
812 | | GLIB_AVAILABLE_MACRO_IN_2_80 g_autoptr (GRWLockReaderLocker) \ |
813 | | G_GNUC_UNUSED var = g_rw_lock_reader_locker_new (mutex) |
814 | | #endif /* g_autoptr */ |
815 | | |
816 | | G_END_DECLS |
817 | | |
818 | | #endif /* __G_THREAD_H__ */ |