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 multithreaded 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 multithread
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 multithread 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 callback 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 @thread_func functions passed to
226 @value: data supplied to the thread
229 <!-- ##### ENUM GThreadPriority ##### -->
231 Specifies the priority of a thread.
236 It is not guaranteed, that threads with different priorities really
237 behave accordingly. On some systems (e.g. Linux) only root can increase
238 priorities. On other systems (e.g. Solaris) there doesn't seem to be
239 different scheduling for different priorities. All in all try to avoid
240 being dependent on priorities.
244 @G_THREAD_PRIORITY_LOW: a priority lower than normal
245 @G_THREAD_PRIORITY_NORMAL: the default priority
246 @G_THREAD_PRIORITY_HIGH: a priority higher than normal
247 @G_THREAD_PRIORITY_URGENT: the highest priority
249 <!-- ##### STRUCT GThread ##### -->
251 The #Gthread struct represents a running thread. It has three public
252 members, but the underlying struct is bigger, so you must not copy
253 this struct. You also must not write that information.
258 Resources for a joinable thread are not fully released until
259 g_thread_join() is called for that thread.
263 @joinable: is this thread joinable?
264 @bound: is this thread bound to a system thread?
265 @priority: the priority of the thread
267 <!-- ##### FUNCTION g_thread_create ##### -->
269 This function creates a new thread with the priority @priority. The
270 stack gets the size @stack_size or the default value for the current
271 platform, if @stack_size is 0.
275 If @joinable is #TRUE, you can wait for this threads termination
276 calling g_thread_wait(). Otherwise the thread will just disappear, when
277 ready. If @bound is #TRUE, this thread will be scheduled in the system
278 scope, otherwise the implementation is free to do scheduling in the
279 process scope. The first variant is more expensive resource-wise, but
280 generally faster. On some systems (e.g. Linux) all threads are bound.
284 The new thread executes the function @thread_func with the argument
285 @arg. If the thread was created successfully, it is returned.
289 @error can be NULL to ignore errors, or non-NULL to report errors. The
290 error is set, if and only if the function returns #NULL.
295 It is not guaranteed, that threads with different priorities really
296 behave accordingly. On some systems (e.g. Linux) only root can increase
297 priorities. On other systems (e.g. Solaris) there doesn't seem to be
298 different scheduling for different priorities. All in all try to avoid
299 being dependent on priorities. Use %G_THREAD_PRIORITY_NORMAL here as a
304 @thread_func: a function to execute in the new thread
305 @arg: an argument to supply to the new thread
306 @stack_size: a stack size for the new thread
307 @joinable: should this thread be joinable?
308 @bound: should this thread be bound to a system thread?
309 @priority: a priority for the thread
310 @error: return location for error.
311 @Returns: the new #GThread on success
314 <!-- ##### FUNCTION g_thread_self ##### -->
316 This functions returns the #GThread corresponding to the calling thread.
319 @Returns: the current thread
322 <!-- ##### FUNCTION g_thread_join ##### -->
324 Waits until @thread finishes, i.e. the function @thread_func, as given
325 to g_thread_create, returns or g_thread_exit() is called by
326 @thread. All resources of @thread including the #GThread struct are
327 released. @thread must have been created with @joinable=#TRUE in
331 @thread: a #GThread to be waited for
334 <!-- ##### FUNCTION g_thread_set_priority ##### -->
336 Change the priority of @thread to @priority.
341 It is not guaranteed, that threads with different priorities really
342 behave accordingly. On some systems (e.g. Linux) only root can increase
343 priorities. On other systems (e.g. Solaris) there doesn't seem to be
344 different scheduling for different priorities. All in all try to avoid
345 being dependent on priorities.
350 @priority: a new priority for @thread
353 <!-- ##### FUNCTION g_thread_yield ##### -->
355 Give way to other threads waiting to be scheduled.
359 This function is often used as a method to make busy wait less
360 evil. But in most cases, you will encounter, there are better methods
361 to do that. So in general you shouldn't use that function.
366 <!-- ##### FUNCTION g_thread_exit ##### -->
368 Exit the current thread. If another thread is waiting for that thread
369 using g_thread_join(), that thread will be woken up.
374 Never call g_thread_exit from within a thread of a #GThreadPool, as
375 that will mess up the bookkeeping and lead to funny and unwanted
382 <!-- ##### STRUCT GMutex ##### -->
385 The #GMutex struct is an opaque data structure to represent a mutex
386 (mutual exclusion). It can be used to protect data against shared
387 access. Take for example the following function:
390 <title>A function which will not work in a threaded environment</title>
392 int give_me_next_number ()
394 static int current_number = 0;
396 /* now do a very complicated calculation to calculate the new number,
397 this might for example be a random number generator */
398 current_number = calc_next_number (current_number);
399 return current_number;
406 It is easy to see, that this won't work in a multithreaded
407 application. There current_number must be protected against shared
408 access. A first naive implementation would be:
413 <title>The wrong way to write a thread-safe function</title>
415 int give_me_next_number ()
417 static int current_number = 0;
419 static GMutex * mutex = NULL;
422 mutex = g_mutex_new ();
423 g_mutex_lock (mutex);
424 ret_val = current_number = calc_next_number (current_number);
425 g_mutex_unlock (mutex);
433 This looks like it would work, but there is a race condition while
434 constructing the mutex and this code cannot work reliable. So please do
435 not use such constructs in your own programs. One working solution is:
440 <title>A correct thread-safe function</title>
442 static GMutex *give_me_next_number_mutex = NULL;
444 /* this function must be called before any call to give_me_next_number ()
445 it must be called exactly once. */
446 void init_give_me_next_number ()
448 g_assert (give_me_next_number_mutex == NULL);
449 give_me_next_number_mutex = g_mutex_new ();
452 int give_me_next_number ()
454 static int current_number = 0;
457 g_mutex_lock (give_me_next_number_mutex);
458 ret_val = current_number = calc_next_number (current_number);
459 g_mutex_unlock (give_me_next_number_mutex);
467 #GStaticMutex provides a simpler and safer way of doing this.
471 If you want to use a mutex, but your code should also work without
472 calling g_thread_init() first, you can not use a #GMutex, as
473 g_mutex_new() requires that. Use a #GStaticMutex instead.
477 A #GMutex should only be accessed via the following functions.
482 All of the g_mutex_* functions are actually macros. Apart from taking
483 the addresses of them, you can however use them as if they were functions.
488 <!-- ##### FUNCTION g_mutex_new ##### -->
491 Creates a new #GMutex.
496 This function will abort, if g_thread_init() has not been called yet.
500 @Returns: a new #GMutex
503 <!-- ##### FUNCTION g_mutex_lock ##### -->
506 Locks @mutex. If @mutex is already locked by another thread, the
507 current thread will block until @mutex is unlocked by the other
512 This function can also be used, if g_thread_init() has not yet been
513 called and will do nothing then.
518 #GMutex is not recursive, i.e. a thread will deadlock, if it already
519 has locked the #GMutex while calling g_mutex_lock(). Use
520 #GStaticRecMutex instead, if you need recursive mutexes.
527 <!-- ##### FUNCTION g_mutex_trylock ##### -->
530 Tries to lock @mutex. If @mutex is already locked by another
531 thread, it immediately returns FALSE. Otherwise it locks @mutex
536 This function can also be used, if g_thread_init() has not yet been
537 called and will immediately return TRUE then.
541 @Returns: TRUE, if @mutex could be locked
544 <!-- ##### FUNCTION g_mutex_unlock ##### -->
547 Unlocks @mutex. If another thread is blocked in a g_mutex_lock() call
548 for @mutex, it will be woken and can lock @mutex itself.
552 This function can also be used, if g_thread_init() has not yet been
553 called and will do nothing then.
559 <!-- ##### FUNCTION g_mutex_free ##### -->
568 <!-- ##### STRUCT GStaticMutex ##### -->
571 A #GStaticMutex works like a #GMutex, but it has one significant
572 advantage. It doesn't need to be created at run-time like a #GMutex,
573 but can be defined at compile-time. Here is a shorter, easier and
574 safer version of our give_me_next_number() example:
579 <title>Using GStaticMutex to simplify thread-safe programming</title>
581 int give_me_next_number ()
583 static int current_number = 0;
585 static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
587 g_static_mutex_lock (&mutex);
588 ret_val = current_number = calc_next_number (current_number);
589 g_static_mutex_unlock (&mutex);
597 Sometimes you would like to dynamically create a mutex. If you don't
598 want to require prior calling to g_thread_init(), because your code
599 should also be usable in non-threaded programs, you are not able to
600 use g_mutex_new() and thus #GMutex, as that requires a prior call to
601 g_thread_init(). In theses cases you can also use a #GStaticMutex. It
602 must be initialized with g_static_mutex_init() before using it and
603 freed with with g_static_mutex_free() when not needed anymore to free
604 up any allocated recourses.
608 Even though #GStaticMutex is not opaque, it should only be used with
609 the following functions, as it is defined differently on different
614 All of the g_static_mutex_* functions can also be used, if
615 g_thread_init() has not yet been called.
620 All of the g_static_mutex_* functions are actually macros. Apart from
621 taking the addresses of them, you can however use them as if they were
627 <!-- ##### MACRO G_STATIC_MUTEX_INIT ##### -->
630 A #GStaticMutex must be initialized with this macro, before it can be
631 used. This macro can used be to initialize a variable, but it cannot
632 be assigned to a variable. In that case you have to use
633 g_static_mutex_init().
639 GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
646 <!-- ##### FUNCTION g_static_mutex_init ##### -->
648 Initializes @mutex. Alternatively you can initialize it with
649 #G_STATIC_MUTEX_INIT.
652 @mutex: a #GStaticMutex to be initialized
655 <!-- ##### FUNCTION g_static_mutex_lock ##### -->
657 works like g_mutex_lock(), but for a #GStaticMutex.
660 @mutex: a #GStaticMutex
663 <!-- ##### FUNCTION g_static_mutex_trylock ##### -->
666 works like g_mutex_trylock(), but for a #GStaticMutex.
669 @mutex: a #GStaticMutex
670 @Returns: TRUE, if the #GStaticMutex could be locked
673 <!-- ##### FUNCTION g_static_mutex_unlock ##### -->
676 works like g_mutex_unlock(), but for a #GStaticMutex.
679 @mutex: a #GStaticMutex
682 <!-- ##### FUNCTION g_static_mutex_get_mutex ##### -->
685 For some operations (like g_cond_wait()) you must have a #GMutex
686 instead of a #GStaticMutex. This function will return the
687 corresponding #GMutex for @mutex.
690 @mutex: a #GStaticMutex
691 @Returns: the #GMutex corresponding to @mutex
694 <!-- ##### FUNCTION g_static_mutex_free ##### -->
696 Releases all resources allocated to @mutex.
700 You don't have to call this functions for a #GStaticMutex with an
701 unbounded lifetime, i.e. objects declared 'static', but if you have a
702 #GStaticMutex as a member of a structure and the structure is freed,
703 you should also free the #GStaticMutex.
706 @mutex: a #GStaticMutex to be freed
709 <!-- ##### MACRO G_LOCK_DEFINE ##### -->
712 The G_LOCK_* macros provide a convenient interface to #GStaticMutex
713 with the advantage that they will expand to nothing in programs
714 compiled against a thread-disabled GLib, saving code and memory
715 there. #G_LOCK_DEFINE defines a lock. It can appear, where variable
716 definitions may appear in programs, i.e. in the first block of a
717 function or outside of functions. The @name parameter will be mangled
718 to get the name of the #GStaticMutex. This means, that you can use
719 names of existing variables as the parameter, e.g. the name of the
720 variable you intent to protect with the lock. Look at our
721 give_me_next_number() example using the G_LOCK_* macros:
726 <title>Using the G_LOCK_* convenience macros</title>
728 G_LOCK_DEFINE (current_number);
730 int give_me_next_number ()
732 static int current_number = 0;
735 G_LOCK (current_number);
736 ret_val = current_number = calc_next_number (current_number);
737 G_UNLOCK (current_number);
744 @name: the name of the lock
747 <!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
750 This works like #G_LOCK_DEFINE, but it creates a static object.
753 @name: the name of the lock
756 <!-- ##### MACRO G_LOCK_EXTERN ##### -->
759 This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
762 @name: the name of the lock
765 <!-- ##### MACRO G_LOCK ##### -->
768 works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
771 @name: the name of the lock
774 <!-- ##### MACRO G_TRYLOCK ##### -->
777 works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
780 @name: the name of the lock
781 @Returns: TRUE, if the lock could be locked
784 <!-- ##### MACRO G_UNLOCK ##### -->
787 works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
790 @name: the name of the lock
793 <!-- ##### STRUCT GStaticRecMutex ##### -->
795 A #GStaticRecMutex works like a #GStaticMutex, but it can be locked
796 multiple times by one thread. If you enter it n times, however, you
797 have to unlock it n times again to let other threads lock it. An
798 exception is the function g_static_rec_mutex_unlock_full(), that
799 allows you to unlock a #GStaticRecMutex completely returning the depth,
800 i.e. the number of times this mutex was locked. The depth can later be
801 used to restore the state by calling g_static_rec_mutex_lock_full().
805 Even though #GStaticRecMutex is not opaque, it should only be used with
806 the following functions.
810 All of the g_static_rec_mutex_* functions can also be used, if
811 g_thread_init() has not been called.
818 <!-- ##### MACRO G_STATIC_REC_MUTEX_INIT ##### -->
820 A #GStaticRecMutex must be initialized with this macro, before it can
821 be used. This macro can used be to initialize a variable, but it
822 cannot be assigned to a variable. In that case you have to use
823 g_static_rec_mutex_init().
829 GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
836 <!-- ##### FUNCTION g_static_rec_mutex_init ##### -->
838 A #GStaticRecMutex must be initialized with this function, before it
839 can be used. Alternatively you can initialize it with
840 #G_STATIC_REC_MUTEX_INIT.
843 @mutex: a #GStaticRecMutex to be initialized
846 <!-- ##### FUNCTION g_static_rec_mutex_lock ##### -->
848 Locks @mutex. If @mutex is already locked by another thread, the
849 current thread will block until @mutex is unlocked by the other
850 thread. If @mutex is already locked by the calling thread, this
851 functions increases the depth of @mutex and returns immediately.
854 @mutex: a #GStaticRecMutex to lock
857 <!-- ##### FUNCTION g_static_rec_mutex_trylock ##### -->
859 Tries to lock @mutex. If @mutex is already locked by another thread,
860 it immediately returns #FALSE. Otherwise it locks @mutex and returns
861 #TRUE. If @mutex is already locked by the calling thread, this
862 functions increases the depth of @mutex and immediately returns #TRUE.
865 @mutex: a #GStaticRecMutex to lock
866 @Returns: TRUE, if @mutex could be locked
869 <!-- ##### FUNCTION g_static_rec_mutex_unlock ##### -->
871 Unlocks @mutex. Another threads can, however, only lock @mutex when it
872 has been unlocked as many times, as it had been locked before. If
873 @mutex is completely unlocked and another thread is blocked in a
874 g_static_rec_mutex_lock() call for @mutex, it will be woken and can
878 @mutex: a #GStaticRecMutex to unlock
881 <!-- ##### FUNCTION g_static_rec_mutex_lock_full ##### -->
883 Works like calling g_static_rec_mutex_lock() for @mutex n times.
886 @mutex: a #GStaticRecMutex to lock
887 @depth: number of times this mutex has to be unlocked to be completely unlocked
890 <!-- ##### FUNCTION g_static_rec_mutex_unlock_full ##### -->
892 Completely unlocks @mutex. If another thread is blocked in a
893 g_static_rec_mutex_lock() call for @mutex, it will be woken and can
894 lock @mutex itself. This function returns the number of times, that
895 @mutex has been locked by the current thread. To restore the state
896 before the call to g_static_rec_mutex_unlock_full() you can call
897 g_static_rec_mutex_lock_full() with the depth returned by this
901 @mutex: a #GStaticRecMutex to completely unlock
902 @Returns: number of times @mutex has been locked by the current thread
905 <!-- ##### FUNCTION g_static_rec_mutex_free ##### -->
907 Releases all resources allocated to a #GStaticRecMutex.
911 You don't have to call this functions for a #GStaticRecMutex with an
912 unbounded lifetime, i.e. objects declared 'static', but if you have a
913 #GStaticRecMutex as a member of a structure and the structure is
914 freed, you should also free the #GStaticRecMutex.
917 @mutex: a #GStaticRecMutex to be freed
920 <!-- ##### STRUCT GStaticRWLock ##### -->
932 <!-- ##### MACRO G_STATIC_RW_LOCK_INIT ##### -->
939 <!-- ##### FUNCTION g_static_rw_lock_init ##### -->
947 <!-- ##### FUNCTION g_static_rw_lock_reader_lock ##### -->
955 <!-- ##### FUNCTION g_static_rw_lock_reader_trylock ##### -->
964 <!-- ##### FUNCTION g_static_rw_lock_reader_unlock ##### -->
972 <!-- ##### FUNCTION g_static_rw_lock_writer_lock ##### -->
980 <!-- ##### FUNCTION g_static_rw_lock_writer_trylock ##### -->
989 <!-- ##### FUNCTION g_static_rw_lock_writer_unlock ##### -->
997 <!-- ##### FUNCTION g_static_rw_lock_free ##### -->
1005 <!-- ##### STRUCT GCond ##### -->
1008 The #GCond struct is an opaque data structure to represent a
1009 condition. A #GCond is an object, that threads can block on, if they
1010 find a certain condition to be false. If other threads change the
1011 state of this condition they can signal the #GCond, such that the
1012 waiting thread is woken up.
1017 <title>Using GCond to block a thread until a condition is satisfied</title>
1019 GCond* data_cond = NULL; /* Must be initialized somewhere */
1020 GMutex* data_mutex = NULL; /* Must be initialized somewhere */
1021 gpointer current_data = NULL;
1023 void push_data (gpointer data)
1025 g_mutex_lock (data_mutex);
1026 current_data = data;
1027 g_cond_signal (data_cond);
1028 g_mutex_unlock (data_mutex);
1031 gpointer pop_data ()
1035 g_mutex_lock (data_mutex);
1036 while (!current_data)
1037 g_cond_wait (data_cond, data_mutex);
1038 data = current_data;
1039 current_data = NULL;
1040 g_mutex_unlock (data_mutex);
1048 Whenever a thread calls pop_data() now, it will wait until
1049 current_data is non-NULL, i.e. until some other thread has called
1055 It is important to use the g_cond_wait() and g_cond_timed_wait()
1056 functions only inside a loop, which checks for the condition to be
1057 true as it is not guaranteed that the waiting thread will find it
1058 fulfilled, even if the signaling thread left the condition
1059 in that state. This is because another thread can have altered the
1060 condition, before the waiting thread got the chance to be woken up,
1061 even if the condition itself is protected by a #GMutex, like above.
1066 A #GCond should only be accessed via the following functions.
1071 All of the g_cond_* functions are actually macros. Apart from taking
1072 the addresses of them, you can however use them as if they were functions.
1077 <!-- ##### FUNCTION g_cond_new ##### -->
1080 Creates a new #GCond. This function will abort, if g_thread_init()
1081 has not been called yet.
1084 @Returns: a new #GCond
1087 <!-- ##### FUNCTION g_cond_signal ##### -->
1089 If threads are waiting for @cond, exactly one of them is woken up. It
1090 is good practice to hold the same lock as the waiting thread, while
1091 calling this function, though not required.
1095 This function can also be used, if g_thread_init() has
1096 not yet been called and will do nothing then.
1102 <!-- ##### FUNCTION g_cond_broadcast ##### -->
1105 If threads are waiting for @cond, all of them are woken up. It is good
1106 practice to lock the same mutex as the waiting threads, while calling
1107 this function, though not required.
1111 This function can also be used, if g_thread_init() has
1112 not yet been called and will do nothing then.
1118 <!-- ##### FUNCTION g_cond_wait ##### -->
1121 Waits until this thread is woken up on @cond. The @mutex is unlocked
1122 before falling asleep and locked again before resuming.
1126 This function can also be used, if g_thread_init() has not yet been
1127 called and will immediately return then.
1131 @mutex: a #GMutex, that is currently locked
1134 <!-- ##### FUNCTION g_cond_timed_wait ##### -->
1137 Waits until this thread is woken up on @cond, but not longer than
1138 until the time, that is specified by @abs_time. The @mutex is
1139 unlocked before falling asleep and locked again before resuming.
1143 If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
1147 This function can also be used, if g_thread_init() has not yet been
1148 called and will immediately return TRUE then.
1152 @mutex: a #GMutex, that is currently locked
1153 @abs_time: a #GTimeVal, determining the final time
1154 @Returns: TRUE, if the thread is woken up in time
1157 <!-- ##### FUNCTION g_cond_free ##### -->
1160 Destroys the #GCond.
1166 <!-- ##### STRUCT GPrivate ##### -->
1168 The #GPrivate struct is an opaque data structure to represent a thread
1169 private data key. Threads can thereby obtain and set a pointer, which
1170 is private to the current thread. Take our give_me_next_number()
1171 example from above. Now we don't want current_number to be shared
1172 between the threads, but to be private to each thread. This can be
1176 <title>Using GPrivate for per-thread data</title>
1178 GPrivate* current_number_key = NULL; /* Must be initialized somewhere */
1179 /* with g_private_new (g_free); */
1181 int give_me_next_number ()
1183 int *current_number = g_private_get (current_number_key);
1185 if (!current_number)
1187 current_number = g_new (int,1);
1188 *current_number = 0;
1189 g_private_set (current_number_key, current_number);
1191 *current_number = calc_next_number (*current_number);
1192 return *current_number;
1199 Here the pointer belonging to the key current_number_key is read. If
1200 it is NULL, it has not been set yet. Then get memory for an integer
1201 value, assign this memory to the pointer and write the pointer
1202 back. Now we have an integer value, that is private to the current
1207 The #GPrivate struct should only be accessed via the following functions.
1212 All of the g_private_* functions are actually macros. Apart from taking
1213 the addresses of them, you can however use them as if they were functions.
1218 <!-- ##### FUNCTION g_private_new ##### -->
1221 Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer
1222 to a destructor function. Whenever a thread ends and the corresponding
1223 pointer keyed to this instance of #GPrivate is non-NULL, the
1224 destructor is called with this pointer as the argument.
1229 @destructor is working quite differently from @notify in
1230 g_static_private_set().
1236 A #GPrivate can not be freed. Reuse it instead, if you can to avoid
1237 shortage or use #GStaticPrivate.
1243 This function will abort, if g_thread_init() has not been called yet.
1247 @destructor: a function to handle the data keyed to #GPrivate, when a
1249 @Returns: a new #GPrivate
1252 <!-- ##### FUNCTION g_private_get ##### -->
1255 Returns the pointer keyed to @private_key for the current thread. This
1256 pointer is NULL, when g_private_set() hasn't been called for the
1257 current @private_key and thread yet.
1261 This function can also be used, if g_thread_init() has not yet been
1262 called and will return the value of @private_key casted to #gpointer then.
1265 @private_key: a #GPrivate
1266 @Returns: the corresponding pointer
1269 <!-- ##### FUNCTION g_private_set ##### -->
1272 Sets the pointer keyed to @private_key for the current thread.
1276 This function can also be used, if g_thread_init() has not yet been
1277 called and will set @private_key to @data casted to #GPrivate* then.
1280 @private_key: a #GPrivate
1281 @data: the new pointer
1284 <!-- ##### STRUCT GStaticPrivate ##### -->
1287 A #GStaticPrivate works almost like a #GPrivate, but it has one
1288 significant advantage. It doesn't need to be created at run-time like
1289 a #GPrivate, but can be defined at compile-time. This is similar to
1290 the difference between #GMutex and #GStaticMutex. Now look at our
1291 give_me_next_number() example with #GStaticPrivate:
1296 <title>Using GStaticPrivate for per-thread data</title>
1298 int give_me_next_number ()
1300 static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
1301 int *current_number = g_static_private_get (&current_number_key);
1303 if (!current_number)
1305 current_number = g_new (int,1);
1306 *current_number = 0;
1307 g_static_private_set (&current_number_key, current_number, g_free);
1309 *current_number = calc_next_number (*current_number);
1310 return *current_number;
1318 <!-- ##### MACRO G_STATIC_PRIVATE_INIT ##### -->
1320 Every #GStaticPrivate must be initialized with this macro, before it can
1327 GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
1334 <!-- ##### FUNCTION g_static_private_init ##### -->
1336 Initializes @private_key. Alternatively you can initialize it with
1337 #G_STATIC_PRIVATE_INIT.
1340 @private_key: a #GStaticPrivate to be initialized
1343 <!-- ##### FUNCTION g_static_private_get ##### -->
1345 Works like g_private_get() only for a #GStaticPrivate.
1349 This function also works, if g_thread_init() has not yet been called.
1352 @private_key: a #GStaticPrivate
1353 @Returns: the corresponding pointer
1356 <!-- ##### FUNCTION g_static_private_get_for_thread ##### -->
1366 <!-- ##### FUNCTION g_static_private_set ##### -->
1368 Sets the pointer keyed to @private_key for the current thread and the
1369 function @notify to be called with that pointer (NULL or non-NULL),
1370 whenever the pointer is set again or whenever the current thread ends.
1374 This function also works, if g_thread_init() has not yet been
1375 called. If g_thread_init() is called later, the @data keyed to
1376 @private_key will be inherited only by the main thread, i.e. the one that
1377 called g_thread_init().
1382 @notify is working quite differently from @destructor in
1387 @private_key: a #GStaticPrivate
1388 @data: the new pointer
1389 @notify: a function to be called with the pointer, whenever the
1390 current thread ends or sets this pointer again
1393 <!-- ##### FUNCTION g_static_private_set_for_thread ##### -->
1404 <!-- ##### FUNCTION g_static_private_free ##### -->
1406 Releases all resources allocated to @private_key.
1410 You don't have to call this functions for a #GStaticPrivate with an
1411 unbounded lifetime, i.e. objects declared 'static', but if you have a
1412 #GStaticPrivate as a member of a structure and the structure is freed,
1413 you should also free the #GStaticPrivate.
1416 @private_key: a #GStaticPrivate to be freed