threads.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

g_mutex_new() requires that. Use a #GStaticMutex instead.
</para>

<para>
A #GMutex should only be accessed via the following functions.
</para>

<note>
<para>
All of the <function>g_mutex_*</function> functions are actually macros. 
Apart from taking their addresses, you can however use them as if they 
were functions.
</para>
</note>


<!-- ##### FUNCTION g_mutex_new ##### -->

<para>
Creates a new #GMutex. 
</para>

<note>
<para>
This function will abort, if g_thread_init() has not been called yet.
</para>
</note>

@Returns: a new #GMutex.


<!-- ##### FUNCTION g_mutex_lock ##### -->

<para>
Locks @mutex. If @mutex is already locked by another thread, the
current thread will block until @mutex is unlocked by the other
thread.
</para>

<para>
This function can also be used, if g_thread_init() has not yet been
called and will do nothing then.
</para>

<note>
<para>
#GMutex is not recursive, i.e. a thread will deadlock, if it already
has locked @mutex while calling g_mutex_lock(). Use
#GStaticRecMutex instead, if you need recursive mutexes.
</para>
</note>

@mutex: a #GMutex.


<!-- ##### FUNCTION g_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.
</para>

<para>
This function can also be used, if g_thread_init() has not yet been
called and will immediately return %TRUE then.
</para>

<note>
<para>
#GMutex is not recursive, i.e. g_mutex_trylock() will return %FALSE,
if the current thread already has locked @mutex. Use
#GStaticRecMutex instead, if you need recursive mutexes.
</para>
</note>

@mutex: a #GMutex.
@Returns: %TRUE, if @mutex could be locked.


<!-- ##### FUNCTION g_mutex_unlock ##### -->

<para>
Unlocks @mutex. If another thread is blocked in a g_mutex_lock() call
for @mutex, it will be woken and can lock @mutex itself.
</para>

<para>
This function can also be used, if g_thread_init() has not yet been
called and will do nothing then.
</para>

@mutex: a #GMutex.


<!-- ##### FUNCTION g_mutex_free ##### -->

<para>
Destroys @mutex.
</para>

@mutex: a #GMutex.


<!-- ##### STRUCT GStaticMutex ##### -->

<para>
A #GStaticMutex works like a #GMutex, but it has one significant
advantage. It doesn't need to be created at run-time like a #GMutex,
but can be defined at compile-time. Here is a shorter, easier and
safer version of our <function>give_me_next_number()</function> example:
</para>

<para>
<example>
<title>Using <structname>GStaticMutex</structname> to simplify thread-safe programming</title>
<programlisting>
  int give_me_next_number (<!>)
  {
    static int current_number = 0;
    int ret_val;
    static GStaticMutex mutex = G_STATIC_MUTEX_INIT;

    g_static_mutex_lock (&amp;mutex);
    ret_val = current_number = calc_next_number (current_number); 
    g_static_mutex_unlock (&amp;mutex);
    return ret_val;
  }
</programlisting>
</example>
</para>

<para>
Sometimes you would like to dynamically create a mutex. If you don't
want to require prior calling to g_thread_init(), because your code
should also be usable in non-threaded programs, you are not able to
use g_mutex_new() and thus #GMutex, as that requires a prior call to
g_thread_init(). In theses cases you can also use a #GStaticMutex. It
must be initialized with g_static_mutex_init() before using it and
freed with with g_static_mutex_free() when not needed anymore to free
up any allocated resources.
</para>

<para>
Even though #GStaticMutex is not opaque, it should only be used with
the following functions, as it is defined differently on different
platforms.
</para>

<para>
All of the <function>g_static_mutex_*</function> functions can also be 
used, if g_thread_init() has not yet been called.
</para>

<note>
<para>
All of the <function>g_static_mutex_*</function> functions are actually 
macros. Apart from taking their addresses, you can however use them 
as if they were functions.
</para>
</note>


<!-- ##### MACRO G_STATIC_MUTEX_INIT ##### -->

<para>
A #GStaticMutex must be initialized with this macro, before it can be
used. This macro can used be to initialize a variable, but it cannot
be assigned to a variable. In that case you have to use
g_static_mutex_init().
</para>

<para>
<informalexample>
<programlisting>
GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
</programlisting>
</informalexample>
</para>



<!-- ##### FUNCTION g_static_mutex_init ##### -->
<para>
Initializes @mutex. Alternatively you can initialize it with
#G_STATIC_MUTEX_INIT.
</para>

@mutex: a #GStaticMutex to be initialized.


<!-- ##### FUNCTION g_static_mutex_lock ##### -->
<para>
Works like g_mutex_lock(), but for a #GStaticMutex.
</para>

@mutex: a #GStaticMutex.


<!-- ##### FUNCTION g_static_mutex_trylock ##### -->

<para>
Works like g_mutex_trylock(), but for a #GStaticMutex.
</para>

