<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="glib-Thread-Pools">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Thread-Pools.top_of_page">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>

<refsect1 id="glib-Thread-Pools.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GThreadPool"><returnvalue>GThreadPool</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-thread-pool-new">g_thread_pool_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-push">g_thread_pool_push</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-set-max-threads">g_thread_pool_set_max_threads</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-get-max-threads">g_thread_pool_get_max_threads</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-get-num-threads">g_thread_pool_get_num_threads</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-unprocessed">g_thread_pool_unprocessed</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-free">g_thread_pool_free</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-set-max-unused-threads">g_thread_pool_set_max_unused_threads</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-get-max-unused-threads">g_thread_pool_get_max_unused_threads</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-get-num-unused-threads">g_thread_pool_get_num_unused_threads</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-stop-unused-threads">g_thread_pool_stop_unused_threads</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-set-sort-function">g_thread_pool_set_sort_function</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-set-max-idle-time">g_thread_pool_set_max_idle_time</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-get-max-idle-time">g_thread_pool_get_max_idle_time</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-thread-pool-move-to-front">g_thread_pool_move_to_front</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="glib-Thread-Pools.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
<tbody>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GThreadPool">GThreadPool</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-Thread-Pools.includes"><title>Includes</title><synopsis>#include &lt;glib.h&gt;
</synopsis></refsect1>

<refsect1 id="glib-Thread-Pools.description" role="desc">
<title role="desc.title">Description</title>
<para>Sometimes you wish to asynchronously 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
too 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"><function>g_thread_pool_new()</function></link>.
It is destroyed by <link linkend="g-thread-pool-free"><function>g_thread_pool_free()</function></link>.</para>
<para>If you want to execute a certain task within a thread pool,
you call <link linkend="g-thread-pool-push"><function>g_thread_pool_push()</function></link>.</para>
<para>To get the current number of running threads you call
<link linkend="g-thread-pool-get-num-threads"><function>g_thread_pool_get_num_threads()</function></link>. To get the number of still
unprocessed tasks you call <link linkend="g-thread-pool-unprocessed"><function>g_thread_pool_unprocessed()</function></link>. To control
the maximal number of threads for a thread pool, you use
<link linkend="g-thread-pool-get-max-threads"><function>g_thread_pool_get_max_threads()</function></link> and <link linkend="g-thread-pool-set-max-threads"><function>g_thread_pool_set_max_threads()</function></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"><function>g_thread_pool_get_num_unused_threads()</function></link>. The maximal number can be
controlled by <link linkend="g-thread-pool-get-max-unused-threads"><function>g_thread_pool_get_max_unused_threads()</function></link> and
<link linkend="g-thread-pool-set-max-unused-threads"><function>g_thread_pool_set_max_unused_threads()</function></link>. All currently unused threads
can be stopped by calling <link linkend="g-thread-pool-stop-unused-threads"><function>g_thread_pool_stop_unused_threads()</function></link>.</para>

