threads.sgml

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

The <literal>G_LOCK_</literal>* macros provide a convenient interface to <link linkend="GStaticMutex">GStaticMutex</link>
with the advantage that they will expand to nothing in programs
compiled against a thread-disabled GLib, saving code and memory
there. <link linkend="G-LOCK-DEFINE-CAPS">G_LOCK_DEFINE</link> 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 <parameter>name</parameter> parameter will be mangled
to get the name of the <link linkend="GStaticMutex">GStaticMutex</link>. 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><link linkend="give-me-next-number">give_me_next_number</link>()</function> example using the <literal>G_LOCK_</literal>* macros:
</para>

<para>
<example>
<title>Using the <literal>G_LOCK_</literal>* 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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry>the name of the lock.


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

<para>
This works like <link linkend="G-LOCK-DEFINE-CAPS">G_LOCK_DEFINE</link>, but it creates a static object.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry>the name of the lock.


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

<para>
This declares a lock, that is defined with <link linkend="G-LOCK-DEFINE-CAPS">G_LOCK_DEFINE</link> in another module.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry>the name of the lock.


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

<para>
Works like <link linkend="g-mutex-lock">g_mutex_lock</link>(), but for a lock defined with <link linkend="G-LOCK-DEFINE-CAPS">G_LOCK_DEFINE</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry>the name of the lock.


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

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


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

<para>
Works like <link linkend="g-mutex-unlock">g_mutex_unlock</link>(), but for a lock defined with <link linkend="G-LOCK-DEFINE-CAPS">G_LOCK_DEFINE</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry>the name of the lock.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GStaticRecMutex">struct GStaticRecMutex</title>
<programlisting>struct GStaticRecMutex
{
  GStaticMutex mutex;
  guint depth;
  GSystemThread owner;
};
</programlisting>
<para>
A <link linkend="GStaticRecMutex">GStaticRecMutex</link> works like a <link linkend="GStaticMutex">GStaticMutex</link>, 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 <link linkend="g-static-rec-mutex-unlock-full">g_static_rec_mutex_unlock_full</link>(), that
allows you to unlock a <link linkend="GStaticRecMutex">GStaticRecMutex</link> 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 <link linkend="g-static-rec-mutex-lock-full">g_static_rec_mutex_lock_full</link>().
</para>

<para>
Even though <link linkend="GStaticRecMutex">GStaticRecMutex</link> 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 <link linkend="g-thread-init">g_thread_init</link>() has not been called.
</para></refsect2>
<refsect2>
<title><anchor id="G-STATIC-REC-MUTEX-INIT-CAPS">G_STATIC_REC_MUTEX_INIT</title>
<programlisting>#define G_STATIC_REC_MUTEX_INIT { G_STATIC_MUTEX_INIT }
</programlisting>
<para>
A <link linkend="GStaticRecMutex">GStaticRecMutex</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-rec-mutex-init">g_static_rec_mutex_init</link>().
</para>

<para>
<informalexample>
<programlisting>
GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
</programlisting>
</informalexample>
</para></refsect2>
<refsect2>
<title><anchor id="g-static-rec-mutex-init">g_static_rec_mutex_init ()</title>
<programlisting>void        g_static_rec_mutex_init         (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);</programlisting>
<para>
A <link linkend="GStaticRecMutex">GStaticRecMutex</link> must be initialized with this function, before it
can be used. Alternatively you can initialize it with
<link linkend="G-STATIC-REC-MUTEX-INIT-CAPS">G_STATIC_REC_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="GStaticRecMutex">GStaticRecMutex</link> to be initialized.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-static-rec-mutex-lock">g_static_rec_mutex_lock ()</title>
<programlisting>void        g_static_rec_mutex_lock         (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);</programlisting>
<para>
Locks <parameter>mutex</parameter>. If <parameter>mutex</parameter> is already locked by another thread, the
current thread will block until <parameter>mutex</parameter> is unlocked by the other
thread. If <parameter>mutex</parameter> is already locked by the calling thread, this
functions increases the depth of <parameter>mutex</parameter> and returns immediately.
</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="GStaticRecMutex">GStaticRecMutex</link> to lock.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-static-rec-mutex-trylock">g_static_rec_mutex_trylock ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_static_rec_mutex_trylock      (<link linkend="GStaticRecMutex">GStaticRecMutex</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>. If <parameter>mutex</parameter> is already locked by the calling thread, this
functions increases the depth of <parameter>mutex</parameter> and immediately  returns <literal>TRUE</literal>.
</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="GStaticRecMutex">GStaticRecMutex</link> to lock.
</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-static-rec-mutex-unlock">g_static_rec_mutex_unlock ()</title>
<programlisting>void        g_static_rec_mutex_unlock       (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);</programlisting>
<para>
Unlocks <parameter>mutex</parameter>. Another threads can, however, only lock <parameter>mutex</parameter> when it
has been unlocked as many times, as it had been locked before. If
<parameter>mutex</parameter> is completely unlocked and another thread is blocked in a
<link linkend="g-static-rec-mutex-lock">g_static_rec_mutex_lock</link>() call for <parameter>mutex</parameter>, it will be woken and can
lock <parameter>mutex</parameter> itself.
</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="GStaticRecMutex">GStaticRecMutex</link> to unlock.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-static-rec-mutex-lock-full">g_static_rec_mutex_lock_full ()</title>
<programlisting>void        g_static_rec_mutex_lock_full    (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex,
                                             <link linkend="guint">guint</link> depth);</programlisting>
<para>
Works like calling <link linkend="g-static-rec-mutex-lock">g_static_rec_mutex_lock</link>() for <parameter>mutex</parameter> <parameter>depth</parameter> times.
</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="GStaticRecMutex">GStaticRecMutex</link> to lock.
</entry></row>
<row><entry align="right"><parameter>depth</parameter>&nbsp;:</entry>
<entry>number of times this mutex has to be unlocked to be completely unlocked.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-static-rec-mutex-unlock-full">g_static_rec_mutex_unlock_full ()</title>
<programlisting><link linkend="guint">guint</link>       g_static_rec_mutex_unlock_full  (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);</programlisting>
<para>
Completely unlocks <parameter>mutex</parameter>. If another thread is blocked in a
<link linkend="g-static-rec-mutex-lock">g_static_rec_mutex_lock</link>() call for <parameter>mutex</parameter>, it will be woken and can
lock <parameter>mutex</parameter> itself. This function returns the number of times, that
<parameter>mutex</parameter> has been locked by the current thread. To restore the state
before the call to <link linkend="g-static-rec-mutex-unlock-full">g_static_rec_mutex_unlock_full</link>() you can call
<link linkend="g-static-rec-mutex-lock-full">g_static_rec_mutex_lock_full</link>() with the depth returned by this
function.
</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="GStaticRecMutex">GStaticRecMutex</link> to completely unlock.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>number of times <parameter>mutex</parameter> has been locked by the current threa