threads.sgml

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

<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry>a function to execute in the new thread.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>an argument to supply to the new thread.
</entry></row>
<row><entry align="right"><parameter>stack_size</parameter>&nbsp;:</entry>
<entry>a stack size for the new thread.
</entry></row>
<row><entry align="right"><parameter>joinable</parameter>&nbsp;:</entry>
<entry>should this thread be joinable?
</entry></row>
<row><entry align="right"><parameter>bound</parameter>&nbsp;:</entry>
<entry>should this thread be bound to a system thread?
</entry></row>
<row><entry align="right"><parameter>priority</parameter>&nbsp;:</entry>
<entry>a priority for the thread.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry>return location for error.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GThread">GThread</link> on success.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-self">g_thread_self ()</title>
<programlisting><link linkend="GThread">GThread</link>*    g_thread_self                   (void);</programlisting>
<para>
This functions returns the <link linkend="GThread">GThread</link> corresponding to the calling thread.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the current thread.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-join">g_thread_join ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_thread_join                   (<link linkend="GThread">GThread</link> *thread);</programlisting>
<para>
Waits until <parameter>thread</parameter> finishes, i.e. the function <parameter>func</parameter>, as given
to <link linkend="g-thread-create">g_thread_create</link>(), returns or <link linkend="g-thread-exit">g_thread_exit</link>() is called by
<parameter>thread</parameter>. All resources of <parameter>thread</parameter> including the <link linkend="GThread">GThread</link> struct are
released. <parameter>thread</parameter> must have been created with <parameter>joinable</parameter>=<literal>TRUE</literal> in
<link linkend="g-thread-create">g_thread_create</link>(). The value returned by <parameter>func</parameter> or given to
<link linkend="g-thread-exit">g_thread_exit</link>() by <parameter>thread</parameter> is 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>thread</parameter>&nbsp;:</entry>
<entry>a <link linkend="GThread">GThread</link> to be waited for.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the return value of the thread.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-set-priority">g_thread_set_priority ()</title>
<programlisting>void        g_thread_set_priority           (<link linkend="GThread">GThread</link> *thread,
                                             <link linkend="GThreadPriority">GThreadPriority</link> priority);</programlisting>
<para>
Changes the priority of <parameter>thread</parameter> to <parameter>priority</parameter>.
</para>

<note>
<para>
It is not guaranteed, that threads with different priorities really
behave accordingly. On some systems (e.g. Linux) only root can increase
priorities. On other systems (e.g. Solaris) there doesn't seem to be
different scheduling for different priorities. All in all try to avoid
being dependent on priorities.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>thread</parameter>&nbsp;:</entry>
<entry>a <link linkend="GThread">GThread</link>.
</entry></row>
<row><entry align="right"><parameter>priority</parameter>&nbsp;:</entry>
<entry>a new priority for <parameter>thread</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-yield">g_thread_yield ()</title>
<programlisting>void        g_thread_yield                  ();</programlisting>
<para>
Gives way to other threads waiting to be scheduled. 
</para>

<para>
This function is often used as a method to make busy wait less
evil. But in most cases, you will encounter, there are better methods
to do that. So in general you shouldn't use that function.
</para></refsect2>
<refsect2>
<title><anchor id="g-thread-exit">g_thread_exit ()</title>
<programlisting>void        g_thread_exit                   (<link linkend="gpointer">gpointer</link> retval);</programlisting>
<para>
Exits the current thread. If another thread is waiting for that thread
using <link linkend="g-thread-join">g_thread_join</link>() and the current thread is joinable, the waiting
thread will be woken up and getting <parameter>retval</parameter> as the return value of
<link linkend="g-thread-join">g_thread_join</link>(). If the current thread is not joinable, <parameter>retval</parameter> is
ignored. Calling
</para>

<para>
<informalexample>
<programlisting>
g_thread_exit (retval);
</programlisting>
</informalexample>
</para>

<para>
is equivalent to calling 
</para>

<para>
<informalexample>
<programlisting>
return retval;
</programlisting>
</informalexample>
</para>

<para>
in the function <parameter>func</parameter>, as given to <link linkend="g-thread-create">g_thread_create</link>().
</para>

<note>
<para>
Never call <link linkend="g-thread-exit">g_thread_exit</link>() from within a thread of a <link linkend="GThreadPool">GThreadPool</link>, as
that will mess up the bookkeeping and lead to funny and unwanted results.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>retval</parameter>&nbsp;:</entry>
<entry>the return value of this thread.


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

<para>
The <link linkend="GMutex">GMutex</link> 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:

<example>
<title>A function which will not work in a threaded environment</title>
<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;
  }
</programlisting>
</example>
</para>

<para>
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:
</para>

<para>
<example>
<title>The wrong way to write a thread-safe function</title>
<programlisting>
  int give_me_next_number (<!>)
  {
    static int current_number = 0;
    int ret_val;
    static GMutex * mutex = NULL;

    if (!mutex)
      mutex = <link linkend="g-mutex-new">g_mutex_new</link>();
    g_mutex_lock (mutex);
    ret_val = current_number = calc_next_number (current_number); 
    g_mutex_unlock (mutex);
    return ret_val;
  }
</programlisting>
</example>
</para>

<para>
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:
</para>

<para>
<example>
<title>A correct thread-safe function</title>
<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;
  }
</programlisting>
</example>
</para>

<para>
<link linkend="GStaticMutex">GStaticMutex</link> provides a simpler and safer way of doing this.
</para>

<para>
If you want to use a mutex, but your code should also work without
calling <link linkend="g-thread-init">g_thread_init</link>() first, you can not use a <link linkend="GMutex">GMutex</link>, as
<link linkend="g-mutex-new">g_mutex_new</link>() requires that. Use a <link linkend="GStaticMutex">GStaticMutex</link> instead.
</para>

<para>
A <link linkend="GMutex">GMutex</link> 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></refsect2>
<refsect2>
<title><anchor id="g-mutex-new">g_mutex_new ()</title>
<programlisting><link linkend="GMutex">GMutex</link>*     g_mutex_new                     ();</programlisting>

<para>
Creates a new <link linkend="GMutex">GMutex</link>. 
</para>

<note>
<para>
This function will abort, if <link linkend="g-thread-init">g_thread_init</link>() has not been called yet.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new <link linkend="GMutex">GMutex</link>.


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

<para>
Locks <parameter>mutex</parameter>. If <parameter>mutex</parameter> is already locked by another thread, the