threads.sgml

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

You should only call <link linkend="g-thread-init">g_thread_init</link>() with a non-<literal>NULL</literal> parameter if you
really know what you are doing.
</para>
</note>

<note>
<para>
<link linkend="g-thread-init">g_thread_init</link>() must not be called directly or indirectly as a
callback from GLib. Also no mutexes may be currently locked, while
calling <link linkend="g-thread-init">g_thread_init</link>().
</para>
</note>

<para>
<link linkend="g-thread-init">g_thread_init</link>() might only be called once. On the second call
it will abort with an error. If you want to make sure, that the thread
system is initialized, you can do that too:
</para>

<para>
<informalexample>
<programlisting>
if (!g_thread_supported (<!>)) g_thread_init (NULL);
</programlisting>
</informalexample>
</para>

<para>
After that line either the thread system is initialized or the program
will abort, if no thread system is available in GLib, i.e. either
<link linkend="G-THREADS-ENABLED-CAPS">G_THREADS_ENABLED</link> is not defined or <link linkend="G-THREADS-IMPL-NONE-CAPS">G_THREADS_IMPL_NONE</link> is defined.
</para>

<para>
If no thread system is available and <parameter>vtable</parameter> is <literal>NULL</literal> or if not all
elements of <parameter>vtable</parameter> are non-<literal>NULL</literal>, then <link linkend="g-thread-init">g_thread_init</link>() will abort.
</para>

<note>
<para>
To use <link linkend="g-thread-init">g_thread_init</link>() in your program, you have to link with the
libraries that the command <command>pkg-config --libs gthread-2.0</command> 
outputs. This is not the case for all the other thread related functions of
GLib. Those can be used without having to link with the thread libraries.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>vtable</parameter>&nbsp;:</entry>
<entry>a function table of type <link linkend="GThreadFunctions">GThreadFunctions</link>, that provides the
entry points to the thread system to be used.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-supported">g_thread_supported ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_thread_supported              ();</programlisting>
<para>
This function returns, whether the thread system is initialized or
not.
</para>

<note>
<para>
This function is actually a macro. Apart from taking the address of it
you can however use it as if it was a function.
</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><literal>TRUE</literal>, if the thread system is initialized.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GThreadFunc">GThreadFunc ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    (*GThreadFunc)                  (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of the <parameter>func</parameter> functions passed to
<link linkend="g-thread-create">g_thread_create</link>() or <link linkend="g-thread-create-full">g_thread_create_full</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>data passed to the thread.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the return value of the thread, which will be returned by
<link linkend="g-thread-join">g_thread_join</link>().


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GThreadPriority">enum GThreadPriority</title>
<programlisting>typedef enum
{
  G_THREAD_PRIORITY_LOW,
  G_THREAD_PRIORITY_NORMAL,
  G_THREAD_PRIORITY_HIGH,
  G_THREAD_PRIORITY_URGENT
} GThreadPriority;
</programlisting>
<para>
Specifies the priority of a thread. 
</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="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_THREAD_PRIORITY_LOW</literal></entry>
<entry>a priority lower than normal
</entry>
</row>
<row>
<entry><literal>G_THREAD_PRIORITY_NORMAL</literal></entry>
<entry>the default priority
</entry>
</row>
<row>
<entry><literal>G_THREAD_PRIORITY_HIGH</literal></entry>
<entry>a priority higher than normal
</entry>
</row>
<row>
<entry><literal>G_THREAD_PRIORITY_URGENT</literal></entry>
<entry>the highest priority

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GThread">struct GThread</title>
<programlisting>struct GThread
{
  GThreadFunc func;
  gpointer data;
  gboolean joinable;
  GThreadPriority priority;
};
</programlisting>
<para>
The <link linkend="GThread">GThread</link> struct represents a running thread. It has three public
read-only members, but the underlying struct is bigger, so you must
not copy this struct.
</para>

<note>
<para>
Resources for a joinable thread are not fully released until
<link linkend="g-thread-join">g_thread_join</link>() is called for that thread.
</para>
</note><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="GThreadFunc">GThreadFunc</link> <structfield>func</structfield></entry>
<entry>the function executing in that thread
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> <structfield>data</structfield></entry>
<entry>the argument to the function
</entry>
</row>
<row>
<entry><link linkend="gboolean">gboolean</link> <structfield>joinable</structfield></entry>
<entry>is this thread joinable?
</entry>
</row>
<row>
<entry><link linkend="GThreadPriority">GThreadPriority</link> <structfield>priority</structfield></entry>
<entry>the priority of the thread

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-create">g_thread_create ()</title>
<programlisting><link linkend="GThread">GThread</link>*    g_thread_create                 (<link linkend="GThreadFunc">GThreadFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="gboolean">gboolean</link> joinable,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
This function creates a new thread with the priority <parameter>priority</parameter>.
</para>

<para>
If <parameter>joinable</parameter> is <literal>TRUE</literal>, you can wait for this threads termination
calling <link linkend="g-thread-join">g_thread_join</link>(). Otherwise the thread will just disappear, when
ready. 
</para>

<para>
The new thread executes the function <parameter>func</parameter> with the argument
<parameter>data</parameter>. If the thread was created successfully, it is returned.
</para>

<para>
<parameter>error</parameter> can be <literal>NULL</literal> to ignore errors, or non-<literal>NULL</literal> to report errors. The
error is set, if and only if the function returns <literal>NULL</literal>.
</para><informaltable pgwide="1" frame="none" role="params">
<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>joinable</parameter>&nbsp;:</entry>
<entry>should this thread be joinable?
</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-create-full">g_thread_create_full ()</title>
<programlisting><link linkend="GThread">GThread</link>*    g_thread_create_full            (<link linkend="GThreadFunc">GThreadFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="gulong">gulong</link> stack_size,
                                             <link linkend="gboolean">gboolean</link> joinable,
                                             <link linkend="gboolean">gboolean</link> bound,
                                             <link linkend="GThreadPriority">GThreadPriority</link> priority,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
This function creates a new thread with the priority <parameter>priority</parameter>. The
stack gets the size <parameter>stack_size</parameter> or the default value for the current
platform, if <parameter>stack_size</parameter> is 0.
</para>

<para>
If <parameter>joinable</parameter> is <literal>TRUE</literal>, you can wait for this threads termination
calling <link linkend="g-thread-join">g_thread_join</link>(). Otherwise the thread will just disappear, when
ready. If <parameter>bound</parameter> is <literal>TRUE</literal>, this thread will be scheduled in the system
scope, otherwise the implementation is free to do scheduling in the
process scope. The first variant is more expensive resource-wise, but
generally faster. On some systems (e.g. Linux) all threads are bound.
</para>

<para>
The new thread executes the function <parameter>func</parameter> with the argument
<parameter>data</parameter>. If the thread was created successfully, it is returned.
</para>

<para>
<parameter>error</parameter> can be <literal>NULL</literal> to ignore errors, or non-<literal>NULL</literal> to report errors. The
error is set, if and only if the function returns <literal>NULL</literal>.
</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. Use <literal>G_THREAD_PRIORITY_NORMAL</literal> here as a
default.
</para>
</note>

<note>
<para>
Only use <link linkend="g-thread-create-full">g_thread_create_full</link>(), when you really can't use
<link linkend="g-thread-create">g_thread_create</link>() instead. <link linkend="g-thread-create">g_thread_create</link>() does not take
<parameter>stack_size</parameter>, <parameter>bound</parameter> and <parameter>priority</parameter> as arguments, as they should only be
used for cases, where it is inevitable. 
</para>
</note><informaltable pgwide="1" frame="none" role="params">