src/glib/ThreadPool.d

   1 /*
   2  * This file is part of duit.
   3  *
   4  * duit is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation; either version 2.1 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * duit is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with duit; if not, write to the Free Software
  16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  17  */
  18
  19 // generated automatically - do not change
  20 // find conversion definition on APILookup.txt
  21 // implement new conversion functionalities on the wrap.utils pakage
  22
  23 /*
  24  * Conversion parameters:
  25  * inFile  = glib-Thread-Pools.html
  26  * outPack = glib
  27  * outFile = ThreadPool
  28  * strct   = GThreadPool
  29  * realStrct=
  30  * ctorStrct=
  31  * clss    = ThreadPool
  32  * interf  =
  33  * class Code: No
  34  * interface Code: No
  35  * template for:
  36  * extend  =
  37  * implements:
  38  * prefixes:
  39  *      - g_thread_pool_
  40  * omit structs:
  41  * omit prefixes:
  42  * omit code:
  43  * imports:
  44  *      - glib.ErrorG
  45  *      - glib.ListG
  46  *      - glib.MainLoop
  47  * structWrap:
  48  *      - GList* -> ListG
  49  * local aliases:
  50  */
  51
  52 module glib.ThreadPool;
  53
  54 private import glib.glibtypes;
  55
  56 private import lib.glib;
  57
  58 private import glib.ErrorG;
  59 private import glib.ListG;
  60 private import glib.MainLoop;
  61
  62 /**
  63  * Description
  64  * Sometimes you wish to asyncronously fork out the execution of work and
  65  * continue working in your own thread. If that will happen often, the
  66  * overhead of starting and destroying a thread each time might be to
  67  * high. In such cases reusing already started threads seems like a good
  68  * idea. And it indeed is, but implementing this can be tedious and
  69  * error-prone.
  70  * Therefore GLib provides thread pools for your convenience. An added
  71  * advantage is, that the threads can be shared between the different
  72  * subsystems of your program, when they are using GLib.
  73  * To create a new thread pool, you use g_thread_pool_new(). It is
  74  * destroyed by g_thread_pool_free().
  75  * If you want to execute a certain task within a thread pool, you call
  76  * g_thread_pool_push().
  77  * To get the current number of running threads you call
  78  * g_thread_pool_get_num_threads(). To get the number of still
  79  * unprocessed tasks you call g_thread_pool_unprocessed(). To control the
  80  * maximal number of threads for a thread pool, you use
  81  * g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads().
  82  * Finally you can control the number of unused threads, that are kept
  83  * alive by GLib for future use. The current number can be fetched with
  84  * g_thread_pool_get_num_unused_threads(). The maximal number can be
  85  * controlled by g_thread_pool_get_max_unused_threads() and
  86  * g_thread_pool_set_max_unused_threads(). All currently unused threads
  87  * can be stopped by calling g_thread_pool_stop_unused_threads().
  88  */
  89 public class ThreadPool
  90 {
  91
  92         /** the main Gtk struct */
  93         protected GThreadPool* gThreadPool;
  94
  95
  96         public GThreadPool* getThreadPoolStruct()
  97         {
  98                 return gThreadPool;
  99         }
 100
 101
 102         /** the main Gtk struct as a void* */
 103         protected void* getStruct()
 104         {
 105                 return cast(void*)gThreadPool;
 106         }
 107
 108         /**
 109          * Sets our main struct and passes it to the parent class
 110          */
 111         public this (GThreadPool* gThreadPool)
 112         {
 113                 this.gThreadPool = gThreadPool;
 114         }
 115
 116         /**
 117          */
 118
 119
 120         /**
 121          * This function creates a new thread pool.
 122          * Whenever you call g_thread_pool_push(), either a new thread is
 123          * created or an unused one is reused. At most max_threads threads
 124          * are running concurrently for this thread pool. max_threads = -1
 125          * allows unlimited threads to be created for this thread pool. The
 126          * newly created or reused thread now executes the function func with
 127          * the two arguments. The first one is the parameter to
 128          * g_thread_pool_push() and the second one is user_data.
 129          * The parameter exclusive determines, whether the thread pool owns
 130          * all threads exclusive or whether the threads are shared
 131          * globally. If exclusive is TRUE, max_threads threads are started
 132          * immediately and they will run exclusively for this thread pool until
 133          * it is destroyed by g_thread_pool_free(). If exclusive is FALSE,
 134          * threads are created, when needed and shared between all
 135          * non-exclusive thread pools. This implies that max_threads may not
 136          * be -1 for exclusive thread pools.
 137          * error can be NULL to ignore errors, or non-NULL to report
 138          * errors. An error can only occur when exclusive is set to TRUE and
 139          * not all max_threads threads could be created.
 140          * func:
 141          *  a function to execute in the threads of the new thread pool
 142          * user_data:
 143          *  user data that is handed over to func every time it
 144          *  is called
 145          * max_threads:
 146          *  the maximal number of threads to execute concurrently in
 147          *  the new thread pool, -1 means no limit
 148          * exclusive:
 149          *  should this thread pool be exclusive?
 150          * error:
 151          *  return location for error
 152          * Returns:
 153          *  the new GThreadPool
 154          */
 155         public this (GFunc func, void* userData, int maxThreads, int exclusive, GError** error)
 156         {
 157                 // GThreadPool* g_thread_pool_new (GFunc func,  gpointer user_data,  gint max_threads,  gboolean exclusive,  GError **error);
 158                 this(cast(GThreadPool*)g_thread_pool_new(func, userData, maxThreads, exclusive, error) );
 159         }
 160
 161         /**
 162          * Inserts data into the list of tasks to be executed by pool. When
 163          * the number of currently running threads is lower than the maximal
 164          * allowed number of threads, a new thread is started (or reused) with
 165          * the properties given to g_thread_pool_new(). Otherwise data stays
 166          * in the queue until a thread in this pool finishes its previous task
 167          * and processes data.
 168          * error can be NULL to ignore errors, or non-NULL to report
 169          * errors. An error can only occur when a new thread couldn't be
 170          * created. In that case data is simply appended to the queue of work
 171          * to do.
 172          * pool:
 173          *  a GThreadPool
 174          * data:
 175          *  a new task for pool
 176          * error:
 177          *  return location for error
 178          */
 179         public void push(void* data, GError** error)
 180         {
 181                 // void g_thread_pool_push (GThreadPool *pool,  gpointer data,  GError **error);
 182                 g_thread_pool_push(gThreadPool, data, error);
 183         }
 184
 185         /**
 186          * Sets the maximal allowed number of threads for pool. A value of -1
 187          * means, that the maximal number of threads is unlimited.
 188          * Setting max_threads to 0 means stopping all work for pool. It is
 189          * effectively frozen until max_threads is set to a non-zero value
 190          * again.
 191          * A thread is never terminated while calling func, as supplied by
 192          * g_thread_pool_new(). Instead the maximal number of threads only
 193          * has effect for the allocation of new threads in g_thread_pool_push().
 194          * A new thread is allocated, whenever the number of currently
 195          * running threads in pool is smaller than the maximal number.
 196          * error can be NULL to ignore errors, or non-NULL to report
 197          * errors. An error can only occur when a new thread couldn't be
 198          * created.
 199          * pool:
 200          *  a GThreadPool
 201          * max_threads:
 202          *  a new maximal number of threads for pool
 203          * error:
 204          *  return location for error
 205          */
 206         public void setMaxThreads(int maxThreads, GError** error)
 207         {
 208                 // void g_thread_pool_set_max_threads (GThreadPool *pool,  gint max_threads,  GError **error);
 209                 g_thread_pool_set_max_threads(gThreadPool, maxThreads, error);
 210         }
 211
 212         /**
 213          * Returns the maximal number of threads for pool.
 214          * pool:
 215          *  a GThreadPool
 216          * Returns:
 217          *  the maximal number of threads
 218          */
 219         public int getMaxThreads()
 220         {
 221                 // gint g_thread_pool_get_max_threads (GThreadPool *pool);
 222                 return g_thread_pool_get_max_threads(gThreadPool);
 223         }
 224
 225         /**
 226          * Returns the number of threads currently running in pool.
 227          * pool:
 228          *  a GThreadPool
 229          * Returns:
 230          *  the number of threads currently running
 231          */
 232         public uint getNumThreads()
 233         {
 234                 // guint g_thread_pool_get_num_threads (GThreadPool *pool);
 235                 return g_thread_pool_get_num_threads(gThreadPool);
 236         }
 237
 238         /**
 239          * Returns the number of tasks still unprocessed in pool.
 240          * pool:
 241          *  a GThreadPool
 242          * Returns:
 243          *  the number of unprocessed tasks
 244          */
 245         public uint unprocessed()
 246         {
 247                 // guint g_thread_pool_unprocessed (GThreadPool *pool);
 248                 return g_thread_pool_unprocessed(gThreadPool);
 249         }
 250
 251         /**
 252          * Frees all resources allocated for pool.
 253          * If immediate is TRUE, no new task is processed for
 254          * pool. Otherwise pool is not freed before the last task is
 255          * processed. Note however, that no thread of this pool is
 256          * interrupted, while processing a task. Instead at least all still
 257          * running threads can finish their tasks before the pool is freed.
 258          * If wait is TRUE, the functions does not return before all tasks
 259          * to be processed (dependent on immediate, whether all or only the
 260          * currently running) are ready. Otherwise the function returns immediately.
 261          * After calling this function pool must not be used anymore.
 262          * pool:
 263          *  a GThreadPool
 264          * immediate:
 265          *  should pool shut down immediately?
 266          * wait:
 267          *  should the function wait for all tasks to be finished?
 268          */
 269         public void free(int immediate, int wait)
 270         {
 271                 // void g_thread_pool_free (GThreadPool *pool,  gboolean immediate,  gboolean wait);
 272                 g_thread_pool_free(gThreadPool, immediate, wait);
 273         }
 274
 275         /**
 276          * Sets the maximal number of unused threads to max_threads. If
 277          * max_threads is -1, no limit is imposed on the number of unused
 278          * threads.
 279          * max_threads:
 280          *  maximal number of unused threads
 281          */
 282         public static void setMaxUnusedThreads(int maxThreads)
 283         {
 284                 // void g_thread_pool_set_max_unused_threads  (gint max_threads);
 285                 g_thread_pool_set_max_unused_threads(maxThreads);
 286         }
 287
 288         /**
 289          * Returns the maximal allowed number of unused threads.
 290          * Returns:
 291          *  the maximal number of unused threads
 292          */
 293         public static int getMaxUnusedThreads()
 294         {
 295                 // gint g_thread_pool_get_max_unused_threads  (void);
 296                 return g_thread_pool_get_max_unused_threads();
 297         }
 298
 299         /**
 300          * Returns the number of currently unused threads.
 301          * Returns:
 302          *  the number of currently unused threads
 303          */
 304         public static uint getNumUnusedThreads()
 305         {
 306                 // guint g_thread_pool_get_num_unused_threads  (void);
 307                 return g_thread_pool_get_num_unused_threads();
 308         }
 309
 310         /**
 311          * Stops all currently unused threads. This does not change the
 312          * maximal number of unused threads. This function can be used to
 313          * regularly stop all unused threads e.g. from g_timeout_add().
 314          */
 315         public static void stopUnusedThreads()
 316         {
 317                 // void g_thread_pool_stop_unused_threads  (void);
 318                 g_thread_pool_stop_unused_threads();
 319         }
 320
 321         /**
 322          * Sets the function used to sort the list of tasks. This allows the
 323          * tasks to be processed by a priority determined by func, and not
 324          * just in the order in which they were added to the pool.
 325          * Note, if the maximum number of threads is more than 1, the order
 326          * that threads are executed can not be guranteed 100%. Threads are
 327          * scheduled by the operating system and are executed at random. It
 328          * cannot be assumed that threads are executed in the order they are
 329          * created.
 330          * pool:
 331          *  a GThreadPool
 332          * func:
 333          *  the GCompareDataFunc used to sort the list of tasks.
 334          *  This function is passed two tasks. It should return
 335          *  0 if the order in which they are handled does not matter,
 336          *  a negative value if the first task should be processed before
 337          *  the second or a positive value if the second task should be
 338          *  processed first.
 339          * user_data:
 340          *  user data passed to func.
 341          * Since 2.10
 342          */
 343         public void setSortFunction(GCompareDataFunc func, void* userData)
 344         {
 345                 // void g_thread_pool_set_sort_function (GThreadPool *pool,  GCompareDataFunc func,  gpointer user_data);
 346                 g_thread_pool_set_sort_function(gThreadPool, func, userData);
 347         }
 348
 349         /**
 350          * This function will set the maximum interval that a thread waiting
 351          * in the pool for new tasks can be idle for before being
 352          * stopped. This function is similar to calling
 353          * g_thread_pool_stop_unused_threads() on a regular timeout, except,
 354          * this is done on a per thread basis.
 355          * By setting interval to 0, idle threads will not be stopped.
 356          * This function makes use of g_async_queue_timed_pop() using
 357          * interval.
 358          * interval:
 359          *  the maximum interval (1/1000ths of a second) a thread
 360          *  can be idle.
 361          * Since 2.10
 362          */
 363         public static void setMaxIdleTime(uint interval)
 364         {
 365                 // void g_thread_pool_set_max_idle_time (guint interval);
 366                 g_thread_pool_set_max_idle_time(interval);
 367         }
 368
 369         /**
 370          * This function will return the maximum interval that a thread will
 371          * wait in the thread pool for new tasks before being stopped.
 372          * If this function returns 0, threads waiting in the thread pool for
 373          * new work are not stopped.
 374          * Returns:
 375          *  the maximum interval to wait for new tasks in the
 376          *  thread pool before stopping the thread (1/1000ths of a second).
 377          * Since 2.10
 378          * See Also
 379          * GThread
 380          * GLib thread system.
 381          */
 382         public static uint getMaxIdleTime()
 383         {
 384                 // guint g_thread_pool_get_max_idle_time (void);
 385                 return g_thread_pool_get_max_idle_time();
 386         }
 387 }