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,
34 Currently there is only as much thread support included in GLib as is
35 necessary to make GLib itself multithread safe. Version 1.4 of GLib
36 will contain full thread support. For now the most portable way to
37 create threads is to require the macro #G_THREADS_IMPL_POSIX to be
38 defined and use POSIX threads then. This will work on almost all
39 platforms (except most notably Solaris and DCE threads.).
42 <!-- ##### SECTION See_Also ##### -->
47 <!-- ##### MACRO G_THREADS_ENABLED ##### -->
50 This macro is defined, if GLib was compiled with thread support. This
51 does not necessarily mean, that there is a thread implementation
52 available, but the infrastructure is in place and once you provide a
53 thread implementation to g_thread_init(), GLib will be multithread
54 safe. It isn't and can't be, if #G_THREADS_ENABLED is not defined.
59 <!-- ##### MACRO G_THREADS_IMPL_POSIX ##### -->
62 This macro is defined, if POSIX style threads are used.
67 <!-- ##### MACRO G_THREADS_IMPL_SOLARIS ##### -->
70 This macro is defined, if the SOLARIS thread system is used.
75 <!-- ##### MACRO G_THREADS_IMPL_NONE ##### -->
78 This macro is defined, if no thread implementation is used. You can
79 however provide one to g_thread_init() to make GLib multithread safe.
84 <!-- ##### MACRO G_THREAD_ERROR ##### -->
91 <!-- ##### ENUM GThreadError ##### -->
96 @G_THREAD_ERROR_AGAIN:
98 <!-- ##### STRUCT GThreadFunctions ##### -->
101 This function table is used by g_thread_init() to initialize the
102 thread system. The functions in that table are directly used by their
103 g_* prepended counterparts, that are described here, e.g. if you call
104 g_mutex_new() then mutex_new() from the table provided to
105 g_thread_init() will be called.
110 This struct should only be used, if you know, what you are doing.
132 @thread_set_priority:
135 <!-- ##### FUNCTION g_thread_init ##### -->
138 Before you use a thread related function in GLib, you should
139 initialize the thread system. This is done by calling
140 g_thread_init(). Most of the time you will only have to call
146 You should only call g_thread_init() with a non-NULL parameter, if you
147 really know, what you are doing.
153 g_thread_init() must not be called directly or indirectly as a
159 g_thread_init() might only be called once. On the second call
160 it will abort with an error. If you want to make sure, that the thread
161 system is initialized, you can do that too:
167 if (!g_thread_supported ()) g_thread_init (NULL);
173 After that line either the thread system is initialized or the program
174 will abort, if no thread system is available in GLib, i.e. either
175 #G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined.
179 If no thread system is available and @vtable is NULL or if not all
180 elements of @vtable are non-NULL, then g_thread_init() will abort.
185 To use g_thread_init() in your program, you have to link with the
186 libraries, that the command "glib-config --libs gthread" outputs. This
187 is not the case for all the other thread related functions of
188 GLib. Those can be used without having to link with the thread
193 @vtable: a function table of type #GThreadFunctions, that provides the
194 entry points to the thread system to be used.
197 <!-- ##### FUNCTION g_thread_supported ##### -->
199 This function returns, whether the thread system is initialized or
205 This function is actually a macro. Apart from taking the address of it
206 you can however use it as if it was a function.
210 @Returns: TRUE, if the thread system is initialized.
213 <!-- ##### USER_FUNCTION GThreadFunc ##### -->
221 <!-- ##### ENUM GThreadPriority ##### -->
226 @G_THREAD_PRIORITY_LOW:
227 @G_THREAD_PRIORITY_NORMAL:
228 @G_THREAD_PRIORITY_HIGH:
229 @G_THREAD_PRIORITY_URGENT:
231 <!-- ##### STRUCT GThread ##### -->
240 <!-- ##### FUNCTION g_thread_create ##### -->
255 <!-- ##### FUNCTION g_thread_self ##### -->
263 <!-- ##### FUNCTION g_thread_join ##### -->
271 <!-- ##### FUNCTION g_thread_set_priority ##### -->
280 <!-- ##### MACRO g_thread_yield ##### -->
287 <!-- ##### MACRO g_thread_exit ##### -->
294 <!-- ##### STRUCT GMutex ##### -->
297 The #GMutex struct is an opaque data structure to represent a mutex
298 (mutual exclusion). It can be used to protect data against shared
299 access. Take for example the following function:
302 <title>A function which will not work in a threaded environment</title>
304 int give_me_next_number ()
306 static int current_number = 0;
308 /* now do a very complicated calculation to calculate the new number,
309 this might for example be a random number generator */
310 current_number = calc_next_number (current_number);
311 return current_number;
318 It is easy to see, that this won't work in a multithreaded
319 application. There current_number must be protected against shared
320 access. A first naive implementation would be:
325 <title>The wrong way to write a thread-safe function</title>
327 int give_me_next_number ()
329 static int current_number = 0;
331 static GMutex * mutex = NULL;
334 mutex = g_mutex_new ();
335 g_mutex_lock (mutex);
336 ret_val = current_number = calc_next_number (current_number);
337 g_mutex_unlock (mutex);
345 This looks like it would work, but there is a race condition while
346 constructing the mutex and this code can't work reliable. So please do
347 not use such constructs in your own programs. One working solution is:
352 <title>A correct thread-safe function</title>
354 static GMutex *give_me_next_number_mutex = NULL;
356 /* this function must be called before any call to give_me_next_number ()
357 it must be called exactly once. */
358 void init_give_me_next_number ()
360 g_assert (give_me_next_number_mutex == NULL);
361 give_me_next_number_mutex = g_mutex_new ();
364 int give_me_next_number ()
366 static int current_number = 0;
369 g_mutex_lock (give_me_next_number_mutex);
370 ret_val = current_number = calc_next_number (current_number);
371 g_mutex_unlock (give_me_next_number_mutex);
379 #GStaticMutex provides a simpler and safer way of doing this.
383 A #GMutex should only be accessed via the following functions.
388 All of the g_mutex_* functions are actually macros. Apart from taking
389 the addresses of them, you can however use them as if they were functions.
394 <!-- ##### FUNCTION g_mutex_new ##### -->
397 Creates a new #GMutex.
402 This function will abort, if g_thread_init() has not been called yet.
406 @Returns: a new #GMutex.
409 <!-- ##### FUNCTION g_mutex_lock ##### -->
412 Locks the #GMutex. If the #GMutex is already locked by another thread,
413 the current thread will block until the #GMutex is unlocked by the
418 This function can also be used, if g_thread_init() has not yet been
419 called and will do nothing then.
424 #GMutex is not guaranteed to be recursive, i.e. a thread might block,
425 if it already has locked the #GMutex. It will deadlock then, of
433 <!-- ##### FUNCTION g_mutex_trylock ##### -->
436 Tries to lock the #GMutex. If the #GMutex is already locked by another
437 thread, it immediately returns FALSE. Otherwise it locks the #GMutex
442 This function can also be used, if g_thread_init() has not yet been
443 called and will immediately return TRUE then.
447 @Returns: TRUE, if the #GMutex could be locked.
450 <!-- ##### FUNCTION g_mutex_unlock ##### -->
453 Unlocks the #GMutex. If another thread is blocked in a g_mutex_lock()
454 call, it will be woken and can lock the #GMutex itself. This function
455 can also be used, if g_thread_init() has not yet been called and will
462 <!-- ##### FUNCTION g_mutex_free ##### -->
465 Destroys the #GMutex.
471 <!-- ##### STRUCT GStaticMutex ##### -->
474 A #GStaticMutex works like a #GMutex, but it has one significant
475 advantage. It doesn't need to be created at run-time like a #GMutex,
476 but can be defined at compile-time. Here is a shorter, easier and
477 safer version of our give_me_next_number() example:
482 <title>Using GStaticMutex to simplify thread-safe programming</title>
484 int give_me_next_number ()
486 static int current_number = 0;
488 static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
490 g_static_mutex_lock (&mutex);
491 ret_val = current_number = calc_next_number (current_number);
492 g_static_mutex_unlock (&mutex);
500 Even though #GStaticMutex is not opaque, it should only be used with
501 the following functions, as it is defined differently on different
505 <para>All of the g_static_mutex_* functions can also be used, if
506 g_thread_init() has not yet.
511 All of the g_static_mutex_* functions are actually macros. Apart from
512 taking the addresses of them, you can however use them as if they were
518 <!-- ##### MACRO G_STATIC_MUTEX_INIT ##### -->
521 Every #GStaticMutex must be initialized with this macro, before it can
527 <title>Initializing a GStaticMutext</title>
529 GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
536 <!-- ##### FUNCTION g_static_mutex_lock ##### -->
538 works like g_mutex_lock(), but for a #GStaticMutex.
541 @mutex: a #GStaticMutex.
544 <!-- ##### FUNCTION g_static_mutex_trylock ##### -->
547 works like g_mutex_trylock(), but for a #GStaticMutex.
550 @mutex: a #GStaticMutex.
551 @Returns: TRUE, if the #GStaticMutex could be locked.
554 <!-- ##### FUNCTION g_static_mutex_unlock ##### -->
557 works like g_mutex_unlock(), but for a #GStaticMutex.
560 @mutex: a #GStaticMutex.
563 <!-- ##### FUNCTION g_static_mutex_get_mutex ##### -->
566 For some operations (like g_cond_wait()) you must have a #GMutex
567 instead of a #GStaticMutex. This function will return the
568 corresponding #GMutex for every #GStaticMutex.
571 @mutex: a #GStaticMutex.
572 @Returns: the corresponding #GMutex.
575 <!-- ##### MACRO G_LOCK_DEFINE ##### -->
578 The G_LOCK_* macros provide a convenient interface to #GStaticMutex
579 with the advantage that they will expand to nothing in programs
580 compiled against a thread-disabled GLib, saving code and memory
581 there. #G_LOCK_DEFINE defines a lock. It can occur, where variable
582 definitions may occur in programs, i.e. in the first block of a
583 function or outside of functions. The @name parameter will be mangled
584 to get the name of the #GStaticMutex. This means, that you can use
585 names of existing variables as the parameter, e.g. the name of the
586 variable you intent to protect with the lock. Look at our
587 give_me_next_number() example using the G_LOCK_* macros:
592 <title>Using the G_LOCK_* convenience macros</title>
594 G_LOCK_DEFINE (current_number);
596 int give_me_next_number ()
598 static int current_number = 0;
601 G_LOCK (current_number);
602 ret_val = current_number = calc_next_number (current_number);
603 G_UNLOCK (current_number);
610 @name: the name of the lock.
613 <!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
616 This works like #G_LOCK_DEFINE, but it creates a static object.
619 @name: the name of the lock.
622 <!-- ##### MACRO G_LOCK_EXTERN ##### -->
625 This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
628 @name: the name of the lock.
631 <!-- ##### MACRO G_LOCK ##### -->
634 works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
637 @name: the name of the lock.
640 <!-- ##### MACRO G_TRYLOCK ##### -->
643 works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
646 @name: the name of the lock.
647 @Returns: TRUE, if the lock could be locked.
650 <!-- ##### MACRO G_UNLOCK ##### -->
653 works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
656 @name: the name of the lock.
659 <!-- ##### STRUCT GStaticRecMutex ##### -->
668 <!-- ##### MACRO G_STATIC_REC_MUTEX_INIT ##### -->
675 <!-- ##### FUNCTION g_static_rec_mutex_lock ##### -->
683 <!-- ##### FUNCTION g_static_rec_mutex_trylock ##### -->
692 <!-- ##### FUNCTION g_static_rec_mutex_unlock ##### -->
700 <!-- ##### FUNCTION g_static_rec_mutex_lock_full ##### -->
709 <!-- ##### FUNCTION g_static_rec_mutex_unlock_full ##### -->
718 <!-- ##### STRUCT GStaticRWLock ##### -->
730 <!-- ##### MACRO G_STATIC_RW_LOCK_INIT ##### -->
737 <!-- ##### FUNCTION g_static_rw_lock_reader_lock ##### -->
745 <!-- ##### FUNCTION g_static_rw_lock_reader_trylock ##### -->
754 <!-- ##### FUNCTION g_static_rw_lock_reader_unlock ##### -->
762 <!-- ##### FUNCTION g_static_rw_lock_writer_lock ##### -->
770 <!-- ##### FUNCTION g_static_rw_lock_writer_trylock ##### -->
779 <!-- ##### FUNCTION g_static_rw_lock_writer_unlock ##### -->
787 <!-- ##### FUNCTION g_static_rw_lock_free ##### -->
795 <!-- ##### STRUCT GCond ##### -->
798 The #GCond struct is an opaque data structure to represent a
799 condition. A #GCond is an object, that threads can block on, if they
800 find a certain condition to be false. If other threads change the
801 state of this condition they can signal the #GCond, such that the
802 waiting thread is woken up.
807 <title>Using GCond to block a thread until a condition is satisfied</title>
809 GCond* data_cond = NULL; /* Must be initialized somewhere */
810 GMutex* data_mutex = NULL; /* Must be initialized somewhere */
811 gpointer current_data = NULL;
813 void push_data (gpointer data)
815 g_mutex_lock (data_mutex);
817 g_cond_signal (data_cond);
818 g_mutex_unlock (data_mutex);
825 g_mutex_lock (data_mutex);
826 while (!current_data)
827 g_cond_wait (data_cond, data_mutex);
830 g_mutex_unlock (data_mutex);
838 Whenever a thread calls pop_data() now, it will wait until
839 current_data is non-NULL, i.e. until some other thread has called
845 It is important to use the g_cond_wait() and g_cond_timed_wait()
846 functions only inside a loop, which checks for the condition to be
847 true as it is not guaranteed that the waiting thread will find it
848 fulfilled, even if the signaling thread left the condition
849 in that state. This is because another thread can have altered the
850 condition, before the waiting thread got the chance to be woken up,
851 even if the condition itself is protected by a #GMutex, like above.
856 A #GCond should only be accessed via the following functions.
861 All of the g_cond_* functions are actually macros. Apart from taking
862 the addresses of them, you can however use them as if they were functions.
867 <!-- ##### FUNCTION g_cond_new ##### -->
870 Creates a new #GCond. This function will abort, if g_thread_init()
871 has not been called yet.
874 @Returns: a new #GCond.
877 <!-- ##### FUNCTION g_cond_signal ##### -->
879 If threads are waiting for @cond, exactly one of them is woken up. It
880 is good practice to hold the same lock as the waiting thread, while
881 calling this function, though not required.
885 This function can also be used, if g_thread_init() has
886 not yet been called and will do nothing then.
892 <!-- ##### FUNCTION g_cond_broadcast ##### -->
895 If threads are waiting for @cond, all of them are woken up. It is good
896 practice to lock the same mutex as the waiting threads, while calling
897 this function, though not required.
901 This function can also be used, if g_thread_init() has
902 not yet been called and will do nothing then.
908 <!-- ##### FUNCTION g_cond_wait ##### -->
911 Waits until this thread is woken up on the #GCond. The #GMutex is
912 unlocked before falling asleep and locked again before resuming.
916 This function can also be used, if g_thread_init() has not yet been
917 called and will immediately return then.
921 @mutex: the #GMutex, that is currently locked.
924 <!-- ##### FUNCTION g_cond_timed_wait ##### -->
927 Waits until this thread is woken up on the #GCond, but not longer than
928 until the time, that is specified by @abs_time. The #GMutex is
929 unlocked before falling asleep and locked again before resuming.
933 If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
937 This function can also be used, if g_thread_init() has not yet been
938 called and will immediately return TRUE then.
942 @mutex: the #GMutex, that is currently locked.
943 @abs_time: a #GTimeVal, determining the final time.
944 @Returns: TRUE, if the thread is woken up in time.
947 <!-- ##### FUNCTION g_cond_free ##### -->
956 <!-- ##### STRUCT GPrivate ##### -->
958 The #GPrivate struct is an opaque data structure to represent a thread
959 private data key. Threads can thereby obtain and set a pointer, which
960 is private to the current thread. Take our give_me_next_number()
961 example from above. Now we don't want current_number to be shared
962 between the threads, but to be private to each thread. This can be
966 <title>Using GPrivate for per-thread data</title>
968 GPrivate* current_number_key = NULL; /* Must be initialized somewhere */
969 /* with g_private_new (g_free); */
971 int give_me_next_number ()
973 int *current_number = g_private_get (current_number_key);
977 current_number = g_new (int,1);
979 g_private_set (current_number_key, current_number);
981 *current_number = calc_next_number (*current_number);
982 return *current_number;
989 Here the pointer belonging to the key current_number_key is read. If
990 it is NULL, it has not been set yet. Then get memory for an integer
991 value, assign this memory to the pointer and write the pointer
992 back. Now we have an integer value, that is private to the current
997 The #GPrivate struct should only be accessed via the following functions.
1002 All of the g_private_* functions are actually macros. Apart from taking
1003 the addresses of them, you can however use them as if they were functions.
1008 <!-- ##### FUNCTION g_private_new ##### -->
1011 Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer
1012 to a destructor function. Whenever a thread ends and the corresponding
1013 pointer keyed to this instance of #GPrivate is non-NULL, the
1014 destructor is called with this pointer as the argument.
1019 The @destructor is working quite differently from @notify in
1020 g_static_private_set().
1026 A #GPrivate can not be destroyed. Reuse it instead, if you can to
1033 This function will abort, if g_thread_init() has not been called yet.
1037 @destructor: a function to handle the data keyed to #GPrivate, when a
1042 <!-- ##### FUNCTION g_private_get ##### -->
1045 Returns the pointer keyed to @private_key for the current thread. This
1046 pointer is NULL, when g_private_set() hasn't been called for the
1047 current @private_key and thread yet.
1051 This function can also be used, if g_thread_init() has not yet been
1052 called and will return the value of @private_key casted to #gpointer then.
1055 @private_key: a #GPrivate.
1056 @Returns: the corresponding pointer.
1059 <!-- ##### FUNCTION g_private_set ##### -->
1062 Sets the pointer keyed to @private_key for the current thread.
1066 This function can also be used, if g_thread_init() has not yet been
1067 called and will set @private_key to @data casted to #GPrivate* then.
1070 @private_key: a #GPrivate.
1071 @data: the new pointer.
1072 <!-- # Unused Parameters # -->
1076 <!-- ##### STRUCT GStaticPrivate ##### -->
1079 A #GStaticPrivate works almost like a #GPrivate, but it has one
1080 significant advantage. It doesn't need to be created at run-time like
1081 a #GPrivate, but can be defined at compile-time. This is similar to
1082 the difference between #GMutex and #GStaticMutex. Now look at our
1083 give_me_next_number() example with #GStaticPrivate:
1088 <title>Using GStaticPrivate for per-thread data</title>
1090 int give_me_next_number ()
1092 static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
1093 int *current_number = g_static_private_get (&current_number_key);
1095 if (!current_number)
1097 current_number = g_new (int,1);
1098 *current_number = 0;
1099 g_static_private_set (&current_number_key, current_number, g_free);
1101 *current_number = calc_next_number (*current_number);
1102 return *current_number;
1110 <!-- ##### MACRO G_STATIC_PRIVATE_INIT ##### -->
1112 Every #GStaticPrivate must be initialized with this macro, before it can
1119 GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
1126 <!-- ##### FUNCTION g_static_private_get ##### -->
1128 Works like g_private_get() only for a #GStaticPrivate.
1132 This function also works, if g_thread_init() has not yet been called.
1135 @private_key: a #GStaticPrivate.
1136 @Returns: the corresponding pointer.
1139 <!-- ##### FUNCTION g_static_private_get_for_thread ##### -->
1149 <!-- ##### FUNCTION g_static_private_set ##### -->
1151 Sets the pointer keyed to @private_key for the current thread and the
1152 function @notify to be called with that pointer (NULL or non-NULL),
1153 whenever the pointer is set again or whenever the current thread ends.
1157 This function also works, if g_thread_init() has not yet been
1158 called. If g_thread_init() is called later, the @data keyed to
1159 @private_key will be inherited only by the main thread, i.e. the one that
1160 called g_thread_init().
1165 The @notify is working quite differently from @destructor in
1170 @private_key: a #GStaticPrivate.
1171 @data: the new pointer.
1172 @notify: a function to be called with the pointer, whenever the
1173 current thread ends or sets this pointer again.
1176 <!-- ##### FUNCTION g_static_private_set_for_thread ##### -->