docs/reference/glib/html/glib-Thread-Pools.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Thread Pools</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-core.html" title="GLib Core Application Support">
   9 <link rel="prev" href="glib-Threads.html" title="Threads">
  10 <link rel="next" href="glib-Asynchronous-Queues.html" title="Asynchronous Queues">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-Threads.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-Asynchronous-Queues.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-Thread-Pools.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Thread-Pools.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-Thread-Pools"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-Thread-Pools.top_of_page"></a>Thread Pools</span></h2>
  34 <p>Thread Pools — pools of threads to execute work concurrently</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="glib-Thread-Pools.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;glib.h&gt;
  42
  43 struct              <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool">GThreadPool</a>;
  44 <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="returnvalue">GThreadPool</span></a> *       <a class="link" href="glib-Thread-Pools.html#g-thread-pool-new" title="g_thread_pool_new ()">g_thread_pool_new</a>                   (<em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GFunc" title="GFunc ()"><span class="type">GFunc</span></a> func</code></em>,
  45                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
  46                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_threads</code></em>,
  47                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> exclusive</code></em>,
  48                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  49 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Thread-Pools.html#g-thread-pool-push" title="g_thread_pool_push ()">g_thread_pool_push</a>                  (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>,
  50                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
  51                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  52 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Thread-Pools.html#g-thread-pool-set-max-threads" title="g_thread_pool_set_max_threads ()">g_thread_pool_set_max_threads</a>       (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>,
  53                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_threads</code></em>,
  54                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  55 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-Thread-Pools.html#g-thread-pool-get-max-threads" title="g_thread_pool_get_max_threads ()">g_thread_pool_get_max_threads</a>       (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>);
  56 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Thread-Pools.html#g-thread-pool-get-num-threads" title="g_thread_pool_get_num_threads ()">g_thread_pool_get_num_threads</a>       (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>);
  57 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Thread-Pools.html#g-thread-pool-unprocessed" title="g_thread_pool_unprocessed ()">g_thread_pool_unprocessed</a>           (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>);
  58 <span class="returnvalue">void</span>                <a class="link" href="glib-Thread-Pools.html#g-thread-pool-free" title="g_thread_pool_free ()">g_thread_pool_free</a>                  (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>,
  59                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> immediate</code></em>,
  60                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> wait_</code></em>);
  61 <span class="returnvalue">void</span>                <a class="link" href="glib-Thread-Pools.html#g-thread-pool-set-max-unused-threads" title="g_thread_pool_set_max_unused_threads ()">g_thread_pool_set_max_unused_threads</a>
  62                                                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_threads</code></em>);
  63 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-Thread-Pools.html#g-thread-pool-get-max-unused-threads" title="g_thread_pool_get_max_unused_threads ()">g_thread_pool_get_max_unused_threads</a>
  64                                                         (<em class="parameter"><code><span class="type">void</span></code></em>);
  65 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Thread-Pools.html#g-thread-pool-get-num-unused-threads" title="g_thread_pool_get_num_unused_threads ()">g_thread_pool_get_num_unused_threads</a>
  66                                                         (<em class="parameter"><code><span class="type">void</span></code></em>);
  67 <span class="returnvalue">void</span>                <a class="link" href="glib-Thread-Pools.html#g-thread-pool-stop-unused-threads" title="g_thread_pool_stop_unused_threads ()">g_thread_pool_stop_unused_threads</a>   (<em class="parameter"><code><span class="type">void</span></code></em>);
  68 <span class="returnvalue">void</span>                <a class="link" href="glib-Thread-Pools.html#g-thread-pool-set-sort-function" title="g_thread_pool_set_sort_function ()">g_thread_pool_set_sort_function</a>     (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>,
  69                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
  70                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  71 <span class="returnvalue">void</span>                <a class="link" href="glib-Thread-Pools.html#g-thread-pool-set-max-idle-time" title="g_thread_pool_set_max_idle_time ()">g_thread_pool_set_max_idle_time</a>     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> interval</code></em>);
  72 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Thread-Pools.html#g-thread-pool-get-max-idle-time" title="g_thread_pool_get_max_idle_time ()">g_thread_pool_get_max_idle_time</a>     (<em class="parameter"><code><span class="type">void</span></code></em>);
  73 </pre>
  74 </div>
  75 <div class="refsect1">
  76 <a name="glib-Thread-Pools.description"></a><h2>Description</h2>
  77 <p>
  78 Sometimes you wish to asynchronously fork out the execution of work
  79 and continue working in your own thread. If that will happen often,
  80 the overhead of starting and destroying a thread each time might be
  81 too high. In such cases reusing already started threads seems like a
  82 good idea. And it indeed is, but implementing this can be tedious
  83 and error-prone.
  84 </p>
  85 <p>
  86 Therefore GLib provides thread pools for your convenience. An added
  87 advantage is, that the threads can be shared between the different
  88 subsystems of your program, when they are using GLib.
  89 </p>
  90 <p>
  91 To create a new thread pool, you use <a class="link" href="glib-Thread-Pools.html#g-thread-pool-new" title="g_thread_pool_new ()"><code class="function">g_thread_pool_new()</code></a>.
  92 It is destroyed by <a class="link" href="glib-Thread-Pools.html#g-thread-pool-free" title="g_thread_pool_free ()"><code class="function">g_thread_pool_free()</code></a>.
  93 </p>
  94 <p>
  95 If you want to execute a certain task within a thread pool,
  96 you call <a class="link" href="glib-Thread-Pools.html#g-thread-pool-push" title="g_thread_pool_push ()"><code class="function">g_thread_pool_push()</code></a>.
  97 </p>
  98 <p>
  99 To get the current number of running threads you call
 100 <a class="link" href="glib-Thread-Pools.html#g-thread-pool-get-num-threads" title="g_thread_pool_get_num_threads ()"><code class="function">g_thread_pool_get_num_threads()</code></a>. To get the number of still
 101 unprocessed tasks you call <a class="link" href="glib-Thread-Pools.html#g-thread-pool-unprocessed" title="g_thread_pool_unprocessed ()"><code class="function">g_thread_pool_unprocessed()</code></a>. To control
 102 the maximal number of threads for a thread pool, you use
 103 <a class="link" href="glib-Thread-Pools.html#g-thread-pool-get-max-threads" title="g_thread_pool_get_max_threads ()"><code class="function">g_thread_pool_get_max_threads()</code></a> and <a class="link" href="glib-Thread-Pools.html#g-thread-pool-set-max-threads" title="g_thread_pool_set_max_threads ()"><code class="function">g_thread_pool_set_max_threads()</code></a>.
 104 </p>
 105 <p>
 106 Finally you can control the number of unused threads, that are kept
 107 alive by GLib for future use. The current number can be fetched with
 108 <a class="link" href="glib-Thread-Pools.html#g-thread-pool-get-num-unused-threads" title="g_thread_pool_get_num_unused_threads ()"><code class="function">g_thread_pool_get_num_unused_threads()</code></a>. The maximal number can be
 109 controlled by <a class="link" href="glib-Thread-Pools.html#g-thread-pool-get-max-unused-threads" title="g_thread_pool_get_max_unused_threads ()"><code class="function">g_thread_pool_get_max_unused_threads()</code></a> and
 110 <a class="link" href="glib-Thread-Pools.html#g-thread-pool-set-max-unused-threads" title="g_thread_pool_set_max_unused_threads ()"><code class="function">g_thread_pool_set_max_unused_threads()</code></a>. All currently unused threads
 111 can be stopped by calling <a class="link" href="glib-Thread-Pools.html#g-thread-pool-stop-unused-threads" title="g_thread_pool_stop_unused_threads ()"><code class="function">g_thread_pool_stop_unused_threads()</code></a>.
 112 </p>
 113 </div>
 114 <div class="refsect1">
 115 <a name="glib-Thread-Pools.details"></a><h2>Details</h2>
 116 <div class="refsect2">
 117 <a name="GThreadPool"></a><h3>struct GThreadPool</h3>
 118 <pre class="programlisting">struct GThreadPool {
 119   GFunc func;
 120   gpointer user_data;
 121   gboolean exclusive;
 122 };
 123 </pre>
 124 <p>
 125 The <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> struct represents a thread pool. It has three
 126 public read-only members, but the underlying struct is bigger,
 127 so you must not copy this struct.
 128 </p>
 129 <div class="variablelist"><table border="0">
 130 <col align="left" valign="top">
 131 <tbody>
 132 <tr>
 133 <td><p><span class="term"><a class="link" href="glib-Doubly-Linked-Lists.html#GFunc" title="GFunc ()"><span class="type">GFunc</span></a> <em class="structfield"><code><a name="GThreadPool.func"></a>func</code></em>;</span></p></td>
 134 <td>the function to execute in the threads of this pool</td>
 135 </tr>
 136 <tr>
 137 <td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> <em class="structfield"><code><a name="GThreadPool.user-data"></a>user_data</code></em>;</span></p></td>
 138 <td>the user data for the threads of this pool</td>
 139 </tr>
 140 <tr>
 141 <td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> <em class="structfield"><code><a name="GThreadPool.exclusive"></a>exclusive</code></em>;</span></p></td>
 142 <td>are all threads exclusive to this pool</td>
 143 </tr>
 144 </tbody>
 145 </table></div>
 146 </div>
 147 <hr>
 148 <div class="refsect2">
 149 <a name="g-thread-pool-new"></a><h3>g_thread_pool_new ()</h3>
 150 <pre class="programlisting"><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="returnvalue">GThreadPool</span></a> *       g_thread_pool_new                   (<em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GFunc" title="GFunc ()"><span class="type">GFunc</span></a> func</code></em>,
 151                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
 152                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_threads</code></em>,
 153                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> exclusive</code></em>,
 154                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 155 <p>
 156 This function creates a new thread pool.
 157 </p>
 158 <p>
 159 Whenever you call <a class="link" href="glib-Thread-Pools.html#g-thread-pool-push" title="g_thread_pool_push ()"><code class="function">g_thread_pool_push()</code></a>, either a new thread is
 160 created or an unused one is reused. At most <em class="parameter"><code>max_threads</code></em> threads
 161 are running concurrently for this thread pool. <em class="parameter"><code>max_threads</code></em> = -1
 162 allows unlimited threads to be created for this thread pool. The
 163 newly created or reused thread now executes the function <em class="parameter"><code>func</code></em>
 164 with the two arguments. The first one is the parameter to
 165 <a class="link" href="glib-Thread-Pools.html#g-thread-pool-push" title="g_thread_pool_push ()"><code class="function">g_thread_pool_push()</code></a> and the second one is <em class="parameter"><code>user_data</code></em>.
 166 </p>
 167 <p>
 168 The parameter <em class="parameter"><code>exclusive</code></em> determines whether the thread pool owns
 169 all threads exclusive or shares them with other thread pools.
 170 If <em class="parameter"><code>exclusive</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, <em class="parameter"><code>max_threads</code></em> threads are started
 171 immediately and they will run exclusively for this thread pool
 172 until it is destroyed by <a class="link" href="glib-Thread-Pools.html#g-thread-pool-free" title="g_thread_pool_free ()"><code class="function">g_thread_pool_free()</code></a>. If <em class="parameter"><code>exclusive</code></em> is
 173 <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>, threads are created when needed and shared between all
 174 non-exclusive thread pools. This implies that <em class="parameter"><code>max_threads</code></em> may
 175 not be -1 for exclusive thread pools.
 176 </p>
 177 <p>
 178 <em class="parameter"><code>error</code></em> can be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore errors, or non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to report
 179 errors. An error can only occur when <em class="parameter"><code>exclusive</code></em> is set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>
 180 and not all <em class="parameter"><code>max_threads</code></em> threads could be created.
 181 </p>
 182 <div class="variablelist"><table border="0">
 183 <col align="left" valign="top">
 184 <tbody>
 185 <tr>
 186 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 187 <td>a function to execute in the threads of the new thread pool</td>
 188 </tr>
 189 <tr>
 190 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 191 <td>user data that is handed over to <em class="parameter"><code>func</code></em> every time it
 192 is called</td>
 193 </tr>
 194 <tr>
 195 <td><p><span class="term"><em class="parameter"><code>max_threads</code></em> :</span></p></td>
 196 <td>the maximal number of threads to execute concurrently
 197 in  the new thread pool, -1 means no limit</td>
 198 </tr>
 199 <tr>
 200 <td><p><span class="term"><em class="parameter"><code>exclusive</code></em> :</span></p></td>
 201 <td>should this thread pool be exclusive?</td>
 202 </tr>
 203 <tr>
 204 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 205 <td>return location for error, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 206 </td>
 207 </tr>
 208 <tr>
 209 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 210 <td>the new <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>
 211 </td>
 212 </tr>
 213 </tbody>
 214 </table></div>
 215 </div>
 216 <hr>
 217 <div class="refsect2">
 218 <a name="g-thread-pool-push"></a><h3>g_thread_pool_push ()</h3>
 219 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_thread_pool_push                  (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>,
 220                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
 221                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 222 <p>
 223 Inserts <em class="parameter"><code>data</code></em> into the list of tasks to be executed by <em class="parameter"><code>pool</code></em>.
 224 </p>
 225 <p>
 226 When the number of currently running threads is lower than the
 227 maximal allowed number of threads, a new thread is started (or
 228 reused) with the properties given to <a class="link" href="glib-Thread-Pools.html#g-thread-pool-new" title="g_thread_pool_new ()"><code class="function">g_thread_pool_new()</code></a>.
 229 Otherwise, <em class="parameter"><code>data</code></em> stays in the queue until a thread in this pool
 230 finishes its previous task and processes <em class="parameter"><code>data</code></em>.
 231 </p>
 232 <p>
 233 <em class="parameter"><code>error</code></em> can be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore errors, or non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to report
 234 errors. An error can only occur when a new thread couldn't be
 235 created. In that case <em class="parameter"><code>data</code></em> is simply appended to the queue of
 236 work to do.
 237 </p>
 238 <p>
 239 Before version 2.32, this function did not return a success status.
 240 </p>
 241 <div class="variablelist"><table border="0">
 242 <col align="left" valign="top">
 243 <tbody>
 244 <tr>
 245 <td><p><span class="term"><em class="parameter"><code>pool</code></em> :</span></p></td>
 246 <td>a <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>
 247 </td>
 248 </tr>
 249 <tr>
 250 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 251 <td>a new task for <em class="parameter"><code>pool</code></em>
 252 </td>
 253 </tr>
 254 <tr>
 255 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 256 <td>return location for error, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 257 </td>
 258 </tr>
 259 <tr>
 260 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 261 <td>
 262 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> on success, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if an error occurred</td>
 263 </tr>
 264 </tbody>
 265 </table></div>
 266 </div>
 267 <hr>
 268 <div class="refsect2">
 269 <a name="g-thread-pool-set-max-threads"></a><h3>g_thread_pool_set_max_threads ()</h3>
 270 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_thread_pool_set_max_threads       (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>,
 271                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_threads</code></em>,
 272                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 273 <p>
 274 Sets the maximal allowed number of threads for <em class="parameter"><code>pool</code></em>.
 275 A value of -1 means that the maximal number of threads
 276 is unlimited. If <em class="parameter"><code>pool</code></em> is an exclusive thread pool, setting
 277 the maximal number of threads to -1 is not allowed.
 278 </p>
 279 <p>
 280 Setting <em class="parameter"><code>max_threads</code></em> to 0 means stopping all work for <em class="parameter"><code>pool</code></em>.
 281 It is effectively frozen until <em class="parameter"><code>max_threads</code></em> is set to a non-zero
 282 value again.
 283 </p>
 284 <p>
 285 A thread is never terminated while calling <em class="parameter"><code>func</code></em>, as supplied by
 286 <a class="link" href="glib-Thread-Pools.html#g-thread-pool-new" title="g_thread_pool_new ()"><code class="function">g_thread_pool_new()</code></a>. Instead the maximal number of threads only
 287 has effect for the allocation of new threads in <a class="link" href="glib-Thread-Pools.html#g-thread-pool-push" title="g_thread_pool_push ()"><code class="function">g_thread_pool_push()</code></a>.
 288 A new thread is allocated, whenever the number of currently
 289 running threads in <em class="parameter"><code>pool</code></em> is smaller than the maximal number.
 290 </p>
 291 <p>
 292 <em class="parameter"><code>error</code></em> can be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore errors, or non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to report
 293 errors. An error can only occur when a new thread couldn't be
 294 created.
 295 </p>
 296 <p>
 297 Before version 2.32, this function did not return a success status.
 298 </p>
 299 <div class="variablelist"><table border="0">
 300 <col align="left" valign="top">
 301 <tbody>
 302 <tr>
 303 <td><p><span class="term"><em class="parameter"><code>pool</code></em> :</span></p></td>
 304 <td>a <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>
 305 </td>
 306 </tr>
 307 <tr>
 308 <td><p><span class="term"><em class="parameter"><code>max_threads</code></em> :</span></p></td>
 309 <td>a new maximal number of threads for <em class="parameter"><code>pool</code></em>,
 310 or -1 for unlimited</td>
 311 </tr>
 312 <tr>
 313 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 314 <td>return location for error, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 315 </td>
 316 </tr>
 317 <tr>
 318 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 319 <td>
 320 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> on success, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if an error occurred</td>
 321 </tr>
 322 </tbody>
 323 </table></div>
 324 </div>
 325 <hr>
 326 <div class="refsect2">
 327 <a name="g-thread-pool-get-max-threads"></a><h3>g_thread_pool_get_max_threads ()</h3>
 328 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_thread_pool_get_max_threads       (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>);</pre>
 329 <p>
 330 Returns the maximal number of threads for <em class="parameter"><code>pool</code></em>.
 331 </p>
 332 <div class="variablelist"><table border="0">
 333 <col align="left" valign="top">
 334 <tbody>
 335 <tr>
 336 <td><p><span class="term"><em class="parameter"><code>pool</code></em> :</span></p></td>
 337 <td>a <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>
 338 </td>
 339 </tr>
 340 <tr>
 341 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 342 <td>the maximal number of threads</td>
 343 </tr>
 344 </tbody>
 345 </table></div>
 346 </div>
 347 <hr>
 348 <div class="refsect2">
 349 <a name="g-thread-pool-get-num-threads"></a><h3>g_thread_pool_get_num_threads ()</h3>
 350 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_thread_pool_get_num_threads       (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>);</pre>
 351 <p>
 352 Returns the number of threads currently running in <em class="parameter"><code>pool</code></em>.
 353 </p>
 354 <div class="variablelist"><table border="0">
 355 <col align="left" valign="top">
 356 <tbody>
 357 <tr>
 358 <td><p><span class="term"><em class="parameter"><code>pool</code></em> :</span></p></td>
 359 <td>a <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>
 360 </td>
 361 </tr>
 362 <tr>
 363 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 364 <td>the number of threads currently running</td>
 365 </tr>
 366 </tbody>
 367 </table></div>
 368 </div>
 369 <hr>
 370 <div class="refsect2">
 371 <a name="g-thread-pool-unprocessed"></a><h3>g_thread_pool_unprocessed ()</h3>
 372 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_thread_pool_unprocessed           (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>);</pre>
 373 <p>
 374 Returns the number of tasks still unprocessed in <em class="parameter"><code>pool</code></em>.
 375 </p>
 376 <div class="variablelist"><table border="0">
 377 <col align="left" valign="top">
 378 <tbody>
 379 <tr>
 380 <td><p><span class="term"><em class="parameter"><code>pool</code></em> :</span></p></td>
 381 <td>a <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>
 382 </td>
 383 </tr>
 384 <tr>
 385 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 386 <td>the number of unprocessed tasks</td>
 387 </tr>
 388 </tbody>
 389 </table></div>
 390 </div>
 391 <hr>
 392 <div class="refsect2">
 393 <a name="g-thread-pool-free"></a><h3>g_thread_pool_free ()</h3>
 394 <pre class="programlisting"><span class="returnvalue">void</span>                g_thread_pool_free                  (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>,
 395                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> immediate</code></em>,
 396                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> wait_</code></em>);</pre>
 397 <p>
 398 Frees all resources allocated for <em class="parameter"><code>pool</code></em>.
 399 </p>
 400 <p>
 401 If <em class="parameter"><code>immediate</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, no new task is processed for <em class="parameter"><code>pool</code></em>.
 402 Otherwise <em class="parameter"><code>pool</code></em> is not freed before the last task is processed.
 403 Note however, that no thread of this pool is interrupted while
 404 processing a task. Instead at least all still running threads
 405 can finish their tasks before the <em class="parameter"><code>pool</code></em> is freed.
 406 </p>
 407 <p>
 408 If <em class="parameter"><code>wait_</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, the functions does not return before all
 409 tasks to be processed (dependent on <em class="parameter"><code>immediate</code></em>, whether all
 410 or only the currently running) are ready.
 411 Otherwise the function returns immediately.
 412 </p>
 413 <p>
 414 After calling this function <em class="parameter"><code>pool</code></em> must not be used anymore.
 415 </p>
 416 <div class="variablelist"><table border="0">
 417 <col align="left" valign="top">
 418 <tbody>
 419 <tr>
 420 <td><p><span class="term"><em class="parameter"><code>pool</code></em> :</span></p></td>
 421 <td>a <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>
 422 </td>
 423 </tr>
 424 <tr>
 425 <td><p><span class="term"><em class="parameter"><code>immediate</code></em> :</span></p></td>
 426 <td>should <em class="parameter"><code>pool</code></em> shut down immediately?</td>
 427 </tr>
 428 <tr>
 429 <td><p><span class="term"><em class="parameter"><code>wait_</code></em> :</span></p></td>
 430 <td>should the function wait for all tasks to be finished?</td>
 431 </tr>
 432 </tbody>
 433 </table></div>
 434 </div>
 435 <hr>
 436 <div class="refsect2">
 437 <a name="g-thread-pool-set-max-unused-threads"></a><h3>g_thread_pool_set_max_unused_threads ()</h3>
 438 <pre class="programlisting"><span class="returnvalue">void</span>                g_thread_pool_set_max_unused_threads
 439                                                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_threads</code></em>);</pre>
 440 <p>
 441 Sets the maximal number of unused threads to <em class="parameter"><code>max_threads</code></em>.
 442 If <em class="parameter"><code>max_threads</code></em> is -1, no limit is imposed on the number
 443 of unused threads.
 444 </p>
 445 <div class="variablelist"><table border="0">
 446 <col align="left" valign="top">
 447 <tbody><tr>
 448 <td><p><span class="term"><em class="parameter"><code>max_threads</code></em> :</span></p></td>
 449 <td>maximal number of unused threads</td>
 450 </tr></tbody>
 451 </table></div>
 452 </div>
 453 <hr>
 454 <div class="refsect2">
 455 <a name="g-thread-pool-get-max-unused-threads"></a><h3>g_thread_pool_get_max_unused_threads ()</h3>
 456 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_thread_pool_get_max_unused_threads
 457                                                         (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 458 <p>
 459 Returns the maximal allowed number of unused threads.
 460 </p>
 461 <div class="variablelist"><table border="0">
 462 <col align="left" valign="top">
 463 <tbody><tr>
 464 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 465 <td>the maximal number of unused threads</td>
 466 </tr></tbody>
 467 </table></div>
 468 </div>
 469 <hr>
 470 <div class="refsect2">
 471 <a name="g-thread-pool-get-num-unused-threads"></a><h3>g_thread_pool_get_num_unused_threads ()</h3>
 472 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_thread_pool_get_num_unused_threads
 473                                                         (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 474 <p>
 475 Returns the number of currently unused threads.
 476 </p>
 477 <div class="variablelist"><table border="0">
 478 <col align="left" valign="top">
 479 <tbody><tr>
 480 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 481 <td>the number of currently unused threads</td>
 482 </tr></tbody>
 483 </table></div>
 484 </div>
 485 <hr>
 486 <div class="refsect2">
 487 <a name="g-thread-pool-stop-unused-threads"></a><h3>g_thread_pool_stop_unused_threads ()</h3>
 488 <pre class="programlisting"><span class="returnvalue">void</span>                g_thread_pool_stop_unused_threads   (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 489 <p>
 490 Stops all currently unused threads. This does not change the
 491 maximal number of unused threads. This function can be used to
 492 regularly stop all unused threads e.g. from <a class="link" href="glib-The-Main-Event-Loop.html#g-timeout-add" title="g_timeout_add ()"><code class="function">g_timeout_add()</code></a>.
 493 </p>
 494 </div>
 495 <hr>
 496 <div class="refsect2">
 497 <a name="g-thread-pool-set-sort-function"></a><h3>g_thread_pool_set_sort_function ()</h3>
 498 <pre class="programlisting"><span class="returnvalue">void</span>                g_thread_pool_set_sort_function     (<em class="parameter"><code><a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> *pool</code></em>,
 499                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
 500                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 501 <p>
 502 Sets the function used to sort the list of tasks. This allows the
 503 tasks to be processed by a priority determined by <em class="parameter"><code>func</code></em>, and not
 504 just in the order in which they were added to the pool.
 505 </p>
 506 <p>
 507 Note, if the maximum number of threads is more than 1, the order
 508 that threads are executed cannot be guaranteed 100%. Threads are
 509 scheduled by the operating system and are executed at random. It
 510 cannot be assumed that threads are executed in the order they are
 511 created.
 512 </p>
 513 <div class="variablelist"><table border="0">
 514 <col align="left" valign="top">
 515 <tbody>
 516 <tr>
 517 <td><p><span class="term"><em class="parameter"><code>pool</code></em> :</span></p></td>
 518 <td>a <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>
 519 </td>
 520 </tr>
 521 <tr>
 522 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 523 <td>the <a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> used to sort the list of tasks.
 524 This function is passed two tasks. It should return
 525 0 if the order in which they are handled does not matter,
 526 a negative value if the first task should be processed before
 527 the second or a positive value if the second task should be
 528 processed first.</td>
 529 </tr>
 530 <tr>
 531 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 532 <td>user data passed to <em class="parameter"><code>func</code></em>
 533 </td>
 534 </tr>
 535 </tbody>
 536 </table></div>
 537 <p class="since">Since 2.10</p>
 538 </div>
 539 <hr>
 540 <div class="refsect2">
 541 <a name="g-thread-pool-set-max-idle-time"></a><h3>g_thread_pool_set_max_idle_time ()</h3>
 542 <pre class="programlisting"><span class="returnvalue">void</span>                g_thread_pool_set_max_idle_time     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> interval</code></em>);</pre>
 543 <p>
 544 This function will set the maximum <em class="parameter"><code>interval</code></em> that a thread
 545 waiting in the pool for new tasks can be idle for before
 546 being stopped. This function is similar to calling
 547 <a class="link" href="glib-Thread-Pools.html#g-thread-pool-stop-unused-threads" title="g_thread_pool_stop_unused_threads ()"><code class="function">g_thread_pool_stop_unused_threads()</code></a> on a regular timeout,
 548 except this is done on a per thread basis.
 549 </p>
 550 <p>
 551 By setting <em class="parameter"><code>interval</code></em> to 0, idle threads will not be stopped.
 552 </p>
 553 <p>
 554 This function makes use of <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-timed-pop" title="g_async_queue_timed_pop ()"><code class="function">g_async_queue_timed_pop()</code></a> using
 555 <em class="parameter"><code>interval</code></em>.
 556 </p>
 557 <div class="variablelist"><table border="0">
 558 <col align="left" valign="top">
 559 <tbody><tr>
 560 <td><p><span class="term"><em class="parameter"><code>interval</code></em> :</span></p></td>
 561 <td>the maximum <em class="parameter"><code>interval</code></em> (in milliseconds)
 562 a thread can be idle</td>
 563 </tr></tbody>
 564 </table></div>
 565 <p class="since">Since 2.10</p>
 566 </div>
 567 <hr>
 568 <div class="refsect2">
 569 <a name="g-thread-pool-get-max-idle-time"></a><h3>g_thread_pool_get_max_idle_time ()</h3>
 570 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_thread_pool_get_max_idle_time     (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 571 <p>
 572 This function will return the maximum <em class="parameter"><code>interval</code></em> that a
 573 thread will wait in the thread pool for new tasks before
 574 being stopped.
 575 </p>
 576 <p>
 577 If this function returns 0, threads waiting in the thread
 578 pool for new work are not stopped.
 579 </p>
 580 <div class="variablelist"><table border="0">
 581 <col align="left" valign="top">
 582 <tbody><tr>
 583 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 584 <td>the maximum <em class="parameter"><code>interval</code></em> (milliseconds) to wait
 585 for new tasks in the thread pool before stopping the
 586 thread</td>
 587 </tr></tbody>
 588 </table></div>
 589 <p class="since">Since 2.10</p>
 590 </div>
 591 </div>
 592 <div class="refsect1">
 593 <a name="glib-Thread-Pools.see-also"></a><h2>See Also</h2>
 594 <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a>
 595 </div>
 596 </div>
 597 <div class="footer">
 598 <hr>
 599           Generated by GTK-Doc V1.18</div>
 600 </body>
 601 </html>