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. Future versions of
36 GLib might contain functions to actually create threads and the
37 like. For now the most portable way to create threads is to require
38 the macro #G_THREADS_IMPL_POSIX to be defined and use POSIX threads
39 then. This will work on almost all platforms (except most notably
43 <!-- ##### SECTION See_Also ##### -->
48 <!-- ##### MACRO G_THREADS_ENABLED ##### -->
51 This macro is defined, if GLib was compiled with thread support. This
52 does not necessarily mean, that there is a thread implementation
53 available, but the infrastructure is in place and once you provide a
54 thread implementation to g_thread_init(), GLib will be multithread
55 safe. It isn't and can't be, if #G_THREADS_ENABLED is not defined.
60 <!-- ##### MACRO G_THREADS_IMPL_POSIX ##### -->
63 This macro is defined, if POSIX style threads are used.
68 <!-- ##### MACRO G_THREADS_IMPL_SOLARIS ##### -->
71 This macro is defined, if the SOLARIS thread system is used.
76 <!-- ##### MACRO G_THREADS_IMPL_NSPR ##### -->
79 This macro is defined, if the NSPR thread implementation is used.
80 NSPR is the cross platform library of mozilla.
85 <!-- ##### MACRO G_THREADS_IMPL_NONE ##### -->
88 This macro is defined, if no thread implementation is used. You can
89 however provide one to g_thread_init() to make GLib multithread safe.
94 <!-- ##### STRUCT GThreadFunctions ##### -->
97 This function table is used by g_thread_init() to initialize the
98 thread system. The functions in that table are directly used by their
99 g_* prepended counterparts, that are described here, e.g. if you call
100 g_mutex_new() then mutex_new() from the table provided to
101 g_thread_init() will be called.
106 This struct should only be used, if you know, what you are doing.
125 <!-- ##### FUNCTION g_thread_init ##### -->
128 Before you use a thread related function in GLib, you should
129 initialize the thread system. This is done by calling
130 g_thread_init(). Most of the time you will only have to call
136 You should only call g_thread_init() with a non-NULL parameter, if you
137 really know, what you are doing.
143 g_thread_init() must not be called directly or indirectly as a
149 g_thread_init() might only be called once. On the second call
150 it will abort with an error. If you want to make sure, that the thread
151 system is initialized, you can do that too:
157 if (!g_thread_supported ()) g_thread_init (NULL);
163 After that line either the thread system is initialized or the program
164 will abort, if no thread system is available in GLib, i.e. either
165 #G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined.
169 If no thread system is available and @vtable is NULL or if not all
170 elements of @vtable are non-NULL, then g_thread_init() will abort.
175 To use g_thread_init() in your program, you have to link with the
176 libraries, that the command "glib-config --libs gthread" outputs. This
177 is not the case for all the other thread related functions of
178 GLib. Those can be used without having to link with the thread
183 @vtable: a function table of type #GThreadFunctions, that provides the
184 entry points to the thread system to be used.
187 <!-- ##### MACRO g_thread_supported ##### -->
189 This function returns, whether the thread system is initialized or
195 This function is actually a macro. Apart from taking the address of it
196 you can however use it as if it was a function.
200 @Returns: TRUE, if the thread system is initialized.
203 <!-- ##### STRUCT GMutex ##### -->
206 The #GMutex struct is an opaque data structure to represent a mutex
207 (mutual exclusion). It can be used to protect data against shared
208 access. Take for example the following function:
212 <title>A function which will not work in a threaded environment</title>
214 int give_me_next_number ()
216 static int current_number = 0;
218 /* now do a very complicated calculation to calculate the new number,
219 this might for example be a random number generator */
220 current_number = calc_next_number (current_number);
221 return current_number;
228 It is easy to see, that this won't work in a multithreaded
229 application. There current_number must be protected against shared
230 access. A first naive implementation would be:
235 <title>The wrong way to write a thread-safe function</title>
237 int give_me_next_number ()
239 static int current_number = 0;
241 static GMutex * mutex = NULL;
244 mutex = g_mutex_new ();
245 g_mutex_lock (mutex);
246 ret_val = current_number = calc_next_number (current_number);
247 g_mutex_unlock (mutex);
255 This looks like it would work, but there is a race condition while
256 constructing the mutex and this code can't work reliable. So please do
257 not use such constructs in your own programs. One working solution is:
262 <title>A correct thread-safe function</title>
264 static GMutex *give_me_next_number_mutex = NULL;
266 /* this function must be called before any call to give_me_next_number ()
267 it must be called exactly once. */
268 void init_give_me_next_number ()
270 g_assert (give_me_next_number_mutex == NULL);
271 give_me_next_number_mutex = g_mutex_new ();
274 int give_me_next_number ()
276 static int current_number = 0;
279 g_mutex_lock (give_me_next_number_mutex);
280 ret_val = current_number = calc_next_number (current_number);
281 g_mutex_unlock (give_me_next_number_mutex);
289 #GStaticMutex provides a simpler and safer way of doing this.
293 A #GMutex should only be accessed via the following functions.
298 All of the g_mutex_* functions are actually macros. Apart from taking
299 the addresses of them, you can however use them as if they were functions.
304 <!-- ##### MACRO g_mutex_new ##### -->
307 Creates a new #GMutex.
312 This function will abort, if g_thread_init() has not been called yet.
316 @Returns: a new #GMutex.
319 <!-- ##### MACRO g_mutex_lock ##### -->
322 Locks the #GMutex. If the #GMutex is already locked by another thread,
323 the current thread will block until the #GMutex is unlocked by the
328 This function can also be used, if g_thread_init() has not yet been
329 called and will do nothing then.
334 #GMutex is not guaranteed to be recursive, i.e. a thread might block,
335 if it already has locked the #GMutex. It will deadlock then, of
343 <!-- ##### MACRO g_mutex_trylock ##### -->
346 Tries to lock the #GMutex. If the #GMutex is already locked by another
347 thread, it immediately returns FALSE. Otherwise it locks the #GMutex
352 This function can also be used, if g_thread_init() has not yet been
353 called and will immediately return TRUE then.
357 @Returns: TRUE, if the #GMutex could be locked.
360 <!-- ##### MACRO g_mutex_unlock ##### -->
363 Unlocks the #GMutex. If another thread is blocked in a g_mutex_lock()
364 call, it will be woken and can lock the #GMutex itself. This function
365 can also be used, if g_thread_init() has not yet been called and will
372 <!-- ##### MACRO g_mutex_free ##### -->
375 Destroys the #GMutex.
381 <!-- ##### STRUCT GStaticMutex ##### -->
384 A #GStaticMutex works like a #GMutex, but it has one significant
385 advantage. It doesn't need to be created at run-time like a #GMutex,
386 but can be defined at compile-time. Here is a shorter, easier and
387 safer version of our give_me_next_number() example:
392 <title>Using GStaticMutex to simplify thread-safe programming</title>
394 int give_me_next_number ()
396 static int current_number = 0;
398 static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
400 g_static_mutex_lock (&mutex);
401 ret_val = current_number = calc_next_number (current_number);
402 g_static_mutex_unlock (&mutex);
410 Even though #GStaticMutex is not opaque, it should only be used with
411 the following functions, as it is defined differently on different
415 <para>All of the g_static_mutex_* functions can also be used, if
416 g_thread_init() has not yet.
421 All of the g_static_mutex_* functions are actually macros. Apart from
422 taking the addresses of them, you can however use them as if they were
429 <!-- ##### MACRO G_STATIC_MUTEX_INIT ##### -->
432 Every #GStaticMutex must be initialized with this macro, before it can
438 <title>Initializing a GStaticMutext</title>
440 GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
447 <!-- ##### MACRO g_static_mutex_lock ##### -->
449 works like g_mutex_lock(), but for a #GStaticMutex.
452 @mutex: a #GStaticMutex.
455 <!-- ##### MACRO g_static_mutex_trylock ##### -->
458 works like g_mutex_trylock(), but for a #GStaticMutex.
461 @mutex: a #GStaticMutex.
462 @Returns: TRUE, if the #GStaticMutex could be locked.
465 <!-- ##### MACRO g_static_mutex_unlock ##### -->
468 works like g_mutex_unlock(), but for a #GStaticMutex.
471 @mutex: a #GStaticMutex.
474 <!-- ##### MACRO g_static_mutex_get_mutex ##### -->
477 For some operations (like g_cond_wait()) you must have a #GMutex
478 instead of a #GStaticMutex. This function will return the
479 corresponding #GMutex for every #GStaticMutex.
482 @mutex: a #GStaticMutex.
483 @Returns: the corresponding #GMutex.
486 <!-- ##### MACRO G_LOCK_DEFINE ##### -->
489 The G_LOCK_* macros provide a convenient interface to #GStaticMutex
490 with the advantage that they will expand to nothing in programs
491 compiled against a thread-disabled GLib, saving code and memory
492 there. #G_LOCK_DEFINE defines a lock. It can occur, where variable
493 definitions may occur in programs, i.e. in the first block of a
494 function or outside of functions. The @name parameter will be mangled
495 to get the name of the #GStaticMutex. This means, that you can use
496 names of existing variables as the parameter, e.g. the name of the
497 variable you intent to protect with the lock. Look at our
498 give_me_next_number() example using the G_LOCK_* macros:
503 <title>Using the G_LOCK_* convenience macros</title>
505 int give_me_next_number ()
507 static int current_number = 0;
509 G_LOCK_DEFINE_STATIC (current_number);
511 G_LOCK (current_number);
512 ret_val = current_number = calc_next_number (current_number);
513 G_UNLOCK (current_number);
520 @name: the name of the lock.
523 <!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
526 This works like #G_LOCK_DEFINE, but it creates a static object.
529 @name: the name of the lock.
532 <!-- ##### MACRO G_LOCK_EXTERN ##### -->
535 This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
538 @name: the name of the lock.
541 <!-- ##### MACRO G_LOCK ##### -->
544 works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
547 @name: the name of the lock.
550 <!-- ##### MACRO G_TRYLOCK ##### -->
553 works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
556 @name: the name of the lock.
557 @Returns: TRUE, if the lock could be locked.
560 <!-- ##### MACRO G_UNLOCK ##### -->
563 works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
566 @name: the name of the lock.
569 <!-- ##### STRUCT GCond ##### -->
572 The #GCond struct is an opaque data structure to represent a
573 condition. A #GCond is an object, that threads can block on, if they
574 find a certain condition to be false. If other threads change the
575 state of this condition they can signal the #GCond, such that the
576 waiting thread is woken up.
581 <title>Using GCond to block a thread until a condition is satisfied</title>
583 GCond* data_cond = NULL; /* Must be initialized somewhere */
584 GMutex* data_mutex = NULL; /* Must be initialized somewhere */
585 gpointer current_data = NULL;
587 void push_data (gpointer data)
589 g_mutex_lock (data_mutex);
591 g_cond_signal (data_cond);
592 g_mutex_unlock (data_mutex);
599 g_mutex_lock (data_mutex);
600 while (!current_data)
601 g_cond_wait (data_cond, data_mutex);
604 g_mutex_unlock (data_mutex);
612 Whenever a thread calls pop_data() now, it will wait until
613 current_data is non-NULL, i.e. until some other thread has called
619 It is important to use the g_cond_wait() and g_cond_timed_wait()
620 functions only inside a loop, which checks for the condition to be
621 true as it is not guaranteed that the waiting thread will find it
622 fulfilled, even if the signaling thread left the condition
623 in that state. This is because another thread can have altered the
624 condition, before the waiting thread got the chance to be woken up,
625 even if the condition itself is protected by a #GMutex, like above.
630 A #GCond should only be accessed via the following functions.
635 All of the g_cond_* functions are actually macros. Apart from taking
636 the addresses of them, you can however use them as if they were functions.
641 <!-- ##### MACRO g_cond_new ##### -->
644 Creates a new #GCond. This function will abort, if g_thread_init()
645 has not been called yet.
648 @Returns: a new #GCond.
651 <!-- ##### MACRO g_cond_signal ##### -->
653 If threads are waiting for @cond, exactly one of them is woken up. It
654 is good practice to hold the same lock as the waiting thread, while
655 calling this function, though not required.
659 This function can also be used, if g_thread_init() has
660 not yet been called and will do nothing then.
666 <!-- ##### MACRO g_cond_broadcast ##### -->
669 If threads are waiting for @cond, all of them are woken up. It is good
670 practice to lock the same mutex as the waiting threads, while calling
671 this function, though not required.
675 This function can also be used, if g_thread_init() has
676 not yet been called and will do nothing then.
682 <!-- ##### MACRO g_cond_wait ##### -->
685 Waits until this thread is woken up on the #GCond. The #GMutex is
686 unlocked before falling asleep and locked again before resuming.
690 This function can also be used, if g_thread_init() has not yet been
691 called and will immediately return then.
695 @mutex: the #GMutex, that is currently locked.
698 <!-- ##### MACRO g_cond_timed_wait ##### -->
701 Waits until this thread is woken up on the #GCond, but not longer than
702 until the time, that is specified by @abs_time. The #GMutex is
703 unlocked before falling asleep and locked again before resuming.
707 If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
711 This function can also be used, if g_thread_init() has not yet been
712 called and will immediately return TRUE then.
716 @mutex: the #GMutex, that is currently locked.
717 @abs_time: a #GTimeVal, determining the final time.
718 @Returns: TRUE, if the thread is woken up in time.
721 <!-- ##### MACRO g_cond_free ##### -->
730 <!-- ##### STRUCT GPrivate ##### -->
732 The #GPrivate struct is an opaque data structure to represent a thread
733 private data key. Threads can thereby obtain and set a pointer, which
734 is private to the current thread. Take our give_me_next_number()
735 example from above. Now we don't want current_number to be shared
736 between the threads, but to be private to each thread. This can be
741 <title>Using GPrivate for per-thread data</title>
743 GPrivate* current_number_key = NULL; /* Must be initialized somewhere */
744 /* with g_private_new (g_free); */
746 int give_me_next_number ()
748 int *current_number = g_private_get (current_number_key);
752 current_number = g_new (int,1);
754 g_private_set (current_number_key, current_number);
756 *current_number = calc_next_number (*current_number);
757 return *current_number;
764 Here the pointer belonging to the key current_number_key is read. If
765 it is NULL, it has not been set yet. Then get memory for an integer
766 value, assign this memory to the pointer and write the pointer
767 back. Now we have an integer value, that is private to the current
772 The #GPrivate struct should only be accessed via the following functions.
777 All of the g_private_* functions are actually macros. Apart from taking
778 the addresses of them, you can however use them as if they were functions.
783 <!-- ##### MACRO g_private_new ##### -->
786 Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer
787 to a destructor function. Whenever a thread ends and the corresponding
788 pointer keyed to this instance of #GPrivate is non-NULL, the
789 destructor is called with this pointer as the argument.
794 The @destructor is working quite differently from @notify in
795 g_static_private_set().
801 A #GPrivate can not be destroyed. Reuse it instead, if you can to
808 This function will abort, if g_thread_init() has not been called yet.
812 @destructor: a function to handle the data keyed to #GPrivate, when a
816 <!-- ##### MACRO g_private_get ##### -->
819 Returns the pointer keyed to @private_key for the current thread. This
820 pointer is NULL, when g_private_set() hasn't been called for the
821 current @private_key and thread yet.
825 This function can also be used, if g_thread_init() has not yet been
826 called and will return the value of @private_key casted to #gpointer then.
829 @private_key: a #GPrivate.
830 @Returns: the corresponding pointer.
833 <!-- ##### MACRO g_private_set ##### -->
836 Sets the pointer keyed to @private_key for the current thread.
840 This function can also be used, if g_thread_init() has not yet been
841 called and will set @private_key to @data casted to #GPrivate* then.
844 @private_key: a #GPrivate.
846 <!-- # Unused Parameters # -->
847 @data: the new pointer.
850 <!-- ##### STRUCT GStaticPrivate ##### -->
853 A #GStaticPrivate works almost like a #GPrivate, but it has one
854 significant advantage. It doesn't need to be created at run-time like
855 a #GPrivate, but can be defined at compile-time. This is similar to
856 the difference between #GMutex and #GStaticMutex. Now look at our
857 give_me_next_number() example with #GStaticPrivate:
862 <title>Using GStaticPrivate for per-thread data</title>
864 int give_me_next_number ()
866 static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
867 int *current_number = g_static_private_get (&current_number_key);
871 current_number = g_new (int,1);
873 g_static_private_set (&current_number_key, current_number, g_free);
875 *current_number = calc_next_number (*current_number);
876 return *current_number;
884 <!-- ##### MACRO G_STATIC_PRIVATE_INIT ##### -->
886 Every #GStaticPrivate must be initialized with this macro, before it can
893 GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
900 <!-- ##### FUNCTION g_static_private_get ##### -->
902 Works like g_private_get() only for a #GStaticPrivate.
906 This function also works, if g_thread_init() has not yet been called.
909 @private_key: a #GStaticPrivate.
910 @Returns: the corresponding pointer.
913 <!-- ##### FUNCTION g_static_private_set ##### -->
915 Sets the pointer keyed to @private_key for the current thread and the
916 function @notify to be called with that pointer (NULL or non-NULL),
917 whenever the pointer is set again or whenever the current thread ends.
921 This function also works, if g_thread_init() has not yet been
922 called. If g_thread_init() is called later, the @data keyed to
923 @private_key will be inherited only by the main thread, i.e. the one that
924 called g_thread_init().
929 The @notify is working quite differently from @destructor in
934 @private_key: a #GStaticPrivate.
935 @data: the new pointer.
936 @notify: a function to be called with the pointer, whenever the
937 current thread ends or sets this pointer again.