</refsect1>
<refsect1 id="glib-Thread-Pools.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-thread-pool-new" role="function">
<title>g_thread_pool_new&#160;()</title>
<indexterm zone="g-thread-pool-new"><primary sortas="thread_pool_new">g_thread_pool_new</primary></indexterm>
<programlisting language="C"><link linkend="GThreadPool"><returnvalue>GThreadPool</returnvalue></link>&#160;*
g_thread_pool_new (<parameter><link linkend="GFunc"><type>GFunc</type></link> func</parameter>,
                   <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>,
                   <parameter><link linkend="gint"><type>gint</type></link> max_threads</parameter>,
                   <parameter><link linkend="gboolean"><type>gboolean</type></link> exclusive</parameter>,
                   <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>This function creates a new thread pool.</para>
<para>Whenever you call <link linkend="g-thread-pool-push"><function>g_thread_pool_push()</function></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"><function>g_thread_pool_push()</function></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 shares them with other thread pools.
If <parameter>exclusive</parameter>
 is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, <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"><function>g_thread_pool_free()</function></link>. If <parameter>exclusive</parameter>
 is
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, 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. Besides, exclusive thread
pools are not affected by <link linkend="g-thread-pool-set-max-idle-time"><function>g_thread_pool_set_max_idle_time()</function></link>
since their threads are never considered idle and returned to the
global pool.</para>
<para><parameter>error</parameter>
 can be <link linkend="NULL:CAPS"><literal>NULL</literal></link> to ignore errors, or non-<link linkend="NULL:CAPS"><literal>NULL</literal></link> to report
errors. An error can only occur when <parameter>exclusive</parameter>
 is set to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>
and not all <parameter>max_threads</parameter>
 threads could be created.
See <link linkend="GThreadError"><type>GThreadError</type></link> for possible errors that may occur.
Note, even in case of error a valid <link linkend="GThreadPool"><type>GThreadPool</type></link> is returned.</para>
<refsect3 id="g-thread-pool-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>func</para></entry>
<entry role="parameter_description"><para>a function to execute in the threads of the new thread pool</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>user data that is handed over to <parameter>func</parameter>
every time it
is called</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>max_threads</para></entry>
<entry role="parameter_description"><para>the maximal number of threads to execute concurrently
in  the new thread pool, -1 means no limit</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>exclusive</para></entry>
<entry role="parameter_description"><para>should this thread pool be exclusive?</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-thread-pool-new.returns" role="returns">
<title>Returns</title>
<para> the new <link linkend="GThreadPool"><type>GThreadPool</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-push" role="function">
<title>g_thread_pool_push&#160;()</title>
<indexterm zone="g-thread-pool-push"><primary sortas="thread_pool_push">g_thread_pool_push</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_thread_pool_push (<parameter><link linkend="GThreadPool"><type>GThreadPool</type></link> *pool</parameter>,
                    <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>,
                    <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Inserts <parameter>data</parameter>
 into the list of tasks to be executed by <parameter>pool</parameter>
.</para>
<para>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"><function>g_thread_pool_new()</function></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 <link linkend="NULL:CAPS"><literal>NULL</literal></link> to ignore errors, or non-<link linkend="NULL:CAPS"><literal>NULL</literal></link> 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>Before version 2.32, this function did not return a success status.</para>
<refsect3 id="g-thread-pool-push.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pool</para></entry>
<entry role="parameter_description"><para>a <link linkend="GThreadPool"><type>GThreadPool</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>a new task for <parameter>pool</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-thread-pool-push.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred</para>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-set-max-threads" role="function">
<title>g_thread_pool_set_max_threads&#160;()</title>
<indexterm zone="g-thread-pool-set-max-threads"><primary sortas="thread_pool_set_max_threads">g_thread_pool_set_max_threads</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_thread_pool_set_max_threads (<parameter><link linkend="GThreadPool"><type>GThreadPool</type></link> *pool</parameter>,
                               <parameter><link linkend="gint"><type>gint</type></link> max_threads</parameter>,
                               <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</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. If <parameter>pool</parameter>
 is an exclusive thread pool, setting
the maximal number of threads to -1 is not allowed.</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"><function>g_thread_pool_new()</function></link>. Instead the maximal number of threads only
has effect for the allocation of new threads in <link linkend="g-thread-pool-push"><function>g_thread_pool_push()</function></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 <link linkend="NULL:CAPS"><literal>NULL</literal></link> to ignore errors, or non-<link linkend="NULL:CAPS"><literal>NULL</literal></link> to report
errors. An error can only occur when a new thread couldn't be
created.</para>
<para>Before version 2.32, this function did not return a success status.</para>
<refsect3 id="g-thread-pool-set-max-threads.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pool</para></entry>
<entry role="parameter_description"><para>a <link linkend="GThreadPool"><type>GThreadPool</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>max_threads</para></entry>
<entry role="parameter_description"><para>a new maximal number of threads for <parameter>pool</parameter>
,
or -1 for unlimited</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-thread-pool-set-max-threads.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred</para>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-get-max-threads" role="function">
<title>g_thread_pool_get_max_threads&#160;()</title>
<indexterm zone="g-thread-pool-get-max-threads"><primary sortas="thread_pool_get_max_threads">g_thread_pool_get_max_threads</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_thread_pool_get_max_threads (<parameter><link linkend="GThreadPool"><type>GThreadPool</type></link> *pool</parameter>);</programlisting>
<para>Returns the maximal number of threads for <parameter>pool</parameter>
.</para>
<refsect3 id="g-thread-pool-get-max-threads.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pool</para></entry>
<entry role="parameter_description"><para>a <link linkend="GThreadPool"><type>GThreadPool</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-thread-pool-get-max-threads.returns" role="returns">
<title>Returns</title>
<para> the maximal number of threads</para>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-get-num-threads" role="function">
<title>g_thread_pool_get_num_threads&#160;()</title>
<indexterm zone="g-thread-pool-get-num-threads"><primary sortas="thread_pool_get_num_threads">g_thread_pool_get_num_threads</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_thread_pool_get_num_threads (<parameter><link linkend="GThreadPool"><type>GThreadPool</type></link> *pool</parameter>);</programlisting>
<para>Returns the number of threads currently running in <parameter>pool</parameter>
.</para>
<refsect3 id="g-thread-pool-get-num-threads.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pool</para></entry>
<entry role="parameter_description"><para>a <link linkend="GThreadPool"><type>GThreadPool</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-thread-pool-get-num-threads.returns" role="returns">
<title>Returns</title>
<para> the number of threads currently running</para>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-unprocessed" role="function">
<title>g_thread_pool_unprocessed&#160;()</title>
<indexterm zone="g-thread-pool-unprocessed"><primary sortas="thread_pool_unprocessed">g_thread_pool_unprocessed</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_thread_pool_unprocessed (<parameter><link linkend="GThreadPool"><type>GThreadPool</type></link> *pool</parameter>);</programlisting>
<para>Returns the number of tasks still unprocessed in <parameter>pool</parameter>
.</para>
<refsect3 id="g-thread-pool-unprocessed.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pool</para></entry>
<entry role="parameter_description"><para>a <link linkend="GThreadPool"><type>GThreadPool</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-thread-pool-unprocessed.returns" role="returns">
<title>Returns</title>
<para> the number of unprocessed tasks</para>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-free" role="function">
<title>g_thread_pool_free&#160;()</title>
<indexterm zone="g-thread-pool-free"><primary sortas="thread_pool_free">g_thread_pool_free</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_thread_pool_free (<parameter><link linkend="GThreadPool"><type>GThreadPool</type></link> *pool</parameter>,
                    <parameter><link linkend="gboolean"><type>gboolean</type></link> immediate</parameter>,
                    <parameter><link linkend="gboolean"><type>gboolean</type></link> wait_</parameter>);</programlisting>
<para>Frees all resources allocated for <parameter>pool</parameter>
.</para>
<para>If <parameter>immediate</parameter>
 is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, 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 <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, 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>
<refsect3 id="g-thread-pool-free.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pool</para></entry>
<entry role="parameter_description"><para>a <link linkend="GThreadPool"><type>GThreadPool</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>immediate</para></entry>
<entry role="parameter_description"><para>should <parameter>pool</parameter>
shut down immediately?</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>wait_</para></entry>
<entry role="parameter_description"><para>should the function wait for all tasks to be finished?</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-set-max-unused-threads" role="function">
<title>g_thread_pool_set_max_unused_threads&#160;()</title>
<indexterm zone="g-thread-pool-set-max-unused-threads"><primary sortas="thread_pool_set_max_unused_threads">g_thread_pool_set_max_unused_threads</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_thread_pool_set_max_unused_threads (<parameter><link linkend="gint"><type>gint</type></link> max_threads</parameter>);</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>The default value is 2.</para>
<refsect3 id="g-thread-pool-set-max-unused-threads.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>max_threads</para></entry>
<entry role="parameter_description"><para>maximal number of unused threads</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-get-max-unused-threads" role="function">
<title>g_thread_pool_get_max_unused_threads&#160;()</title>
<indexterm zone="g-thread-pool-get-max-unused-threads"><primary sortas="thread_pool_get_max_unused_threads">g_thread_pool_get_max_unused_threads</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_thread_pool_get_max_unused_threads (<parameter><type>void</type></parameter>);</programlisting>
<para>Returns the maximal allowed number of unused threads.</para>
<refsect3 id="g-thread-pool-get-max-unused-threads.returns" role="returns">
<title>Returns</title>
<para> the maximal number of unused threads</para>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-get-num-unused-threads" role="function">
<title>g_thread_pool_get_num_unused_threads&#160;()</title>
<indexterm zone="g-thread-pool-get-num-unused-threads"><primary sortas="thread_pool_get_num_unused_threads">g_thread_pool_get_num_unused_threads</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_thread_pool_get_num_unused_threads (<parameter><type>void</type></parameter>);</programlisting>
<para>Returns the number of currently unused threads.</para>
<refsect3 id="g-thread-pool-get-num-unused-threads.returns" role="returns">
<title>Returns</title>
<para> the number of currently unused threads</para>
</refsect3></refsect2>
<refsect2 id="g-thread-pool-stop-unused-threads" role="function">
<title>g_thread_pool_stop_unused_threads&#160;()</title>
<indexterm zone="g-thread-pool-stop-unused-threads"><primary sortas="thread_pool_stop_unused_threads">g_thread_pool_stop_unused_threads</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_thread_pool_stop_unused_threads (<parameter><type>void</type></parameter>);</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"><function>g_timeout_add()</function></link>.</para>
</refsect2>
<refsect2 id="g-thread-pool-set-sort-function" role="function" condition="since:2.10">
<title>g_thread_pool_set_sort_function&#160;()</title>
<indexterm zone="g-thread-pool-set-sort-function" role="2.10"><primary sortas="thread_pool_set_sort_function">g_thread_pool_set_sort_function</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_thread_pool_set_sort_function (<parameter><link linkend="GThreadPool"><type>GThreadPool</type></link> *pool</parameter>,
                                 <parameter><link linkend="GCompareDataFunc"><type>GCompareDataFunc</type></link> func</parameter>,
                                 <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</programlisting>
<para>Sets the function used to sort the list of tasks. This allows the
tasks to be processed by a priority determined by <parameter>func</parameter>
, and not
just in the order in which they were added to the pool.</para>
<para>Note, if the maximum number of threads is more than 1, the order
that threads are executed cannot be guaranteed 100%. Threads are
scheduled by the operating system and are executed at random. It
cannot be assumed that threads are executed in the order they are
created.</para>
<refsect3 id="g-thread-pool-set-sort-function.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pool</para></entry>
<entry role="parameter_description"><para>a <link linkend="GThreadPool"><type>GThreadPool</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>func</para></entry>
<entry role="parameter_description"><para>the <link linkend="GCompareDataFunc"><type>GCompareDataFunc</type></link> used to sort the list of tasks.
This function is passed two tasks. It should return
0 if the order in which they are handled does not matter,
a negative value if the first task should be processed before
the second or a positive value if the second task should be
processed first.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>user data passed to <parameter>func</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.10">2.10</link></para></refsect2>
<refsect2 id="g-thread-pool-set-max-idle-time" role="function" condition="since:2.10">
<title>g_thread_pool_set_max_idle_time&#160;()</title>
<indexterm zone="g-thread-pool-set-max-idle-time" role="2.10"><primary sortas="thread_pool_set_max_idle_time">g_thread_pool_set_max_idle_time</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_thread_pool_set_max_idle_time (<parameter><link linkend="guint"><type>guint</type></link> interval</parameter>);</programlisting>
<para>This function will set the maximum <parameter>interval</parameter>
 that a thread
waiting in the pool for new tasks can be idle for before
being stopped. This function is similar to calling
<link linkend="g-thread-pool-stop-unused-threads"><function>g_thread_pool_stop_unused_threads()</function></link> on a regular timeout,
except this is done on a per thread basis.</para>
<para>By setting <parameter>interval</parameter>
 to 0, idle threads will not be stopped.</para>
<para>The default value is 15000 (15 seconds).</para>
<refsect3 id="g-thread-pool-set-max-idle-time.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>interval</para></entry>
<entry role="parameter_description"><para>the maximum <parameter>interval</parameter>
(in milliseconds)
a thread can be idle</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.10">2.10</link></para></refsect2>
<refsect2 id="g-thread-pool-get-max-idle-time" role="function" condition="since:2.10">
<title>g_thread_pool_get_max_idle_time&#160;()</title>
<indexterm zone="g-thread-pool-get-max-idle-time" role="2.10"><primary sortas="thread_pool_get_max_idle_time">g_thread_pool_get_max_idle_time</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_thread_pool_get_max_idle_time (<parameter><type>void</type></parameter>);</programlisting>
<para>This function will return the maximum <parameter>interval</parameter>
 that a
thread will wait in the thread pool for new tasks before
being stopped.</para>
<para>If this function returns 0, threads waiting in the thread
pool for new work are not stopped.</para>
<refsect3 id="g-thread-pool-get-max-idle-time.returns" role="returns">
<title>Returns</title>
<para> the maximum <parameter>interval</parameter>
(milliseconds) to wait
for new tasks in the thread pool before stopping the
thread</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.10">2.10</link></para></refsect2>
<refsect2 id="g-thread-pool-move-to-front" role="function" condition="since:2.46">
<title>g_thread_pool_move_to_front&#160;()</title>
<indexterm zone="g-thread-pool-move-to-front" role="2.46"><primary sortas="thread_pool_move_to_front">g_thread_pool_move_to_front</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_thread_pool_move_to_front (<parameter><link linkend="GThreadPool"><type>GThreadPool</type></link> *pool</parameter>,
                             <parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</programlisting>
<para>Moves the item to the front of the queue of unprocessed
items, so that it will be processed next.</para>
<refsect3 id="g-thread-pool-move-to-front.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pool</para></entry>
<entry role="parameter_description"><para>a <link linkend="GThreadPool"><type>GThreadPool</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>an unprocessed item in the pool</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-thread-pool-move-to-front.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the item was found and moved</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.46">2.46</link></para></refsect2>

</refsect1>
<refsect1 id="glib-Thread-Pools.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GThreadPool" role="struct">
<title>struct GThreadPool</title>
<indexterm zone="GThreadPool"><primary sortas="ThreadPool">GThreadPool</primary></indexterm>
<programlisting language="C">struct GThreadPool {
  GFunc func;
  gpointer user_data;
  gboolean exclusive;
};
</programlisting>
<para>The <link linkend="GThreadPool"><type>GThreadPool</type></link> struct represents a thread pool. It has three
public read-only members, but the underlying struct is bigger,
so you must not copy this struct.</para>
<refsect3 id="GThreadPool.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><link linkend="GFunc"><type>GFunc</type></link>&#160;<structfield id="GThreadPool.func">func</structfield>;</para></entry>
<entry role="struct_member_description"><para>the function to execute in the threads of this pool</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="gpointer"><type>gpointer</type></link>&#160;<structfield id="GThreadPool.user-data">user_data</structfield>;</para></entry>
<entry role="struct_member_description"><para>the user data for the threads of this pool</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="gboolean"><type>gboolean</type></link>&#160;<structfield id="GThreadPool.exclusive">exclusive</structfield>;</para></entry>
<entry role="struct_member_description"><para>are all threads exclusive to this pool</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>

</refsect1>
<refsect1 id="glib-Thread-Pools.see-also">
<title>See Also</title>
<para><link linkend="GThread"><type>GThread</type></link></para>

</refsect1>

</refentry>
