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 <!-- ##### STRUCT GThreadFunctions ##### -->
87 This function table is used by g_thread_init() to initialize the
88 thread system. The functions in that table are directly used by their
89 g_* prepended counterparts, that are described here, e.g. if you call
90 g_mutex_new() then mutex_new() from the table provided to
91 g_thread_init() will be called.
96 This struct should only be used, if you know, what you are doing.
115 <!-- ##### FUNCTION g_thread_init ##### -->
118 Before you use a thread related function in GLib, you should
119 initialize the thread system. This is done by calling
120 g_thread_init(). Most of the time you will only have to call
126 You should only call g_thread_init() with a non-NULL parameter, if you
127 really know, what you are doing.
133 g_thread_init() must not be called directly or indirectly as a
139 g_thread_init() might only be called once. On the second call
140 it will abort with an error. If you want to make sure, that the thread
141 system is initialized, you can do that too:
147 if (!g_thread_supported ()) g_thread_init (NULL);
153 After that line either the thread system is initialized or the program
154 will abort, if no thread system is available in GLib, i.e. either
155 #G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined.
159 If no thread system is available and @vtable is NULL or if not all
160 elements of @vtable are non-NULL, then g_thread_init() will abort.
165 To use g_thread_init() in your program, you have to link with the
166 libraries, that the command "glib-config --libs gthread" outputs. This
167 is not the case for all the other thread related functions of
168 GLib. Those can be used without having to link with the thread
173 @vtable: a function table of type #GThreadFunctions, that provides the
174 entry points to the thread system to be used.
177 <!-- ##### MACRO g_thread_supported ##### -->
179 This function returns, whether the thread system is initialized or
185 This function is actually a macro. Apart from taking the address of it
186 you can however use it as if it was a function.
190 @Returns: TRUE, if the thread system is initialized.
193 <!-- ##### STRUCT GMutex ##### -->
196 The #GMutex struct is an opaque data structure to represent a mutex
197 (mutual exclusion). It can be used to protect data against shared
198 access. Take for example the following function:
201 <title>A function which will not work in a threaded environment</title>
203 int give_me_next_number ()
205 static int current_number = 0;
207 /* now do a very complicated calculation to calculate the new number,
208 this might for example be a random number generator */
209 current_number = calc_next_number (current_number);
210 return current_number;
217 It is easy to see, that this won't work in a multithreaded
218 application. There current_number must be protected against shared
219 access. A first naive implementation would be:
224 <title>The wrong way to write a thread-safe function</title>
226 int give_me_next_number ()
228 static int current_number = 0;
230 static GMutex * mutex = NULL;
233 mutex = g_mutex_new ();
234 g_mutex_lock (mutex);
235 ret_val = current_number = calc_next_number (current_number);
236 g_mutex_unlock (mutex);
244 This looks like it would work, but there is a race condition while
245 constructing the mutex and this code can't work reliable. So please do
246 not use such constructs in your own programs. One working solution is:
251 <title>A correct thread-safe function</title>
253 static GMutex *give_me_next_number_mutex = NULL;
255 /* this function must be called before any call to give_me_next_number ()
256 it must be called exactly once. */
257 void init_give_me_next_number ()
259 g_assert (give_me_next_number_mutex == NULL);
260 give_me_next_number_mutex = g_mutex_new ();
263 int give_me_next_number ()
265 static int current_number = 0;
268 g_mutex_lock (give_me_next_number_mutex);
269 ret_val = current_number = calc_next_number (current_number);
270 g_mutex_unlock (give_me_next_number_mutex);
278 #GStaticMutex provides a simpler and safer way of doing this.
282 A #GMutex should only be accessed via the following functions.
287 All of the g_mutex_* functions are actually macros. Apart from taking
288 the addresses of them, you can however use them as if they were functions.
293 <!-- ##### MACRO g_mutex_new ##### -->
296 Creates a new #GMutex.
301 This function will abort, if g_thread_init() has not been called yet.
305 @Returns: a new #GMutex.
308 <!-- ##### MACRO g_mutex_lock ##### -->
311 Locks the #GMutex. If the #GMutex is already locked by another thread,
312 the current thread will block until the #GMutex is unlocked by the
317 This function can also be used, if g_thread_init() has not yet been
318 called and will do nothing then.
323 #GMutex is not guaranteed to be recursive, i.e. a thread might block,
324 if it already has locked the #GMutex. It will deadlock then, of
332 <!-- ##### MACRO g_mutex_trylock ##### -->
335 Tries to lock the #GMutex. If the #GMutex is already locked by another
336 thread, it immediately returns FALSE. Otherwise it locks the #GMutex
341 This function can also be used, if g_thread_init() has not yet been
342 called and will immediately return TRUE then.
346 @Returns: TRUE, if the #GMutex could be locked.
349 <!-- ##### MACRO g_mutex_unlock ##### -->
352 Unlocks the #GMutex. If another thread is blocked in a g_mutex_lock()
353 call, it will be woken and can lock the #GMutex itself. This function
354 can also be used, if g_thread_init() has not yet been called and will
361 <!-- ##### MACRO g_mutex_free ##### -->
364 Destroys the #GMutex.
370 <!-- ##### STRUCT GStaticMutex ##### -->
373 A #GStaticMutex works like a #GMutex, but it has one significant
374 advantage. It doesn't need to be created at run-time like a #GMutex,
375 but can be defined at compile-time. Here is a shorter, easier and
376 safer version of our give_me_next_number() example:
381 <title>Using GStaticMutex to simplify thread-safe programming</title>
383 int give_me_next_number ()
385 static int current_number = 0;
387 static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
389 g_static_mutex_lock (&mutex);
390 ret_val = current_number = calc_next_number (current_number);
391 g_static_mutex_unlock (&mutex);
399 Even though #GStaticMutex is not opaque, it should only be used with
400 the following functions, as it is defined differently on different
404 <para>All of the g_static_mutex_* functions can also be used, if
405 g_thread_init() has not yet.
410 All of the g_static_mutex_* functions are actually macros. Apart from
411 taking the addresses of them, you can however use them as if they were
418 <!-- ##### MACRO G_STATIC_MUTEX_INIT ##### -->
421 Every #GStaticMutex must be initialized with this macro, before it can
427 <title>Initializing a GStaticMutext</title>
429 GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
436 <!-- ##### MACRO g_static_mutex_lock ##### -->
438 works like g_mutex_lock(), but for a #GStaticMutex.
441 @mutex: a #GStaticMutex.
444 <!-- ##### MACRO g_static_mutex_trylock ##### -->
447 works like g_mutex_trylock(), but for a #GStaticMutex.
450 @mutex: a #GStaticMutex.
451 @Returns: TRUE, if the #GStaticMutex could be locked.
454 <!-- ##### MACRO g_static_mutex_unlock ##### -->
457 works like g_mutex_unlock(), but for a #GStaticMutex.
460 @mutex: a #GStaticMutex.
463 <!-- ##### MACRO g_static_mutex_get_mutex ##### -->
466 For some operations (like g_cond_wait()) you must have a #GMutex
467 instead of a #GStaticMutex. This function will return the
468 corresponding #GMutex for every #GStaticMutex.
471 @mutex: a #GStaticMutex.
472 @Returns: the corresponding #GMutex.
475 <!-- ##### MACRO G_LOCK_DEFINE ##### -->
478 The G_LOCK_* macros provide a convenient interface to #GStaticMutex
479 with the advantage that they will expand to nothing in programs
480 compiled against a thread-disabled GLib, saving code and memory
481 there. #G_LOCK_DEFINE defines a lock. It can occur, where variable
482 definitions may occur in programs, i.e. in the first block of a
483 function or outside of functions. The @name parameter will be mangled
484 to get the name of the #GStaticMutex. This means, that you can use
485 names of existing variables as the parameter, e.g. the name of the
486 variable you intent to protect with the lock. Look at our
487 give_me_next_number() example using the G_LOCK_* macros:
492 <title>Using the G_LOCK_* convenience macros</title>
494 G_LOCK_DEFINE (current_number);
496 int give_me_next_number ()
498 static int current_number = 0;
501 G_LOCK (current_number);
502 ret_val = current_number = calc_next_number (current_number);
503 G_UNLOCK (current_number);
510 @name: the name of the lock.
513 <!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
516 This works like #G_LOCK_DEFINE, but it creates a static object.
519 @name: the name of the lock.
522 <!-- ##### MACRO G_LOCK_EXTERN ##### -->
525 This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
528 @name: the name of the lock.
531 <!-- ##### MACRO G_LOCK ##### -->
534 works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
537 @name: the name of the lock.
540 <!-- ##### MACRO G_TRYLOCK ##### -->
543 works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
546 @name: the name of the lock.
547 @Returns: TRUE, if the lock could be locked.
550 <!-- ##### MACRO G_UNLOCK ##### -->
553 works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
556 @name: the name of the lock.
559 <!-- ##### STRUCT GCond ##### -->
562 The #GCond struct is an opaque data structure to represent a
563 condition. A #GCond is an object, that threads can block on, if they
564 find a certain condition to be false. If other threads change the
565 state of this condition they can signal the #GCond, such that the
566 waiting thread is woken up.
571 <title>Using GCond to block a thread until a condition is satisfied</title>
573 GCond* data_cond = NULL; /* Must be initialized somewhere */
574 GMutex* data_mutex = NULL; /* Must be initialized somewhere */
575 gpointer current_data = NULL;
577 void push_data (gpointer data)
579 g_mutex_lock (data_mutex);
581 g_cond_signal (data_cond);
582 g_mutex_unlock (data_mutex);
589 g_mutex_lock (data_mutex);
590 while (!current_data)
591 g_cond_wait (data_cond, data_mutex);
594 g_mutex_unlock (data_mutex);
602 Whenever a thread calls pop_data() now, it will wait until
603 current_data is non-NULL, i.e. until some other thread has called
609 It is important to use the g_cond_wait() and g_cond_timed_wait()
610 functions only inside a loop, which checks for the condition to be
611 true as it is not guaranteed that the waiting thread will find it
612 fulfilled, even if the signaling thread left the condition
613 in that state. This is because another thread can have altered the
614 condition, before the waiting thread got the chance to be woken up,
615 even if the condition itself is protected by a #GMutex, like above.
620 A #GCond should only be accessed via the following functions.
625 All of the g_cond_* functions are actually macros. Apart from taking
626 the addresses of them, you can however use them as if they were functions.
631 <!-- ##### MACRO g_cond_new ##### -->
634 Creates a new #GCond. This function will abort, if g_thread_init()
635 has not been called yet.
638 @Returns: a new #GCond.
641 <!-- ##### MACRO g_cond_signal ##### -->
643 If threads are waiting for @cond, exactly one of them is woken up. It
644 is good practice to hold the same lock as the waiting thread, while
645 calling this function, though not required.
649 This function can also be used, if g_thread_init() has
650 not yet been called and will do nothing then.
656 <!-- ##### MACRO g_cond_broadcast ##### -->
659 If threads are waiting for @cond, all of them are woken up. It is good
660 practice to lock the same mutex as the waiting threads, while calling
661 this function, though not required.
665 This function can also be used, if g_thread_init() has
666 not yet been called and will do nothing then.
672 <!-- ##### MACRO g_cond_wait ##### -->
675 Waits until this thread is woken up on the #GCond. The #GMutex is
676 unlocked before falling asleep and locked again before resuming.
680 This function can also be used, if g_thread_init() has not yet been
681 called and will immediately return then.
685 @mutex: the #GMutex, that is currently locked.
688 <!-- ##### MACRO g_cond_timed_wait ##### -->
691 Waits until this thread is woken up on the #GCond, but not longer than
692 until the time, that is specified by @abs_time. The #GMutex is
693 unlocked before falling asleep and locked again before resuming.
697 If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
701 This function can also be used, if g_thread_init() has not yet been
702 called and will immediately return TRUE then.
706 @mutex: the #GMutex, that is currently locked.
707 @abs_time: a #GTimeVal, determining the final time.
708 @Returns: TRUE, if the thread is woken up in time.
711 <!-- ##### MACRO g_cond_free ##### -->
720 <!-- ##### STRUCT GPrivate ##### -->
722 The #GPrivate struct is an opaque data structure to represent a thread
723 private data key. Threads can thereby obtain and set a pointer, which
724 is private to the current thread. Take our give_me_next_number()
725 example from above. Now we don't want current_number to be shared
726 between the threads, but to be private to each thread. This can be
730 <title>Using GPrivate for per-thread data</title>
732 GPrivate* current_number_key = NULL; /* Must be initialized somewhere */
733 /* with g_private_new (g_free); */
735 int give_me_next_number ()
737 int *current_number = g_private_get (current_number_key);
741 current_number = g_new (int,1);
743 g_private_set (current_number_key, current_number);
745 *current_number = calc_next_number (*current_number);
746 return *current_number;
753 Here the pointer belonging to the key current_number_key is read. If
754 it is NULL, it has not been set yet. Then get memory for an integer
755 value, assign this memory to the pointer and write the pointer
756 back. Now we have an integer value, that is private to the current
761 The #GPrivate struct should only be accessed via the following functions.
766 All of the g_private_* functions are actually macros. Apart from taking
767 the addresses of them, you can however use them as if they were functions.
772 <!-- ##### MACRO g_private_new ##### -->
775 Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer
776 to a destructor function. Whenever a thread ends and the corresponding
777 pointer keyed to this instance of #GPrivate is non-NULL, the
778 destructor is called with this pointer as the argument.
783 The @destructor is working quite differently from @notify in
784 g_static_private_set().
790 A #GPrivate can not be destroyed. Reuse it instead, if you can to
797 This function will abort, if g_thread_init() has not been called yet.
801 @destructor: a function to handle the data keyed to #GPrivate, when a
805 <!-- ##### MACRO g_private_get ##### -->
808 Returns the pointer keyed to @private_key for the current thread. This
809 pointer is NULL, when g_private_set() hasn't been called for the
810 current @private_key and thread yet.
814 This function can also be used, if g_thread_init() has not yet been
815 called and will return the value of @private_key casted to #gpointer then.
818 @private_key: a #GPrivate.
819 @Returns: the corresponding pointer.
822 <!-- ##### MACRO g_private_set ##### -->
825 Sets the pointer keyed to @private_key for the current thread.
829 This function can also be used, if g_thread_init() has not yet been
830 called and will set @private_key to @data casted to #GPrivate* then.
833 @private_key: a #GPrivate.
835 <!-- # Unused Parameters # -->
836 @data: the new pointer.
839 <!-- ##### STRUCT GStaticPrivate ##### -->
842 A #GStaticPrivate works almost like a #GPrivate, but it has one
843 significant advantage. It doesn't need to be created at run-time like
844 a #GPrivate, but can be defined at compile-time. This is similar to
845 the difference between #GMutex and #GStaticMutex. Now look at our
846 give_me_next_number() example with #GStaticPrivate:
851 <title>Using GStaticPrivate for per-thread data</title>
853 int give_me_next_number ()
855 static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
856 int *current_number = g_static_private_get (&current_number_key);
860 current_number = g_new (int,1);
862 g_static_private_set (&current_number_key, current_number, g_free);
864 *current_number = calc_next_number (*current_number);
865 return *current_number;
873 <!-- ##### MACRO G_STATIC_PRIVATE_INIT ##### -->
875 Every #GStaticPrivate must be initialized with this macro, before it can
882 GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
889 <!-- ##### FUNCTION g_static_private_get ##### -->
891 Works like g_private_get() only for a #GStaticPrivate.
895 This function also works, if g_thread_init() has not yet been called.
898 @private_key: a #GStaticPrivate.
899 @Returns: the corresponding pointer.
902 <!-- ##### FUNCTION g_static_private_set ##### -->
904 Sets the pointer keyed to @private_key for the current thread and the
905 function @notify to be called with that pointer (NULL or non-NULL),
906 whenever the pointer is set again or whenever the current thread ends.
910 This function also works, if g_thread_init() has not yet been
911 called. If g_thread_init() is called later, the @data keyed to
912 @private_key will be inherited only by the main thread, i.e. the one that
913 called g_thread_init().
918 The @notify is working quite differently from @destructor in
923 @private_key: a #GStaticPrivate.
924 @data: the new pointer.
925 @notify: a function to be called with the pointer, whenever the
926 current thread ends or sets this pointer again.