thread_pools.sgml

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

<refentry id="glib-Thread-Pools">
<refmeta>
<refentrytitle>Thread Pools</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Thread Pools</refname><refpurpose>pools of threads to execute work concurrently.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GThreadPool">GThreadPool</link>;
<link linkend="GThreadPool">GThreadPool</link>* <link linkend="g-thread-pool-new">g_thread_pool_new</link>              (<link linkend="GFunc">GFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data,
                                             <link linkend="gint">gint</link> max_threads,
                                             <link linkend="gboolean">gboolean</link> exclusive,
                                             <link linkend="GError">GError</link> **error);
void        <link linkend="g-thread-pool-push">g_thread_pool_push</link>              (<link linkend="GThreadPool">GThreadPool</link> *pool,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GError">GError</link> **error);
void        <link linkend="g-thread-pool-set-max-threads">g_thread_pool_set_max_threads</link>   (<link linkend="GThreadPool">GThreadPool</link> *pool,
                                             <link linkend="gint">gint</link> max_threads,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gint">gint</link>        <link linkend="g-thread-pool-get-max-threads">g_thread_pool_get_max_threads</link>   (<link linkend="GThreadPool">GThreadPool</link> *pool);
<link linkend="guint">guint</link>       <link linkend="g-thread-pool-get-num-threads">g_thread_pool_get_num_threads</link>   (<link linkend="GThreadPool">GThreadPool</link> *pool);
<link linkend="guint">guint</link>       <link linkend="g-thread-pool-unprocessed">g_thread_pool_unprocessed</link>       (<link linkend="GThreadPool">GThreadPool</link> *pool);
void        <link linkend="g-thread-pool-free">g_thread_pool_free</link>              (<link linkend="GThreadPool">GThreadPool</link> *pool,
                                             <link linkend="gboolean">gboolean</link> immediate,
                                             <link linkend="gboolean">gboolean</link> wait);
void        <link linkend="g-thread-pool-set-max-unused-threads">g_thread_pool_set_max_unused_threads</link>
                                            (<link linkend="gint">gint</link> max_threads);
<link linkend="gint">gint</link>        <link linkend="g-thread-pool-get-max-unused-threads">g_thread_pool_get_max_unused_threads</link>
                                            (void);
<link linkend="guint">guint</link>       <link linkend="g-thread-pool-get-num-unused-threads">g_thread_pool_get_num_unused_threads</link>
                                            (void);
void        <link linkend="g-thread-pool-stop-unused-threads">g_thread_pool_stop_unused_threads</link>
                                            (void);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
Sometimes you wish to asyncronously fork out the execution of work and
continue working in your own thread. If that will happen often, the
overhead of starting and destroying a thread each time might be to
high. In such cases reusing already started threads seems like a good
idea. And it indeed is, but implementing this can be tedious and
error-prone.
</para>

<para>
Therefore GLib provides thread pools for your convenience. An added
advantage is, that the threads can be shared between the different
subsystems of your program, when they are using GLib.
</para>

<para>
To create a new thread pool, you use <link linkend="g-thread-pool-new">g_thread_pool_new</link>(). It is
destroyed by <link linkend="g-thread-pool-free">g_thread_pool_free</link>().
</para>

<para>
If you want to execute a certain task within a thread pool, you call
<link linkend="g-thread-pool-push">g_thread_pool_push</link>().
</para>

<para>
To get the current number of running threads you call
<link linkend="g-thread-pool-get-num-threads">g_thread_pool_get_num_threads</link>(). To get the number of still
unprocessed tasks you call <link linkend="g-thread-pool-unprocessed">g_thread_pool_unprocessed</link>(). To control the
maximal number of threads for a thread pool, you use
<link linkend="g-thread-pool-get-max-threads">g_thread_pool_get_max_threads</link>() and <link linkend="g-thread-pool-set-max-threads">g_thread_pool_set_max_threads</link>().
</para>

<para>
Finally you can control the number of unused threads, that are kept
alive by GLib for future use. The current number can be fetched with
<link linkend="g-thread-pool-get-num-unused-threads">g_thread_pool_get_num_unused_threads</link>(). The maximal number can be
controlled by <link linkend="g-thread-pool-get-max-unused-threads">g_thread_pool_get_max_unused_threads</link>() and
<link linkend="g-thread-pool-set-max-unused-threads">g_thread_pool_set_max_unused_threads</link>(). All currently unused threads
can be stopped by calling <link linkend="g-thread-pool-stop-unused-threads">g_thread_pool_stop_unused_threads</link>().
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GThreadPool">struct GThreadPool</title>
<programlisting>struct GThreadPool
{
  GFunc func;
  gpointer user_data;
  gboolean exclusive;
};
</programlisting>
<para>
The <link linkend="GThreadPool">GThreadPool</link> struct represents a thread pool. It has six public
read-only members, but the underlying struct is bigger, so you must not copy
this struct.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="GFunc">GFunc</link> <structfield>func</structfield></entry>
<entry>the function to execute in the threads of this pool
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> <structfield>user_data</structfield></entry>
<entry>the user data for the threads of this pool
</entry>
</row>
<row>
<entry><link linkend="gboolean">gboolean</link> <structfield>exclusive</structfield></entry>
<entry>are all threads exclusive to this pool

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-new">g_thread_pool_new ()</title>
<programlisting><link linkend="GThreadPool">GThreadPool</link>* g_thread_pool_new              (<link linkend="GFunc">GFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data,
                                             <link linkend="gint">gint</link> max_threads,
                                             <link linkend="gboolean">gboolean</link> exclusive,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
This function creates a new thread pool.
</para>
<para>
Whenever you call <link linkend="g-thread-pool-push">g_thread_pool_push</link>(), either a new thread is
created or an unused one is reused. At most <parameter>max_threads</parameter> threads
are running concurrently for this thread pool. <parameter>max_threads</parameter> = -1
allows unlimited threads to be created for this thread pool. The
newly created or reused thread now executes the function <parameter>func</parameter> with
the two arguments. The first one is the parameter to
<link linkend="g-thread-pool-push">g_thread_pool_push</link>() and the second one is <parameter>user_data</parameter>.
</para>
<para>
The parameter <parameter>exclusive</parameter> determines, whether the thread pool owns
all threads exclusive or whether the threads are shared
globally. If <parameter>exclusive</parameter> is <literal>TRUE</literal>, <parameter>max_threads</parameter> threads are started
immediately and they will run exclusively for this thread pool until
it is destroyed by <link linkend="g-thread-pool-free">g_thread_pool_free</link>(). If <parameter>exclusive</parameter> is <literal>FALSE</literal>,
threads are created, when needed and shared between all
non-exclusive thread pools. This implies that <parameter>max_threads</parameter> may not
be -1 for exclusive thread pools.
</para>
<para>
<parameter>error</parameter> can be <literal>NULL</literal> to ignore errors, or non-<literal>NULL</literal> to report
errors. An error can only occur when <parameter>exclusive</parameter> is set to <literal>TRUE</literal> and
not all <parameter>max_threads</parameter> threads could be created.</para>
<para>

</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 threads of the new thread pool
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> user data that is handed over to <parameter>func</parameter> every time it 
  is called
</entry></row>
<row><entry align="right"><parameter>max_threads</parameter>&nbsp;:</entry>
<entry> the maximal number of threads to execute concurrently in 
  the new thread pool, -1 means no limit
</entry></row>
<row><entry align="right"><parameter>exclusive</parameter>&nbsp;:</entry>
<entry> should this thread pool be exclusive?
</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="GThreadPool">GThreadPool</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-push">g_thread_pool_push ()</title>
<programlisting>void        g_thread_pool_push              (<link linkend="GThreadPool">GThreadPool</link> *pool,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Inserts <parameter>data</parameter> into the list of tasks to be executed by <parameter>pool</parameter>. When
the number of currently running threads is lower than the maximal
allowed number of threads, a new thread is started (or reused) with
the properties given to <link linkend="g-thread-pool-new">g_thread_pool_new</link>(). Otherwise <parameter>data</parameter> stays
in the queue until a thread in this pool finishes its previous task
and processes <parameter>data</parameter>. 
</para>
<para>
<parameter>error</parameter> can be <literal>NULL</literal> to ignore errors, or non-<literal>NULL</literal> to report
errors. An error can only occur when a new thread couldn't be
created. In that case <parameter>data</parameter> is simply appended to the queue of work
to do.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pool</parameter>&nbsp;:</entry>
<entry> a <link linkend="GThreadPool">GThreadPool</link>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry> a new task for <parameter>pool</parameter>
</entry></row>