</para>@name: the name of the lock.<!-- ##### MACRO G_LOCK ##### --><para>Works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.</para>@name: the name of the lock.<!-- ##### MACRO G_TRYLOCK ##### --><para>Works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.</para>@name: the name of the lock.@Returns: %TRUE, if the lock could be locked.<!-- ##### MACRO G_UNLOCK ##### --><para>Works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.</para>@name: the name of the lock.<!-- ##### STRUCT GStaticRecMutex ##### --><para>A #GStaticRecMutex works like a #GStaticMutex, but it can be lockedmultiple times by one thread. If you enter it n times, you have tounlock it n times again to let other threads lock it. An exception isthe function g_static_rec_mutex_unlock_full(): that allows you tounlock a #GStaticRecMutex completely returning the depth, (i.e. thenumber of times this mutex was locked). The depth can later be used torestore the state of the #GStaticRecMutex by callingg_static_rec_mutex_lock_full().</para><para>Even though #GStaticRecMutex is not opaque, it should only be used withthe following functions.</para><para>All of the <function>g_static_rec_mutex_*</function> functions canbe used even if g_thread_init() has not been called.</para><!-- ##### MACRO G_STATIC_REC_MUTEX_INIT ##### --><para>A #GStaticRecMutex must be initialized with this macro before it canbe used. This macro can used be to initialize a variable, but itcannot be assigned to a variable. In that case you have to useg_static_rec_mutex_init().</para><para><informalexample><programlisting>GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;</programlisting></informalexample></para><!-- ##### FUNCTION g_static_rec_mutex_init ##### --><para>A #GStaticRecMutex must be initialized with this function before itcan be used. Alternatively you can initialize it with#G_STATIC_REC_MUTEX_INIT.</para>@mutex: a #GStaticRecMutex to be initialized.<!-- ##### FUNCTION g_static_rec_mutex_lock ##### --><para>Locks @mutex. If @mutex is already locked by another thread, thecurrent thread will block until @mutex is unlocked by the otherthread. If @mutex is already locked by the calling thread, thisfunctions increases the depth of @mutex and returns immediately.</para>@mutex: a #GStaticRecMutex to lock.<!-- ##### FUNCTION g_static_rec_mutex_trylock ##### --><para>Tries to lock @mutex. If @mutex is already locked by another thread,it immediately returns %FALSE. Otherwise it locks @mutex and returns%TRUE. If @mutex is already locked by the calling thread, thisfunctions increases the depth of @mutex and immediately  returns %TRUE.</para>@mutex: a #GStaticRecMutex to lock.@Returns: %TRUE, if @mutex could be locked.<!-- ##### FUNCTION g_static_rec_mutex_unlock ##### --><para>Unlocks @mutex. Another thread can will be allowed to lock @mutex onlywhen it has been unlocked as many times as it had been lockedbefore. If @mutex is completely unlocked and another thread is blockedin a g_static_rec_mutex_lock() call for @mutex, it will be woken andcan lock @mutex itself.</para>@mutex: a #GStaticRecMutex to unlock.<!-- ##### FUNCTION g_static_rec_mutex_lock_full ##### --><para>Works like calling g_static_rec_mutex_lock() for @mutex @depth times.</para>@mutex: a #GStaticRecMutex to lock.@depth: number of times this mutex has to be unlocked to be completely unlocked.<!-- ##### FUNCTION g_static_rec_mutex_unlock_full ##### --><para>Completely unlocks @mutex. If another thread is blocked in ag_static_rec_mutex_lock() call for @mutex, it will be woken and canlock @mutex itself. This function returns the number of times that@mutex has been locked by the current thread. To restore the statebefore the call to g_static_rec_mutex_unlock_full() you can callg_static_rec_mutex_lock_full() with the depth returned by thisfunction.</para>@mutex: a #GStaticRecMutex to completely unlock.@Returns: number of times @mutex has been locked by the current thread.<!-- ##### FUNCTION g_static_rec_mutex_free ##### --><para>Releases all resources allocated to a #GStaticRecMutex.</para><para>You don't have to call this functions for a #GStaticRecMutex with anunbounded lifetime, i.e. objects declared 'static', but if you have a#GStaticRecMutex as a member of a structure and the structure isfreed, you should also free the #GStaticRecMutex.</para>@mutex: a #GStaticRecMutex to be freed.<!-- ##### STRUCT GStaticRWLock ##### --><para>The #GStaticRWLock struct represents a read-write lock. A read-writelock can be used for protecting data that some portions of code onlyread from, while others also write. In such situations it isdesirable that several readers can read at once, whereas of courseonly one writer may write at a time. Take a look at the followingexample:<example><title>An array with access functions</title><programlisting>  GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;  GPtrArray *array;  gpointer my_array_get (guint index)  {    gpointer retval = NULL;    if (!array)      return NULL;    g_static_rw_lock_reader_lock (&amp;rwlock);    if (index &lt; array->len)      retval = g_ptr_array_index (array, index);    g_static_rw_lock_reader_unlock (&amp;rwlock);    return retval;  }  void my_array_set (guint index, gpointer data)  {    g_static_rw_lock_writer_lock (&amp;rwlock);    if (!array)      array = g_ptr_array_new (<!-- -->);    if (index >= array->len)      g_ptr_array_set_size (array, index+1);    g_ptr_array_index (array, index) = data;     g_static_rw_lock_writer_unlock (&amp;rwlock);  }</programlisting></example></para><para>This example shows an array which can be accessed by many readers(the <function>my_array_get()</function> function) simultaneously, whereas the writers (the <function>my_array_set()</function> function) will only be allowed once at a time and only if no readers currently access the array. This is because of the potentially dangerous resizing of the array. Using these functions is fully multi-thread safe now. </para><para>Most of the time, writers should have precedence over readers. Thatmeans, for this implementation, that as soon as a writer wants to lockthe data, no other reader is allowed to lock the data, whereas, ofcourse, the readers that already have locked the data are allowed tofinish their operation. As soon as the last reader unlocks the data,the writer will lock it.</para><para>Even though #GStaticRWLock is not opaque, it should only be used withthe following functions.</para><para>All of the <function>g_static_rw_lock_*</function> functions can be used even if g_thread_init() has not been called.</para><note><para>A read-write lock has a higher overhead than a mutex. For example, bothg_static_rw_lock_reader_lock() and g_static_rw_lock_reader_unlock()have to lock and unlock a #GStaticMutex, so it takes at least twice thetime to lock and unlock a #GStaticRWLock that it does to lock and unlock a#GStaticMutex. So only data structures that are accessed by multiplereaders, and which keep the lock for a considerable time justify a#GStaticRWLock. The above example most probably would fare better witha #GStaticMutex.</para></note><!-- ##### MACRO G_STATIC_RW_LOCK_INIT ##### --><para>A #GStaticRWLock must be initialized with this macro before it canbe used. This macro can used be to initialize a variable, but itcannot be assigned to a variable. In that case you have to useg_static_rw_lock_init().</para><para><informalexample><programlisting>GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;</programlisting></informalexample></para><!-- ##### FUNCTION g_static_rw_lock_init ##### --><para>A #GStaticRWLock must be initialized with this function before it canbe used. Alternatively you can initialize it with#G_STATIC_RW_LOCK_INIT.</para>@lock: a #GStaticRWLock to be initialized.<!-- ##### FUNCTION g_static_rw_lock_reader_lock ##### --><para>Locks @lock for reading. There may be unlimited concurrent locks forreading of a #GStaticRWLock at the same time.  If @lock is alreadylocked for writing by another thread or if another thread is alreadywaiting to lock @lock for writing, this function will block until@lock is unlocked by the other writing thread and no other writingthreads want to lock @lock. This lock has to be unlocked byg_static_rw_lock_reader_unlock().</para><para>#GStaticRWLock is not recursive. It might seem to be possible torecursively lock for reading, but that can result in a deadlock, dueto writer preference.</para>@lock: a #GStaticRWLock to lock for reading.<!-- ##### FUNCTION g_static_rw_lock_reader_trylock ##### --><para>Tries to lock @lock for reading. If @lock is already locked forwriting by another thread or if another thread is already waiting tolock @lock for writing, immediately returns %FALSE. Otherwise locks@lock for reading and returns %TRUE. This lock has to be unlocked byg_static_rw_lock_reader_unlock().</para>@lock: a #GStaticRWLock to lock for reading.@Returns: %TRUE, if @lock could be locked for reading.<!-- ##### FUNCTION g_static_rw_lock_reader_unlock ##### --><para>Unlocks @lock. If a thread waits to lock @lock for writing and alllocks for reading have been unlocked, the waiting thread is woken upand can lock @lock for writing.</para>@lock: a #GStaticRWLock to unlock after reading.<!-- ##### FUNCTION g_static_rw_lock_writer_lock ##### --><para>Locks @lock for writing. If @lock is already locked for writing orreading by other threads, this function will block until @lock iscompletely unlocked and then lock @lock for writing. While thisfunctions waits to lock @lock, no other thread can lock @lock forreading. When @lock is locked for writing, no other thread can lock@lock (neither for reading nor writing). This lock has to be unlockedby g_static_rw_lock_writer_unlock().</para>@lock: a #GStaticRWLock to lock for writing.<!-- ##### FUNCTION g_static_rw_lock_writer_trylock ##### --><para>Tries to lock @lock for writing. If @lock is already locked (foreither reading or writing) by another thread, it immediately returns%FALSE. Otherwise it locks @lock for writing and returns %TRUE. Thislock has to be unlocked by g_static_rw_lock_writer_unlock().</para>@lock: a #GStaticRWLock to lock for writing.@Returns: %TRUE, if @lock could be locked for writing.<!-- ##### FUNCTION g_static_rw_lock_writer_unlock ##### --><para>Unlocks @lock. If a thread is waiting to lock @lock for writing andall locks for reading have been unlocked, the waiting thread is wokenup and can lock @lock for writing. If no thread is waiting to lock@lock for writing, and some thread or threads are waiting to lock @lockfor reading, the waiting threads are woken up and can lock @lock forreading.</para>@lock: a #GStaticRWLock to unlock after writing.<!-- ##### FUNCTION g_static_rw_lock_free ##### --><para>Releases all resources allocated to @lock. </para><para>You don't have to call this functions for a #GStaticRWLock with anunbounded lifetime, i.e. objects declared 'static', but if you have a#GStaticRWLock as a member of a structure, and the structure is freed,you should also free the #GStaticRWLock.</para>@lock: a #GStaticRWLock to be freed.<!-- ##### STRUCT GCond ##### --><para>The #GCond struct is an opaque data structure that represents acondition. Threads can block on a #GCond if they find a certaincondition to be false. If other threads change the state of thiscondition they signal the #GCond, and that causes the waiting threadsto be woken up.</para><para><example><title>Using GCond to block a thread until a condition is satisfied</title><programlisting>GCond* data_cond = NULL;   /* Must be initialized somewhere */GMutex* data_mutex = NULL; /* Must be initialized somewhere */gpointer current_data = NULL;void push_data (gpointer data){  g_mutex_lock (data_mutex);  current_data = data;  g_cond_signal (data_cond);  g_mutex_unlock (data_mutex);}gpointer pop_data (<!-- -->){  gpointer data;  g_mutex_lock (data_mutex);  while (!current_data)      g_cond_wait (data_cond, data_mutex);  data = current_data;  current_data = NULL;  g_mutex_unlock (data_mutex);  return data;}</programlisting></example></para><para>Whenever a thread calls <function>pop_data()</function> now, it will wait until current_data is non-%NULL, i.e. until some other thread has called <function>push_data()</function>.</para><note><para>It is important to use the g_cond_wait() and g_cond_timed_wait()functions only inside a loop which checks for the condition to be