thread_pools.sgml

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

<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> return location for error
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-set-max-threads">g_thread_pool_set_max_threads ()</title>
<programlisting>void        g_thread_pool_set_max_threads   (<link linkend="GThreadPool">GThreadPool</link> *pool,
                                             <link linkend="gint">gint</link> max_threads,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Sets the maximal allowed number of threads for <parameter>pool</parameter>. A value of -1
means, that the maximal number of threads is unlimited.
</para>
<para>
Setting <parameter>max_threads</parameter> to 0 means stopping all work for <parameter>pool</parameter>. It is
effectively frozen until <parameter>max_threads</parameter> is set to a non-zero value
again.
</para>
<para>
A thread is never terminated while calling <parameter>func</parameter>, as supplied by
<link linkend="g-thread-pool-new">g_thread_pool_new</link>(). Instead the maximal number of threads only
has effect for the allocation of new threads in <link linkend="g-thread-pool-push">g_thread_pool_push</link>(). 
A new thread is allocated, whenever the number of currently
running threads in <parameter>pool</parameter> is smaller than the maximal number.
</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.</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>max_threads</parameter>&nbsp;:</entry>
<entry> a new maximal number of threads for <parameter>pool</parameter>
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> return location for error
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-get-max-threads">g_thread_pool_get_max_threads ()</title>
<programlisting><link linkend="gint">gint</link>        g_thread_pool_get_max_threads   (<link linkend="GThreadPool">GThreadPool</link> *pool);</programlisting>
<para>
Returns the maximal number of threads for <parameter>pool</parameter>.</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"><emphasis>Returns</emphasis> :</entry><entry> the maximal number of threads
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-get-num-threads">g_thread_pool_get_num_threads ()</title>
<programlisting><link linkend="guint">guint</link>       g_thread_pool_get_num_threads   (<link linkend="GThreadPool">GThreadPool</link> *pool);</programlisting>
<para>
Returns the number of threads currently running in <parameter>pool</parameter>.</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"><emphasis>Returns</emphasis> :</entry><entry> the number of threads currently running
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-unprocessed">g_thread_pool_unprocessed ()</title>
<programlisting><link linkend="guint">guint</link>       g_thread_pool_unprocessed       (<link linkend="GThreadPool">GThreadPool</link> *pool);</programlisting>
<para>
Returns the number of tasks still unprocessed in <parameter>pool</parameter>.</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"><emphasis>Returns</emphasis> :</entry><entry> the number of unprocessed tasks
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-free">g_thread_pool_free ()</title>
<programlisting>void        g_thread_pool_free              (<link linkend="GThreadPool">GThreadPool</link> *pool,
                                             <link linkend="gboolean">gboolean</link> immediate,
                                             <link linkend="gboolean">gboolean</link> wait);</programlisting>
<para>
Frees all resources allocated for <parameter>pool</parameter>.
</para>
<para>
If <parameter>immediate</parameter> is <literal>TRUE</literal>, no new task is processed for
<parameter>pool</parameter>. Otherwise <parameter>pool</parameter> is not freed before the last task is
processed. Note however, that no thread of this pool is
interrupted, while processing a task. Instead at least all still
running threads can finish their tasks before the <parameter>pool</parameter> is freed.
</para>
<para>
If <parameter>wait</parameter> is <literal>TRUE</literal>, the functions does not return before all tasks
to be processed (dependent on <parameter>immediate</parameter>, whether all or only the
currently running) are ready. Otherwise the function returns immediately.
</para>
<para>
After calling this function <parameter>pool</parameter> must not be used anymore.</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>immediate</parameter>&nbsp;:</entry>
<entry> should <parameter>pool</parameter> shut down immediately?
</entry></row>
<row><entry align="right"><parameter>wait</parameter>&nbsp;:</entry>
<entry> should the function wait for all tasks to be finished?
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-set-max-unused-threads">g_thread_pool_set_max_unused_threads ()</title>
<programlisting>void        g_thread_pool_set_max_unused_threads
                                            (<link linkend="gint">gint</link> max_threads);</programlisting>
<para>
Sets the maximal number of unused threads to <parameter>max_threads</parameter>. If
<parameter>max_threads</parameter> is -1, no limit is imposed on the number of unused
threads.</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>max_threads</parameter>&nbsp;:</entry>
<entry> maximal number of unused threads
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-get-max-unused-threads">g_thread_pool_get_max_unused_threads ()</title>
<programlisting><link linkend="gint">gint</link>        g_thread_pool_get_max_unused_threads
                                            (void);</programlisting>
<para>
Returns the maximal allowed number of unused threads.</para>
<para>

</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 maximal number of unused threads
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-get-num-unused-threads">g_thread_pool_get_num_unused_threads ()</title>
<programlisting><link linkend="guint">guint</link>       g_thread_pool_get_num_unused_threads
                                            (void);</programlisting>
<para>
Returns the number of currently unused threads.</para>
<para>

</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 number of currently unused threads
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-thread-pool-stop-unused-threads">g_thread_pool_stop_unused_threads ()</title>
<programlisting>void        g_thread_pool_stop_unused_threads
                                            (void);</programlisting>
<para>
Stops all currently unused threads. This does not change the
maximal number of unused threads. This function can be used to
regularly stop all unused threads e.g. from <link linkend="g-timeout-add">g_timeout_add</link>().</para>
<para>

</para></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<variablelist>

<varlistentry>
<term><link linkend="GThread">GThread</link></term>
<listitem><para>GLib thread system.</para></listitem>
</varlistentry>

</variablelist>
</para>
</refsect1>

</refentry>