docs/reference/glib/tmpl/thread_pools.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Thread Pools
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 pools of threads to execute work concurrently
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Sometimes you wish to asynchronously fork out the execution of work and
  10 continue working in your own thread. If that will happen often, the
  11 overhead of starting and destroying a thread each time might be too
  12 high. In such cases reusing already started threads seems like a good
  13 idea. And it indeed is, but implementing this can be tedious and
  14 error-prone.
  15 </para>
  16
  17 <para>
  18 Therefore GLib provides thread pools for your convenience. An added
  19 advantage is, that the threads can be shared between the different
  20 subsystems of your program, when they are using GLib.
  21 </para>
  22
  23 <para>
  24 To create a new thread pool, you use g_thread_pool_new(). It is
  25 destroyed by g_thread_pool_free().
  26 </para>
  27
  28 <para>
  29 If you want to execute a certain task within a thread pool, you call
  30 g_thread_pool_push().
  31 </para>
  32
  33 <para>
  34 To get the current number of running threads you call
  35 g_thread_pool_get_num_threads(). To get the number of still
  36 unprocessed tasks you call g_thread_pool_unprocessed(). To control the
  37 maximal number of threads for a thread pool, you use
  38 g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads().
  39 </para>
  40
  41 <para>
  42 Finally you can control the number of unused threads, that are kept
  43 alive by GLib for future use. The current number can be fetched with
  44 g_thread_pool_get_num_unused_threads(). The maximal number can be
  45 controlled by g_thread_pool_get_max_unused_threads() and
  46 g_thread_pool_set_max_unused_threads(). All currently unused threads
  47 can be stopped by calling g_thread_pool_stop_unused_threads().
  48 </para>
  49
  50 <!-- ##### SECTION See_Also ##### -->
  51 <para>
  52 <variablelist>
  53
  54 <varlistentry>
  55 <term>#GThread</term>
  56 <listitem><para>GLib thread system.</para></listitem>
  57 </varlistentry>
  58
  59 </variablelist>
  60 </para>
  61
  62 <!-- ##### SECTION Stability_Level ##### -->
  63
  64
  65 <!-- ##### STRUCT GThreadPool ##### -->
  66 <para>
  67 The #GThreadPool struct represents a thread pool. It has six public
  68 read-only members, but the underlying struct is bigger, so you must not copy
  69 this struct.
  70 </para>
  71
  72 @func: the function to execute in the threads of this pool
  73 @user_data: the user data for the threads of this pool
  74 @exclusive: are all threads exclusive to this pool
  75
  76 <!-- ##### FUNCTION g_thread_pool_new ##### -->
  77 <para>
  78
  79 </para>
  80
  81 @func:
  82 @user_data:
  83 @max_threads:
  84 @exclusive:
  85 @error:
  86 @Returns:
  87
  88
  89 <!-- ##### FUNCTION g_thread_pool_push ##### -->
  90 <para>
  91
  92 </para>
  93
  94 @pool:
  95 @data:
  96 @error:
  97
  98
  99 <!-- ##### FUNCTION g_thread_pool_set_max_threads ##### -->
 100 <para>
 101
 102 </para>
 103
 104 @pool:
 105 @max_threads:
 106 @error:
 107
 108
 109 <!-- ##### FUNCTION g_thread_pool_get_max_threads ##### -->
 110 <para>
 111
 112 </para>
 113
 114 @pool:
 115 @Returns:
 116
 117
 118 <!-- ##### FUNCTION g_thread_pool_get_num_threads ##### -->
 119 <para>
 120
 121 </para>
 122
 123 @pool:
 124 @Returns:
 125
 126
 127 <!-- ##### FUNCTION g_thread_pool_unprocessed ##### -->
 128 <para>
 129
 130 </para>
 131
 132 @pool:
 133 @Returns:
 134
 135
 136 <!-- ##### FUNCTION g_thread_pool_free ##### -->
 137 <para>
 138
 139 </para>
 140
 141 @pool:
 142 @immediate:
 143 @wait_:
 144
 145
 146 <!-- ##### FUNCTION g_thread_pool_set_max_unused_threads ##### -->
 147 <para>
 148
 149 </para>
 150
 151 @max_threads:
 152
 153
 154 <!-- ##### FUNCTION g_thread_pool_get_max_unused_threads ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @Returns:
 160
 161
 162 <!-- ##### FUNCTION g_thread_pool_get_num_unused_threads ##### -->
 163 <para>
 164
 165 </para>
 166
 167 @Returns:
 168
 169
 170 <!-- ##### FUNCTION g_thread_pool_stop_unused_threads ##### -->
 171 <para>
 172
 173 </para>
 174
 175
 176
 177 <!-- ##### FUNCTION g_thread_pool_set_sort_function ##### -->
 178 <para>
 179
 180 </para>
 181
 182 @pool:
 183 @func:
 184 @user_data:
 185
 186
 187 <!-- ##### FUNCTION g_thread_pool_set_max_idle_time ##### -->
 188 <para>
 189
 190 </para>
 191
 192 @interval:
 193
 194
 195 <!-- ##### FUNCTION g_thread_pool_get_max_idle_time ##### -->
 196 <para>
 197
 198 </para>
 199
 200 @Returns:
 201
 202