<!-- ##### SECTION Title ##### -->Threads<!-- ##### SECTION Short_Description ##### -->thread abstraction; including threads, different mutexes, conditionsand thread private data.<!-- ##### SECTION Long_Description ##### --><para>Threads act almost like processes, but unlike processes all threads ofone process share the same memory. This is good, as it provides easycommunication between the involved threads via this shared memory, andit is bad, because strange things (so called "Heisenbugs") mighthappen if the program is not carefully designed. In particular, due tothe concurrent nature of threads, no assumptions on the order ofexecution of code running in different threads can be made, unlessorder is explicitly forced by the programmer through synchronizationprimitives.</para><para>The aim of the thread related functions in GLib is to provide aportable means for writing multi-threaded software. There areprimitives for mutexes to protect the access to portions of memory(#GMutex, #GStaticMutex, #G_LOCK_DEFINE, #GStaticRecMutex and#GStaticRWLock). There are primitives for condition variables to allowsynchronization of threads (#GCond).  There are primitivesfor thread-private data - data that every thread has a private instance of(#GPrivate, #GStaticPrivate). Last but definitely not least there areprimitives to portably create and manage threads (#GThread).</para><para>You must call g_thread_init() before executing any other GLibfunctions in a threaded GLib program. After that, GLib is completelythread safe (all global data is automatically locked), but individualdata structure instances are not automatically locked for performancereasons. So, for example you must coordinate accesses to the same#GHashTable from multiple threads.  The two notable exceptions fromthis rule are #GMainLoop and #GAsyncQueue,which <emphasis>are</emphasis> threadsafe and needs no furtherapplication-level locking to be accessed from multiple threads.</para><!-- ##### SECTION See_Also ##### --><para><variablelist><varlistentry><term>#GThreadPool</term><listitem><para>Thread pools.</para></listitem></varlistentry><varlistentry><term>#GAsyncQueue</term><listitem><para>Send asynchronous messages between threads.</para></listitem></varlistentry></variablelist></para><!-- ##### SECTION Stability_Level ##### --><!-- ##### MACRO G_THREADS_ENABLED ##### --><para>This macro is defined if GLib was compiled with thread support. Thisdoes not necessarily mean that there is a thread implementationavailable, but it does mean that the infrastructure is in place andthat once you provide a thread implementation to g_thread_init(), GLibwill be multi-thread safe. If #G_THREADS_ENABLED is not defined, thenGlib is not, and cannot be, multi-thread safe.</para><!-- ##### MACRO G_THREADS_IMPL_POSIX ##### --><para>This macro is defined if POSIX style threads are used.</para><!-- ##### MACRO G_THREADS_IMPL_NONE ##### --><para>This macro is defined if no thread implementation is used. You can,however, provide one to g_thread_init() to make GLib multi-thread safe.</para><!-- ##### MACRO G_THREAD_ERROR ##### --><para>The error domain of the GLib thread subsystem.</para><!-- ##### ENUM GThreadError ##### --><para>Possible errors of thread related functions.</para>@G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resourceshortage. Try again later.<!-- ##### STRUCT GThreadFunctions ##### --><para>This function table is used by g_thread_init() to initialize thethread system. The functions in the table are directly used by theirg_* prepended counterparts (described in this document).  For example,if you call g_mutex_new() then mutex_new() from the table provided tog_thread_init() will be called.</para><note><para>Do not use this struct unless you know what you are doing.</para></note>@mutex_new: @mutex_lock: @mutex_trylock: @mutex_unlock: @mutex_free: @cond_new: @cond_signal: @cond_broadcast: @cond_wait: @cond_timed_wait: @cond_free: @private_new: @private_get: @private_set: @thread_create: @thread_yield: @thread_join: @thread_exit: @thread_set_priority: @thread_self: @thread_equal: <!-- ##### FUNCTION g_thread_init ##### --><para>If you use GLib from more than one thread, you must initializethe thread system by calling g_thread_init(). Most of the time you will only have to call <literal>g_thread_init (NULL)</literal>. </para><note><para>Do not call g_thread_init() with a non-%NULL parameter unless youreally know what you are doing.</para></note><note><para>g_thread_init() must not be called directly or indirectly as acallback from GLib. Also no mutexes may be currently locked whilecalling g_thread_init().</para></note><para>g_thread_init() might only be called once. On the second callit will abort with an error. If you want to make sure that the threadsystem is initialized, you can do this:</para><para><informalexample><programlisting>if (!g_thread_supported (<!-- -->)) g_thread_init (NULL);</programlisting></informalexample></para><para>After that line, either the thread system is initialized or, if nothread system is available in GLib (i.e. either #G_THREADS_ENABLED isnot defined or #G_THREADS_IMPL_NONE is defined), the program willabort.</para><para>If no thread system is available and @vtable is %NULL or if not allelements of @vtable are non-%NULL, then g_thread_init() will abort.</para><note><para>To use g_thread_init() in your program, you have to link with thelibraries that the command <command>pkg-config --libs gthread-2.0</command> outputs. This is not the case for all the other thread related functions ofGLib. Those can be used without having to link with the thread libraries.</para></note>@vtable: a function table of type #GThreadFunctions, that provides theentry points to the thread system to be used.<!-- ##### FUNCTION g_thread_supported ##### --><para>This function returns %TRUE if the thread system is initialized, and%FALSE if it is not.</para><note><para>This function is actually a macro. Apart from taking the address of ityou can however use it as if it was a function.</para></note>@Returns: %TRUE, if the thread system is initialized.<!-- ##### USER_FUNCTION GThreadFunc ##### --><para>Specifies the type of the @func functions passed tog_thread_create() or g_thread_create_full().</para>@data: data passed to the thread.@Returns: the return value of the thread, which will be returned byg_thread_join().<!-- ##### ENUM GThreadPriority ##### --><para>Specifies the priority of a thread. </para><note><para>It is not guaranteed that threads with different priorities reallybehave accordingly. On some systems (e.g. Linux) there are no threadpriorities. On other systems (e.g. Solaris) there doesn't seem to bedifferent scheduling for different priorities. All in all try to avoidbeing dependent on priorities.</para></note>@G_THREAD_PRIORITY_LOW: a priority lower than normal@G_THREAD_PRIORITY_NORMAL: the default priority@G_THREAD_PRIORITY_HIGH: a priority higher than normal@G_THREAD_PRIORITY_URGENT: the highest priority<!-- ##### STRUCT GThread ##### --><para>The #GThread struct represents a running thread. It has three publicread-only members, but the underlying struct is bigger, so you mustnot copy this struct.</para><note><para>Resources for a joinable thread are not fully released untilg_thread_join() is called for that thread.</para></note><!-- ##### FUNCTION g_thread_create ##### --><para>This function creates a new thread with the default priority.</para><para>If @joinable is %TRUE, you can wait for this threads terminationcalling g_thread_join(). Otherwise the thread will just disappear whenit terminates. </para><para>The new thread executes the function @func with the argument@data. If the thread was created successfully, it is returned.</para><para>@error can be %NULL to ignore errors, or non-%NULL to report errors. Theerror is set, if and only if the function returns %NULL.</para>@func: a function to execute in the new thread.@data: an argument to supply to the new thread.@joinable: should this thread be joinable?@error: return location for error.@Returns: the new #GThread on success.<!-- ##### FUNCTION g_thread_create_full ##### --><para>This function creates a new thread with the priority @priority. If theunderlying thread implementation supports it, the thread gets a stacksize of @stack_size or the default value for the current platform, if@stack_size is 0.</para><para>If @joinable is %TRUE, you can wait for this threads terminationcalling g_thread_join(). Otherwise the thread will just disappear whenit terminates. If @bound is %TRUE, this thread will be scheduled inthe system scope, otherwise the implementation is free to doscheduling in the process scope. The first variant is more expensiveresource-wise, but generally faster. On some systems (e.g. Linux) allthreads are bound.</para><para>The new thread executes the function @func with the argument@data. If the thread was created successfully, it is returned.</para><para>@error can be %NULL to ignore errors, or non-%NULL to report errors. Theerror is set, if and only if the function returns %NULL.</para><note><para>It is not guaranteed that threads with different priorities reallybehave accordingly. On some systems (e.g. Linux) there are no threadpriorities. On other systems (e.g. Solaris) there doesn't seem to bedifferent scheduling for different priorities. All in all try to avoidbeing dependent on priorities. Use %G_THREAD_PRIORITY_NORMAL here as adefault.</para></note><note><para>Only use g_thread_create_full() if you really can't useg_thread_create() instead. g_thread_create() does not take@stack_size, @bound, and @priority as arguments, as they should onlybe used in cases in which it is unavoidable.</para></note>@func: a function to execute in the new thread.@data: an argument to supply to the new thread.@stack_size: a stack size for the new thread.@joinable: should this thread be joinable?@bound: should this thread be bound to a system thread?@priority: a priority for the thread.@error: return location for error.@Returns: the new #GThread on success.<!-- ##### FUNCTION g_thread_self ##### --><para>This functions returns the #GThread corresponding to the calling thread.</para>@Returns: the current thread.<!-- ##### FUNCTION g_thread_join ##### --><para>Waits until @thread finishes, i.e. the function @func, as givento g_thread_create(), returns or g_thread_exit() is called by@thread. All resources of @thread including the #GThread struct arereleased. @thread must have been created with @joinable=%TRUE ing_thread_create(). The value returned by @func or given tog_thread_exit() by @thread is returned by this function.</para>@thread: a #GThread to be waited for.@Returns: the return value of the thread.<!-- ##### FUNCTION g_thread_set_priority ##### --><para>Changes the priority of @thread to @priority.</para><note><para>It is not guaranteed that threads with different priorities reallybehave accordingly. On some systems (e.g. Linux) there are no threadpriorities. On other systems (e.g. Solaris) there doesn't seem to bedifferent scheduling for different priorities. All in all try to avoidbeing dependent on priorities.</para></note>@thread: a #GThread.@priority: a new priority for @thread.<!-- ##### FUNCTION g_thread_yield ##### --><para>Gives way to other threads waiting to be scheduled. </para><para>This function is often used as a method to make busy wait lessevil. But in most cases you will encounter, there are better methodsto do that. So in general you shouldn't use this function.</para><!-- ##### FUNCTION g_thread_exit ##### --><para>Exits the current thread. If another thread is waiting for that threadusing g_thread_join() and the current thread is joinable, the waitingthread will be woken up and get @retval as the return value ofg_thread_join(). If the current thread is not joinable, @retval isignored. Calling</para><para><informalexample><programlisting>g_thread_exit (retval);</programlisting>