glib-threads.html

glid编写实例

<p>
Exits the current thread. If another thread is waiting for that thread
using <a href="glib-Threads.html#g-thread-join"><code class="function">g_thread_join()</code></a> and the current thread is joinable, the waiting
thread will be woken up and getting <em class="parameter"><code>retval</code></em> as the return value of
<a href="glib-Threads.html#g-thread-join"><code class="function">g_thread_join()</code></a>. If the current thread is not joinable, <em class="parameter"><code>retval</code></em> is
ignored. Calling
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
g_thread_exit (retval);
</pre></div>
<p>
</p>
<p>
is equivalent to calling 
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
return retval;
</pre></div>
<p>
</p>
<p>
in the function <em class="parameter"><code>func</code></em>, as given to <a href="glib-Threads.html#g-thread-create"><code class="function">g_thread_create()</code></a>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
Never call <a href="glib-Threads.html#g-thread-exit"><code class="function">g_thread_exit()</code></a> from within a thread of a <a href="glib-Thread-Pools.html#GThreadPool"><span class="type">GThreadPool</span></a>, as
that will mess up the bookkeeping and lead to funny and unwanted results.
</p>
</div>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>retval</code></em>&#160;:</span></td>
<td>the return value of this thread.


</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2872752"></a><h3>
<a name="GMutex"></a>GMutex</h3>
<a class="indexterm" name="id2872762"></a><pre class="programlisting">typedef struct _GMutex GMutex;</pre>
<p>
The <a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a> struct is an opaque data structure to represent a mutex
(mutual exclusion). It can be used to protect data against shared
access. Take for example the following function:

</p>
<div class="example">
<a name="id2872787"></a><p class="title"><b>Example&#160;3.&#160;A function which will not work in a threaded environment</b></p>
<pre class="programlisting">
  int give_me_next_number ()
  {
    static int current_number = 0;

    /* now do a very complicated calculation to calculate the new number,
       this might for example be a random number generator */
    current_number = calc_next_number (current_number); 
    return current_number;
  }
</pre>
</div>
<p>
</p>
<p>
It is easy to see, that this won't work in a multi-threaded
application. There current_number must be protected against shared
access. A first naive implementation would be:
</p>
<p>
</p>
<div class="example">
<a name="id2872818"></a><p class="title"><b>Example&#160;4.&#160;The wrong way to write a thread-safe function</b></p>
<pre class="programlisting">
  int give_me_next_number ()
  {
    static int current_number = 0;
    int ret_val;
    static GMutex * mutex = NULL;

    if (!mutex)
      mutex = g_mutex_new ();
    g_mutex_lock (mutex);
    ret_val = current_number = calc_next_number (current_number); 
    g_mutex_unlock (mutex);
    return ret_val;
  }
</pre>
</div>
<p>
</p>
<p>
This looks like it would work, but there is a race condition while
constructing the mutex and this code cannot work reliable. So please do
not use such constructs in your own programs. One working solution is:
</p>
<p>
</p>
<div class="example">
<a name="id2872851"></a><p class="title"><b>Example&#160;5.&#160;A correct thread-safe function</b></p>
<pre class="programlisting">
  static GMutex *give_me_next_number_mutex = NULL;

  /* this function must be called before any call to give_me_next_number ()
     it must be called exactly once. */
  void init_give_me_next_number () 
  {
    g_assert (give_me_next_number_mutex == NULL);
    give_me_next_number_mutex = g_mutex_new ();
  }

  int give_me_next_number ()
  {
    static int current_number = 0;
    int ret_val;

    g_mutex_lock (give_me_next_number_mutex);
    ret_val = current_number = calc_next_number (current_number); 
    g_mutex_unlock (give_me_next_number_mutex);
    return ret_val;
  }