@mutex: a #GStaticMutex.
@Returns: %TRUE, if the #GStaticMutex could be locked.


<!-- ##### FUNCTION g_static_mutex_unlock ##### -->

<para>
Works like g_mutex_unlock(), but for a #GStaticMutex.
</para>

@mutex: a #GStaticMutex.


<!-- ##### FUNCTION g_static_mutex_get_mutex ##### -->

<para>
For some operations (like g_cond_wait()) you must have a #GMutex
instead of a #GStaticMutex. This function will return the
corresponding #GMutex for @mutex.
</para>

@mutex: a #GStaticMutex.
@Returns: the #GMutex corresponding to @mutex.


<!-- ##### FUNCTION g_static_mutex_free ##### -->
<para>
Releases all resources allocated to @mutex. 
</para>

<para>
You don't have to call this functions for a #GStaticMutex with an
unbounded lifetime, i.e. objects declared 'static', but if you have a
#GStaticMutex as a member of a structure and the structure is freed,
you should also free the #GStaticMutex.
</para>

@mutex: a #GStaticMutex to be freed.


<!-- ##### MACRO G_LOCK_DEFINE ##### -->

<para>
The %G_LOCK_* macros provide a convenient interface to #GStaticMutex
with the advantage that they will expand to nothing in programs
compiled against a thread-disabled GLib, saving code and memory
there. #G_LOCK_DEFINE defines a lock. It can appear, where variable
definitions may appear in programs, i.e. in the first block of a
function or outside of functions. The @name parameter will be mangled
to get the name of the #GStaticMutex. This means, that you can use
names of existing variables as the parameter, e.g. the name of the
variable you intent to protect with the lock. Look at our
<function>give_me_next_number()</function> example using the %G_LOCK_* macros:
</para>

<para>
<example>
<title>Using the %G_LOCK_* convenience macros</title>
<programlisting>
G_LOCK_DEFINE (current_number);

int give_me_next_number (<!>)
  {
    static int current_number = 0;
    int ret_val;

    G_LOCK (current_number);
    ret_val = current_number = calc_next_number (current_number); 
    G_UNLOCK (current_number);
    return ret_val;
  }
</programlisting>
</example>
</para>

@name: the name of the lock.


<!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->

<para>
This works like #G_LOCK_DEFINE, but it creates a static object.
</para>

@name: the name of the lock.


<!-- ##### MACRO G_LOCK_EXTERN ##### -->

<para>
This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
</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 locked
multiple times by one thread. If you enter it n times, however, you
have to unlock it n times again to let other threads lock it. An
exception is the function g_static_rec_mutex_unlock_full(), that
allows you to unlock a #GStaticRecMutex completely returning the depth,
i.e. the number of times this mutex was locked. The depth can later be
used to restore the state by calling g_static_rec_mutex_lock_full().
</para>

<para>
Even though #GStaticRecMutex is not opaque, it should only be used with
the following functions.
</para>

<para>
All of the <function>g_static_rec_mutex_*</function> functions can also 
be used, if g_thread_init() has not been called.
</para>

@mutex: 
@depth: 
@owner: 

<!-- ##### MACRO G_STATIC_REC_MUTEX_INIT ##### -->
<para>
A #GStaticRecMutex must be initialized with this macro, before it can
be used. This macro can used be to initialize a variable, but it
cannot be assigned to a variable. In that case you have to use
g_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 it
can 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, the
current thread will block until @mutex is unlocked by the other
thread. If @mutex is already locked by the calling thread, this
functions 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, this
functions 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 threads can, however, only lock @mutex when it
has been unlocked as many times, as it had been locked before. If
@mutex is completely unlocked and another thread is blocked in a
g_static_rec_mutex_lock() call for @mutex, it will be woken and can
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 a
g_static_rec_mutex_lock() call for @mutex, it will be woken and can
lock @mutex itself. This function returns the number of times, that
@mutex has been locked by the current thread. To restore the state
before the call to g_static_rec_mutex_unlock_full() you can call
g_static_rec_mutex_lock_full() with the depth returned by this
function.
</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 an
unbounded lifetime, i.e. objects declared 'static', but if you have a
#GStaticRecMutex as a member of a structure and the structure is
freed, 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-write
lock can be used for protecting data, that some portions of code only
read from, while others also write. In such situations it is
desirable, that several readers can read at once, whereas of course
only one writer may write at a time. Take a look at the following
example:

<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 < 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 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 the writers should have precedence of readers. That
means for this implementation, that as soon as a writer wants to lock
the data, no other reader is allowed to lock the data, whereas of
course the readers, that already have locked the data are allowed to
finish 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 with
the following functions.
</para>

<para>
All of the <function>g_static_rw_lock_*</function> functions can also be 
used, if g_thread_init() has not been called.
</para>

<note>
<para>
A read-write lock has a higher overhead as a mutex. For example both
g_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 the
time to lock and unlock a #GStaticRWLock than to lock and unlock a