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 | |
169 | GLIB_AVAILABLE_IN_2_32 |
170 | void g_mutex_init (GMutex *mutex); |
171 | GLIB_AVAILABLE_IN_2_32 |
172 | void g_mutex_clear (GMutex *mutex); |
173 | GLIB_AVAILABLE_IN_ALL |
174 | void g_mutex_lock (GMutex *mutex); |
175 | GLIB_AVAILABLE_IN_ALL |
176 | gboolean g_mutex_trylock (GMutex *mutex); |
177 | GLIB_AVAILABLE_IN_ALL |
178 | void g_mutex_unlock (GMutex *mutex); |
179 | |
180 | GLIB_AVAILABLE_IN_2_32 |
181 | void g_rw_lock_init (GRWLock *rw_lock); |
182 | GLIB_AVAILABLE_IN_2_32 |
183 | void g_rw_lock_clear (GRWLock *rw_lock); |
184 | GLIB_AVAILABLE_IN_2_32 |
185 | void g_rw_lock_writer_lock (GRWLock *rw_lock); |
186 | GLIB_AVAILABLE_IN_2_32 |
187 | gboolean g_rw_lock_writer_trylock (GRWLock *rw_lock); |
188 | GLIB_AVAILABLE_IN_2_32 |
189 | void g_rw_lock_writer_unlock (GRWLock *rw_lock); |
190 | GLIB_AVAILABLE_IN_2_32 |
191 | void g_rw_lock_reader_lock (GRWLock *rw_lock); |
192 | GLIB_AVAILABLE_IN_2_32 |
193 | gboolean g_rw_lock_reader_trylock (GRWLock *rw_lock); |
194 | GLIB_AVAILABLE_IN_2_32 |
195 | void g_rw_lock_reader_unlock (GRWLock *rw_lock); |
196 | |
197 | GLIB_AVAILABLE_IN_2_32 |
198 | void g_rec_mutex_init (GRecMutex *rec_mutex); |
199 | GLIB_AVAILABLE_IN_2_32 |
200 | void g_rec_mutex_clear (GRecMutex *rec_mutex); |
201 | GLIB_AVAILABLE_IN_2_32 |
202 | void g_rec_mutex_lock (GRecMutex *rec_mutex); |
203 | GLIB_AVAILABLE_IN_2_32 |
204 | gboolean g_rec_mutex_trylock (GRecMutex *rec_mutex); |
205 | GLIB_AVAILABLE_IN_2_32 |
206 | void g_rec_mutex_unlock (GRecMutex *rec_mutex); |
207 | |
208 | GLIB_AVAILABLE_IN_2_32 |
209 | void g_cond_init (GCond *cond); |
210 | GLIB_AVAILABLE_IN_2_32 |
211 | void g_cond_clear (GCond *cond); |
212 | GLIB_AVAILABLE_IN_ALL |
213 | void g_cond_wait (GCond *cond, |
214 | GMutex *mutex); |
215 | GLIB_AVAILABLE_IN_ALL |
216 | void g_cond_signal (GCond *cond); |
217 | GLIB_AVAILABLE_IN_ALL |
218 | void g_cond_broadcast (GCond *cond); |
219 | GLIB_AVAILABLE_IN_2_32 |
220 | gboolean g_cond_wait_until (GCond *cond, |
221 | GMutex *mutex, |
222 | gint64 end_time); |
223 | |
224 | GLIB_AVAILABLE_IN_ALL |
225 | gpointer g_private_get (GPrivate *key); |
226 | GLIB_AVAILABLE_IN_ALL |
227 | void g_private_set (GPrivate *key, |
228 | gpointer value); |
229 | GLIB_AVAILABLE_IN_2_32 |
230 | void g_private_replace (GPrivate *key, |
231 | gpointer value); |
232 | |
233 | GLIB_AVAILABLE_IN_ALL |
234 | gpointer g_once_impl (GOnce *once, |
235 | GThreadFunc func, |
236 | gpointer arg); |
237 | GLIB_AVAILABLE_IN_ALL |
238 | gboolean g_once_init_enter (volatile void *location); |
239 | GLIB_AVAILABLE_IN_ALL |
240 | void g_once_init_leave (volatile void *location, |
241 | gsize result); |
242 | |
243 | GLIB_AVAILABLE_IN_2_80 |
244 | gboolean g_once_init_enter_pointer (void *location); |
245 | GLIB_AVAILABLE_IN_2_80 |
246 | void g_once_init_leave_pointer (void *location, |
247 | gpointer result); |
248 | |
249 | /* Use C11-style atomic extensions to check the fast path for status=ready. If |
250 | * they are not available, fall back to using a mutex and condition variable in |
251 | * g_once_impl(). |
252 | * |
253 | * On the C11-style codepath, only the load of once->status needs to be atomic, |
254 | * as the writes to it and once->retval in g_once_impl() are related by a |
255 | * happens-before relation. Release-acquire semantics are defined such that any |
256 | * atomic/non-atomic write which happens-before a store/release is guaranteed to |
257 | * be seen by the load/acquire of the same atomic variable. */ |
258 | #if defined(G_ATOMIC_LOCK_FREE) && defined(__GCC_HAVE_SYNC_COMPARE_AND_SWAP_4) && defined(__ATOMIC_SEQ_CST) |
259 | # define g_once(once, func, arg) \ |
260 | ((__atomic_load_n (&(once)->status, __ATOMIC_ACQUIRE) == G_ONCE_STATUS_READY) ? \ |
261 | (once)->retval : \ |
262 | g_once_impl ((once), (func), (arg))) |
263 | #else |
264 | # define g_once(once, func, arg) g_once_impl ((once), (func), (arg)) |
265 | #endif |
266 | |
267 | #ifdef __GNUC__ |
268 | # define g_once_init_enter(location) \ |
269 | (G_GNUC_EXTENSION ({ \ |
270 | G_STATIC_ASSERT (sizeof *(location) == sizeof (gpointer)); \ |
271 | (void) (0 ? (gpointer) *(location) : NULL); \ |
272 | (!g_atomic_pointer_get (location) && \ |
273 | g_once_init_enter (location)); \ |
274 | })) |
275 | # define g_once_init_leave(location, result) \ |
276 | (G_GNUC_EXTENSION ({ \ |
277 | G_STATIC_ASSERT (sizeof *(location) == sizeof (gpointer)); \ |
278 | 0 ? (void) (*(location) = (result)) : (void) 0; \ |
279 | g_once_init_leave ((location), (gsize) (result)); \ |
280 | })) |
281 | # define g_once_init_enter_pointer(location) \ |
282 | (G_GNUC_EXTENSION ({ \ |
283 | G_STATIC_ASSERT (sizeof *(location) == sizeof (gpointer)); \ |
284 | (void) (0 ? (gpointer) * (location) : NULL); \ |
285 | (!g_atomic_pointer_get (location) && \ |
286 | g_once_init_enter_pointer (location)); \ |
287 | })) GLIB_AVAILABLE_MACRO_IN_2_80 |
288 | # define g_once_init_leave_pointer(location, result) \ |
289 | (G_GNUC_EXTENSION ({ \ |
290 | G_STATIC_ASSERT (sizeof *(location) == sizeof (gpointer)); \ |
291 | 0 ? (void) (*(location) = (result)) : (void) 0; \ |
292 | g_once_init_leave_pointer ((location), (gpointer) (guintptr) (result)); \ |
293 | })) GLIB_AVAILABLE_MACRO_IN_2_80 |
294 | #else |
295 | # define g_once_init_enter(location) \ |
296 | (g_once_init_enter((location))) |
297 | # define g_once_init_leave(location, result) \ |
298 | (g_once_init_leave((location), (gsize) (result))) |
299 | # define g_once_init_enter_pointer(location) \ |
300 | (g_once_init_enter_pointer((location))) \ |
301 | GLIB_AVAILABLE_MACRO_IN_2_80 |
302 | # define g_once_init_leave_pointer(location, result) \ |
303 | (g_once_init_leave_pointer((location), (gpointer) (guintptr) (result))) \ |
304 | GLIB_AVAILABLE_MACRO_IN_2_80 |
305 | #endif |
306 | |
307 | GLIB_AVAILABLE_IN_2_36 |
308 | guint g_get_num_processors (void); |
309 | |
310 | /** |
311 | * GMutexLocker: |
312 | * |
313 | * Opaque type. See g_mutex_locker_new() for details. |
314 | * Since: 2.44 |
315 | */ |
316 | typedef void GMutexLocker; |
317 | |
318 | /** |
319 | * g_mutex_locker_new: |
320 | * @mutex: a mutex to lock |
321 | * |
322 | * Lock @mutex and return a new #GMutexLocker. Unlock with |
323 | * g_mutex_locker_free(). Using g_mutex_unlock() on @mutex |
324 | * while a #GMutexLocker exists can lead to undefined behaviour. |
325 | * |
326 | * No allocation is performed, it is equivalent to a g_mutex_lock() call. |
327 | * |
328 | * This is intended to be used with g_autoptr(). Note that g_autoptr() |
329 | * is only available when using GCC or clang, so the following example |
330 | * will only work with those compilers: |
331 | * |[ |
332 | * typedef struct |
333 | * { |
334 | * ... |
335 | * GMutex mutex; |
336 | * ... |
337 | * } MyObject; |
338 | * |
339 | * static void |
340 | * my_object_do_stuff (MyObject *self) |
341 | * { |
342 | * g_autoptr(GMutexLocker) locker = g_mutex_locker_new (&self->mutex); |
343 | * |
344 | * // Code with mutex locked here |
345 | * |
346 | * if (condition) |
347 | * // No need to unlock |
348 | * return; |
349 | * |
350 | * // Optionally early unlock |
351 | * g_clear_pointer (&locker, g_mutex_locker_free); |
352 | * |
353 | * // Code with mutex unlocked here |
354 | * } |
355 | * ]| |
356 | * |
357 | * Note that it is common for the declared variable to not be used in the scope, |
358 | * which causes some compilers to warn. That can be avoided by using |
359 | * `G_GNUC_UNUSED` or, since 2.80, [func@GLib.MUTEX_AUTO_LOCK]. |
360 | * |
361 | * Returns: a #GMutexLocker |
362 | * Since: 2.44 |
363 | */ |
364 | GLIB_AVAILABLE_STATIC_INLINE_IN_2_44 |
365 | static inline GMutexLocker * |
366 | g_mutex_locker_new (GMutex *mutex) |
367 | { |
368 | g_mutex_lock (mutex); |
369 | return (GMutexLocker *) mutex; |
370 | } |
371 | |
372 | /** |
373 | * g_mutex_locker_free: |
374 | * @locker: a GMutexLocker |
375 | * |
376 | * Unlock @locker's mutex. See g_mutex_locker_new() for details. |
377 | * |
378 | * No memory is freed, it is equivalent to a g_mutex_unlock() call. |
379 | * |
380 | * Since: 2.44 |
381 | */ |
382 | GLIB_AVAILABLE_STATIC_INLINE_IN_2_44 |
383 | static inline void |
384 | g_mutex_locker_free (GMutexLocker *locker) |
385 | { |
386 | g_mutex_unlock (mutex: (GMutex *) locker); |
387 | } |
388 | |
389 | /** |
390 | * G_MUTEX_AUTO_LOCK: |
391 | * @mutex: a [type@GLib.Mutex] |
392 | * @var: a variable name to be declared |
393 | * |
394 | * Declare a [type@GLib.MutexLocker] variable with `g_autoptr()` and lock the |
395 | * mutex. The mutex will be unlocked automatically when leaving the scope. The |
396 | * variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is |
397 | * not used in the scope. |
398 | * |
399 | * This feature is only supported on GCC and clang. This macro is not defined on |
400 | * other compilers and should not be used in programs that are intended to be |
401 | * portable to those compilers. |
402 | * |
403 | * Note that this should be used in a place where it is allowed to declare a |
404 | * variable, which could be before any statement in the case |
405 | * `-Wdeclaration-after-statement` is used, or C standard prior to C99. |
406 | * |
407 | * ```c |
408 | * { |
409 | * G_MUTEX_AUTO_LOCK (&obj->mutex, locker); |
410 | * |
411 | * obj->stuff_with_lock (); |
412 | * if (condition) |
413 | * { |
414 | * // No need to unlock |
415 | * return; |
416 | * } |
417 | * |
418 | * // Unlock before end of scope |
419 | * g_clear_pointer (&locker, g_mutex_locker_free); |
420 | * obj->stuff_without_lock (); |
421 | * } |
422 | * ``` |
423 | * |
424 | * Since: 2.80.0 |
425 | */ |
426 | #ifdef g_autoptr |
427 | #define G_MUTEX_AUTO_LOCK(mutex, var) \ |
428 | GLIB_AVAILABLE_MACRO_IN_2_80 g_autoptr (GMutexLocker) \ |
429 | G_GNUC_UNUSED var = g_mutex_locker_new (mutex) |
430 | #endif /* g_autoptr */ |
431 | |
432 | /** |
433 | * GRecMutexLocker: |
434 | * |
435 | * Opaque type. See g_rec_mutex_locker_new() for details. |
436 | * Since: 2.60 |
437 | */ |
438 | typedef void GRecMutexLocker; |
439 | |
440 | /** |
441 | * g_rec_mutex_locker_new: |
442 | * @rec_mutex: a recursive mutex to lock |
443 | * |
444 | * Lock @rec_mutex and return a new #GRecMutexLocker. Unlock with |
445 | * g_rec_mutex_locker_free(). Using g_rec_mutex_unlock() on @rec_mutex |
446 | * while a #GRecMutexLocker exists can lead to undefined behaviour. |
447 | * |
448 | * No allocation is performed, it is equivalent to a g_rec_mutex_lock() call. |
449 | * |
450 | * This is intended to be used with g_autoptr(). Note that g_autoptr() |
451 | * is only available when using GCC or clang, so the following example |
452 | * will only work with those compilers: |
453 | * |[ |
454 | * typedef struct |
455 | * { |
456 | * ... |
457 | * GRecMutex rec_mutex; |
458 | * ... |
459 | * } MyObject; |
460 | * |
461 | * static void |
462 | * my_object_do_stuff (MyObject *self) |
463 | * { |
464 | * g_autoptr(GRecMutexLocker) locker = g_rec_mutex_locker_new (&self->rec_mutex); |
465 | * |
466 | * // Code with rec_mutex locked here |
467 | * |
468 | * if (condition) |
469 | * // No need to unlock |
470 | * return; |
471 | * |
472 | * // Optionally early unlock |
473 | * g_clear_pointer (&locker, g_rec_mutex_locker_free); |
474 | * |
475 | * // Code with rec_mutex unlocked here |
476 | * } |
477 | * ]| |
478 | * |
479 | * Note that it is common for the declared variable to not be used in the scope, |
480 | * which causes some compilers to warn. That can be avoided by using |
481 | * `G_GNUC_UNUSED` or, since 2.80, [func@GLib.REC_MUTEX_AUTO_LOCK]. |
482 | * |
483 | * Returns: a #GRecMutexLocker |
484 | * Since: 2.60 |
485 | */ |
486 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
487 | GLIB_AVAILABLE_STATIC_INLINE_IN_2_60 |
488 | static inline GRecMutexLocker * |
489 | g_rec_mutex_locker_new (GRecMutex *rec_mutex) |
490 | { |
491 | g_rec_mutex_lock (rec_mutex); |
492 | return (GRecMutexLocker *) rec_mutex; |
493 | } |
494 | G_GNUC_END_IGNORE_DEPRECATIONS |
495 | |
496 | /** |
497 | * g_rec_mutex_locker_free: |
498 | * @locker: a GRecMutexLocker |
499 | * |
500 | * Unlock @locker's recursive mutex. See g_rec_mutex_locker_new() for details. |
501 | * |
502 | * No memory is freed, it is equivalent to a g_rec_mutex_unlock() call. |
503 | * |
504 | * Since: 2.60 |
505 | */ |
506 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
507 | GLIB_AVAILABLE_STATIC_INLINE_IN_2_60 |
508 | static inline void |
509 | g_rec_mutex_locker_free (GRecMutexLocker *locker) |
510 | { |
511 | g_rec_mutex_unlock (rec_mutex: (GRecMutex *) locker); |
512 | } |
513 | G_GNUC_END_IGNORE_DEPRECATIONS |
514 | |
515 | /** |
516 | * G_REC_MUTEX_AUTO_LOCK: |
517 | * @mutex: a [type@GLib.RecMutex] |
518 | * @var: a variable name to be declared |
519 | * |
520 | * Declare a [type@GLib.RecMutexLocker] variable with `g_autoptr()` and lock the |
521 | * mutex. The mutex will be unlocked automatically when leaving the scope. The |
522 | * variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it is |
523 | * not used in the scope. |
524 | * |
525 | * This feature is only supported on GCC and clang. This macro is not defined on |
526 | * other compilers and should not be used in programs that are intended to be |
527 | * portable to those compilers. |
528 | * |
529 | * Note that this should be used in a place where it is allowed to declare a |
530 | * variable, which could be before any statement in the case |
531 | * `-Wdeclaration-after-statement` is used, or C standard prior to C99. |
532 | * |
533 | * ```c |
534 | * { |
535 | * G_REC_MUTEX_AUTO_LOCK (&obj->rec_mutex, locker); |
536 | * |
537 | * obj->stuff_with_lock (); |
538 | * if (condition) |
539 | * { |
540 | * // No need to unlock |
541 | * return; |
542 | * } |
543 | * |
544 | * // Unlock before end of scope |
545 | * g_clear_pointer (&locker, g_rec_mutex_locker_free); |
546 | * obj->stuff_without_lock (); |
547 | * } |
548 | * ``` |
549 | * |
550 | * Since: 2.80.0 |
551 | */ |
552 | #ifdef g_autoptr |
553 | #define G_REC_MUTEX_AUTO_LOCK(mutex, var) \ |
554 | GLIB_AVAILABLE_MACRO_IN_2_80 g_autoptr (GRecMutexLocker) \ |
555 | G_GNUC_UNUSED var = g_rec_mutex_locker_new (mutex) |
556 | #endif /* g_autoptr */ |
557 | |
558 | /** |
559 | * GRWLockWriterLocker: |
560 | * |
561 | * Opaque type. See g_rw_lock_writer_locker_new() for details. |
562 | * Since: 2.62 |
563 | */ |
564 | typedef void GRWLockWriterLocker; |
565 | |
566 | /** |
567 | * g_rw_lock_writer_locker_new: |
568 | * @rw_lock: a #GRWLock |
569 | * |
570 | * Obtain a write lock on @rw_lock and return a new #GRWLockWriterLocker. |
571 | * Unlock with g_rw_lock_writer_locker_free(). Using g_rw_lock_writer_unlock() |
572 | * on @rw_lock while a #GRWLockWriterLocker exists can lead to undefined |
573 | * behaviour. |
574 | * |
575 | * No allocation is performed, it is equivalent to a g_rw_lock_writer_lock() call. |
576 | * |
577 | * This is intended to be used with g_autoptr(). Note that g_autoptr() |
578 | * is only available when using GCC or clang, so the following example |
579 | * will only work with those compilers: |
580 | * |[ |
581 | * typedef struct |
582 | * { |
583 | * ... |
584 | * GRWLock rw_lock; |
585 | * GPtrArray *array; |
586 | * ... |
587 | * } MyObject; |
588 | * |
589 | * static gchar * |
590 | * my_object_get_data (MyObject *self, guint index) |
591 | * { |
592 | * g_autoptr(GRWLockReaderLocker) locker = g_rw_lock_reader_locker_new (&self->rw_lock); |
593 | * |
594 | * // Code with a read lock obtained on rw_lock here |
595 | * |
596 | * if (self->array == NULL) |
597 | * // No need to unlock |
598 | * return NULL; |
599 | * |
600 | * if (index < self->array->len) |
601 | * // No need to unlock |
602 | * return g_ptr_array_index (self->array, index); |
603 | * |
604 | * // Optionally early unlock |
605 | * g_clear_pointer (&locker, g_rw_lock_reader_locker_free); |
606 | * |
607 | * // Code with rw_lock unlocked here |
608 | * return NULL; |
609 | * } |
610 | * |
611 | * static void |
612 | * my_object_set_data (MyObject *self, guint index, gpointer data) |
613 | * { |
614 | * g_autoptr(GRWLockWriterLocker) locker = g_rw_lock_writer_locker_new (&self->rw_lock); |
615 | * |
616 | * // Code with a write lock obtained on rw_lock here |
617 | * |
618 | * if (self->array == NULL) |
619 | * self->array = g_ptr_array_new (); |
620 | * |
621 | * if (condition) |
622 | * // No need to unlock |
623 | * return; |
624 | * |
625 | * if (index >= self->array->len) |
626 | * g_ptr_array_set_size (self->array, index+1); |
627 | * g_ptr_array_index (self->array, index) = data; |
628 | * |
629 | * // Optionally early unlock |
630 | * g_clear_pointer (&locker, g_rw_lock_writer_locker_free); |
631 | * |
632 | * // Code with rw_lock unlocked here |
633 | * } |
634 | * ]| |
635 | * |
636 | * Note that it is common for the declared variable to not be used in the scope, |
637 | * which causes some compilers to warn. That can be avoided by using |
638 | * `G_GNUC_UNUSED` or, since 2.80, [func@GLib.RW_LOCK_WRITER_AUTO_LOCK]. |
639 | * |
640 | * Returns: a #GRWLockWriterLocker |
641 | * Since: 2.62 |
642 | */ |
643 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
644 | GLIB_AVAILABLE_STATIC_INLINE_IN_2_62 |
645 | static inline GRWLockWriterLocker * |
646 | g_rw_lock_writer_locker_new (GRWLock *rw_lock) |
647 | { |
648 | g_rw_lock_writer_lock (rw_lock); |
649 | return (GRWLockWriterLocker *) rw_lock; |
650 | } |
651 | G_GNUC_END_IGNORE_DEPRECATIONS |
652 | |
653 | /** |
654 | * g_rw_lock_writer_locker_free: |
655 | * @locker: a GRWLockWriterLocker |
656 | * |
657 | * Release a write lock on @locker's read-write lock. See |
658 | * g_rw_lock_writer_locker_new() for details. |
659 | * |
660 | * No memory is freed, it is equivalent to a g_rw_lock_writer_unlock() call. |
661 | * |
662 | * Since: 2.62 |
663 | */ |
664 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
665 | GLIB_AVAILABLE_STATIC_INLINE_IN_2_62 |
666 | static inline void |
667 | g_rw_lock_writer_locker_free (GRWLockWriterLocker *locker) |
668 | { |
669 | g_rw_lock_writer_unlock (rw_lock: (GRWLock *) locker); |
670 | } |
671 | G_GNUC_END_IGNORE_DEPRECATIONS |
672 | |
673 | /** |
674 | * G_RW_LOCK_WRITER_AUTO_LOCK: |
675 | * @mutex: a [type@GLib.RWLock] |
676 | * @var: a variable name to be declared |
677 | * |
678 | * Declare a [type@GLib.RWLockWriterLocker] variable with `g_autoptr()` and lock |
679 | * for writing. The mutex will be unlocked automatically when leaving the scope. |
680 | * The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it |
681 | * is not used in the scope. |
682 | * |
683 | * This feature is only supported on GCC and clang. This macro is not defined on |
684 | * other compilers and should not be used in programs that are intended to be |
685 | * portable to those compilers. |
686 | * |
687 | * Note that this should be used in a place where it is allowed to declare a |
688 | * variable, which could be before any statement in the case |
689 | * `-Wdeclaration-after-statement` is used, or C standard prior to C99. |
690 | * |
691 | * ```c |
692 | * { |
693 | * G_RW_LOCK_WRITER_AUTO_LOCK (&obj->rw_lock, locker); |
694 | * |
695 | * obj->stuff_with_lock (); |
696 | * if (condition) |
697 | * { |
698 | * // No need to unlock |
699 | * return; |
700 | * } |
701 | * |
702 | * // Unlock before end of scope |
703 | * g_clear_pointer (&locker, g_rw_lock_writer_locker_free); |
704 | * obj->stuff_without_lock (); |
705 | * } |
706 | * ``` |
707 | * |
708 | * Since: 2.80.0 |
709 | */ |
710 | #ifdef g_autoptr |
711 | #define G_RW_LOCK_WRITER_AUTO_LOCK(mutex, var) \ |
712 | GLIB_AVAILABLE_MACRO_IN_2_80 g_autoptr (GRWLockWriterLocker) \ |
713 | G_GNUC_UNUSED var = g_rw_lock_writer_locker_new (mutex) |
714 | #endif /* g_autoptr */ |
715 | |
716 | /** |
717 | * GRWLockReaderLocker: |
718 | * |
719 | * Opaque type. See g_rw_lock_reader_locker_new() for details. |
720 | * Since: 2.62 |
721 | */ |
722 | typedef void GRWLockReaderLocker; |
723 | |
724 | /** |
725 | * g_rw_lock_reader_locker_new: |
726 | * @rw_lock: a #GRWLock |
727 | * |
728 | * Obtain a read lock on @rw_lock and return a new #GRWLockReaderLocker. |
729 | * Unlock with g_rw_lock_reader_locker_free(). Using g_rw_lock_reader_unlock() |
730 | * on @rw_lock while a #GRWLockReaderLocker exists can lead to undefined |
731 | * behaviour. |
732 | * |
733 | * No allocation is performed, it is equivalent to a g_rw_lock_reader_lock() call. |
734 | * |
735 | * This is intended to be used with g_autoptr(). For a code sample, see |
736 | * g_rw_lock_writer_locker_new(). |
737 | * |
738 | * Returns: a #GRWLockReaderLocker |
739 | * Since: 2.62 |
740 | */ |
741 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
742 | GLIB_AVAILABLE_STATIC_INLINE_IN_2_62 |
743 | static inline GRWLockReaderLocker * |
744 | g_rw_lock_reader_locker_new (GRWLock *rw_lock) |
745 | { |
746 | g_rw_lock_reader_lock (rw_lock); |
747 | return (GRWLockReaderLocker *) rw_lock; |
748 | } |
749 | G_GNUC_END_IGNORE_DEPRECATIONS |
750 | |
751 | /** |
752 | * g_rw_lock_reader_locker_free: |
753 | * @locker: a GRWLockReaderLocker |
754 | * |
755 | * Release a read lock on @locker's read-write lock. See |
756 | * g_rw_lock_reader_locker_new() for details. |
757 | * |
758 | * No memory is freed, it is equivalent to a g_rw_lock_reader_unlock() call. |
759 | * |
760 | * Since: 2.62 |
761 | */ |
762 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
763 | GLIB_AVAILABLE_STATIC_INLINE_IN_2_62 |
764 | static inline void |
765 | g_rw_lock_reader_locker_free (GRWLockReaderLocker *locker) |
766 | { |
767 | g_rw_lock_reader_unlock (rw_lock: (GRWLock *) locker); |
768 | } |
769 | G_GNUC_END_IGNORE_DEPRECATIONS |
770 | |
771 | /** |
772 | * G_RW_LOCK_READER_AUTO_LOCK: |
773 | * @mutex: a [type@GLib.RWLock] |
774 | * @var: a variable name to be declared |
775 | * |
776 | * Declare a [type@GLib.RWLockReaderLocker] variable with `g_autoptr()` and lock |
777 | * for reading. The mutex will be unlocked automatically when leaving the scope. |
778 | * The variable is declared with `G_GNUC_UNUSED` to avoid compiler warning if it |
779 | * is not used in the scope. |
780 | * |
781 | * This feature is only supported on GCC and clang. This macro is not defined on |
782 | * other compilers and should not be used in programs that are intended to be |
783 | * portable to those compilers. |
784 | * |
785 | * Note that this should be used in a place where it is allowed to declare a |
786 | * variable, which could be before any statement in the case |
787 | * `-Wdeclaration-after-statement` is used, or C standard prior to C99. |
788 | * |
789 | * ```c |
790 | * { |
791 | * G_RW_LOCK_READER_AUTO_LOCK (&obj->rw_lock, locker); |
792 | * |
793 | * obj->stuff_with_lock (); |
794 | * if (condition) |
795 | * { |
796 | * // No need to unlock |
797 | * return; |
798 | * } |
799 | * |
800 | * // Unlock before end of scope |
801 | * g_clear_pointer (&locker, g_rw_lock_reader_locker_free); |
802 | * obj->stuff_without_lock (); |
803 | * } |
804 | * ``` |
805 | * |
806 | * Since: 2.80.0 |
807 | */ |
808 | #ifdef g_autoptr |
809 | #define G_RW_LOCK_READER_AUTO_LOCK(mutex, var) \ |
810 | GLIB_AVAILABLE_MACRO_IN_2_80 g_autoptr (GRWLockReaderLocker) \ |
811 | G_GNUC_UNUSED var = g_rw_lock_reader_locker_new (mutex) |
812 | #endif /* g_autoptr */ |
813 | |
814 | G_END_DECLS |
815 | |
816 | #endif /* __G_THREAD_H__ */ |
817 | |