</pre>
</div>
<p>
</p>
<p>
<a href="glib-Threads.html#GStaticMutex"><span class="type">GStaticMutex</span></a> provides a simpler and safer way of doing this.
</p>
<p>
If you want to use a mutex, but your code should also work without
calling <a href="glib-Threads.html#g-thread-init"><code class="function">g_thread_init()</code></a> first, you can not use a <a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a>, as
<a href="glib-Threads.html#g-mutex-new"><code class="function">g_mutex_new()</code></a> requires that. Use a <a href="glib-Threads.html#GStaticMutex"><span class="type">GStaticMutex</span></a> instead.
</p>
<p>
A <a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a> should only be accessed via the following functions.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
All of the <code class="function">g_mutex_*</code> functions are actually macros. 
Apart from taking their addresses, you can however use them as if they 
were functions.
</p>
</div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2872966"></a><h3>
<a name="g-mutex-new"></a>g_mutex_new ()</h3>
<a class="indexterm" name="id2872977"></a><pre class="programlisting"><a href="glib-Threads.html#GMutex">GMutex</a>*     g_mutex_new                     ();</pre>
<p>
Creates a new <a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a>. 
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
This function will abort, if <a href="glib-Threads.html#g-thread-init"><code class="function">g_thread_init()</code></a> has not been called yet.
</p>
</div>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span>&#160;:</span></td>
<td>a new <a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a>.


</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2873047"></a><h3>
<a name="g-mutex-lock"></a>g_mutex_lock ()</h3>
<a class="indexterm" name="id2873057"></a><pre class="programlisting">void        g_mutex_lock                    (<a href="glib-Threads.html#GMutex">GMutex</a> *mutex);</pre>
<p>
Locks <em class="parameter"><code>mutex</code></em>. If <em class="parameter"><code>mutex</code></em> is already locked by another thread, the
current thread will block until <em class="parameter"><code>mutex</code></em> is unlocked by the other
thread.
</p>
<p>
This function can also be used, if <a href="glib-Threads.html#g-thread-init"><code class="function">g_thread_init()</code></a> has not yet been
called and will do nothing then.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
<a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a> is neither guaranteed to be recursive nor to be non-recursive,
i.e. a thread could deadlock while calling <a href="glib-Threads.html#g-mutex-lock"><code class="function">g_mutex_lock()</code></a>, if it
already has locked <em class="parameter"><code>mutex</code></em>. Use <a href="glib-Threads.html#GStaticRecMutex"><span class="type">GStaticRecMutex</span></a>, if you need recursive
mutexes.
</p>
</div>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>mutex</code></em>&#160;:</span></td>
<td>a <a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a>.


</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2873188"></a><h3>
<a name="g-mutex-trylock"></a>g_mutex_trylock ()</h3>
<a class="indexterm" name="id2873199"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gboolean">gboolean</a>    g_mutex_trylock                 (<a href="glib-Threads.html#GMutex">GMutex</a> *mutex);</pre>
<p>
Tries to lock <em class="parameter"><code>mutex</code></em>. If <em class="parameter"><code>mutex</code></em> is already locked by another
thread, it immediately returns <code class="literal">FALSE</code>. Otherwise it locks <em class="parameter"><code>mutex</code></em>
and returns <code class="literal">TRUE</code>.
</p>
<p>
This function can also be used, if <a href="glib-Threads.html#g-thread-init"><code class="function">g_thread_init()</code></a> has not yet been
called and will immediately return <code class="literal">TRUE</code> then.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
<a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a> is neither guaranteed to be recursive nor to be non-recursive,
i.e. the return value of <a href="glib-Threads.html#g-mutex-trylock"><code class="function">g_mutex_trylock()</code></a> could be both <code class="literal">FALSE</code> or
<code class="literal">TRUE</code>, if the current thread already has locked <em class="parameter"><code>mutex</code></em>. Use
<a href="glib-Threads.html#GStaticRecMutex"><span class="type">GStaticRecMutex</span></a>, if you need recursive mutexes.
</p>
</div>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>mutex</code></em>&#160;:</span></td>
<td>a <a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a>.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span>&#160;:</span></td>
<td>
<code class="literal">TRUE</code>, if <em class="parameter"><code>mutex</code></em> could be locked.


</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2873380"></a><h3>
<a name="g-mutex-unlock"></a>g_mutex_unlock ()</h3>
<a class="indexterm" name="id2873391"></a><pre class="programlisting">void        g_mutex_unlock                  (<a href="glib-Threads.html#GMutex">GMutex</a> *mutex);</pre>
<p>
Unlocks <em class="parameter"><code>mutex</code></em>. If another thread is blocked in a <a href="glib-Threads.html#g-mutex-lock"><code class="function">g_mutex_lock()</code></a> call
for <em class="parameter"><code>mutex</code></em>, it will be woken and can lock <em class="parameter"><code>mutex</code></em> itself.
</p>
<p>