1 <!-- ##### SECTION Title ##### -->
5 <!-- ##### SECTION Short_Description ##### -->
7 thread abstraction; including threads, different mutexes, conditions
8 and thread private data.
10 <!-- ##### SECTION Long_Description ##### -->
13 Threads act almost like processes, but unlike processes all threads of
14 one process share the same memory. This is good, as it provides easy
15 communication between the involved threads via this shared memory, and
16 it is bad, because strange things (so called Heisenbugs) might happen,
17 when the program is not carefully designed. Especially bad is, that due
18 to the concurrent nature of threads no assumptions on the order of
19 execution of different threads can be done unless explicitly forced by
20 the programmer through synchronization primitives.
24 The aim of the thread related functions in GLib is to provide a
25 portable means for writing multi-threaded software. There are
26 primitives for mutexes to protect the access to portions of memory
27 (#GMutex, #GStaticMutex, #G_LOCK_DEFINE, #GStaticRecMutex and
28 #GStaticRWLock), there are primitives for condition variables to allow
29 synchronization of threads (#GCond) and finally there are primitives
30 for thread-private data, that every thread has a private instance of
31 (#GPrivate, #GStaticPrivate). Last but definitely not least there are
32 primitives to portably create and manage threads (#GThread).
35 <!-- ##### SECTION See_Also ##### -->
40 <term>#GThreadPool</term>
41 <listitem><para>Thread pools.</para></listitem>
45 <term>#GAsyncQueue</term>
46 <listitem><para>Send asynchronous messages between threads.</para></listitem>
52 <!-- ##### MACRO G_THREADS_ENABLED ##### -->
55 This macro is defined, if GLib was compiled with thread support. This
56 does not necessarily mean, that there is a thread implementation
57 available, but the infrastructure is in place and once you provide a
58 thread implementation to g_thread_init(), GLib will be multi-thread
59 safe. It isn't and cannot be, if #G_THREADS_ENABLED is not defined.
64 <!-- ##### MACRO G_THREADS_IMPL_POSIX ##### -->
67 This macro is defined, if POSIX style threads are used.
72 <!-- ##### MACRO G_THREADS_IMPL_SOLARIS ##### -->
75 This macro is defined, if the Solaris thread system is used.
80 <!-- ##### MACRO G_THREADS_IMPL_NONE ##### -->
83 This macro is defined, if no thread implementation is used. You can
84 however provide one to g_thread_init() to make GLib multi-thread safe.
89 <!-- ##### MACRO G_THREAD_ERROR ##### -->
91 The error domain of the GLib thread subsystem.
96 <!-- ##### ENUM GThreadError ##### -->
98 Possible errors of thread related functions.
101 @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource
102 shortage. Try again later.
104 <!-- ##### STRUCT GThreadFunctions ##### -->
107 This function table is used by g_thread_init() to initialize the
108 thread system. The functions in that table are directly used by their
109 g_* prepended counterparts, that are described here, e.g. if you call
110 g_mutex_new() then mutex_new() from the table provided to
111 g_thread_init() will be called.
116 This struct should only be used, if you know, what you are doing.
138 @thread_set_priority:
141 <!-- ##### FUNCTION g_thread_init ##### -->
144 Before you use a thread related function in GLib, you should
145 initialize the thread system. This is done by calling
146 g_thread_init(). Most of the time you will only have to call
152 You should only call g_thread_init() with a non-NULL parameter, if you
153 really know, what you are doing.
159 g_thread_init() must not be called directly or indirectly as a
160 call-back from GLib. Also no mutexes may be currently locked, while
161 calling g_thread_init().
166 g_thread_init() might only be called once. On the second call
167 it will abort with an error. If you want to make sure, that the thread
168 system is initialized, you can do that too:
174 if (!g_thread_supported ()) g_thread_init (NULL);
180 After that line either the thread system is initialized or the program
181 will abort, if no thread system is available in GLib, i.e. either
182 #G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined.
186 If no thread system is available and @vtable is NULL or if not all
187 elements of @vtable are non-NULL, then g_thread_init() will abort.
192 To use g_thread_init() in your program, you have to link with the
193 libraries, that the command "glib-config --libs gthread" outputs. This
194 is not the case for all the other thread related functions of
195 GLib. Those can be used without having to link with the thread
200 @vtable: a function table of type #GThreadFunctions, that provides the
201 entry points to the thread system to be used
204 <!-- ##### FUNCTION g_thread_supported ##### -->
206 This function returns, whether the thread system is initialized or
212 This function is actually a macro. Apart from taking the address of it
213 you can however use it as if it was a function.
217 @Returns: TRUE, if the thread system is initialized
220 <!-- ##### USER_FUNCTION GThreadFunc ##### -->
222 Specifies the type of the @func functions passed to
223 g_thread_create() or g_thread_create_full().
226 @data: data passed to the thread
227 @Returns: the return value of the thread, which will be returned by
231 <!-- ##### ENUM GThreadPriority ##### -->
233 Specifies the priority of a thread.
238 It is not guaranteed, that threads with different priorities really
239 behave accordingly. On some systems (e.g. Linux) only root can increase
240 priorities. On other systems (e.g. Solaris) there doesn't seem to be
241 different scheduling for different priorities. All in all try to avoid
242 being dependent on priorities.
246 @G_THREAD_PRIORITY_LOW: a priority lower than normal
247 @G_THREAD_PRIORITY_NORMAL: the default priority
248 @G_THREAD_PRIORITY_HIGH: a priority higher than normal
249 @G_THREAD_PRIORITY_URGENT: the highest priority
251 <!-- ##### STRUCT GThread ##### -->
253 The #GThread struct represents a running thread. It has three public
254 read-only members, but the underlying struct is bigger, so you must
255 not copy this struct.
260 Resources for a joinable thread are not fully released until
261 g_thread_join() is called for that thread.
265 @func: the function executing in that thread
266 @data: the argument to the function
267 @joinable: is this thread joinable?
268 @priority: the priority of the thread
270 <!-- ##### FUNCTION g_thread_create ##### -->
272 This function creates a new thread with the priority @priority.
276 If @joinable is #TRUE, you can wait for this threads termination
277 calling g_thread_wait(). Otherwise the thread will just disappear, when
282 The new thread executes the function @func with the argument
283 @data. If the thread was created successfully, it is returned.
287 @error can be NULL to ignore errors, or non-NULL to report errors. The
288 error is set, if and only if the function returns #NULL.
291 @func: a function to execute in the new thread
292 @data: an argument to supply to the new thread
293 @joinable: should this thread be joinable?
294 @error: return location for error.
295 @Returns: the new #GThread on success
298 <!-- ##### FUNCTION g_thread_create_full ##### -->
300 This function creates a new thread with the priority @priority. The
301 stack gets the size @stack_size or the default value for the current
302 platform, if @stack_size is 0.
306 If @joinable is #TRUE, you can wait for this threads termination
307 calling g_thread_wait(). Otherwise the thread will just disappear, when
308 ready. If @bound is #TRUE, this thread will be scheduled in the system
309 scope, otherwise the implementation is free to do scheduling in the
310 process scope. The first variant is more expensive resource-wise, but
311 generally faster. On some systems (e.g. Linux) all threads are bound.
315 The new thread executes the function @func with the argument
316 @data. If the thread was created successfully, it is returned.
320 @error can be NULL to ignore errors, or non-NULL to report errors. The
321 error is set, if and only if the function returns #NULL.
326 It is not guaranteed, that threads with different priorities really
327 behave accordingly. On some systems (e.g. Linux) only root can increase
328 priorities. On other systems (e.g. Solaris) there doesn't seem to be
329 different scheduling for different priorities. All in all try to avoid
330 being dependent on priorities. Use %G_THREAD_PRIORITY_NORMAL here as a
337 Only use g_thread_create_full(), when you really can't use
338 g_thread_create() instead. g_thread_create() does not take
339 @stack_size, @bound and @priority as arguments, as they should only be
340 used for cases, where it is inevitable.
344 @func: a function to execute in the new thread
345 @data: an argument to supply to the new thread
346 @stack_size: a stack size for the new thread
347 @joinable: should this thread be joinable?
348 @bound: should this thread be bound to a system thread?
349 @priority: a priority for the thread
350 @error: return location for error.
351 @Returns: the new #GThread on success
354 <!-- ##### FUNCTION g_thread_self ##### -->
356 This functions returns the #GThread corresponding to the calling thread.
359 @Returns: the current thread
362 <!-- ##### FUNCTION g_thread_join ##### -->
364 Waits until @thread finishes, i.e. the function @func, as given
365 to g_thread_create, returns or g_thread_exit() is called by
366 @thread. All resources of @thread including the #GThread struct are
367 released. @thread must have been created with @joinable=#TRUE in
368 g_thread_create(). The value returned by @func or given to
369 g_thread_exit() by @thread is returned by this function.
372 @thread: a #GThread to be waited for
373 @Returns: the return value of the thread
376 <!-- ##### FUNCTION g_thread_set_priority ##### -->
378 Change the priority of @thread to @priority.
383 It is not guaranteed, that threads with different priorities really
384 behave accordingly. On some systems (e.g. Linux) only root can increase
385 priorities. On other systems (e.g. Solaris) there doesn't seem to be
386 different scheduling for different priorities. All in all try to avoid
387 being dependent on priorities.
392 @priority: a new priority for @thread
395 <!-- ##### FUNCTION g_thread_yield ##### -->
397 Give way to other threads waiting to be scheduled.
401 This function is often used as a method to make busy wait less
402 evil. But in most cases, you will encounter, there are better methods
403 to do that. So in general you shouldn't use that function.
408 <!-- ##### FUNCTION g_thread_exit ##### -->
410 Exit the current thread. If another thread is waiting for that thread
411 using g_thread_join() and the current thread is joinable, the waiting
412 thread will be woken up and getting @retval as the return value of
413 g_thread_join(). If the current thread is not joinable, @retval is
420 g_thread_join (retval);
426 is equivalent to calling
438 in the function @func, as given to g_thread_create().
443 Never call g_thread_exit from within a thread of a #GThreadPool, as
444 that will mess up the bookkeeping and lead to funny and unwanted
449 @retval: the return value of this thread
452 <!-- ##### STRUCT GMutex ##### -->
455 The #GMutex struct is an opaque data structure to represent a mutex
456 (mutual exclusion). It can be used to protect data against shared
457 access. Take for example the following function:
460 <title>A function which will not work in a threaded environment</title>
462 int give_me_next_number ()
464 static int current_number = 0;
466 /* now do a very complicated calculation to calculate the new number,
467 this might for example be a random number generator */
468 current_number = calc_next_number (current_number);
469 return current_number;
476 It is easy to see, that this won't work in a multi-threaded
477 application. There current_number must be protected against shared
478 access. A first naive implementation would be:
483 <title>The wrong way to write a thread-safe function</title>
485 int give_me_next_number ()
487 static int current_number = 0;
489 static GMutex * mutex = NULL;
492 mutex = g_mutex_new ();
493 g_mutex_lock (mutex);
494 ret_val = current_number = calc_next_number (current_number);
495 g_mutex_unlock (mutex);
503 This looks like it would work, but there is a race condition while
504 constructing the mutex and this code cannot work reliable. So please do
505 not use such constructs in your own programs. One working solution is:
510 <title>A correct thread-safe function</title>
512 static GMutex *give_me_next_number_mutex = NULL;
514 /* this function must be called before any call to give_me_next_number ()
515 it must be called exactly once. */
516 void init_give_me_next_number ()
518 g_assert (give_me_next_number_mutex == NULL);
519 give_me_next_number_mutex = g_mutex_new ();
522 int give_me_next_number ()
524 static int current_number = 0;
527 g_mutex_lock (give_me_next_number_mutex);
528 ret_val = current_number = calc_next_number (current_number);
529 g_mutex_unlock (give_me_next_number_mutex);
537 #GStaticMutex provides a simpler and safer way of doing this.
541 If you want to use a mutex, but your code should also work without
542 calling g_thread_init() first, you can not use a #GMutex, as
543 g_mutex_new() requires that. Use a #GStaticMutex instead.
547 A #GMutex should only be accessed via the following functions.
552 All of the g_mutex_* functions are actually macros. Apart from taking
553 the addresses of them, you can however use them as if they were functions.
558 <!-- ##### FUNCTION g_mutex_new ##### -->
561 Creates a new #GMutex.
566 This function will abort, if g_thread_init() has not been called yet.
570 @Returns: a new #GMutex
573 <!-- ##### FUNCTION g_mutex_lock ##### -->
576 Locks @mutex. If @mutex is already locked by another thread, the
577 current thread will block until @mutex is unlocked by the other
582 This function can also be used, if g_thread_init() has not yet been
583 called and will do nothing then.
588 #GMutex is not recursive, i.e. a thread will deadlock, if it already
589 has locked @mutex while calling g_mutex_lock(). Use
590 #GStaticRecMutex instead, if you need recursive mutexes.
597 <!-- ##### FUNCTION g_mutex_trylock ##### -->
600 Tries to lock @mutex. If @mutex is already locked by another
601 thread, it immediately returns FALSE. Otherwise it locks @mutex
606 This function can also be used, if g_thread_init() has not yet been
607 called and will immediately return TRUE then.
612 #GMutex is not recursive, i.e. g_mutex_trylock() will return FALSE,
613 if the current thread already has locked @mutex. Use
614 #GStaticRecMutex instead, if you need recursive mutexes.
619 @Returns: TRUE, if @mutex could be locked
622 <!-- ##### FUNCTION g_mutex_unlock ##### -->
625 Unlocks @mutex. If another thread is blocked in a g_mutex_lock() call
626 for @mutex, it will be woken and can lock @mutex itself.
630 This function can also be used, if g_thread_init() has not yet been
631 called and will do nothing then.
637 <!-- ##### FUNCTION g_mutex_free ##### -->
646 <!-- ##### STRUCT GStaticMutex ##### -->
649 A #GStaticMutex works like a #GMutex, but it has one significant
650 advantage. It doesn't need to be created at run-time like a #GMutex,
651 but can be defined at compile-time. Here is a shorter, easier and
652 safer version of our give_me_next_number() example:
657 <title>Using GStaticMutex to simplify thread-safe programming</title>
659 int give_me_next_number ()
661 static int current_number = 0;
663 static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
665 g_static_mutex_lock (&mutex);
666 ret_val = current_number = calc_next_number (current_number);
667 g_static_mutex_unlock (&mutex);
675 Sometimes you would like to dynamically create a mutex. If you don't
676 want to require prior calling to g_thread_init(), because your code
677 should also be usable in non-threaded programs, you are not able to
678 use g_mutex_new() and thus #GMutex, as that requires a prior call to
679 g_thread_init(). In theses cases you can also use a #GStaticMutex. It
680 must be initialized with g_static_mutex_init() before using it and
681 freed with with g_static_mutex_free() when not needed anymore to free
682 up any allocated recourses.
686 Even though #GStaticMutex is not opaque, it should only be used with
687 the following functions, as it is defined differently on different
692 All of the g_static_mutex_* functions can also be used, if
693 g_thread_init() has not yet been called.
698 All of the g_static_mutex_* functions are actually macros. Apart from
699 taking the addresses of them, you can however use them as if they were
705 <!-- ##### MACRO G_STATIC_MUTEX_INIT ##### -->
708 A #GStaticMutex must be initialized with this macro, before it can be
709 used. This macro can used be to initialize a variable, but it cannot
710 be assigned to a variable. In that case you have to use
711 g_static_mutex_init().
717 GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
724 <!-- ##### FUNCTION g_static_mutex_init ##### -->
726 Initializes @mutex. Alternatively you can initialize it with
727 #G_STATIC_MUTEX_INIT.
730 @mutex: a #GStaticMutex to be initialized
733 <!-- ##### FUNCTION g_static_mutex_lock ##### -->
735 Works like g_mutex_lock(), but for a #GStaticMutex.
738 @mutex: a #GStaticMutex
741 <!-- ##### FUNCTION g_static_mutex_trylock ##### -->
744 Works like g_mutex_trylock(), but for a #GStaticMutex.
747 @mutex: a #GStaticMutex
748 @Returns: TRUE, if the #GStaticMutex could be locked
751 <!-- ##### FUNCTION g_static_mutex_unlock ##### -->
754 Works like g_mutex_unlock(), but for a #GStaticMutex.
757 @mutex: a #GStaticMutex
760 <!-- ##### FUNCTION g_static_mutex_get_mutex ##### -->
763 For some operations (like g_cond_wait()) you must have a #GMutex
764 instead of a #GStaticMutex. This function will return the
765 corresponding #GMutex for @mutex.
768 @mutex: a #GStaticMutex
769 @Returns: the #GMutex corresponding to @mutex
772 <!-- ##### FUNCTION g_static_mutex_free ##### -->
774 Releases all resources allocated to @mutex.
778 You don't have to call this functions for a #GStaticMutex with an
779 unbounded lifetime, i.e. objects declared 'static', but if you have a
780 #GStaticMutex as a member of a structure and the structure is freed,
781 you should also free the #GStaticMutex.
784 @mutex: a #GStaticMutex to be freed
787 <!-- ##### MACRO G_LOCK_DEFINE ##### -->
790 The G_LOCK_* macros provide a convenient interface to #GStaticMutex
791 with the advantage that they will expand to nothing in programs
792 compiled against a thread-disabled GLib, saving code and memory
793 there. #G_LOCK_DEFINE defines a lock. It can appear, where variable
794 definitions may appear in programs, i.e. in the first block of a
795 function or outside of functions. The @name parameter will be mangled
796 to get the name of the #GStaticMutex. This means, that you can use
797 names of existing variables as the parameter, e.g. the name of the
798 variable you intent to protect with the lock. Look at our
799 give_me_next_number() example using the G_LOCK_* macros:
804 <title>Using the G_LOCK_* convenience macros</title>
806 G_LOCK_DEFINE (current_number);
808 int give_me_next_number ()
810 static int current_number = 0;
813 G_LOCK (current_number);
814 ret_val = current_number = calc_next_number (current_number);
815 G_UNLOCK (current_number);
822 @name: the name of the lock
825 <!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
828 This works like #G_LOCK_DEFINE, but it creates a static object.
831 @name: the name of the lock
834 <!-- ##### MACRO G_LOCK_EXTERN ##### -->
837 This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
840 @name: the name of the lock
843 <!-- ##### MACRO G_LOCK ##### -->
846 Works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
849 @name: the name of the lock
852 <!-- ##### MACRO G_TRYLOCK ##### -->
855 Works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
858 @name: the name of the lock
859 @Returns: TRUE, if the lock could be locked
862 <!-- ##### MACRO G_UNLOCK ##### -->
865 Works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
868 @name: the name of the lock
871 <!-- ##### STRUCT GStaticRecMutex ##### -->
873 A #GStaticRecMutex works like a #GStaticMutex, but it can be locked
874 multiple times by one thread. If you enter it n times, however, you
875 have to unlock it n times again to let other threads lock it. An
876 exception is the function g_static_rec_mutex_unlock_full(), that
877 allows you to unlock a #GStaticRecMutex completely returning the depth,
878 i.e. the number of times this mutex was locked. The depth can later be
879 used to restore the state by calling g_static_rec_mutex_lock_full().
883 Even though #GStaticRecMutex is not opaque, it should only be used with
884 the following functions.
888 All of the g_static_rec_mutex_* functions can also be used, if
889 g_thread_init() has not been called.
896 <!-- ##### MACRO G_STATIC_REC_MUTEX_INIT ##### -->
898 A #GStaticRecMutex must be initialized with this macro, before it can
899 be used. This macro can used be to initialize a variable, but it
900 cannot be assigned to a variable. In that case you have to use
901 g_static_rec_mutex_init().
907 GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
914 <!-- ##### FUNCTION g_static_rec_mutex_init ##### -->
916 A #GStaticRecMutex must be initialized with this function, before it
917 can be used. Alternatively you can initialize it with
918 #G_STATIC_REC_MUTEX_INIT.
921 @mutex: a #GStaticRecMutex to be initialized
924 <!-- ##### FUNCTION g_static_rec_mutex_lock ##### -->
926 Locks @mutex. If @mutex is already locked by another thread, the
927 current thread will block until @mutex is unlocked by the other
928 thread. If @mutex is already locked by the calling thread, this
929 functions increases the depth of @mutex and returns immediately.
932 @mutex: a #GStaticRecMutex to lock
935 <!-- ##### FUNCTION g_static_rec_mutex_trylock ##### -->
937 Tries to lock @mutex. If @mutex is already locked by another thread,
938 it immediately returns #FALSE. Otherwise it locks @mutex and returns
939 #TRUE. If @mutex is already locked by the calling thread, this
940 functions increases the depth of @mutex and immediately returns #TRUE.
943 @mutex: a #GStaticRecMutex to lock
944 @Returns: TRUE, if @mutex could be locked
947 <!-- ##### FUNCTION g_static_rec_mutex_unlock ##### -->
949 Unlocks @mutex. Another threads can, however, only lock @mutex when it
950 has been unlocked as many times, as it had been locked before. If
951 @mutex is completely unlocked and another thread is blocked in a
952 g_static_rec_mutex_lock() call for @mutex, it will be woken and can
956 @mutex: a #GStaticRecMutex to unlock
959 <!-- ##### FUNCTION g_static_rec_mutex_lock_full ##### -->
961 Works like calling g_static_rec_mutex_lock() for @mutex n times.
964 @mutex: a #GStaticRecMutex to lock
965 @depth: number of times this mutex has to be unlocked to be completely unlocked
968 <!-- ##### FUNCTION g_static_rec_mutex_unlock_full ##### -->
970 Completely unlocks @mutex. If another thread is blocked in a
971 g_static_rec_mutex_lock() call for @mutex, it will be woken and can
972 lock @mutex itself. This function returns the number of times, that
973 @mutex has been locked by the current thread. To restore the state
974 before the call to g_static_rec_mutex_unlock_full() you can call
975 g_static_rec_mutex_lock_full() with the depth returned by this
979 @mutex: a #GStaticRecMutex to completely unlock
980 @Returns: number of times @mutex has been locked by the current thread
983 <!-- ##### FUNCTION g_static_rec_mutex_free ##### -->
985 Releases all resources allocated to a #GStaticRecMutex.
989 You don't have to call this functions for a #GStaticRecMutex with an
990 unbounded lifetime, i.e. objects declared 'static', but if you have a
991 #GStaticRecMutex as a member of a structure and the structure is
992 freed, you should also free the #GStaticRecMutex.
995 @mutex: a #GStaticRecMutex to be freed
998 <!-- ##### STRUCT GStaticRWLock ##### -->
1000 The #GStaticRWLock struct represents a read-write lock. A read-write
1001 lock can be used for protecting data, that some portions of code only
1002 read from, while others also write. In such situations it is
1003 desirable, that several readers can read at once, whereas of course
1004 only one writer may write at a time. Take a look at the following
1008 <title>An array with access functions</title>
1010 GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;
1014 gpointer my_array_get (guint index)
1016 gpointer retval = NULL;
1021 g_static_rw_lock_reader_lock (&rwlock);
1023 if (index < array->len)
1024 retval = g_ptr_array_index (array, index);
1026 g_static_rw_lock_reader_unlock (&rwlock);
1031 void my_array_set (guint index, gpointer data)
1033 g_static_rw_lock_writer_lock (&rwlock);
1036 array = g_ptr_array_new ();
1038 if (index >= array->len)
1039 g_ptr_array_set_size (array, index+1);
1041 g_ptr_array_index (array, index) = data;
1043 g_static_rw_lock_writer_unlock (&rwlock);
1050 This example shows an array, which can be accessed by many readers
1051 (the my_array_get function) simultaneously, whereas the writers (the
1052 my_array_set function) only will be allowed once a time and only if no
1053 readers currently access the array. This is because of the potentially
1054 dangerous resizing of the array. Using that functions is fully
1055 multi-thread safe now.
1059 Most of the time the writers should have precedence of readers. That
1060 means for this implementation, that as soon as a writer wants to lock
1061 the data, no other reader is allowed to lock the data, whereas of
1062 course the readers, that already have locked the data are allowed to
1063 finish their operation. As soon as the last reader unlocks the data,
1064 the writer will lock it.
1068 Even though #GStaticRWLock is not opaque, it should only be used with
1069 the following functions.
1073 All of the g_static_rw_lock_* functions can also be used, if
1074 g_thread_init() has not been called.
1079 A read-write lock has a higher overhead as a mutex. For example both
1080 g_static_rw_lock_reader_lock() and g_static_rw_lock_reader_unlock()
1081 has to lock and unlock a #GStaticMutex, so it takes at least twice the
1082 time to lock and unlock a #GStaticRWLock than to lock and unlock a
1083 #GStaticMutex. So only data structures, that are accessed by multiple
1084 readers, which keep the lock for a considerable time justify a
1085 #GStaticRWLock. The above example most probably would fare better with
1097 <!-- ##### MACRO G_STATIC_RW_LOCK_INIT ##### -->
1099 A #GStaticRWLock must be initialized with this macro, before it can
1100 be used. This macro can used be to initialize a variable, but it
1101 cannot be assigned to a variable. In that case you have to use
1102 g_static_rw_lock_init().
1108 GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;
1115 <!-- ##### FUNCTION g_static_rw_lock_init ##### -->
1117 A #GStaticRWLock must be initialized with this function, before it can
1118 be used. Alternatively you can initialize it with
1119 #G_STATIC_RW_LOCK_INIT.
1122 @lock: a #GStaticRWLock to be initialized
1125 <!-- ##### FUNCTION g_static_rw_lock_reader_lock ##### -->
1127 Locks @lock for reading. There may be unlimited concurrent locks for
1128 reading of a #GStaticRWLock at the same time. If @lock is already
1129 locked for writing by another thread or if another thread is already
1130 waiting to lock @lock for writing, this function will block until
1131 @lock is unlocked by the other writing thread and no other writing
1132 threads want to lock @lock. This lock has to be unlocked by
1133 g_static_rw_lock_reader_unlock().
1137 #GStaticRWLock in general is not recursive, but as there may be
1138 unlimited concurrent locks for reading, it effectively is for
1139 recursive for reading, but for reading only. Locking for writing after
1140 locking for reading will deadlock, the same holds true for the
1144 @lock: a #GStaticRWLock to lock for reading
1147 <!-- ##### FUNCTION g_static_rw_lock_reader_trylock ##### -->
1149 Tries to lock @lock for reading. If @lock is already locked for
1150 writing by another thread or if another thread is already waiting to
1151 lock @lock for writing, it immediately returns #FALSE. Otherwise it
1152 locks @lock for reading and returns TRUE. This lock has to be unlocked
1153 by g_static_rw_lock_reader_unlock().
1156 @lock: a #GStaticRWLock to lock for reading
1157 @Returns: TRUE, if @lock could be locked for reading
1160 <!-- ##### FUNCTION g_static_rw_lock_reader_unlock ##### -->
1162 Unlocks @lock. If a thread waits to lock @lock for writing and all
1163 locks for reading have been unlocked, the waiting thread is woken up
1164 and can lock @lock for writing.
1167 @lock: a #GStaticRWLock to unlock after reading
1170 <!-- ##### FUNCTION g_static_rw_lock_writer_lock ##### -->
1172 Locks @lock for writing. If @lock is already locked for writing or
1173 reading by other threads, this function will block until @lock is
1174 completely unlocked and then lock @lock for writing. While this
1175 functions waits to lock @lock, no other thread can lock @lock for
1176 reading. When @lock is locked for writing, no other thread can lock
1177 @lock (neither for reading nor writing). This lock has to be unlocked
1178 by g_static_rw_lock_writer_unlock().
1181 @lock: a #GStaticRWLock to lock for writing
1184 <!-- ##### FUNCTION g_static_rw_lock_writer_trylock ##### -->
1186 Tries to lock @lock for writing. If @lock is already locked (for
1187 either reading or writing) by another thread, it immediately returns
1188 #FALSE. Otherwise it locks @lock for writing and returns TRUE. This
1189 lock has to be unlocked by g_static_rw_lock_writer_unlock().
1192 @lock: a #GStaticRWLock to lock for writing
1193 @Returns: TRUE, if @lock could be locked for writing
1196 <!-- ##### FUNCTION g_static_rw_lock_writer_unlock ##### -->
1198 Unlocks @lock. If a thread waits to lock @lock for writing and all
1199 locks for reading have been unlocked, the waiting thread is woken up
1200 and can lock @lock for writing. If no thread waits to lock @lock for
1201 writing and threads wait to lock @lock for reading, the waiting
1202 threads are woken up and can lock @lock for reading.
1205 @lock: a #GStaticRWLock to unlock after writing
1208 <!-- ##### FUNCTION g_static_rw_lock_free ##### -->
1210 Releases all resources allocated to @lock.
1214 You don't have to call this functions for a #GStaticRWLock with an
1215 unbounded lifetime, i.e. objects declared 'static', but if you have a
1216 #GStaticRWLock as a member of a structure and the structure is freed,
1217 you should also free the #GStaticRWLock.
1220 @lock: a #GStaticRWLock to be freed
1223 <!-- ##### STRUCT GCond ##### -->
1226 The #GCond struct is an opaque data structure to represent a
1227 condition. A #GCond is an object, that threads can block on, if they
1228 find a certain condition to be false. If other threads change the
1229 state of this condition they can signal the #GCond, such that the
1230 waiting thread is woken up.
1235 <title>Using GCond to block a thread until a condition is satisfied</title>
1237 GCond* data_cond = NULL; /* Must be initialized somewhere */
1238 GMutex* data_mutex = NULL; /* Must be initialized somewhere */
1239 gpointer current_data = NULL;
1241 void push_data (gpointer data)
1243 g_mutex_lock (data_mutex);
1244 current_data = data;
1245 g_cond_signal (data_cond);
1246 g_mutex_unlock (data_mutex);
1249 gpointer pop_data ()
1253 g_mutex_lock (data_mutex);
1254 while (!current_data)
1255 g_cond_wait (data_cond, data_mutex);
1256 data = current_data;
1257 current_data = NULL;
1258 g_mutex_unlock (data_mutex);
1266 Whenever a thread calls pop_data() now, it will wait until
1267 current_data is non-NULL, i.e. until some other thread has called
1273 It is important to use the g_cond_wait() and g_cond_timed_wait()
1274 functions only inside a loop, which checks for the condition to be
1275 true as it is not guaranteed that the waiting thread will find it
1276 fulfilled, even if the signaling thread left the condition
1277 in that state. This is because another thread can have altered the
1278 condition, before the waiting thread got the chance to be woken up,
1279 even if the condition itself is protected by a #GMutex, like above.
1284 A #GCond should only be accessed via the following functions.
1289 All of the g_cond_* functions are actually macros. Apart from taking
1290 the addresses of them, you can however use them as if they were functions.
1295 <!-- ##### FUNCTION g_cond_new ##### -->
1298 Creates a new #GCond. This function will abort, if g_thread_init()
1299 has not been called yet.
1302 @Returns: a new #GCond
1305 <!-- ##### FUNCTION g_cond_signal ##### -->
1307 If threads are waiting for @cond, exactly one of them is woken up. It
1308 is good practice to hold the same lock as the waiting thread, while
1309 calling this function, though not required.
1313 This function can also be used, if g_thread_init() has
1314 not yet been called and will do nothing then.
1320 <!-- ##### FUNCTION g_cond_broadcast ##### -->
1323 If threads are waiting for @cond, all of them are woken up. It is good
1324 practice to lock the same mutex as the waiting threads, while calling
1325 this function, though not required.
1329 This function can also be used, if g_thread_init() has
1330 not yet been called and will do nothing then.
1336 <!-- ##### FUNCTION g_cond_wait ##### -->
1339 Waits until this thread is woken up on @cond. The @mutex is unlocked
1340 before falling asleep and locked again before resuming.
1344 This function can also be used, if g_thread_init() has not yet been
1345 called and will immediately return then.
1349 @mutex: a #GMutex, that is currently locked
1352 <!-- ##### FUNCTION g_cond_timed_wait ##### -->
1355 Waits until this thread is woken up on @cond, but not longer than
1356 until the time, that is specified by @abs_time. The @mutex is
1357 unlocked before falling asleep and locked again before resuming.
1361 If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
1365 This function can also be used, if g_thread_init() has not yet been
1366 called and will immediately return TRUE then.
1370 To easily calculate @abs_time a combination of g_get_current_time()
1371 and g_time_val_add() can be used.
1375 @mutex: a #GMutex, that is currently locked
1376 @abs_time: a #GTimeVal, determining the final time
1377 @Returns: TRUE, if the thread is woken up in time
1380 <!-- ##### FUNCTION g_cond_free ##### -->
1383 Destroys the #GCond.
1389 <!-- ##### STRUCT GPrivate ##### -->
1391 The #GPrivate struct is an opaque data structure to represent a thread
1392 private data key. Threads can thereby obtain and set a pointer, which
1393 is private to the current thread. Take our give_me_next_number()
1394 example from above. Now we don't want current_number to be shared
1395 between the threads, but to be private to each thread. This can be
1399 <title>Using GPrivate for per-thread data</title>
1401 GPrivate* current_number_key = NULL; /* Must be initialized somewhere */
1402 /* with g_private_new (g_free); */
1404 int give_me_next_number ()
1406 int *current_number = g_private_get (current_number_key);
1408 if (!current_number)
1410 current_number = g_new (int,1);
1411 *current_number = 0;
1412 g_private_set (current_number_key, current_number);
1414 *current_number = calc_next_number (*current_number);
1415 return *current_number;
1422 Here the pointer belonging to the key current_number_key is read. If
1423 it is NULL, it has not been set yet. Then get memory for an integer
1424 value, assign this memory to the pointer and write the pointer
1425 back. Now we have an integer value, that is private to the current
1430 The #GPrivate struct should only be accessed via the following functions.
1435 All of the g_private_* functions are actually macros. Apart from taking
1436 the addresses of them, you can however use them as if they were functions.
1441 <!-- ##### FUNCTION g_private_new ##### -->
1444 Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer
1445 to a destructor function. Whenever a thread ends and the corresponding
1446 pointer keyed to this instance of #GPrivate is non-NULL, the
1447 destructor is called with this pointer as the argument.
1452 @destructor is working quite differently from @notify in
1453 g_static_private_set().
1459 A #GPrivate can not be freed. Reuse it instead, if you can to avoid
1460 shortage or use #GStaticPrivate.
1466 This function will abort, if g_thread_init() has not been called yet.
1470 @destructor: a function to handle the data keyed to #GPrivate, when a
1472 @Returns: a new #GPrivate
1475 <!-- ##### FUNCTION g_private_get ##### -->
1478 Returns the pointer keyed to @private_key for the current thread. This
1479 pointer is NULL, when g_private_set() hasn't been called for the
1480 current @private_key and thread yet.
1484 This function can also be used, if g_thread_init() has not yet been
1485 called and will return the value of @private_key casted to #gpointer then.
1488 @private_key: a #GPrivate
1489 @Returns: the corresponding pointer
1492 <!-- ##### FUNCTION g_private_set ##### -->
1495 Sets the pointer keyed to @private_key for the current thread.
1499 This function can also be used, if g_thread_init() has not yet been
1500 called and will set @private_key to @data casted to #GPrivate* then.
1503 @private_key: a #GPrivate
1504 @data: the new pointer
1507 <!-- ##### STRUCT GStaticPrivate ##### -->
1510 A #GStaticPrivate works almost like a #GPrivate, but it has one
1511 significant advantage. It doesn't need to be created at run-time like
1512 a #GPrivate, but can be defined at compile-time. This is similar to
1513 the difference between #GMutex and #GStaticMutex. Now look at our
1514 give_me_next_number() example with #GStaticPrivate:
1519 <title>Using GStaticPrivate for per-thread data</title>
1521 int give_me_next_number ()
1523 static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
1524 int *current_number = g_static_private_get (&current_number_key);
1526 if (!current_number)
1528 current_number = g_new (int,1);
1529 *current_number = 0;
1530 g_static_private_set (&current_number_key, current_number, g_free);
1532 *current_number = calc_next_number (*current_number);
1533 return *current_number;
1541 <!-- ##### MACRO G_STATIC_PRIVATE_INIT ##### -->
1543 Every #GStaticPrivate must be initialized with this macro, before it can
1550 GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
1557 <!-- ##### FUNCTION g_static_private_init ##### -->
1559 Initializes @private_key. Alternatively you can initialize it with
1560 #G_STATIC_PRIVATE_INIT.
1563 @private_key: a #GStaticPrivate to be initialized
1566 <!-- ##### FUNCTION g_static_private_get ##### -->
1568 Works like g_private_get() only for a #GStaticPrivate.
1572 This function also works, if g_thread_init() has not yet been called.
1575 @private_key: a #GStaticPrivate
1576 @Returns: the corresponding pointer
1579 <!-- ##### FUNCTION g_static_private_set ##### -->
1581 Sets the pointer keyed to @private_key for the current thread and the
1582 function @notify to be called with that pointer (NULL or non-NULL),
1583 whenever the pointer is set again or whenever the current thread ends.
1587 This function also works, if g_thread_init() has not yet been
1588 called. If g_thread_init() is called later, the @data keyed to
1589 @private_key will be inherited only by the main thread, i.e. the one that
1590 called g_thread_init().
1595 @notify is working quite differently from @destructor in
1600 @private_key: a #GStaticPrivate
1601 @data: the new pointer
1602 @notify: a function to be called with the pointer, whenever the
1603 current thread ends or sets this pointer again
1606 <!-- ##### FUNCTION g_static_private_free ##### -->
1608 Releases all resources allocated to @private_key.
1612 You don't have to call this functions for a #GStaticPrivate with an
1613 unbounded lifetime, i.e. objects declared 'static', but if you have a
1614 #GStaticPrivate as a member of a structure and the structure is freed,
1615 you should also free the #GStaticPrivate.
1618 @private_key: a #GStaticPrivate to be freed