64522ae2e83cdfb3e13fb09c188e9a3900284abc
[platform/upstream/glib.git] / glib / gthread.c
1 /* GLIB - Library of useful routines for C programming
2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
3  *
4  * gthread.c: MT safety related functions
5  * Copyright 1998 Sebastian Wilhelmi; University of Karlsruhe
6  *                Owen Taylor
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Lesser General Public
10  * License as published by the Free Software Foundation; either
11  * version 2 of the License, or (at your option) any later version.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with this library; if not, write to the
20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21  * Boston, MA 02111-1307, USA.
22  */
23
24 /* Prelude {{{1 ----------------------------------------------------------- */
25
26 /*
27  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
28  * file for a list of people on the GLib Team.  See the ChangeLog
29  * files for a list of changes.  These files are distributed with
30  * GLib at ftp://ftp.gtk.org/pub/gtk/.
31  */
32
33 /*
34  * MT safe
35  */
36
37 /* implement gthread.h's inline functions */
38 #define G_IMPLEMENT_INLINES 1
39 #define __G_THREAD_C__
40
41 #include "config.h"
42
43 #include "gthread.h"
44 #include "gthreadprivate.h"
45 #include "gslice.h"
46 #include "gmain.h"
47
48 #ifdef HAVE_UNISTD_H
49 #include <unistd.h>
50 #endif
51
52 #ifndef G_OS_WIN32
53 #include <sys/time.h>
54 #include <time.h>
55 #else
56 #include <windows.h>
57 #endif /* G_OS_WIN32 */
58
59 #include <string.h>
60
61 #include "garray.h"
62 #include "gbitlock.h"
63 #include "gslist.h"
64 #include "gtestutils.h"
65 #include "gtimer.h"
66
67 /**
68  * SECTION:threads
69  * @title: Threads
70  * @short_description: thread abstraction; including threads, different
71  *                     mutexes, conditions and thread private data
72  * @see_also: #GThreadPool, #GAsyncQueue
73  *
74  * Threads act almost like processes, but unlike processes all threads
75  * of one process share the same memory. This is good, as it provides
76  * easy communication between the involved threads via this shared
77  * memory, and it is bad, because strange things (so called
78  * "Heisenbugs") might happen if the program is not carefully designed.
79  * In particular, due to the concurrent nature of threads, no
80  * assumptions on the order of execution of code running in different
81  * threads can be made, unless order is explicitly forced by the
82  * programmer through synchronization primitives.
83  *
84  * The aim of the thread related functions in GLib is to provide a
85  * portable means for writing multi-threaded software. There are
86  * primitives for mutexes to protect the access to portions of memory
87  * (#GMutex, #GStaticMutex, #G_LOCK_DEFINE, #GStaticRecMutex and
88  * #GStaticRWLock). There is a facility to use individual bits for
89  * locks (g_bit_lock()). There are primitives for condition variables to
90  * allow synchronization of threads (#GCond).  There are primitives for
91  * thread-private data - data that every thread has a private instance
92  * of (#GPrivate, #GStaticPrivate). There are facilities for one-time
93  * initialization (#GOnce, g_once_init_enter()). Last but definitely
94  * not least there are primitives to portably create and manage
95  * threads (#GThread).
96  *
97  * The threading system is initialized with g_thread_init(), which
98  * takes an optional custom thread implementation or %NULL for the
99  * default implementation. If you want to call g_thread_init() with a
100  * non-%NULL argument this must be done before executing any other GLib
101  * functions (except g_mem_set_vtable()). This is a requirement even if
102  * no threads are in fact ever created by the process.
103  *
104  * Calling g_thread_init() with a %NULL argument is somewhat more
105  * relaxed. You may call any other glib functions in the main thread
106  * before g_thread_init() as long as g_thread_init() is not called from
107  * a glib callback, or with any locks held. However, many libraries
108  * above glib does not support late initialization of threads, so doing
109  * this should be avoided if possible.
110  *
111  * Please note that since version 2.24 the GObject initialization
112  * function g_type_init() initializes threads (with a %NULL argument),
113  * so most applications, including those using Gtk+ will run with
114  * threads enabled. If you want a special thread implementation, make
115  * sure you call g_thread_init() before g_type_init() is called.
116  *
117  * After calling g_thread_init(), GLib is completely thread safe (all
118  * global data is automatically locked), but individual data structure
119  * instances are not automatically locked for performance reasons. So,
120  * for example you must coordinate accesses to the same #GHashTable
121  * from multiple threads.  The two notable exceptions from this rule
122  * are #GMainLoop and #GAsyncQueue, which <emphasis>are</emphasis>
123  * threadsafe and need no further application-level locking to be
124  * accessed from multiple threads.
125  *
126  * To help debugging problems in multithreaded applications, GLib
127  * supports error-checking mutexes that will give you helpful error
128  * messages on common problems. To use error-checking mutexes, define
129  * the symbol #G_ERRORCHECK_MUTEXES when compiling the application.
130  **/
131
132 /**
133  * G_THREADS_IMPL_POSIX:
134  *
135  * This macro is defined if POSIX style threads are used.
136  **/
137
138 /**
139  * G_THREADS_ENABLED:
140  *
141  * This macro is defined, for backward compatibility, to indicate that
142  * GLib has been compiled with thread support. As of glib 2.28, it is
143  * always defined.
144  **/
145
146 /**
147  * G_THREADS_IMPL_NONE:
148  *
149  * This macro is defined if no thread implementation is used. You can,
150  * however, provide one to g_thread_init() to make GLib multi-thread
151  * safe.
152  **/
153
154 /* G_LOCK Documentation {{{1 ---------------------------------------------- */
155
156 /* IMPLEMENTATION NOTE:
157  *
158  * G_LOCK_DEFINE and friends are convenience macros defined in
159  * gthread.h.  Their documentation lives here.
160  */
161
162 /**
163  * G_LOCK_DEFINE:
164  * @name: the name of the lock.
165  *
166  * The %G_LOCK_* macros provide a convenient interface to #GStaticMutex
167  * with the advantage that they will expand to nothing in programs
168  * compiled against a thread-disabled GLib, saving code and memory
169  * there. #G_LOCK_DEFINE defines a lock. It can appear anywhere
170  * variable definitions may appear in programs, i.e. in the first block
171  * of a function or outside of functions. The @name parameter will be
172  * mangled to get the name of the #GStaticMutex. This means that you
173  * can use names of existing variables as the parameter - e.g. the name
174  * of the variable you intent to protect with the lock. Look at our
175  * <function>give_me_next_number()</function> example using the
176  * %G_LOCK_* macros:
177  *
178  * <example>
179  *  <title>Using the %G_LOCK_* convenience macros</title>
180  *  <programlisting>
181  *   G_LOCK_DEFINE (current_number);
182  *
183  *   int
184  *   give_me_next_number (void)
185  *   {
186  *     static int current_number = 0;
187  *     int ret_val;
188  *
189  *     G_LOCK (current_number);
190  *     ret_val = current_number = calc_next_number (current_number);
191  *     G_UNLOCK (current_number);
192  *
193  *     return ret_val;
194  *   }
195  *  </programlisting>
196  * </example>
197  **/
198
199 /**
200  * G_LOCK_DEFINE_STATIC:
201  * @name: the name of the lock.
202  *
203  * This works like #G_LOCK_DEFINE, but it creates a static object.
204  **/
205
206 /**
207  * G_LOCK_EXTERN:
208  * @name: the name of the lock.
209  *
210  * This declares a lock, that is defined with #G_LOCK_DEFINE in another
211  * module.
212  **/
213
214 /**
215  * G_LOCK:
216  * @name: the name of the lock.
217  *
218  * Works like g_mutex_lock(), but for a lock defined with
219  * #G_LOCK_DEFINE.
220  **/
221
222 /**
223  * G_TRYLOCK:
224  * @name: the name of the lock.
225  * @Returns: %TRUE, if the lock could be locked.
226  *
227  * Works like g_mutex_trylock(), but for a lock defined with
228  * #G_LOCK_DEFINE.
229  **/
230
231 /**
232  * G_UNLOCK:
233  * @name: the name of the lock.
234  *
235  * Works like g_mutex_unlock(), but for a lock defined with
236  * #G_LOCK_DEFINE.
237  **/
238
239 /* GThreadError {{{1 ------------------------------------------------------- */
240 /**
241  * GThreadError:
242  * @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource
243  *                        shortage. Try again later.
244  *
245  * Possible errors of thread related functions.
246  **/
247
248 /**
249  * G_THREAD_ERROR:
250  *
251  * The error domain of the GLib thread subsystem.
252  **/
253 GQuark
254 g_thread_error_quark (void)
255 {
256   return g_quark_from_static_string ("g_thread_error");
257 }
258
259 /* Miscellaneous Structures {{{1 ------------------------------------------ */
260 typedef struct _GRealThread GRealThread;
261 struct  _GRealThread
262 {
263   GThread thread;
264   /* Bit 0 protects private_data. To avoid deadlocks, do not block while
265    * holding this (particularly on the g_thread lock). */
266   volatile gint private_data_lock;
267   GArray *private_data;
268   GRealThread *next;
269   gpointer retval;
270   GSystemThread system_thread;
271 };
272
273 #define LOCK_PRIVATE_DATA(self)   g_bit_lock (&(self)->private_data_lock, 0)
274 #define UNLOCK_PRIVATE_DATA(self) g_bit_unlock (&(self)->private_data_lock, 0)
275
276 typedef struct _GStaticPrivateNode GStaticPrivateNode;
277 struct _GStaticPrivateNode
278 {
279   gpointer       data;
280   GDestroyNotify destroy;
281 };
282
283 static void    g_thread_cleanup (gpointer data);
284 static void    g_thread_fail (void);
285 static guint64 gettime (void);
286
287 guint64        (*g_thread_gettime) (void) = gettime;
288
289 /* Global Variables {{{1 -------------------------------------------------- */
290
291 static GSystemThread zero_thread; /* This is initialized to all zero */
292 gboolean g_thread_use_default_impl = TRUE;
293
294 /**
295  * g_thread_supported:
296  * @Returns: %TRUE, if the thread system is initialized.
297  *
298  * This function returns %TRUE if the thread system is initialized, and
299  * %FALSE if it is not.
300  *
301  * <note><para>This function is actually a macro. Apart from taking the
302  * address of it you can however use it as if it was a
303  * function.</para></note>
304  **/
305
306 /* IMPLEMENTATION NOTE:
307  *
308  * g_thread_supported() is just returns g_threads_got_initialized
309  */
310 gboolean g_threads_got_initialized = FALSE;
311
312
313 /* Thread Implementation Virtual Function Table {{{1 ---------------------- */
314 /* Virtual Function Table Documentation {{{2 ------------------------------ */
315 /**
316  * GThreadFunctions:
317  * @mutex_new: virtual function pointer for g_mutex_new()
318  * @mutex_lock: virtual function pointer for g_mutex_lock()
319  * @mutex_trylock: virtual function pointer for g_mutex_trylock()
320  * @mutex_unlock: virtual function pointer for g_mutex_unlock()
321  * @mutex_free: virtual function pointer for g_mutex_free()
322  * @cond_new: virtual function pointer for g_cond_new()
323  * @cond_signal: virtual function pointer for g_cond_signal()
324  * @cond_broadcast: virtual function pointer for g_cond_broadcast()
325  * @cond_wait: virtual function pointer for g_cond_wait()
326  * @cond_timed_wait: virtual function pointer for g_cond_timed_wait()
327  * @cond_free: virtual function pointer for g_cond_free()
328  * @private_new: virtual function pointer for g_private_new()
329  * @private_get: virtual function pointer for g_private_get()
330  * @private_set: virtual function pointer for g_private_set()
331  * @thread_create: virtual function pointer for g_thread_create()
332  * @thread_yield: virtual function pointer for g_thread_yield()
333  * @thread_join: virtual function pointer for g_thread_join()
334  * @thread_exit: virtual function pointer for g_thread_exit()
335  * @thread_set_priority: virtual function pointer for
336  *                       g_thread_set_priority()
337  * @thread_self: virtual function pointer for g_thread_self()
338  * @thread_equal: used internally by recursive mutex locks and by some
339  *                assertion checks
340  *
341  * This function table is used by g_thread_init() to initialize the
342  * thread system. The functions in the table are directly used by their
343  * g_* prepended counterparts (described in this document).  For
344  * example, if you call g_mutex_new() then mutex_new() from the table
345  * provided to g_thread_init() will be called.
346  *
347  * <note><para>Do not use this struct unless you know what you are
348  * doing.</para></note>
349  **/
350
351 /* IMPLEMENTATION NOTE:
352  *
353  * g_thread_functions_for_glib_use is a global symbol that gets used by
354  * most of the "primitive" threading calls.  g_mutex_lock(), for
355  * example, is just a macro that calls the appropriate virtual function
356  * out of this table.
357  *
358  * For that reason, all of those macros are documented here.
359  */
360 static GThreadFunctions g_thread_functions_for_glib_use_old = {
361 /* GMutex Virtual Functions {{{2 ------------------------------------------ */
362
363 /**
364  * GMutex:
365  *
366  * The #GMutex struct is an opaque data structure to represent a mutex
367  * (mutual exclusion). It can be used to protect data against shared
368  * access. Take for example the following function:
369  *
370  * <example>
371  *  <title>A function which will not work in a threaded environment</title>
372  *  <programlisting>
373  *   int
374  *   give_me_next_number (void)
375  *   {
376  *     static int current_number = 0;
377  *
378  *     /<!-- -->* now do a very complicated calculation to calculate the new
379  *      * number, this might for example be a random number generator
380  *      *<!-- -->/
381  *     current_number = calc_next_number (current_number);
382  *
383  *     return current_number;
384  *   }
385  *  </programlisting>
386  * </example>
387  *
388  * It is easy to see that this won't work in a multi-threaded
389  * application. There current_number must be protected against shared
390  * access. A first naive implementation would be:
391  *
392  * <example>
393  *  <title>The wrong way to write a thread-safe function</title>
394  *  <programlisting>
395  *   int
396  *   give_me_next_number (void)
397  *   {
398  *     static int current_number = 0;
399  *     int ret_val;
400  *     static GMutex * mutex = NULL;
401  *
402  *     if (!mutex) mutex = g_mutex_new (<!-- -->);
403  *
404  *     g_mutex_lock (mutex);
405  *     ret_val = current_number = calc_next_number (current_number);
406  *     g_mutex_unlock (mutex);
407  *
408  *     return ret_val;
409  *   }
410  *  </programlisting>
411  * </example>
412  *
413  * This looks like it would work, but there is a race condition while
414  * constructing the mutex and this code cannot work reliable. Please do
415  * not use such constructs in your own programs! One working solution
416  * is:
417  *
418  * <example>
419  *  <title>A correct thread-safe function</title>
420  *  <programlisting>
421  *   static GMutex *give_me_next_number_mutex = NULL;
422  *
423  *   /<!-- -->* this function must be called before any call to
424  *    * give_me_next_number(<!-- -->)
425  *    *
426  *    * it must be called exactly once.
427  *    *<!-- -->/
428  *   void
429  *   init_give_me_next_number (void)
430  *   {
431  *     g_assert (give_me_next_number_mutex == NULL);
432  *     give_me_next_number_mutex = g_mutex_new (<!-- -->);
433  *   }
434  *
435  *   int
436  *   give_me_next_number (void)
437  *   {
438  *     static int current_number = 0;
439  *     int ret_val;
440  *
441  *     g_mutex_lock (give_me_next_number_mutex);
442  *     ret_val = current_number = calc_next_number (current_number);
443  *     g_mutex_unlock (give_me_next_number_mutex);
444  *
445  *     return ret_val;
446  *   }
447  *  </programlisting>
448  * </example>
449  *
450  * #GStaticMutex provides a simpler and safer way of doing this.
451  *
452  * If you want to use a mutex, and your code should also work without
453  * calling g_thread_init() first, then you cannot use a #GMutex, as
454  * g_mutex_new() requires that the thread system be initialized. Use a
455  * #GStaticMutex instead.
456  *
457  * A #GMutex should only be accessed via the following functions.
458  *
459  * <note><para>All of the <function>g_mutex_*</function> functions are
460  * actually macros. Apart from taking their addresses, you can however
461  * use them as if they were functions.</para></note>
462  **/
463
464 /**
465  * g_mutex_new:
466  * @Returns: a new #GMutex.
467  *
468  * Creates a new #GMutex.
469  *
470  * <note><para>This function will abort if g_thread_init() has not been
471  * called yet.</para></note>
472  **/
473   (GMutex*(*)())g_thread_fail,
474
475 /**
476  * g_mutex_lock:
477  * @mutex: a #GMutex.
478  *
479  * Locks @mutex. If @mutex is already locked by another thread, the
480  * current thread will block until @mutex is unlocked by the other
481  * thread.
482  *
483  * This function can be used even if g_thread_init() has not yet been
484  * called, and, in that case, will do nothing.
485  *
486  * <note><para>#GMutex is neither guaranteed to be recursive nor to be
487  * non-recursive, i.e. a thread could deadlock while calling
488  * g_mutex_lock(), if it already has locked @mutex. Use
489  * #GStaticRecMutex, if you need recursive mutexes.</para></note>
490  **/
491   NULL,
492
493 /**
494  * g_mutex_trylock:
495  * @mutex: a #GMutex.
496  * @Returns: %TRUE, if @mutex could be locked.
497  *
498  * Tries to lock @mutex. If @mutex is already locked by another thread,
499  * it immediately returns %FALSE. Otherwise it locks @mutex and returns
500  * %TRUE.
501  *
502  * This function can be used even if g_thread_init() has not yet been
503  * called, and, in that case, will immediately return %TRUE.
504  *
505  * <note><para>#GMutex is neither guaranteed to be recursive nor to be
506  * non-recursive, i.e. the return value of g_mutex_trylock() could be
507  * both %FALSE or %TRUE, if the current thread already has locked
508  * @mutex. Use #GStaticRecMutex, if you need recursive
509  * mutexes.</para></note>
510  **/
511   NULL,
512
513 /**
514  * g_mutex_unlock:
515  * @mutex: a #GMutex.
516  *
517  * Unlocks @mutex. If another thread is blocked in a g_mutex_lock()
518  * call for @mutex, it will be woken and can lock @mutex itself.
519  *
520  * This function can be used even if g_thread_init() has not yet been
521  * called, and, in that case, will do nothing.
522  **/
523   NULL,
524
525 /**
526  * g_mutex_free:
527  * @mutex: a #GMutex.
528  *
529  * Destroys @mutex.
530  *
531  * <note><para>Calling g_mutex_free() on a locked mutex may result in
532  * undefined behaviour.</para></note>
533  **/
534   NULL,
535
536 /* GCond Virtual Functions {{{2 ------------------------------------------ */
537
538 /**
539  * GCond:
540  *
541  * The #GCond struct is an opaque data structure that represents a
542  * condition. Threads can block on a #GCond if they find a certain
543  * condition to be false. If other threads change the state of this
544  * condition they signal the #GCond, and that causes the waiting
545  * threads to be woken up.
546  *
547  * <example>
548  *  <title>
549  *   Using GCond to block a thread until a condition is satisfied
550  *  </title>
551  *  <programlisting>
552  *   GCond* data_cond = NULL; /<!-- -->* Must be initialized somewhere *<!-- -->/
553  *   GMutex* data_mutex = NULL; /<!-- -->* Must be initialized somewhere *<!-- -->/
554  *   gpointer current_data = NULL;
555  *
556  *   void
557  *   push_data (gpointer data)
558  *   {
559  *     g_mutex_lock (data_mutex);
560  *     current_data = data;
561  *     g_cond_signal (data_cond);
562  *     g_mutex_unlock (data_mutex);
563  *   }
564  *
565  *   gpointer
566  *   pop_data (void)
567  *   {
568  *     gpointer data;
569  *
570  *     g_mutex_lock (data_mutex);
571  *     while (!current_data)
572  *       g_cond_wait (data_cond, data_mutex);
573  *     data = current_data;
574  *     current_data = NULL;
575  *     g_mutex_unlock (data_mutex);
576  *
577  *     return data;
578  *   }
579  *  </programlisting>
580  * </example>
581  *
582  * Whenever a thread calls <function>pop_data()</function> now, it will
583  * wait until current_data is non-%NULL, i.e. until some other thread
584  * has called <function>push_data()</function>.
585  *
586  * <note><para>It is important to use the g_cond_wait() and
587  * g_cond_timed_wait() functions only inside a loop which checks for the
588  * condition to be true.  It is not guaranteed that the waiting thread
589  * will find the condition fulfilled after it wakes up, even if the
590  * signaling thread left the condition in that state: another thread may
591  * have altered the condition before the waiting thread got the chance
592  * to be woken up, even if the condition itself is protected by a
593  * #GMutex, like above.</para></note>
594  *
595  * A #GCond should only be accessed via the following functions.
596  *
597  * <note><para>All of the <function>g_cond_*</function> functions are
598  * actually macros. Apart from taking their addresses, you can however
599  * use them as if they were functions.</para></note>
600  **/
601
602 /**
603  * g_cond_new:
604  * @Returns: a new #GCond.
605  *
606  * Creates a new #GCond. This function will abort, if g_thread_init()
607  * has not been called yet.
608  **/
609   (GCond*(*)())g_thread_fail,
610
611 /**
612  * g_cond_signal:
613  * @cond: a #GCond.
614  *
615  * If threads are waiting for @cond, exactly one of them is woken up.
616  * It is good practice to hold the same lock as the waiting thread
617  * while calling this function, though not required.
618  *
619  * This function can be used even if g_thread_init() has not yet been
620  * called, and, in that case, will do nothing.
621  **/
622   NULL,
623
624 /**
625  * g_cond_broadcast:
626  * @cond: a #GCond.
627  *
628  * If threads are waiting for @cond, all of them are woken up. It is
629  * good practice to lock the same mutex as the waiting threads, while
630  * calling this function, though not required.
631  *
632  * This function can be used even if g_thread_init() has not yet been
633  * called, and, in that case, will do nothing.
634  **/
635   NULL,
636
637 /**
638  * g_cond_wait:
639  * @cond: a #GCond.
640  * @mutex: a #GMutex, that is currently locked.
641  *
642  * Waits until this thread is woken up on @cond. The @mutex is unlocked
643  * before falling asleep and locked again before resuming.
644  *
645  * This function can be used even if g_thread_init() has not yet been
646  * called, and, in that case, will immediately return.
647  **/
648   NULL,
649
650 /**
651  * g_cond_timed_wait:
652  * @cond: a #GCond.
653  * @mutex: a #GMutex that is currently locked.
654  * @abs_time: a #GTimeVal, determining the final time.
655  * @Returns: %TRUE if @cond was signalled, or %FALSE on timeout.
656  *
657  * Waits until this thread is woken up on @cond, but not longer than
658  * until the time specified by @abs_time. The @mutex is unlocked before
659  * falling asleep and locked again before resuming.
660  *
661  * If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait().
662  *
663  * This function can be used even if g_thread_init() has not yet been
664  * called, and, in that case, will immediately return %TRUE.
665  *
666  * To easily calculate @abs_time a combination of g_get_current_time()
667  * and g_time_val_add() can be used.
668  **/
669   NULL,
670
671 /**
672  * g_cond_free:
673  * @cond: a #GCond.
674  *
675  * Destroys the #GCond.
676  **/
677   NULL,
678
679 /* GPrivate Virtual Functions {{{2 --------------------------------------- */
680
681 /**
682  * GPrivate:
683  *
684  * <note><para>
685  * #GStaticPrivate is a better choice for most uses.
686  * </para></note>
687  *
688  * The #GPrivate struct is an opaque data structure to represent a
689  * thread private data key. Threads can thereby obtain and set a
690  * pointer which is private to the current thread. Take our
691  * <function>give_me_next_number(<!-- -->)</function> example from
692  * above.  Suppose we don't want <literal>current_number</literal> to be
693  * shared between the threads, but instead to be private to each thread.
694  * This can be done as follows:
695  *
696  * <example>
697  *  <title>Using GPrivate for per-thread data</title>
698  *  <programlisting>
699  *   GPrivate* current_number_key = NULL; /<!-- -->* Must be initialized somewhere
700  *                                           with g_private_new (g_free); *<!-- -->/
701  *
702  *   int
703  *   give_me_next_number (void)
704  *   {
705  *     int *current_number = g_private_get (current_number_key);
706  *
707  *     if (!current_number)
708  *       {
709  *         current_number = g_new (int, 1);
710  *         *current_number = 0;
711  *         g_private_set (current_number_key, current_number);
712  *       }
713  *
714  *     *current_number = calc_next_number (*current_number);
715  *
716  *     return *current_number;
717  *   }
718  *  </programlisting>
719  * </example>
720  *
721  * Here the pointer belonging to the key
722  * <literal>current_number_key</literal> is read. If it is %NULL, it has
723  * not been set yet. Then get memory for an integer value, assign this
724  * memory to the pointer and write the pointer back. Now we have an
725  * integer value that is private to the current thread.
726  *
727  * The #GPrivate struct should only be accessed via the following
728  * functions.
729  *
730  * <note><para>All of the <function>g_private_*</function> functions are
731  * actually macros. Apart from taking their addresses, you can however
732  * use them as if they were functions.</para></note>
733  **/
734
735 /**
736  * g_private_new:
737  * @destructor: a function to destroy the data keyed to #GPrivate when
738  *              a thread ends.
739  * @Returns: a new #GPrivate.
740  *
741  * Creates a new #GPrivate. If @destructor is non-%NULL, it is a
742  * pointer to a destructor function. Whenever a thread ends and the
743  * corresponding pointer keyed to this instance of #GPrivate is
744  * non-%NULL, the destructor is called with this pointer as the
745  * argument.
746  *
747  * <note><para>
748  * #GStaticPrivate is a better choice for most uses.
749  * </para></note>
750  *
751  * <note><para>@destructor is used quite differently from @notify in
752  * g_static_private_set().</para></note>
753  *
754  * <note><para>A #GPrivate cannot be freed. Reuse it instead, if you
755  * can, to avoid shortage, or use #GStaticPrivate.</para></note>
756  *
757  * <note><para>This function will abort if g_thread_init() has not been
758  * called yet.</para></note>
759  **/
760   (GPrivate*(*)(GDestroyNotify))g_thread_fail,
761
762 /**
763  * g_private_get:
764  * @private_key: a #GPrivate.
765  * @Returns: the corresponding pointer.
766  *
767  * Returns the pointer keyed to @private_key for the current thread. If
768  * g_private_set() hasn't been called for the current @private_key and
769  * thread yet, this pointer will be %NULL.
770  *
771  * This function can be used even if g_thread_init() has not yet been
772  * called, and, in that case, will return the value of @private_key
773  * casted to #gpointer. Note however, that private data set
774  * <emphasis>before</emphasis> g_thread_init() will
775  * <emphasis>not</emphasis> be retained <emphasis>after</emphasis> the
776  * call. Instead, %NULL will be returned in all threads directly after
777  * g_thread_init(), regardless of any g_private_set() calls issued
778  * before threading system intialization.
779  **/
780   NULL,
781
782 /**
783  * g_private_set:
784  * @private_key: a #GPrivate.
785  * @data: the new pointer.
786  *
787  * Sets the pointer keyed to @private_key for the current thread.
788  *
789  * This function can be used even if g_thread_init() has not yet been
790  * called, and, in that case, will set @private_key to @data casted to
791  * #GPrivate*. See g_private_get() for resulting caveats.
792  **/
793   NULL,
794
795 /* GThread Virtual Functions {{{2 ---------------------------------------- */
796 /**
797  * GThread:
798  *
799  * The #GThread struct represents a running thread. It has three public
800  * read-only members, but the underlying struct is bigger, so you must
801  * not copy this struct.
802  *
803  * <note><para>Resources for a joinable thread are not fully released
804  * until g_thread_join() is called for that thread.</para></note>
805  **/
806
807 /**
808  * GThreadFunc:
809  * @data: data passed to the thread.
810  * @Returns: the return value of the thread, which will be returned by
811  *           g_thread_join().
812  *
813  * Specifies the type of the @func functions passed to
814  * g_thread_create() or g_thread_create_full().
815  **/
816
817 /**
818  * GThreadPriority:
819  * @G_THREAD_PRIORITY_LOW: a priority lower than normal
820  * @G_THREAD_PRIORITY_NORMAL: the default priority
821  * @G_THREAD_PRIORITY_HIGH: a priority higher than normal
822  * @G_THREAD_PRIORITY_URGENT: the highest priority
823  *
824  * Specifies the priority of a thread.
825  *
826  * <note><para>It is not guaranteed that threads with different priorities
827  * really behave accordingly. On some systems (e.g. Linux) there are no
828  * thread priorities. On other systems (e.g. Solaris) there doesn't
829  * seem to be different scheduling for different priorities. All in all
830  * try to avoid being dependent on priorities.</para></note>
831  **/
832
833 /**
834  * g_thread_create:
835  * @func: a function to execute in the new thread.
836  * @data: an argument to supply to the new thread.
837  * @joinable: should this thread be joinable?
838  * @error: return location for error.
839  * @Returns: the new #GThread on success.
840  *
841  * This function creates a new thread with the default priority.
842  *
843  * If @joinable is %TRUE, you can wait for this threads termination
844  * calling g_thread_join(). Otherwise the thread will just disappear
845  * when it terminates.
846  *
847  * The new thread executes the function @func with the argument @data.
848  * If the thread was created successfully, it is returned.
849  *
850  * @error can be %NULL to ignore errors, or non-%NULL to report errors.
851  * The error is set, if and only if the function returns %NULL.
852  **/
853   (void(*)(GThreadFunc, gpointer, gulong,
854            gboolean, gboolean, GThreadPriority,
855            gpointer, GError**))g_thread_fail,
856
857 /**
858  * g_thread_yield:
859  *
860  * Gives way to other threads waiting to be scheduled.
861  *
862  * This function is often used as a method to make busy wait less evil.
863  * But in most cases you will encounter, there are better methods to do
864  * that. So in general you shouldn't use this function.
865  **/
866   NULL,
867
868   NULL,                                        /* thread_join */
869   NULL,                                        /* thread_exit */
870   NULL,                                        /* thread_set_priority */
871   NULL,                                        /* thread_self */
872   NULL                                         /* thread_equal */
873 };
874
875 /* Local Data {{{1 -------------------------------------------------------- */
876
877 static GMutex    g_once_mutex = G_MUTEX_INIT;
878 static GCond     g_once_cond = G_COND_INIT;
879 static GPrivate  g_thread_specific_private;
880 static GRealThread *g_thread_all_threads = NULL;
881 static GSList   *g_thread_free_indices = NULL;
882 static GSList*   g_once_init_list = NULL;
883
884 G_LOCK_DEFINE_STATIC (g_thread);
885
886 /* Initialisation {{{1 ---------------------------------------------------- */
887
888 /**
889  * g_thread_init:
890  * @vtable: a function table of type #GThreadFunctions, that provides
891  *          the entry points to the thread system to be used.
892  *
893  * If you use GLib from more than one thread, you must initialize the
894  * thread system by calling g_thread_init(). Most of the time you will
895  * only have to call <literal>g_thread_init (NULL)</literal>.
896  *
897  * <note><para>Do not call g_thread_init() with a non-%NULL parameter unless
898  * you really know what you are doing.</para></note>
899  *
900  * <note><para>g_thread_init() must not be called directly or indirectly as a
901  * callback from GLib. Also no mutexes may be currently locked while
902  * calling g_thread_init().</para></note>
903  *
904  * <note><para>g_thread_init() changes the way in which #GTimer measures
905  * elapsed time. As a consequence, timers that are running while
906  * g_thread_init() is called may report unreliable times.</para></note>
907  *
908  * Calling g_thread_init() multiple times is allowed (since version
909  * 2.24), but nothing happens except for the first call. If the
910  * argument is non-%NULL on such a call a warning will be printed, but
911  * otherwise the argument is ignored.
912  *
913  * If no thread system is available and @vtable is %NULL or if not all
914  * elements of @vtable are non-%NULL, then g_thread_init() will abort.
915  *
916  * <note><para>To use g_thread_init() in your program, you have to link with
917  * the libraries that the command <command>pkg-config --libs
918  * gthread-2.0</command> outputs. This is not the case for all the
919  * other thread related functions of GLib. Those can be used without
920  * having to link with the thread libraries.</para></note>
921  **/
922
923 /* This must be called only once, before any threads are created.
924  * It will only be called from g_thread_init() in -lgthread.
925  */
926 void
927 g_thread_init_glib (void)
928 {
929   static gboolean already_done;
930
931   if (already_done)
932     return;
933
934   already_done = TRUE;
935
936   _g_thread_impl_init ();
937
938   /* We let the main thread (the one that calls g_thread_init) inherit
939    * the static_private data set before calling g_thread_init
940    */
941   GRealThread* main_thread = (GRealThread*) g_thread_self ();
942
943   /* we may only create mutex and cond in here */
944   _g_mem_thread_init_noprivate_nomessage ();
945
946   /* setup the basic threading system */
947   g_threads_got_initialized = TRUE;
948   g_private_init (&g_thread_specific_private, g_thread_cleanup);
949   g_private_set (&g_thread_specific_private, main_thread);
950   G_THREAD_UF (thread_self, (&main_thread->system_thread));
951
952   /* complete memory system initialization, g_private_*() works now */
953   _g_slice_thread_init_nomessage ();
954
955   /* accomplish log system initialization to enable messaging */
956   _g_messages_thread_init_nomessage ();
957 }
958
959 /* The following sections implement: GOnce, GStaticMutex, GStaticRecMutex,
960  * GStaticPrivate, 
961  **/
962
963 /* GOnce {{{1 ------------------------------------------------------------- */
964
965 /**
966  * GOnce:
967  * @status: the status of the #GOnce
968  * @retval: the value returned by the call to the function, if @status
969  *          is %G_ONCE_STATUS_READY
970  *
971  * A #GOnce struct controls a one-time initialization function. Any
972  * one-time initialization function must have its own unique #GOnce
973  * struct.
974  *
975  * Since: 2.4
976  **/
977
978 /**
979  * G_ONCE_INIT:
980  *
981  * A #GOnce must be initialized with this macro before it can be used.
982  *
983  * <informalexample>
984  *  <programlisting>
985  *   GOnce my_once = G_ONCE_INIT;
986  *  </programlisting>
987  * </informalexample>
988  *
989  * Since: 2.4
990  **/
991
992 /**
993  * GOnceStatus:
994  * @G_ONCE_STATUS_NOTCALLED: the function has not been called yet.
995  * @G_ONCE_STATUS_PROGRESS: the function call is currently in progress.
996  * @G_ONCE_STATUS_READY: the function has been called.
997  *
998  * The possible statuses of a one-time initialization function
999  * controlled by a #GOnce struct.
1000  *
1001  * Since: 2.4
1002  **/
1003
1004 /**
1005  * g_once:
1006  * @once: a #GOnce structure
1007  * @func: the #GThreadFunc function associated to @once. This function
1008  *        is called only once, regardless of the number of times it and
1009  *        its associated #GOnce struct are passed to g_once().
1010  * @arg: data to be passed to @func
1011  *
1012  * The first call to this routine by a process with a given #GOnce
1013  * struct calls @func with the given argument. Thereafter, subsequent
1014  * calls to g_once()  with the same #GOnce struct do not call @func
1015  * again, but return the stored result of the first call. On return
1016  * from g_once(), the status of @once will be %G_ONCE_STATUS_READY.
1017  *
1018  * For example, a mutex or a thread-specific data key must be created
1019  * exactly once. In a threaded environment, calling g_once() ensures
1020  * that the initialization is serialized across multiple threads.
1021  *
1022  * <note><para>Calling g_once() recursively on the same #GOnce struct in
1023  * @func will lead to a deadlock.</para></note>
1024  *
1025  * <informalexample>
1026  *  <programlisting>
1027  *   gpointer
1028  *   get_debug_flags (void)
1029  *   {
1030  *     static GOnce my_once = G_ONCE_INIT;
1031  *
1032  *     g_once (&my_once, parse_debug_flags, NULL);
1033  *
1034  *     return my_once.retval;
1035  *   }
1036  *  </programlisting>
1037  * </informalexample>
1038  *
1039  * Since: 2.4
1040  **/
1041 gpointer
1042 g_once_impl (GOnce       *once,
1043              GThreadFunc  func,
1044              gpointer     arg)
1045 {
1046   g_mutex_lock (&g_once_mutex);
1047
1048   while (once->status == G_ONCE_STATUS_PROGRESS)
1049     g_cond_wait (&g_once_cond, &g_once_mutex);
1050
1051   if (once->status != G_ONCE_STATUS_READY)
1052     {
1053       once->status = G_ONCE_STATUS_PROGRESS;
1054       g_mutex_unlock (&g_once_mutex);
1055
1056       once->retval = func (arg);
1057
1058       g_mutex_lock (&g_once_mutex);
1059       once->status = G_ONCE_STATUS_READY;
1060       g_cond_broadcast (&g_once_cond);
1061     }
1062
1063   g_mutex_unlock (&g_once_mutex);
1064
1065   return once->retval;
1066 }
1067
1068 /**
1069  * g_once_init_enter:
1070  * @value_location: location of a static initializable variable
1071  *                  containing 0.
1072  * @Returns: %TRUE if the initialization section should be entered,
1073  *           %FALSE and blocks otherwise
1074  *
1075  * Function to be called when starting a critical initialization
1076  * section. The argument @value_location must point to a static
1077  * 0-initialized variable that will be set to a value other than 0 at
1078  * the end of the initialization section. In combination with
1079  * g_once_init_leave() and the unique address @value_location, it can
1080  * be ensured that an initialization section will be executed only once
1081  * during a program's life time, and that concurrent threads are
1082  * blocked until initialization completed. To be used in constructs
1083  * like this:
1084  *
1085  * <informalexample>
1086  *  <programlisting>
1087  *   static gsize initialization_value = 0;
1088  *
1089  *   if (g_once_init_enter (&amp;initialization_value))
1090  *     {
1091  *       gsize setup_value = 42; /<!-- -->* initialization code here *<!-- -->/
1092  *
1093  *       g_once_init_leave (&amp;initialization_value, setup_value);
1094  *     }
1095  *
1096  *   /<!-- -->* use initialization_value here *<!-- -->/
1097  *  </programlisting>
1098  * </informalexample>
1099  *
1100  * Since: 2.14
1101  **/
1102 gboolean
1103 g_once_init_enter_impl (volatile gsize *value_location)
1104 {
1105   gboolean need_init = FALSE;
1106   g_mutex_lock (&g_once_mutex);
1107   if (g_atomic_pointer_get (value_location) == NULL)
1108     {
1109       if (!g_slist_find (g_once_init_list, (void*) value_location))
1110         {
1111           need_init = TRUE;
1112           g_once_init_list = g_slist_prepend (g_once_init_list, (void*) value_location);
1113         }
1114       else
1115         do
1116           g_cond_wait (&g_once_cond, &g_once_mutex);
1117         while (g_slist_find (g_once_init_list, (void*) value_location));
1118     }
1119   g_mutex_unlock (&g_once_mutex);
1120   return need_init;
1121 }
1122
1123 /**
1124  * g_once_init_leave:
1125  * @value_location: location of a static initializable variable
1126  *                  containing 0.
1127  * @initialization_value: new non-0 value for *@value_location.
1128  *
1129  * Counterpart to g_once_init_enter(). Expects a location of a static
1130  * 0-initialized initialization variable, and an initialization value
1131  * other than 0. Sets the variable to the initialization value, and
1132  * releases concurrent threads blocking in g_once_init_enter() on this
1133  * initialization variable.
1134  *
1135  * Since: 2.14
1136  **/
1137 void
1138 g_once_init_leave (volatile gsize *value_location,
1139                    gsize           initialization_value)
1140 {
1141   g_return_if_fail (g_atomic_pointer_get (value_location) == NULL);
1142   g_return_if_fail (initialization_value != 0);
1143   g_return_if_fail (g_once_init_list != NULL);
1144
1145   g_atomic_pointer_set (value_location, initialization_value);
1146   g_mutex_lock (&g_once_mutex);
1147   g_once_init_list = g_slist_remove (g_once_init_list, (void*) value_location);
1148   g_cond_broadcast (&g_once_cond);
1149   g_mutex_unlock (&g_once_mutex);
1150 }
1151
1152 /* GStaticMutex {{{1 ------------------------------------------------------ */
1153
1154 /**
1155  * GStaticMutex:
1156  *
1157  * A #GStaticMutex works like a #GMutex, but it has one significant
1158  * advantage. It doesn't need to be created at run-time like a #GMutex,
1159  * but can be defined at compile-time. Here is a shorter, easier and
1160  * safer version of our <function>give_me_next_number()</function>
1161  * example:
1162  *
1163  * <example>
1164  *  <title>
1165  *   Using <structname>GStaticMutex</structname>
1166  *   to simplify thread-safe programming
1167  *  </title>
1168  *  <programlisting>
1169  *   int
1170  *   give_me_next_number (void)
1171  *   {
1172  *     static int current_number = 0;
1173  *     int ret_val;
1174  *     static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
1175  *
1176  *     g_static_mutex_lock (&amp;mutex);
1177  *     ret_val = current_number = calc_next_number (current_number);
1178  *     g_static_mutex_unlock (&amp;mutex);
1179  *
1180  *     return ret_val;
1181  *   }
1182  *  </programlisting>
1183  * </example>
1184  *
1185  * Sometimes you would like to dynamically create a mutex. If you don't
1186  * want to require prior calling to g_thread_init(), because your code
1187  * should also be usable in non-threaded programs, you are not able to
1188  * use g_mutex_new() and thus #GMutex, as that requires a prior call to
1189  * g_thread_init(). In theses cases you can also use a #GStaticMutex.
1190  * It must be initialized with g_static_mutex_init() before using it
1191  * and freed with with g_static_mutex_free() when not needed anymore to
1192  * free up any allocated resources.
1193  *
1194  * Even though #GStaticMutex is not opaque, it should only be used with
1195  * the following functions, as it is defined differently on different
1196  * platforms.
1197  *
1198  * All of the <function>g_static_mutex_*</function> functions apart
1199  * from <function>g_static_mutex_get_mutex</function> can also be used
1200  * even if g_thread_init() has not yet been called. Then they do
1201  * nothing, apart from <function>g_static_mutex_trylock</function>,
1202  * which does nothing but returning %TRUE.
1203  *
1204  * <note><para>All of the <function>g_static_mutex_*</function>
1205  * functions are actually macros. Apart from taking their addresses, you
1206  * can however use them as if they were functions.</para></note>
1207  **/
1208
1209 /**
1210  * G_STATIC_MUTEX_INIT:
1211  *
1212  * A #GStaticMutex must be initialized with this macro, before it can
1213  * be used. This macro can used be to initialize a variable, but it
1214  * cannot be assigned to a variable. In that case you have to use
1215  * g_static_mutex_init().
1216  *
1217  * <informalexample>
1218  *  <programlisting>
1219  *   GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
1220  *  </programlisting>
1221  * </informalexample>
1222  **/
1223
1224 /**
1225  * g_static_mutex_init:
1226  * @mutex: a #GStaticMutex to be initialized.
1227  *
1228  * Initializes @mutex. Alternatively you can initialize it with
1229  * #G_STATIC_MUTEX_INIT.
1230  **/
1231 void
1232 g_static_mutex_init (GStaticMutex *mutex)
1233 {
1234   static const GStaticMutex init_mutex = G_STATIC_MUTEX_INIT;
1235
1236   g_return_if_fail (mutex);
1237
1238   *mutex = init_mutex;
1239 }
1240
1241 /* IMPLEMENTATION NOTE:
1242  *
1243  * On some platforms a GStaticMutex is actually a normal GMutex stored
1244  * inside of a structure instead of being allocated dynamically.  We can
1245  * only do this for platforms on which we know, in advance, how to
1246  * allocate (size) and initialise (value) that memory.
1247  *
1248  * On other platforms, a GStaticMutex is nothing more than a pointer to
1249  * a GMutex.  In that case, the first access we make to the static mutex
1250  * must first allocate the normal GMutex and store it into the pointer.
1251  *
1252  * configure.ac writes macros into glibconfig.h to determine if
1253  * g_static_mutex_get_mutex() accesses the structure in memory directly
1254  * (on platforms where we are able to do that) or if it ends up here,
1255  * where we may have to allocate the GMutex before returning it.
1256  */
1257
1258 /**
1259  * g_static_mutex_get_mutex:
1260  * @mutex: a #GStaticMutex.
1261  * @Returns: the #GMutex corresponding to @mutex.
1262  *
1263  * For some operations (like g_cond_wait()) you must have a #GMutex
1264  * instead of a #GStaticMutex. This function will return the
1265  * corresponding #GMutex for @mutex.
1266  **/
1267 GMutex *
1268 g_static_mutex_get_mutex_impl (GMutex** mutex)
1269 {
1270   GMutex *result;
1271
1272   if (!g_thread_supported ())
1273     return NULL;
1274
1275   result = g_atomic_pointer_get (mutex);
1276
1277   if (!result)
1278     {
1279       g_mutex_lock (&g_once_mutex);
1280
1281       result = *mutex;
1282       if (!result)
1283         {
1284           result = g_mutex_new ();
1285           g_atomic_pointer_set (mutex, result);
1286         }
1287
1288       g_mutex_unlock (&g_once_mutex);
1289     }
1290
1291   return result;
1292 }
1293
1294 /* IMPLEMENTATION NOTE:
1295  *
1296  * g_static_mutex_lock(), g_static_mutex_trylock() and
1297  * g_static_mutex_unlock() are all preprocessor macros that wrap the
1298  * corresponding g_mutex_*() function around a call to
1299  * g_static_mutex_get_mutex().
1300  */
1301
1302 /**
1303  * g_static_mutex_lock:
1304  * @mutex: a #GStaticMutex.
1305  *
1306  * Works like g_mutex_lock(), but for a #GStaticMutex.
1307  **/
1308
1309 /**
1310  * g_static_mutex_trylock:
1311  * @mutex: a #GStaticMutex.
1312  * @Returns: %TRUE, if the #GStaticMutex could be locked.
1313  *
1314  * Works like g_mutex_trylock(), but for a #GStaticMutex.
1315  **/
1316
1317 /**
1318  * g_static_mutex_unlock:
1319  * @mutex: a #GStaticMutex.
1320  *
1321  * Works like g_mutex_unlock(), but for a #GStaticMutex.
1322  **/
1323
1324 /**
1325  * g_static_mutex_free:
1326  * @mutex: a #GStaticMutex to be freed.
1327  *
1328  * Releases all resources allocated to @mutex.
1329  *
1330  * You don't have to call this functions for a #GStaticMutex with an
1331  * unbounded lifetime, i.e. objects declared 'static', but if you have
1332  * a #GStaticMutex as a member of a structure and the structure is
1333  * freed, you should also free the #GStaticMutex.
1334  *
1335  * <note><para>Calling g_static_mutex_free() on a locked mutex may
1336  * result in undefined behaviour.</para></note>
1337  **/
1338 void
1339 g_static_mutex_free (GStaticMutex* mutex)
1340 {
1341   GMutex **runtime_mutex;
1342
1343   g_return_if_fail (mutex);
1344
1345   /* The runtime_mutex is the first (or only) member of GStaticMutex,
1346    * see both versions (of glibconfig.h) in configure.ac. Note, that
1347    * this variable is NULL, if g_thread_init() hasn't been called or
1348    * if we're using the default thread implementation and it provides
1349    * static mutexes. */
1350   runtime_mutex = ((GMutex**)mutex);
1351
1352   if (*runtime_mutex)
1353     g_mutex_free (*runtime_mutex);
1354
1355   *runtime_mutex = NULL;
1356 }
1357
1358 /* ------------------------------------------------------------------------ */
1359
1360 /**
1361  * GStaticRecMutex:
1362  *
1363  * A #GStaticRecMutex works like a #GStaticMutex, but it can be locked
1364  * multiple times by one thread. If you enter it n times, you have to
1365  * unlock it n times again to let other threads lock it. An exception
1366  * is the function g_static_rec_mutex_unlock_full(): that allows you to
1367  * unlock a #GStaticRecMutex completely returning the depth, (i.e. the
1368  * number of times this mutex was locked). The depth can later be used
1369  * to restore the state of the #GStaticRecMutex by calling
1370  * g_static_rec_mutex_lock_full().
1371  *
1372  * Even though #GStaticRecMutex is not opaque, it should only be used
1373  * with the following functions.
1374  *
1375  * All of the <function>g_static_rec_mutex_*</function> functions can
1376  * be used even if g_thread_init() has not been called. Then they do
1377  * nothing, apart from <function>g_static_rec_mutex_trylock</function>,
1378  * which does nothing but returning %TRUE.
1379  **/
1380
1381 /**
1382  * G_STATIC_REC_MUTEX_INIT:
1383  *
1384  * A #GStaticRecMutex must be initialized with this macro before it can
1385  * be used. This macro can used be to initialize a variable, but it
1386  * cannot be assigned to a variable. In that case you have to use
1387  * g_static_rec_mutex_init().
1388  *
1389  * <informalexample>
1390  *  <programlisting>
1391  *   GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
1392  * </programlisting>
1393  </informalexample>
1394  **/
1395
1396 /**
1397  * g_static_rec_mutex_init:
1398  * @mutex: a #GStaticRecMutex to be initialized.
1399  *
1400  * A #GStaticRecMutex must be initialized with this function before it
1401  * can be used. Alternatively you can initialize it with
1402  * #G_STATIC_REC_MUTEX_INIT.
1403  **/
1404 void
1405 g_static_rec_mutex_init (GStaticRecMutex *mutex)
1406 {
1407   static const GStaticRecMutex init_mutex = G_STATIC_REC_MUTEX_INIT;
1408
1409   g_return_if_fail (mutex);
1410
1411   *mutex = init_mutex;
1412 }
1413
1414 /**
1415  * g_static_rec_mutex_lock:
1416  * @mutex: a #GStaticRecMutex to lock.
1417  *
1418  * Locks @mutex. If @mutex is already locked by another thread, the
1419  * current thread will block until @mutex is unlocked by the other
1420  * thread. If @mutex is already locked by the calling thread, this
1421  * functions increases the depth of @mutex and returns immediately.
1422  **/
1423 void
1424 g_static_rec_mutex_lock (GStaticRecMutex* mutex)
1425 {
1426   GSystemThread self;
1427
1428   g_return_if_fail (mutex);
1429
1430   if (!g_thread_supported ())
1431     return;
1432
1433   G_THREAD_UF (thread_self, (&self));
1434
1435   if (g_system_thread_equal (self, mutex->owner))
1436     {
1437       mutex->depth++;
1438       return;
1439     }
1440   g_static_mutex_lock (&mutex->mutex);
1441   g_system_thread_assign (mutex->owner, self);
1442   mutex->depth = 1;
1443 }
1444
1445 /**
1446  * g_static_rec_mutex_trylock:
1447  * @mutex: a #GStaticRecMutex to lock.
1448  * @Returns: %TRUE, if @mutex could be locked.
1449  *
1450  * Tries to lock @mutex. If @mutex is already locked by another thread,
1451  * it immediately returns %FALSE. Otherwise it locks @mutex and returns
1452  * %TRUE. If @mutex is already locked by the calling thread, this
1453  * functions increases the depth of @mutex and immediately returns
1454  * %TRUE.
1455  **/
1456 gboolean
1457 g_static_rec_mutex_trylock (GStaticRecMutex* mutex)
1458 {
1459   GSystemThread self;
1460
1461   g_return_val_if_fail (mutex, FALSE);
1462
1463   if (!g_thread_supported ())
1464     return TRUE;
1465
1466   G_THREAD_UF (thread_self, (&self));
1467
1468   if (g_system_thread_equal (self, mutex->owner))
1469     {
1470       mutex->depth++;
1471       return TRUE;
1472     }
1473
1474   if (!g_static_mutex_trylock (&mutex->mutex))
1475     return FALSE;
1476
1477   g_system_thread_assign (mutex->owner, self);
1478   mutex->depth = 1;
1479   return TRUE;
1480 }
1481
1482 /**
1483  * g_static_rec_mutex_unlock:
1484  * @mutex: a #GStaticRecMutex to unlock.
1485  *
1486  * Unlocks @mutex. Another thread will be allowed to lock @mutex only
1487  * when it has been unlocked as many times as it had been locked
1488  * before. If @mutex is completely unlocked and another thread is
1489  * blocked in a g_static_rec_mutex_lock() call for @mutex, it will be
1490  * woken and can lock @mutex itself.
1491  **/
1492 void
1493 g_static_rec_mutex_unlock (GStaticRecMutex* mutex)
1494 {
1495   g_return_if_fail (mutex);
1496
1497   if (!g_thread_supported ())
1498     return;
1499
1500   if (mutex->depth > 1)
1501     {
1502       mutex->depth--;
1503       return;
1504     }
1505   g_system_thread_assign (mutex->owner, zero_thread);
1506   g_static_mutex_unlock (&mutex->mutex);
1507 }
1508
1509 /**
1510  * g_static_rec_mutex_lock_full:
1511  * @mutex: a #GStaticRecMutex to lock.
1512  * @depth: number of times this mutex has to be unlocked to be
1513  *         completely unlocked.
1514  *
1515  * Works like calling g_static_rec_mutex_lock() for @mutex @depth times.
1516  **/
1517 void
1518 g_static_rec_mutex_lock_full   (GStaticRecMutex *mutex,
1519                                 guint            depth)
1520 {
1521   GSystemThread self;
1522   g_return_if_fail (mutex);
1523
1524   if (!g_thread_supported ())
1525     return;
1526
1527   if (depth == 0)
1528     return;
1529
1530   G_THREAD_UF (thread_self, (&self));
1531
1532   if (g_system_thread_equal (self, mutex->owner))
1533     {
1534       mutex->depth += depth;
1535       return;
1536     }
1537   g_static_mutex_lock (&mutex->mutex);
1538   g_system_thread_assign (mutex->owner, self);
1539   mutex->depth = depth;
1540 }
1541
1542 /**
1543  * g_static_rec_mutex_unlock_full:
1544  * @mutex: a #GStaticRecMutex to completely unlock.
1545  * @Returns: number of times @mutex has been locked by the current
1546  *           thread.
1547  *
1548  * Completely unlocks @mutex. If another thread is blocked in a
1549  * g_static_rec_mutex_lock() call for @mutex, it will be woken and can
1550  * lock @mutex itself. This function returns the number of times that
1551  * @mutex has been locked by the current thread. To restore the state
1552  * before the call to g_static_rec_mutex_unlock_full() you can call
1553  * g_static_rec_mutex_lock_full() with the depth returned by this
1554  * function.
1555  **/
1556 guint
1557 g_static_rec_mutex_unlock_full (GStaticRecMutex *mutex)
1558 {
1559   guint depth;
1560
1561   g_return_val_if_fail (mutex, 0);
1562
1563   if (!g_thread_supported ())
1564     return 1;
1565
1566   depth = mutex->depth;
1567
1568   g_system_thread_assign (mutex->owner, zero_thread);
1569   mutex->depth = 0;
1570   g_static_mutex_unlock (&mutex->mutex);
1571
1572   return depth;
1573 }
1574
1575 /**
1576  * g_static_rec_mutex_free:
1577  * @mutex: a #GStaticRecMutex to be freed.
1578  *
1579  * Releases all resources allocated to a #GStaticRecMutex.
1580  *
1581  * You don't have to call this functions for a #GStaticRecMutex with an
1582  * unbounded lifetime, i.e. objects declared 'static', but if you have
1583  * a #GStaticRecMutex as a member of a structure and the structure is
1584  * freed, you should also free the #GStaticRecMutex.
1585  **/
1586 void
1587 g_static_rec_mutex_free (GStaticRecMutex *mutex)
1588 {
1589   g_return_if_fail (mutex);
1590
1591   g_static_mutex_free (&mutex->mutex);
1592 }
1593
1594 /* GStaticPrivate {{{1 ---------------------------------------------------- */
1595
1596 /**
1597  * GStaticPrivate:
1598  *
1599  * A #GStaticPrivate works almost like a #GPrivate, but it has one
1600  * significant advantage. It doesn't need to be created at run-time
1601  * like a #GPrivate, but can be defined at compile-time. This is
1602  * similar to the difference between #GMutex and #GStaticMutex. Now
1603  * look at our <function>give_me_next_number()</function> example with
1604  * #GStaticPrivate:
1605  *
1606  * <example>
1607  *  <title>Using GStaticPrivate for per-thread data</title>
1608  *  <programlisting>
1609  *   int
1610  *   give_me_next_number (<!-- -->)
1611  *   {
1612  *     static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
1613  *     int *current_number = g_static_private_get (&amp;current_number_key);
1614  *
1615  *     if (!current_number)
1616  *       {
1617  *         current_number = g_new (int,1);
1618  *         *current_number = 0;
1619  *         g_static_private_set (&amp;current_number_key, current_number, g_free);
1620  *       }
1621  *
1622  *     *current_number = calc_next_number (*current_number);
1623  *
1624  *     return *current_number;
1625  *   }
1626  *  </programlisting>
1627  * </example>
1628  **/
1629
1630 /**
1631  * G_STATIC_PRIVATE_INIT:
1632  *
1633  * Every #GStaticPrivate must be initialized with this macro, before it
1634  * can be used.
1635  *
1636  * <informalexample>
1637  *  <programlisting>
1638  *   GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
1639  *  </programlisting>
1640  * </informalexample>
1641  **/
1642
1643 /**
1644  * g_static_private_init:
1645  * @private_key: a #GStaticPrivate to be initialized.
1646  *
1647  * Initializes @private_key. Alternatively you can initialize it with
1648  * #G_STATIC_PRIVATE_INIT.
1649  **/
1650 void
1651 g_static_private_init (GStaticPrivate *private_key)
1652 {
1653   private_key->index = 0;
1654 }
1655
1656 /**
1657  * g_static_private_get:
1658  * @private_key: a #GStaticPrivate.
1659  * @Returns: the corresponding pointer.
1660  *
1661  * Works like g_private_get() only for a #GStaticPrivate.
1662  *
1663  * This function works even if g_thread_init() has not yet been called.
1664  **/
1665 gpointer
1666 g_static_private_get (GStaticPrivate *private_key)
1667 {
1668   GRealThread *self = (GRealThread*) g_thread_self ();
1669   GArray *array;
1670   gpointer ret = NULL;
1671
1672   LOCK_PRIVATE_DATA (self);
1673
1674   array = self->private_data;
1675
1676   if (array && private_key->index != 0 && private_key->index <= array->len)
1677     ret = g_array_index (array, GStaticPrivateNode,
1678                          private_key->index - 1).data;
1679
1680   UNLOCK_PRIVATE_DATA (self);
1681   return ret;
1682 }
1683
1684 /**
1685  * g_static_private_set:
1686  * @private_key: a #GStaticPrivate.
1687  * @data: the new pointer.
1688  * @notify: a function to be called with the pointer whenever the
1689  *          current thread ends or sets this pointer again.
1690  *
1691  * Sets the pointer keyed to @private_key for the current thread and
1692  * the function @notify to be called with that pointer (%NULL or
1693  * non-%NULL), whenever the pointer is set again or whenever the
1694  * current thread ends.
1695  *
1696  * This function works even if g_thread_init() has not yet been called.
1697  * If g_thread_init() is called later, the @data keyed to @private_key
1698  * will be inherited only by the main thread, i.e. the one that called
1699  * g_thread_init().
1700  *
1701  * <note><para>@notify is used quite differently from @destructor in
1702  * g_private_new().</para></note>
1703  **/
1704 void
1705 g_static_private_set (GStaticPrivate *private_key,
1706                       gpointer        data,
1707                       GDestroyNotify  notify)
1708 {
1709   GRealThread *self = (GRealThread*) g_thread_self ();
1710   GArray *array;
1711   static guint next_index = 0;
1712   GStaticPrivateNode *node;
1713   gpointer ddata = NULL;
1714   GDestroyNotify ddestroy = NULL;
1715
1716   if (!private_key->index)
1717     {
1718       G_LOCK (g_thread);
1719
1720       if (!private_key->index)
1721         {
1722           if (g_thread_free_indices)
1723             {
1724               private_key->index =
1725                 GPOINTER_TO_UINT (g_thread_free_indices->data);
1726               g_thread_free_indices =
1727                 g_slist_delete_link (g_thread_free_indices,
1728                                      g_thread_free_indices);
1729             }
1730           else
1731             private_key->index = ++next_index;
1732         }
1733
1734       G_UNLOCK (g_thread);
1735     }
1736
1737   LOCK_PRIVATE_DATA (self);
1738
1739   array = self->private_data;
1740   if (!array)
1741     {
1742       array = g_array_new (FALSE, TRUE, sizeof (GStaticPrivateNode));
1743       self->private_data = array;
1744     }
1745
1746   if (private_key->index > array->len)
1747     g_array_set_size (array, private_key->index);
1748
1749   node = &g_array_index (array, GStaticPrivateNode, private_key->index - 1);
1750
1751   ddata = node->data;
1752   ddestroy = node->destroy;
1753
1754   node->data = data;
1755   node->destroy = notify;
1756
1757   UNLOCK_PRIVATE_DATA (self);
1758
1759   if (ddestroy)
1760     ddestroy (ddata);
1761 }
1762
1763 /**
1764  * g_static_private_free:
1765  * @private_key: a #GStaticPrivate to be freed.
1766  *
1767  * Releases all resources allocated to @private_key.
1768  *
1769  * You don't have to call this functions for a #GStaticPrivate with an
1770  * unbounded lifetime, i.e. objects declared 'static', but if you have
1771  * a #GStaticPrivate as a member of a structure and the structure is
1772  * freed, you should also free the #GStaticPrivate.
1773  **/
1774 void
1775 g_static_private_free (GStaticPrivate *private_key)
1776 {
1777   guint idx = private_key->index;
1778   GRealThread *thread, *next;
1779   GArray *garbage = NULL;
1780
1781   if (!idx)
1782     return;
1783
1784   private_key->index = 0;
1785
1786   G_LOCK (g_thread);
1787
1788   thread = g_thread_all_threads;
1789
1790   for (thread = g_thread_all_threads; thread; thread = next)
1791     {
1792       GArray *array;
1793
1794       next = thread->next;
1795
1796       LOCK_PRIVATE_DATA (thread);
1797
1798       array = thread->private_data;
1799
1800       if (array && idx <= array->len)
1801         {
1802           GStaticPrivateNode *node = &g_array_index (array,
1803                                                      GStaticPrivateNode,
1804                                                      idx - 1);
1805           gpointer ddata = node->data;
1806           GDestroyNotify ddestroy = node->destroy;
1807
1808           node->data = NULL;
1809           node->destroy = NULL;
1810
1811           if (ddestroy)
1812             {
1813               /* defer non-trivial destruction til after we've finished
1814                * iterating, since we must continue to hold the lock */
1815               if (garbage == NULL)
1816                 garbage = g_array_new (FALSE, TRUE,
1817                                        sizeof (GStaticPrivateNode));
1818
1819               g_array_set_size (garbage, garbage->len + 1);
1820
1821               node = &g_array_index (garbage, GStaticPrivateNode,
1822                                      garbage->len - 1);
1823               node->data = ddata;
1824               node->destroy = ddestroy;
1825             }
1826         }
1827
1828       UNLOCK_PRIVATE_DATA (thread);
1829     }
1830   g_thread_free_indices = g_slist_prepend (g_thread_free_indices,
1831                                            GUINT_TO_POINTER (idx));
1832   G_UNLOCK (g_thread);
1833
1834   if (garbage)
1835     {
1836       guint i;
1837
1838       for (i = 0; i < garbage->len; i++)
1839         {
1840           GStaticPrivateNode *node;
1841
1842           node = &g_array_index (garbage, GStaticPrivateNode, i);
1843           node->destroy (node->data);
1844         }
1845
1846       g_array_free (garbage, TRUE);
1847     }
1848 }
1849
1850 /* GThread Extra Functions {{{1 ------------------------------------------- */
1851 static void
1852 g_thread_cleanup (gpointer data)
1853 {
1854   if (data)
1855     {
1856       GRealThread* thread = data;
1857       GArray *array;
1858
1859       LOCK_PRIVATE_DATA (thread);
1860       array = thread->private_data;
1861       thread->private_data = NULL;
1862       UNLOCK_PRIVATE_DATA (thread);
1863
1864       if (array)
1865         {
1866           guint i;
1867
1868           for (i = 0; i < array->len; i++ )
1869             {
1870               GStaticPrivateNode *node =
1871                 &g_array_index (array, GStaticPrivateNode, i);
1872               if (node->destroy)
1873                 node->destroy (node->data);
1874             }
1875           g_array_free (array, TRUE);
1876         }
1877
1878       /* We only free the thread structure, if it isn't joinable. If
1879          it is, the structure is freed in g_thread_join */
1880       if (!thread->thread.joinable)
1881         {
1882           GRealThread *t, *p;
1883
1884           G_LOCK (g_thread);
1885           for (t = g_thread_all_threads, p = NULL; t; p = t, t = t->next)
1886             {
1887               if (t == thread)
1888                 {
1889                   if (p)
1890                     p->next = t->next;
1891                   else
1892                     g_thread_all_threads = t->next;
1893                   break;
1894                 }
1895             }
1896           G_UNLOCK (g_thread);
1897
1898           /* Just to make sure, this isn't used any more */
1899           g_system_thread_assign (thread->system_thread, zero_thread);
1900           g_free (thread);
1901         }
1902     }
1903 }
1904
1905 static void
1906 g_thread_fail (void)
1907 {
1908   g_error ("The thread system is not yet initialized.");
1909 }
1910
1911 #define G_NSEC_PER_SEC 1000000000
1912
1913 static guint64
1914 gettime (void)
1915 {
1916   return g_get_monotonic_time () * 1000;
1917 }
1918
1919 static gpointer
1920 g_thread_create_proxy (gpointer data)
1921 {
1922   GRealThread* thread = data;
1923
1924   g_assert (data);
1925
1926   /* This has to happen before G_LOCK, as that might call g_thread_self */
1927   g_private_set (&g_thread_specific_private, data);
1928
1929   /* the lock makes sure, that thread->system_thread is written,
1930      before thread->thread.func is called. See g_thread_create. */
1931   G_LOCK (g_thread);
1932   G_UNLOCK (g_thread);
1933
1934   thread->retval = thread->thread.func (thread->thread.data);
1935
1936   return NULL;
1937 }
1938
1939 /**
1940  * g_thread_create_full:
1941  * @func: a function to execute in the new thread.
1942  * @data: an argument to supply to the new thread.
1943  * @stack_size: a stack size for the new thread.
1944  * @joinable: should this thread be joinable?
1945  * @bound: should this thread be bound to a system thread?
1946  * @priority: a priority for the thread.
1947  * @error: return location for error.
1948  * @Returns: the new #GThread on success.
1949  *
1950  * This function creates a new thread with the priority @priority. If
1951  * the underlying thread implementation supports it, the thread gets a
1952  * stack size of @stack_size or the default value for the current
1953  * platform, if @stack_size is 0.
1954  *
1955  * If @joinable is %TRUE, you can wait for this threads termination
1956  * calling g_thread_join(). Otherwise the thread will just disappear
1957  * when it terminates. If @bound is %TRUE, this thread will be
1958  * scheduled in the system scope, otherwise the implementation is free
1959  * to do scheduling in the process scope. The first variant is more
1960  * expensive resource-wise, but generally faster. On some systems (e.g.
1961  * Linux) all threads are bound.
1962  *
1963  * The new thread executes the function @func with the argument @data.
1964  * If the thread was created successfully, it is returned.
1965  *
1966  * @error can be %NULL to ignore errors, or non-%NULL to report errors.
1967  * The error is set, if and only if the function returns %NULL.
1968  *
1969  * <note><para>It is not guaranteed that threads with different priorities
1970  * really behave accordingly. On some systems (e.g. Linux) there are no
1971  * thread priorities. On other systems (e.g. Solaris) there doesn't
1972  * seem to be different scheduling for different priorities. All in all
1973  * try to avoid being dependent on priorities. Use
1974  * %G_THREAD_PRIORITY_NORMAL here as a default.</para></note>
1975  *
1976  * <note><para>Only use g_thread_create_full() if you really can't use
1977  * g_thread_create() instead. g_thread_create() does not take
1978  * @stack_size, @bound, and @priority as arguments, as they should only
1979  * be used in cases in which it is unavoidable.</para></note>
1980  **/
1981 GThread*
1982 g_thread_create_full (GThreadFunc       func,
1983                       gpointer          data,
1984                       gulong            stack_size,
1985                       gboolean          joinable,
1986                       gboolean          bound,
1987                       GThreadPriority   priority,
1988                       GError          **error)
1989 {
1990   GRealThread* result;
1991   GError *local_error = NULL;
1992   g_return_val_if_fail (func, NULL);
1993   g_return_val_if_fail (priority >= G_THREAD_PRIORITY_LOW, NULL);
1994   g_return_val_if_fail (priority <= G_THREAD_PRIORITY_URGENT, NULL);
1995
1996   result = g_new0 (GRealThread, 1);
1997
1998   result->thread.joinable = joinable;
1999   result->thread.priority = priority;
2000   result->thread.func = func;
2001   result->thread.data = data;
2002   result->private_data = NULL;
2003   G_LOCK (g_thread);
2004   G_THREAD_UF (thread_create, (g_thread_create_proxy, result,
2005                                stack_size, joinable, bound, priority,
2006                                &result->system_thread, &local_error));
2007   if (!local_error)
2008     {
2009       result->next = g_thread_all_threads;
2010       g_thread_all_threads = result;
2011     }
2012   G_UNLOCK (g_thread);
2013
2014   if (local_error)
2015     {
2016       g_propagate_error (error, local_error);
2017       g_free (result);
2018       return NULL;
2019     }
2020
2021   return (GThread*) result;
2022 }
2023
2024 /**
2025  * g_thread_exit:
2026  * @retval: the return value of this thread.
2027  *
2028  * Exits the current thread. If another thread is waiting for that
2029  * thread using g_thread_join() and the current thread is joinable, the
2030  * waiting thread will be woken up and get @retval as the return value
2031  * of g_thread_join(). If the current thread is not joinable, @retval
2032  * is ignored. Calling
2033  *
2034  * <informalexample>
2035  *  <programlisting>
2036  *   g_thread_exit (retval);
2037  *  </programlisting>
2038  * </informalexample>
2039  *
2040  * is equivalent to returning @retval from the function @func, as given
2041  * to g_thread_create().
2042  *
2043  * <note><para>Never call g_thread_exit() from within a thread of a
2044  * #GThreadPool, as that will mess up the bookkeeping and lead to funny
2045  * and unwanted results.</para></note>
2046  **/
2047 void
2048 g_thread_exit (gpointer retval)
2049 {
2050   GRealThread* real = (GRealThread*) g_thread_self ();
2051   real->retval = retval;
2052   G_THREAD_CF (thread_exit, (void)0, ());
2053 }
2054
2055 /**
2056  * g_thread_join:
2057  * @thread: a #GThread to be waited for.
2058  * @Returns: the return value of the thread.
2059  *
2060  * Waits until @thread finishes, i.e. the function @func, as given to
2061  * g_thread_create(), returns or g_thread_exit() is called by @thread.
2062  * All resources of @thread including the #GThread struct are released.
2063  * @thread must have been created with @joinable=%TRUE in
2064  * g_thread_create(). The value returned by @func or given to
2065  * g_thread_exit() by @thread is returned by this function.
2066  **/
2067 gpointer
2068 g_thread_join (GThread* thread)
2069 {
2070   GRealThread* real = (GRealThread*) thread;
2071   GRealThread *p, *t;
2072   gpointer retval;
2073
2074   g_return_val_if_fail (thread, NULL);
2075   g_return_val_if_fail (thread->joinable, NULL);
2076   g_return_val_if_fail (!g_system_thread_equal (real->system_thread,
2077                                                 zero_thread), NULL);
2078
2079   G_THREAD_UF (thread_join, (&real->system_thread));
2080
2081   retval = real->retval;
2082
2083   G_LOCK (g_thread);
2084   for (t = g_thread_all_threads, p = NULL; t; p = t, t = t->next)
2085     {
2086       if (t == (GRealThread*) thread)
2087         {
2088           if (p)
2089             p->next = t->next;
2090           else
2091             g_thread_all_threads = t->next;
2092           break;
2093         }
2094     }
2095   G_UNLOCK (g_thread);
2096
2097   /* Just to make sure, this isn't used any more */
2098   thread->joinable = 0;
2099   g_system_thread_assign (real->system_thread, zero_thread);
2100
2101   /* the thread structure for non-joinable threads is freed upon
2102      thread end. We free the memory here. This will leave a loose end,
2103      if a joinable thread is not joined. */
2104
2105   g_free (thread);
2106
2107   return retval;
2108 }
2109
2110 /**
2111  * g_thread_set_priority:
2112  * @thread: a #GThread.
2113  * @priority: a new priority for @thread.
2114  *
2115  * Changes the priority of @thread to @priority.
2116  *
2117  * <note><para>It is not guaranteed that threads with different
2118  * priorities really behave accordingly. On some systems (e.g. Linux)
2119  * there are no thread priorities. On other systems (e.g. Solaris) there
2120  * doesn't seem to be different scheduling for different priorities. All
2121  * in all try to avoid being dependent on priorities.</para></note>
2122  **/
2123 void
2124 g_thread_set_priority (GThread* thread,
2125                        GThreadPriority priority)
2126 {
2127   GRealThread* real = (GRealThread*) thread;
2128
2129   g_return_if_fail (thread);
2130   g_return_if_fail (!g_system_thread_equal (real->system_thread, zero_thread));
2131   g_return_if_fail (priority >= G_THREAD_PRIORITY_LOW);
2132   g_return_if_fail (priority <= G_THREAD_PRIORITY_URGENT);
2133
2134   thread->priority = priority;
2135
2136   G_THREAD_CF (thread_set_priority, (void)0,
2137                (&real->system_thread, priority));
2138 }
2139
2140 /**
2141  * g_thread_self:
2142  * @Returns: the current thread.
2143  *
2144  * This functions returns the #GThread corresponding to the calling
2145  * thread.
2146  **/
2147 GThread*
2148 g_thread_self (void)
2149 {
2150   GRealThread* thread = g_private_get (&g_thread_specific_private);
2151
2152   if (!thread)
2153     {
2154       /* If no thread data is available, provide and set one.  This
2155          can happen for the main thread and for threads, that are not
2156          created by GLib. */
2157       thread = g_new0 (GRealThread, 1);
2158       thread->thread.joinable = FALSE; /* This is a save guess */
2159       thread->thread.priority = G_THREAD_PRIORITY_NORMAL; /* This is
2160                                                              just a guess */
2161       thread->thread.func = NULL;
2162       thread->thread.data = NULL;
2163       thread->private_data = NULL;
2164
2165       if (g_thread_supported ())
2166         G_THREAD_UF (thread_self, (&thread->system_thread));
2167
2168       g_private_set (&g_thread_specific_private, thread);
2169
2170       G_LOCK (g_thread);
2171       thread->next = g_thread_all_threads;
2172       g_thread_all_threads = thread;
2173       G_UNLOCK (g_thread);
2174     }
2175
2176   return (GThread*)thread;
2177 }
2178
2179 /* GStaticRWLock {{{1 ----------------------------------------------------- */
2180
2181 /**
2182  * GStaticRWLock:
2183  *
2184  * The #GStaticRWLock struct represents a read-write lock. A read-write
2185  * lock can be used for protecting data that some portions of code only
2186  * read from, while others also write. In such situations it is
2187  * desirable that several readers can read at once, whereas of course
2188  * only one writer may write at a time. Take a look at the following
2189  * example:
2190  *
2191  * <example>
2192  *  <title>An array with access functions</title>
2193  *  <programlisting>
2194  *   GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;
2195  *   GPtrArray *array;
2196  *
2197  *   gpointer
2198  *   my_array_get (guint index)
2199  *   {
2200  *     gpointer retval = NULL;
2201  *
2202  *     if (!array)
2203  *       return NULL;
2204  *
2205  *     g_static_rw_lock_reader_lock (&amp;rwlock);
2206  *     if (index &lt; array->len)
2207  *       retval = g_ptr_array_index (array, index);
2208  *     g_static_rw_lock_reader_unlock (&amp;rwlock);
2209  *
2210  *     return retval;
2211  *   }
2212  *
2213  *   void
2214  *   my_array_set (guint index, gpointer data)
2215  *   {
2216  *     g_static_rw_lock_writer_lock (&amp;rwlock);
2217  *
2218  *     if (!array)
2219  *       array = g_ptr_array_new (<!-- -->);
2220  *
2221  *     if (index >= array->len)
2222  *       g_ptr_array_set_size (array, index+1);
2223  *     g_ptr_array_index (array, index) = data;
2224  *
2225  *     g_static_rw_lock_writer_unlock (&amp;rwlock);
2226  *   }
2227  *  </programlisting>
2228  * </example>
2229  *
2230  * This example shows an array which can be accessed by many readers
2231  * (the <function>my_array_get()</function> function) simultaneously,
2232  * whereas the writers (the <function>my_array_set()</function>
2233  * function) will only be allowed once at a time and only if no readers
2234  * currently access the array. This is because of the potentially
2235  * dangerous resizing of the array. Using these functions is fully
2236  * multi-thread safe now.
2237  *
2238  * Most of the time, writers should have precedence over readers. That
2239  * means, for this implementation, that as soon as a writer wants to
2240  * lock the data, no other reader is allowed to lock the data, whereas,
2241  * of course, the readers that already have locked the data are allowed
2242  * to finish their operation. As soon as the last reader unlocks the
2243  * data, the writer will lock it.
2244  *
2245  * Even though #GStaticRWLock is not opaque, it should only be used
2246  * with the following functions.
2247  *
2248  * All of the <function>g_static_rw_lock_*</function> functions can be
2249  * used even if g_thread_init() has not been called. Then they do
2250  * nothing, apart from <function>g_static_rw_lock_*_trylock</function>,
2251  * which does nothing but returning %TRUE.
2252  *
2253  * <note><para>A read-write lock has a higher overhead than a mutex. For
2254  * example, both g_static_rw_lock_reader_lock() and
2255  * g_static_rw_lock_reader_unlock() have to lock and unlock a
2256  * #GStaticMutex, so it takes at least twice the time to lock and unlock
2257  * a #GStaticRWLock that it does to lock and unlock a #GStaticMutex. So
2258  * only data structures that are accessed by multiple readers, and which
2259  * keep the lock for a considerable time justify a #GStaticRWLock. The
2260  * above example most probably would fare better with a
2261  * #GStaticMutex.</para></note>
2262  **/
2263
2264 /**
2265  * G_STATIC_RW_LOCK_INIT:
2266  *
2267  * A #GStaticRWLock must be initialized with this macro before it can
2268  * be used. This macro can used be to initialize a variable, but it
2269  * cannot be assigned to a variable. In that case you have to use
2270  * g_static_rw_lock_init().
2271  *
2272  * <informalexample>
2273  *  <programlisting>
2274  *   GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;
2275  *  </programlisting>
2276  * </informalexample>
2277  **/
2278
2279 /**
2280  * g_static_rw_lock_init:
2281  * @lock: a #GStaticRWLock to be initialized.
2282  *
2283  * A #GStaticRWLock must be initialized with this function before it
2284  * can be used. Alternatively you can initialize it with
2285  * #G_STATIC_RW_LOCK_INIT.
2286  **/
2287 void
2288 g_static_rw_lock_init (GStaticRWLock* lock)
2289 {
2290   static const GStaticRWLock init_lock = G_STATIC_RW_LOCK_INIT;
2291
2292   g_return_if_fail (lock);
2293
2294   *lock = init_lock;
2295 }
2296
2297 inline static void
2298 g_static_rw_lock_wait (GCond** cond, GStaticMutex* mutex)
2299 {
2300   if (!*cond)
2301       *cond = g_cond_new ();
2302   g_cond_wait (*cond, g_static_mutex_get_mutex (mutex));
2303 }
2304
2305 inline static void
2306 g_static_rw_lock_signal (GStaticRWLock* lock)
2307 {
2308   if (lock->want_to_write && lock->write_cond)
2309     g_cond_signal (lock->write_cond);
2310   else if (lock->want_to_read && lock->read_cond)
2311     g_cond_broadcast (lock->read_cond);
2312 }
2313
2314 /**
2315  * g_static_rw_lock_reader_lock:
2316  * @lock: a #GStaticRWLock to lock for reading.
2317  *
2318  * Locks @lock for reading. There may be unlimited concurrent locks for
2319  * reading of a #GStaticRWLock at the same time.  If @lock is already
2320  * locked for writing by another thread or if another thread is already
2321  * waiting to lock @lock for writing, this function will block until
2322  * @lock is unlocked by the other writing thread and no other writing
2323  * threads want to lock @lock. This lock has to be unlocked by
2324  * g_static_rw_lock_reader_unlock().
2325  *
2326  * #GStaticRWLock is not recursive. It might seem to be possible to
2327  * recursively lock for reading, but that can result in a deadlock, due
2328  * to writer preference.
2329  **/
2330 void
2331 g_static_rw_lock_reader_lock (GStaticRWLock* lock)
2332 {
2333   g_return_if_fail (lock);
2334
2335   if (!g_threads_got_initialized)
2336     return;
2337
2338   g_static_mutex_lock (&lock->mutex);
2339   lock->want_to_read++;
2340   while (lock->have_writer || lock->want_to_write)
2341     g_static_rw_lock_wait (&lock->read_cond, &lock->mutex);
2342   lock->want_to_read--;
2343   lock->read_counter++;
2344   g_static_mutex_unlock (&lock->mutex);
2345 }
2346
2347 /**
2348  * g_static_rw_lock_reader_trylock:
2349  * @lock: a #GStaticRWLock to lock for reading.
2350  * @Returns: %TRUE, if @lock could be locked for reading.
2351  *
2352  * Tries to lock @lock for reading. If @lock is already locked for
2353  * writing by another thread or if another thread is already waiting to
2354  * lock @lock for writing, immediately returns %FALSE. Otherwise locks
2355  * @lock for reading and returns %TRUE. This lock has to be unlocked by
2356  * g_static_rw_lock_reader_unlock().
2357  **/
2358 gboolean
2359 g_static_rw_lock_reader_trylock (GStaticRWLock* lock)
2360 {
2361   gboolean ret_val = FALSE;
2362
2363   g_return_val_if_fail (lock, FALSE);
2364
2365   if (!g_threads_got_initialized)
2366     return TRUE;
2367
2368   g_static_mutex_lock (&lock->mutex);
2369   if (!lock->have_writer && !lock->want_to_write)
2370     {
2371       lock->read_counter++;
2372       ret_val = TRUE;
2373     }
2374   g_static_mutex_unlock (&lock->mutex);
2375   return ret_val;
2376 }
2377
2378 /**
2379  * g_static_rw_lock_reader_unlock:
2380  * @lock: a #GStaticRWLock to unlock after reading.
2381  *
2382  * Unlocks @lock. If a thread waits to lock @lock for writing and all
2383  * locks for reading have been unlocked, the waiting thread is woken up
2384  * and can lock @lock for writing.
2385  **/
2386 void
2387 g_static_rw_lock_reader_unlock  (GStaticRWLock* lock)
2388 {
2389   g_return_if_fail (lock);
2390
2391   if (!g_threads_got_initialized)
2392     return;
2393
2394   g_static_mutex_lock (&lock->mutex);
2395   lock->read_counter--;
2396   if (lock->read_counter == 0)
2397     g_static_rw_lock_signal (lock);
2398   g_static_mutex_unlock (&lock->mutex);
2399 }
2400
2401 /**
2402  * g_static_rw_lock_writer_lock:
2403  * @lock: a #GStaticRWLock to lock for writing.
2404  *
2405  * Locks @lock for writing. If @lock is already locked for writing or
2406  * reading by other threads, this function will block until @lock is
2407  * completely unlocked and then lock @lock for writing. While this
2408  * functions waits to lock @lock, no other thread can lock @lock for
2409  * reading. When @lock is locked for writing, no other thread can lock
2410  * @lock (neither for reading nor writing). This lock has to be
2411  * unlocked by g_static_rw_lock_writer_unlock().
2412  **/
2413 void
2414 g_static_rw_lock_writer_lock (GStaticRWLock* lock)
2415 {
2416   g_return_if_fail (lock);
2417
2418   if (!g_threads_got_initialized)
2419     return;
2420
2421   g_static_mutex_lock (&lock->mutex);
2422   lock->want_to_write++;
2423   while (lock->have_writer || lock->read_counter)
2424     g_static_rw_lock_wait (&lock->write_cond, &lock->mutex);
2425   lock->want_to_write--;
2426   lock->have_writer = TRUE;
2427   g_static_mutex_unlock (&lock->mutex);
2428 }
2429
2430 /**
2431  * g_static_rw_lock_writer_trylock:
2432  * @lock: a #GStaticRWLock to lock for writing.
2433  * @Returns: %TRUE, if @lock could be locked for writing.
2434  *
2435  * Tries to lock @lock for writing. If @lock is already locked (for
2436  * either reading or writing) by another thread, it immediately returns
2437  * %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This
2438  * lock has to be unlocked by g_static_rw_lock_writer_unlock().
2439  **/
2440 gboolean
2441 g_static_rw_lock_writer_trylock (GStaticRWLock* lock)
2442 {
2443   gboolean ret_val = FALSE;
2444
2445   g_return_val_if_fail (lock, FALSE);
2446
2447   if (!g_threads_got_initialized)
2448     return TRUE;
2449
2450   g_static_mutex_lock (&lock->mutex);
2451   if (!lock->have_writer && !lock->read_counter)
2452     {
2453       lock->have_writer = TRUE;
2454       ret_val = TRUE;
2455     }
2456   g_static_mutex_unlock (&lock->mutex);
2457   return ret_val;
2458 }
2459
2460 /**
2461  * g_static_rw_lock_writer_unlock:
2462  * @lock: a #GStaticRWLock to unlock after writing.
2463  *
2464  * Unlocks @lock. If a thread is waiting to lock @lock for writing and
2465  * all locks for reading have been unlocked, the waiting thread is
2466  * woken up and can lock @lock for writing. If no thread is waiting to
2467  * lock @lock for writing, and some thread or threads are waiting to
2468  * lock @lock for reading, the waiting threads are woken up and can
2469  * lock @lock for reading.
2470  **/
2471 void
2472 g_static_rw_lock_writer_unlock (GStaticRWLock* lock)
2473 {
2474   g_return_if_fail (lock);
2475
2476   if (!g_threads_got_initialized)
2477     return;
2478
2479   g_static_mutex_lock (&lock->mutex);
2480   lock->have_writer = FALSE;
2481   g_static_rw_lock_signal (lock);
2482   g_static_mutex_unlock (&lock->mutex);
2483 }
2484
2485 /**
2486  * g_static_rw_lock_free:
2487  * @lock: a #GStaticRWLock to be freed.
2488  *
2489  * Releases all resources allocated to @lock.
2490  *
2491  * You don't have to call this functions for a #GStaticRWLock with an
2492  * unbounded lifetime, i.e. objects declared 'static', but if you have
2493  * a #GStaticRWLock as a member of a structure, and the structure is
2494  * freed, you should also free the #GStaticRWLock.
2495  **/
2496 void
2497 g_static_rw_lock_free (GStaticRWLock* lock)
2498 {
2499   g_return_if_fail (lock);
2500
2501   if (lock->read_cond)
2502     {
2503       g_cond_free (lock->read_cond);
2504       lock->read_cond = NULL;
2505     }
2506   if (lock->write_cond)
2507     {
2508       g_cond_free (lock->write_cond);
2509       lock->write_cond = NULL;
2510     }
2511   g_static_mutex_free (&lock->mutex);
2512 }
2513
2514 /* Unsorted {{{1 ---------------------------------------------------------- */
2515
2516 /**
2517  * g_thread_foreach
2518  * @thread_func: function to call for all GThread structures
2519  * @user_data:   second argument to @thread_func
2520  *
2521  * Call @thread_func on all existing #GThread structures. Note that
2522  * threads may decide to exit while @thread_func is running, so
2523  * without intimate knowledge about the lifetime of foreign threads,
2524  * @thread_func shouldn't access the GThread* pointer passed in as
2525  * first argument. However, @thread_func will not be called for threads
2526  * which are known to have exited already.
2527  *
2528  * Due to thread lifetime checks, this function has an execution complexity
2529  * which is quadratic in the number of existing threads.
2530  *
2531  * Since: 2.10
2532  */
2533 void
2534 g_thread_foreach (GFunc    thread_func,
2535                   gpointer user_data)
2536 {
2537   GSList *slist = NULL;
2538   GRealThread *thread;
2539   g_return_if_fail (thread_func != NULL);
2540   /* snapshot the list of threads for iteration */
2541   G_LOCK (g_thread);
2542   for (thread = g_thread_all_threads; thread; thread = thread->next)
2543     slist = g_slist_prepend (slist, thread);
2544   G_UNLOCK (g_thread);
2545   /* walk the list, skipping non-existent threads */
2546   while (slist)
2547     {
2548       GSList *node = slist;
2549       slist = node->next;
2550       /* check whether the current thread still exists */
2551       G_LOCK (g_thread);
2552       for (thread = g_thread_all_threads; thread; thread = thread->next)
2553         if (thread == node->data)
2554           break;
2555       G_UNLOCK (g_thread);
2556       if (thread)
2557         thread_func (thread, user_data);
2558       g_slist_free_1 (node);
2559     }
2560 }
2561
2562 /**
2563  * g_thread_get_initialized
2564  *
2565  * Indicates if g_thread_init() has been called.
2566  *
2567  * Returns: %TRUE if threads have been initialized.
2568  *
2569  * Since: 2.20
2570  */
2571 gboolean
2572 g_thread_get_initialized ()
2573 {
2574   return g_thread_supported ();
2575 }
2576
2577 GMutex *
2578 g_mutex_new (void)
2579 {
2580   GMutex *mutex;
2581
2582   mutex = g_slice_new (GMutex);
2583   g_mutex_init (mutex);
2584
2585   return mutex;
2586 }
2587
2588 void
2589 g_mutex_free (GMutex *mutex)
2590 {
2591   g_mutex_clear (mutex);
2592   g_slice_free (GMutex, mutex);
2593 }
2594
2595 GCond *
2596 g_cond_new (void)
2597 {
2598   GCond *cond;
2599
2600   cond = g_slice_new (GCond);
2601   g_cond_init (cond);
2602
2603   return cond;
2604 }
2605
2606 void
2607 g_cond_free (GCond *cond)
2608 {
2609   g_cond_clear (cond);
2610   g_slice_free (GCond, cond);
2611 }