1 <!-- ##### SECTION Title ##### -->
5 <!-- ##### SECTION Short_Description ##### -->
7 thread abstraction; including mutexes, conditions and thread private data.
9 <!-- ##### SECTION Long_Description ##### -->
12 Threads act almost like processes, but unlike processes all threads of
13 one process share the same memory. This is good, as it provides easy
14 communication between the involved threads via this shared memory, and
15 it is bad, because strange things (so called Heisenbugs) might happen,
16 when the program is not carefully designed. Especially bad is, that due
17 to the concurrent nature of threads no assumptions on the order of
18 execution of different threads can be done unless explictly forced by
19 the programmer through synchronization primitives.
23 The aim of the thread related functions in GLib is to provide a
24 portable means for writing multithread safe software. There are
25 primitives for mutexes to protect the access to portions of memory
26 (#GMutex, #GStaticMutex, #G_LOCK_DEFINE and friends), there are
27 primitives for condition variables to allow synchronization of threads
28 (#GCond) and finally there are primitives for thread-private data,
29 that every thread has a private instance of (#GPrivate,
33 <!-- ##### SECTION See_Also ##### -->
38 <!-- ##### MACRO G_THREADS_ENABLED ##### -->
41 This macro is defined, if GLib was compiled with thread support. This
42 does not necessarily mean, that there is a thread implementation
43 available, but the infrastructure is in place and once you provide a
44 thread implementation to g_thread_init(), GLib will be multithread
45 safe. It isn't and cannot be, if #G_THREADS_ENABLED is not defined.
50 <!-- ##### MACRO G_THREADS_IMPL_POSIX ##### -->
53 This macro is defined, if POSIX style threads are used.
58 <!-- ##### MACRO G_THREADS_IMPL_SOLARIS ##### -->
61 This macro is defined, if the SOLARIS thread system is used.
66 <!-- ##### MACRO G_THREADS_IMPL_NONE ##### -->
69 This macro is defined, if no thread implementation is used. You can
70 however provide one to g_thread_init() to make GLib multithread safe.
75 <!-- ##### MACRO G_THREAD_ERROR ##### -->
82 <!-- ##### ENUM GThreadError ##### -->
87 @G_THREAD_ERROR_AGAIN:
89 <!-- ##### STRUCT GThreadFunctions ##### -->
92 This function table is used by g_thread_init() to initialize the
93 thread system. The functions in that table are directly used by their
94 g_* prepended counterparts, that are described here, e.g. if you call
95 g_mutex_new() then mutex_new() from the table provided to
96 g_thread_init() will be called.
101 This struct should only be used, if you know, what you are doing.
123 @thread_set_priority:
126 <!-- ##### FUNCTION g_thread_init ##### -->
129 Before you use a thread related function in GLib, you should
130 initialize the thread system. This is done by calling
131 g_thread_init(). Most of the time you will only have to call
137 You should only call g_thread_init() with a non-NULL parameter, if you
138 really know, what you are doing.
144 g_thread_init() must not be called directly or indirectly as a
150 g_thread_init() might only be called once. On the second call
151 it will abort with an error. If you want to make sure, that the thread
152 system is initialized, you can do that too:
158 if (!g_thread_supported ()) g_thread_init (NULL);
164 After that line either the thread system is initialized or the program
165 will abort, if no thread system is available in GLib, i.e. either
166 #G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined.
170 If no thread system is available and @vtable is NULL or if not all
171 elements of @vtable are non-NULL, then g_thread_init() will abort.
176 To use g_thread_init() in your program, you have to link with the
177 libraries, that the command "glib-config --libs gthread" outputs. This
178 is not the case for all the other thread related functions of
179 GLib. Those can be used without having to link with the thread
184 @vtable: a function table of type #GThreadFunctions, that provides the
185 entry points to the thread system to be used.
188 <!-- ##### FUNCTION g_thread_supported ##### -->
190 This function returns, whether the thread system is initialized or
196 This function is actually a macro. Apart from taking the address of it
197 you can however use it as if it was a function.
201 @Returns: TRUE, if the thread system is initialized.
204 <!-- ##### USER_FUNCTION GThreadFunc ##### -->
212 <!-- ##### ENUM GThreadPriority ##### -->
217 @G_THREAD_PRIORITY_LOW:
218 @G_THREAD_PRIORITY_NORMAL:
219 @G_THREAD_PRIORITY_HIGH:
220 @G_THREAD_PRIORITY_URGENT:
222 <!-- ##### STRUCT GThread ##### -->
231 <!-- ##### FUNCTION g_thread_create ##### -->
246 <!-- ##### FUNCTION g_thread_self ##### -->
254 <!-- ##### FUNCTION g_thread_join ##### -->
262 <!-- ##### FUNCTION g_thread_set_priority ##### -->
271 <!-- ##### MACRO g_thread_yield ##### -->
278 <!-- ##### MACRO g_thread_exit ##### -->
285 <!-- ##### STRUCT GMutex ##### -->
288 The #GMutex struct is an opaque data structure to represent a mutex
289 (mutual exclusion). It can be used to protect data against shared
290 access. Take for example the following function:
293 <title>A function which will not work in a threaded environment</title>
295 int give_me_next_number ()
297 static int current_number = 0;
299 /* now do a very complicated calculation to calculate the new number,
300 this might for example be a random number generator */
301 current_number = calc_next_number (current_number);
302 return current_number;
309 It is easy to see, that this won't work in a multithreaded
310 application. There current_number must be protected against shared
311 access. A first naive implementation would be:
316 <title>The wrong way to write a thread-safe function</title>
318 int give_me_next_number ()
320 static int current_number = 0;
322 static GMutex * mutex = NULL;
325 mutex = g_mutex_new ();
326 g_mutex_lock (mutex);
327 ret_val = current_number = calc_next_number (current_number);
328 g_mutex_unlock (mutex);
336 This looks like it would work, but there is a race condition while
337 constructing the mutex and this code cannot work reliable. So please do
338 not use such constructs in your own programs. One working solution is:
343 <title>A correct thread-safe function</title>
345 static GMutex *give_me_next_number_mutex = NULL;
347 /* this function must be called before any call to give_me_next_number ()
348 it must be called exactly once. */
349 void init_give_me_next_number ()
351 g_assert (give_me_next_number_mutex == NULL);
352 give_me_next_number_mutex = g_mutex_new ();
355 int give_me_next_number ()
357 static int current_number = 0;
360 g_mutex_lock (give_me_next_number_mutex);
361 ret_val = current_number = calc_next_number (current_number);
362 g_mutex_unlock (give_me_next_number_mutex);
370 #GStaticMutex provides a simpler and safer way of doing this.
374 A #GMutex should only be accessed via the following functions.
379 All of the g_mutex_* functions are actually macros. Apart from taking
380 the addresses of them, you can however use them as if they were functions.
385 <!-- ##### FUNCTION g_mutex_new ##### -->
388 Creates a new #GMutex.
393 This function will abort, if g_thread_init() has not been called yet.
397 @Returns: a new #GMutex.
400 <!-- ##### FUNCTION g_mutex_lock ##### -->
403 Locks the #GMutex. If the #GMutex is already locked by another thread,
404 the current thread will block until the #GMutex is unlocked by the
409 This function can also be used, if g_thread_init() has not yet been
410 called and will do nothing then.
415 #GMutex is not guaranteed to be recursive, i.e. a thread might block,
416 if it already has locked the #GMutex. It will deadlock then, of
424 <!-- ##### FUNCTION g_mutex_trylock ##### -->
427 Tries to lock the #GMutex. If the #GMutex is already locked by another
428 thread, it immediately returns FALSE. Otherwise it locks the #GMutex
433 This function can also be used, if g_thread_init() has not yet been
434 called and will immediately return TRUE then.
438 @Returns: TRUE, if the #GMutex could be locked.
441 <!-- ##### FUNCTION g_mutex_unlock ##### -->
444 Unlocks the #GMutex. If another thread is blocked in a g_mutex_lock()
445 call, it will be woken and can lock the #GMutex itself. This function
446 can also be used, if g_thread_init() has not yet been called and will
453 <!-- ##### FUNCTION g_mutex_free ##### -->
456 Destroys the #GMutex.
462 <!-- ##### STRUCT GStaticMutex ##### -->
465 A #GStaticMutex works like a #GMutex, but it has one significant
466 advantage. It doesn't need to be created at run-time like a #GMutex,
467 but can be defined at compile-time. Here is a shorter, easier and
468 safer version of our give_me_next_number() example:
472 Sometimes you would like to dynamically create a mutex. If you don't
473 want to require prior calling to g_thread_init(), because your code
474 should also be usable in non-threaded programs, you are not able to
475 use g_mutex_new() and thus #GMutex, as that requires a prior call to
476 g_thread_init(). In theses cases you can also use a #GStaticMutex, but
477 you should remember to free the #GStaticMutex with
478 g_static_mutex_free() when not needed anymore to free up any
484 <title>Using GStaticMutex to simplify thread-safe programming</title>
486 int give_me_next_number ()
488 static int current_number = 0;
490 static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
492 g_static_mutex_lock (&mutex);
493 ret_val = current_number = calc_next_number (current_number);
494 g_static_mutex_unlock (&mutex);
502 Even though #GStaticMutex is not opaque, it should only be used with
503 the following functions, as it is defined differently on different
507 <para>All of the g_static_mutex_* functions can also be used, if
508 g_thread_init() has not yet.
513 All of the g_static_mutex_* functions are actually macros. Apart from
514 taking the addresses of them, you can however use them as if they were
520 <!-- ##### MACRO G_STATIC_MUTEX_INIT ##### -->
523 Every #GStaticMutex must be initialized with this macro, before it can
529 <title>Initializing a GStaticMutext</title>
531 GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
538 <!-- ##### FUNCTION g_static_mutex_lock ##### -->
540 works like g_mutex_lock(), but for a #GStaticMutex.
543 @mutex: a #GStaticMutex.
546 <!-- ##### FUNCTION g_static_mutex_trylock ##### -->
549 works like g_mutex_trylock(), but for a #GStaticMutex.
552 @mutex: a #GStaticMutex.
553 @Returns: TRUE, if the #GStaticMutex could be locked.
556 <!-- ##### FUNCTION g_static_mutex_unlock ##### -->
559 works like g_mutex_unlock(), but for a #GStaticMutex.
562 @mutex: a #GStaticMutex.
565 <!-- ##### FUNCTION g_static_mutex_get_mutex ##### -->
568 For some operations (like g_cond_wait()) you must have a #GMutex
569 instead of a #GStaticMutex. This function will return the
570 corresponding #GMutex for every #GStaticMutex.
573 @mutex: a #GStaticMutex.
574 @Returns: the corresponding #GMutex.
577 <!-- ##### FUNCTION g_static_mutex_free ##### -->
579 Releases all resources allocated to a #GStaticMutex. You don't have to
580 call this functions for a #GStaticMutex with an unbounded lifetime,
581 i.e. objects declared 'static', but if you have a #GStaticMutex as a
582 member of a structure and the structure is freed, you should also free
586 @mutex: a #GStaticMutex.
589 <!-- ##### MACRO G_LOCK_DEFINE ##### -->
592 The G_LOCK_* macros provide a convenient interface to #GStaticMutex
593 with the advantage that they will expand to nothing in programs
594 compiled against a thread-disabled GLib, saving code and memory
595 there. #G_LOCK_DEFINE defines a lock. It can occur, where variable
596 definitions may occur in programs, i.e. in the first block of a
597 function or outside of functions. The @name parameter will be mangled
598 to get the name of the #GStaticMutex. This means, that you can use
599 names of existing variables as the parameter, e.g. the name of the
600 variable you intent to protect with the lock. Look at our
601 give_me_next_number() example using the G_LOCK_* macros:
606 <title>Using the G_LOCK_* convenience macros</title>
608 G_LOCK_DEFINE (current_number);
610 int give_me_next_number ()
612 static int current_number = 0;
615 G_LOCK (current_number);
616 ret_val = current_number = calc_next_number (current_number);
617 G_UNLOCK (current_number);
624 @name: the name of the lock.
627 <!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
630 This works like #G_LOCK_DEFINE, but it creates a static object.
633 @name: the name of the lock.
636 <!-- ##### MACRO G_LOCK_EXTERN ##### -->
639 This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
642 @name: the name of the lock.
645 <!-- ##### MACRO G_LOCK ##### -->
648 works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
651 @name: the name of the lock.
654 <!-- ##### MACRO G_TRYLOCK ##### -->
657 works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
660 @name: the name of the lock.
661 @Returns: TRUE, if the lock could be locked.
664 <!-- ##### MACRO G_UNLOCK ##### -->
667 works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
670 @name: the name of the lock.
673 <!-- ##### STRUCT GStaticRecMutex ##### -->
682 <!-- ##### MACRO G_STATIC_REC_MUTEX_INIT ##### -->
689 <!-- ##### FUNCTION g_static_rec_mutex_lock ##### -->
697 <!-- ##### FUNCTION g_static_rec_mutex_trylock ##### -->
706 <!-- ##### FUNCTION g_static_rec_mutex_unlock ##### -->
714 <!-- ##### FUNCTION g_static_rec_mutex_lock_full ##### -->
723 <!-- ##### FUNCTION g_static_rec_mutex_unlock_full ##### -->
732 <!-- ##### STRUCT GStaticRWLock ##### -->
744 <!-- ##### MACRO G_STATIC_RW_LOCK_INIT ##### -->
751 <!-- ##### FUNCTION g_static_rw_lock_reader_lock ##### -->
759 <!-- ##### FUNCTION g_static_rw_lock_reader_trylock ##### -->
768 <!-- ##### FUNCTION g_static_rw_lock_reader_unlock ##### -->
776 <!-- ##### FUNCTION g_static_rw_lock_writer_lock ##### -->
784 <!-- ##### FUNCTION g_static_rw_lock_writer_trylock ##### -->
793 <!-- ##### FUNCTION g_static_rw_lock_writer_unlock ##### -->
801 <!-- ##### FUNCTION g_static_rw_lock_free ##### -->
809 <!-- ##### STRUCT GCond ##### -->
812 The #GCond struct is an opaque data structure to represent a
813 condition. A #GCond is an object, that threads can block on, if they
814 find a certain condition to be false. If other threads change the
815 state of this condition they can signal the #GCond, such that the
816 waiting thread is woken up.
821 <title>Using GCond to block a thread until a condition is satisfied</title>
823 GCond* data_cond = NULL; /* Must be initialized somewhere */
824 GMutex* data_mutex = NULL; /* Must be initialized somewhere */
825 gpointer current_data = NULL;
827 void push_data (gpointer data)
829 g_mutex_lock (data_mutex);
831 g_cond_signal (data_cond);
832 g_mutex_unlock (data_mutex);
839 g_mutex_lock (data_mutex);
840 while (!current_data)
841 g_cond_wait (data_cond, data_mutex);
844 g_mutex_unlock (data_mutex);
852 Whenever a thread calls pop_data() now, it will wait until
853 current_data is non-NULL, i.e. until some other thread has called
859 It is important to use the g_cond_wait() and g_cond_timed_wait()
860 functions only inside a loop, which checks for the condition to be
861 true as it is not guaranteed that the waiting thread will find it
862 fulfilled, even if the signaling thread left the condition
863 in that state. This is because another thread can have altered the
864 condition, before the waiting thread got the chance to be woken up,
865 even if the condition itself is protected by a #GMutex, like above.
870 A #GCond should only be accessed via the following functions.
875 All of the g_cond_* functions are actually macros. Apart from taking
876 the addresses of them, you can however use them as if they were functions.
881 <!-- ##### FUNCTION g_cond_new ##### -->
884 Creates a new #GCond. This function will abort, if g_thread_init()
885 has not been called yet.
888 @Returns: a new #GCond.
891 <!-- ##### FUNCTION g_cond_signal ##### -->
893 If threads are waiting for @cond, exactly one of them is woken up. It
894 is good practice to hold the same lock as the waiting thread, while
895 calling this function, though not required.
899 This function can also be used, if g_thread_init() has
900 not yet been called and will do nothing then.
906 <!-- ##### FUNCTION g_cond_broadcast ##### -->
909 If threads are waiting for @cond, all of them are woken up. It is good
910 practice to lock the same mutex as the waiting threads, while calling
911 this function, though not required.
915 This function can also be used, if g_thread_init() has
916 not yet been called and will do nothing then.
922 <!-- ##### FUNCTION g_cond_wait ##### -->
925 Waits until this thread is woken up on the #GCond. The #GMutex is
926 unlocked before falling asleep and locked again before resuming.
930 This function can also be used, if g_thread_init() has not yet been
931 called and will immediately return then.
935 @mutex: the #GMutex, that is currently locked.
938 <!-- ##### FUNCTION g_cond_timed_wait ##### -->
941 Waits until this thread is woken up on the #GCond, but not longer than
942 until the time, that is specified by @abs_time. The #GMutex is
943 unlocked before falling asleep and locked again before resuming.
947 If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
951 This function can also be used, if g_thread_init() has not yet been
952 called and will immediately return TRUE then.
956 @mutex: the #GMutex, that is currently locked.
957 @abs_time: a #GTimeVal, determining the final time.
958 @Returns: TRUE, if the thread is woken up in time.
961 <!-- ##### FUNCTION g_cond_free ##### -->
970 <!-- ##### STRUCT GPrivate ##### -->
972 The #GPrivate struct is an opaque data structure to represent a thread
973 private data key. Threads can thereby obtain and set a pointer, which
974 is private to the current thread. Take our give_me_next_number()
975 example from above. Now we don't want current_number to be shared
976 between the threads, but to be private to each thread. This can be
980 <title>Using GPrivate for per-thread data</title>
982 GPrivate* current_number_key = NULL; /* Must be initialized somewhere */
983 /* with g_private_new (g_free); */
985 int give_me_next_number ()
987 int *current_number = g_private_get (current_number_key);
991 current_number = g_new (int,1);
993 g_private_set (current_number_key, current_number);
995 *current_number = calc_next_number (*current_number);
996 return *current_number;
1003 Here the pointer belonging to the key current_number_key is read. If
1004 it is NULL, it has not been set yet. Then get memory for an integer
1005 value, assign this memory to the pointer and write the pointer
1006 back. Now we have an integer value, that is private to the current
1011 The #GPrivate struct should only be accessed via the following functions.
1016 All of the g_private_* functions are actually macros. Apart from taking
1017 the addresses of them, you can however use them as if they were functions.
1022 <!-- ##### FUNCTION g_private_new ##### -->
1025 Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer
1026 to a destructor function. Whenever a thread ends and the corresponding
1027 pointer keyed to this instance of #GPrivate is non-NULL, the
1028 destructor is called with this pointer as the argument.
1033 The @destructor is working quite differently from @notify in
1034 g_static_private_set().
1040 A #GPrivate can not be destroyed. Reuse it instead, if you can to
1047 This function will abort, if g_thread_init() has not been called yet.
1051 @destructor: a function to handle the data keyed to #GPrivate, when a
1056 <!-- ##### FUNCTION g_private_get ##### -->
1059 Returns the pointer keyed to @private_key for the current thread. This
1060 pointer is NULL, when g_private_set() hasn't been called for the
1061 current @private_key and thread yet.
1065 This function can also be used, if g_thread_init() has not yet been
1066 called and will return the value of @private_key casted to #gpointer then.
1069 @private_key: a #GPrivate.
1070 @Returns: the corresponding pointer.
1073 <!-- ##### FUNCTION g_private_set ##### -->
1076 Sets the pointer keyed to @private_key for the current thread.
1080 This function can also be used, if g_thread_init() has not yet been
1081 called and will set @private_key to @data casted to #GPrivate* then.
1084 @private_key: a #GPrivate.
1085 @data: the new pointer.
1088 <!-- ##### STRUCT GStaticPrivate ##### -->
1091 A #GStaticPrivate works almost like a #GPrivate, but it has one
1092 significant advantage. It doesn't need to be created at run-time like
1093 a #GPrivate, but can be defined at compile-time. This is similar to
1094 the difference between #GMutex and #GStaticMutex. Now look at our
1095 give_me_next_number() example with #GStaticPrivate:
1100 <title>Using GStaticPrivate for per-thread data</title>
1102 int give_me_next_number ()
1104 static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
1105 int *current_number = g_static_private_get (&current_number_key);
1107 if (!current_number)
1109 current_number = g_new (int,1);
1110 *current_number = 0;
1111 g_static_private_set (&current_number_key, current_number, g_free);
1113 *current_number = calc_next_number (*current_number);
1114 return *current_number;
1122 <!-- ##### MACRO G_STATIC_PRIVATE_INIT ##### -->
1124 Every #GStaticPrivate must be initialized with this macro, before it can
1131 GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
1138 <!-- ##### FUNCTION g_static_private_get ##### -->
1140 Works like g_private_get() only for a #GStaticPrivate.
1144 This function also works, if g_thread_init() has not yet been called.
1147 @private_key: a #GStaticPrivate.
1148 @Returns: the corresponding pointer.
1151 <!-- ##### FUNCTION g_static_private_get_for_thread ##### -->
1161 <!-- ##### FUNCTION g_static_private_set ##### -->
1163 Sets the pointer keyed to @private_key for the current thread and the
1164 function @notify to be called with that pointer (NULL or non-NULL),
1165 whenever the pointer is set again or whenever the current thread ends.
1169 This function also works, if g_thread_init() has not yet been
1170 called. If g_thread_init() is called later, the @data keyed to
1171 @private_key will be inherited only by the main thread, i.e. the one that
1172 called g_thread_init().
1177 The @notify is working quite differently from @destructor in
1182 @private_key: a #GStaticPrivate.
1183 @data: the new pointer.
1184 @notify: a function to be called with the pointer, whenever the
1185 current thread ends or sets this pointer again.
1188 <!-- ##### FUNCTION g_static_private_set_for_thread ##### -->