threads.sgml

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

current thread will block until <parameter>mutex</parameter> is unlocked by the other
thread.
</para>

<para>
This function can also be used, if <link linkend="g-thread-init">g_thread_init</link>() has not yet been
called and will do nothing then.
</para>

<note>
<para>
<link linkend="GMutex">GMutex</link> is not recursive, i.e. a thread will deadlock, if it already
has locked <parameter>mutex</parameter> while calling <link linkend="g-mutex-lock">g_mutex_lock</link>(). Use
<link linkend="GStaticRecMutex">GStaticRecMutex</link> instead, if you need recursive mutexes.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GMutex">GMutex</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-mutex-trylock">g_mutex_trylock ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_mutex_trylock                 (<link linkend="GMutex">GMutex</link> *mutex);</programlisting>

<para>
Tries to lock <parameter>mutex</parameter>. If <parameter>mutex</parameter> is already locked by another
thread, it immediately returns <literal>FALSE</literal>. Otherwise it locks <parameter>mutex</parameter>
and returns <literal>TRUE</literal>.
</para>

<para>
This function can also be used, if <link linkend="g-thread-init">g_thread_init</link>() has not yet been
called and will immediately return <literal>TRUE</literal> then.
</para>

<note>
<para>
<link linkend="GMutex">GMutex</link> is not recursive, i.e. <link linkend="g-mutex-trylock">g_mutex_trylock</link>() will return <literal>FALSE</literal>,
if the current thread already has locked <parameter>mutex</parameter>. Use
<link linkend="GStaticRecMutex">GStaticRecMutex</link> instead, if you need recursive mutexes.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GMutex">GMutex</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal>, if <parameter>mutex</parameter> could be locked.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-mutex-unlock">g_mutex_unlock ()</title>
<programlisting>void        g_mutex_unlock                  (<link linkend="GMutex">GMutex</link> *mutex);</programlisting>

<para>
Unlocks <parameter>mutex</parameter>. If another thread is blocked in a <link linkend="g-mutex-lock">g_mutex_lock</link>() call
for <parameter>mutex</parameter>, it will be woken and can lock <parameter>mutex</parameter> itself.
</para>

<para>
This function can also be used, if <link linkend="g-thread-init">g_thread_init</link>() has not yet been
called and will do nothing then.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GMutex">GMutex</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-mutex-free">g_mutex_free ()</title>
<programlisting>void        g_mutex_free                    (<link linkend="GMutex">GMutex</link> *mutex);</programlisting>

<para>
Destroys <parameter>mutex</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GMutex">GMutex</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GStaticMutex">struct GStaticMutex</title>
<programlisting>struct GStaticMutex;</programlisting>

<para>
A <link linkend="GStaticMutex">GStaticMutex</link> works like a <link linkend="GMutex">GMutex</link>, but it has one significant
advantage. It doesn't need to be created at run-time like a <link linkend="GMutex">GMutex</link>,
but can be defined at compile-time. Here is a shorter, easier and
safer version of our <function><link linkend="give-me-next-number">give_me_next_number</link>()</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 <link linkend="g-thread-init">g_thread_init</link>(), because your code
should also be usable in non-threaded programs, you are not able to
use <link linkend="g-mutex-new">g_mutex_new</link>() and thus <link linkend="GMutex">GMutex</link>, as that requires a prior call to
<link linkend="g-thread-init">g_thread_init</link>(). In theses cases you can also use a <link linkend="GStaticMutex">GStaticMutex</link>. It
must be initialized with <link linkend="g-static-mutex-init">g_static_mutex_init</link>() before using it and
freed with with <link linkend="g-static-mutex-free">g_static_mutex_free</link>() when not needed anymore to free
up any allocated resources.
</para>

<para>
Even though <link linkend="GStaticMutex">GStaticMutex</link> 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 <link linkend="g-thread-init">g_thread_init</link>() 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></refsect2>
<refsect2>
<title><anchor id="G-STATIC-MUTEX-INIT-CAPS">G_STATIC_MUTEX_INIT</title>
<programlisting>#define G_STATIC_MUTEX_INIT
</programlisting>

<para>
A <link linkend="GStaticMutex">GStaticMutex</link> 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
<link linkend="g-static-mutex-init">g_static_mutex_init</link>().
</para>

<para>
<informalexample>
<programlisting>
GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
</programlisting>
</informalexample>
</para></refsect2>
<refsect2>
<title><anchor id="g-static-mutex-init">g_static_mutex_init ()</title>
<programlisting>void        g_static_mutex_init             (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);</programlisting>
<para>
Initializes <parameter>mutex</parameter>. Alternatively you can initialize it with
<link linkend="G-STATIC-MUTEX-INIT-CAPS">G_STATIC_MUTEX_INIT</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GStaticMutex">GStaticMutex</link> to be initialized.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-static-mutex-lock">g_static_mutex_lock ()</title>
<programlisting>void        g_static_mutex_lock             (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);</programlisting>
<para>
Works like <link linkend="g-mutex-lock">g_mutex_lock</link>(), but for a <link linkend="GStaticMutex">GStaticMutex</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GStaticMutex">GStaticMutex</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-static-mutex-trylock">g_static_mutex_trylock ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_static_mutex_trylock          (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);</programlisting>

<para>
Works like <link linkend="g-mutex-trylock">g_mutex_trylock</link>(), but for a <link linkend="GStaticMutex">GStaticMutex</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GStaticMutex">GStaticMutex</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal>, if the <link linkend="GStaticMutex">GStaticMutex</link> could be locked.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-static-mutex-unlock">g_static_mutex_unlock ()</title>
<programlisting>void        g_static_mutex_unlock           (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);</programlisting>

<para>
Works like <link linkend="g-mutex-unlock">g_mutex_unlock</link>(), but for a <link linkend="GStaticMutex">GStaticMutex</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GStaticMutex">GStaticMutex</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-static-mutex-get-mutex">g_static_mutex_get_mutex ()</title>
<programlisting><link linkend="GMutex">GMutex</link>*     g_static_mutex_get_mutex        (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);</programlisting>

<para>
For some operations (like <link linkend="g-cond-wait">g_cond_wait</link>()) you must have a <link linkend="GMutex">GMutex</link>
instead of a <link linkend="GStaticMutex">GStaticMutex</link>. This function will return the
corresponding <link linkend="GMutex">GMutex</link> for <parameter>mutex</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GStaticMutex">GStaticMutex</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GMutex">GMutex</link> corresponding to <parameter>mutex</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-static-mutex-free">g_static_mutex_free ()</title>
<programlisting>void        g_static_mutex_free             (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);</programlisting>
<para>
Releases all resources allocated to <parameter>mutex</parameter>. 
</para>

<para>
You don't have to call this functions for a <link linkend="GStaticMutex">GStaticMutex</link> with an
unbounded lifetime, i.e. objects declared 'static', but if you have a
<link linkend="GStaticMutex">GStaticMutex</link> as a member of a structure and the structure is freed,
you should also free the <link linkend="GStaticMutex">GStaticMutex</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mutex</parameter>&nbsp;:</entry>
<entry>a <link linkend="GStaticMutex">GStaticMutex</link> to be freed.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-LOCK-DEFINE-CAPS">G_LOCK_DEFINE()</title>
<programlisting>#define     G_LOCK_DEFINE(name)</programlisting>

<para>