gtkD/src/glib/ThreadPool.d

   1 /*
   2  * This file is part of gtkD.
   3  *
   4  * gtkD 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  * gtkD 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 gtkD; 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  * module aliases:
  50  * local aliases:
  51  */
  52
  53 module glib.ThreadPool;
  54
  55 version(noAssert)
  56 {
  57         version(Tango)
  58         {
  59                 import tango.io.Stdout; // use the tango loging?
  60         }
  61 }
  62
  63 private import gtkc.glibtypes;
  64
  65 private import gtkc.glib;
  66
  67
  68 private import glib.ErrorG;
  69 private import glib.ListG;
  70 private import glib.MainLoop;
  71
  72
  73
  74
  75 /**
  76  * Description
  77  * Sometimes you wish to asyncronously fork out the execution of work and
  78  * continue working in your own thread. If that will happen often, the
  79  * overhead of starting and destroying a thread each time might be to
  80  * high. In such cases reusing already started threads seems like a good
  81  * idea. And it indeed is, but implementing this can be tedious and
  82  * error-prone.
  83  * Therefore GLib provides thread pools for your convenience. An added
  84  * advantage is, that the threads can be shared between the different
  85  * subsystems of your program, when they are using GLib.
  86  * To create a new thread pool, you use g_thread_pool_new(). It is
  87  * destroyed by g_thread_pool_free().
  88  * If you want to execute a certain task within a thread pool, you call
  89  * g_thread_pool_push().
  90  * To get the current number of running threads you call
  91  * g_thread_pool_get_num_threads(). To get the number of still
  92  * unprocessed tasks you call g_thread_pool_unprocessed(). To control the
  93  * maximal number of threads for a thread pool, you use
  94  * g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads().
  95  * Finally you can control the number of unused threads, that are kept
  96  * alive by GLib for future use. The current number can be fetched with
  97  * g_thread_pool_get_num_unused_threads(). The maximal number can be
  98  * controlled by g_thread_pool_get_max_unused_threads() and
  99  * g_thread_pool_set_max_unused_threads(). All currently unused threads
 100  * can be stopped by calling g_thread_pool_stop_unused_threads().
 101  */
 102 public class ThreadPool
 103 {
 104
 105         /** the main Gtk struct */
 106         protected GThreadPool* gThreadPool;
 107
 108
 109         public GThreadPool* getThreadPoolStruct()
 110         {
 111                 return gThreadPool;
 112         }
 113
 114
 115         /** the main Gtk struct as a void* */
 116         protected void* getStruct()
 117         {
 118                 return cast(void*)gThreadPool;
 119         }
 120
 121         /**
 122          * Sets our main struct and passes it to the parent class
 123          */
 124         public this (GThreadPool* gThreadPool)
 125         {
 126                 version(noAssert)
 127                 {
 128                         if ( gThreadPool is null )
 129                         {
 130                                 int zero = 0;
 131                                 version(Tango)
 132                                 {
 133                                         Stdout("struct gThreadPool is null on constructor").newline;
 134                                 }
 135                                 else
 136                                 {
 137                                         printf("struct gThreadPool is null on constructor");
 138                                 }
 139                                 zero = zero / zero;
 140                         }
 141                 }
 142                 else
 143                 {
 144                         assert(gThreadPool !is null, "struct gThreadPool is null on constructor");
 145                 }
 146                 this.gThreadPool = gThreadPool;
 147         }
 148
 149         /**
 150          */
 151
 152
 153         /**
 154          * This function creates a new thread pool.
 155          * Whenever you call g_thread_pool_push(), either a new thread is
 156          * created or an unused one is reused. At most max_threads threads
 157          * are running concurrently for this thread pool. max_threads = -1
 158          * allows unlimited threads to be created for this thread pool. The
 159          * newly created or reused thread now executes the function func with
 160          * the two arguments. The first one is the parameter to
 161          * g_thread_pool_push() and the second one is user_data.
 162          * The parameter exclusive determines, whether the thread pool owns
 163          * all threads exclusive or whether the threads are shared
 164          * globally. If exclusive is TRUE, max_threads threads are started
 165          * immediately and they will run exclusively for this thread pool until
 166          * it is destroyed by g_thread_pool_free(). If exclusive is FALSE,
 167          * threads are created, when needed and shared between all
 168          * non-exclusive thread pools. This implies that max_threads may not
 169          * be -1 for exclusive thread pools.
 170          * error can be NULL to ignore errors, or non-NULL to report
 171          * errors. An error can only occur when exclusive is set to TRUE and
 172          * not all max_threads threads could be created.
 173          * func:
 174          *  a function to execute in the threads of the new thread pool
 175          * user_data:
 176          *  user data that is handed over to func every time it
 177          *  is called
 178          * max_threads:
 179          *  the maximal number of threads to execute concurrently in
 180          *  the new thread pool, -1 means no limit
 181          * exclusive:
 182          *  should this thread pool be exclusive?
 183          * error:
 184          *  return location for error
 185          * Returns:
 186          *  the new GThreadPool
 187          */
 188         public this (GFunc func, void* userData, int maxThreads, int exclusive, GError** error)
 189         {
 190                 // GThreadPool* g_thread_pool_new (GFunc func,  gpointer user_data,  gint max_threads,  gboolean exclusive,  GError **error);
 191                 this(cast(GThreadPool*)g_thread_pool_new(func, userData, maxThreads, exclusive, error) );
 192         }
 193
 194         /**
 195          * Inserts data into the list of tasks to be executed by pool. When
 196          * the number of currently running threads is lower than the maximal
 197          * allowed number of threads, a new thread is started (or reused) with
 198          * the properties given to g_thread_pool_new(). Otherwise data stays
 199          * in the queue until a thread in this pool finishes its previous task
 200          * and processes data.
 201          * error can be NULL to ignore errors, or non-NULL to report
 202          * errors. An error can only occur when a new thread couldn't be
 203          * created. In that case data is simply appended to the queue of work
 204          * to do.
 205          * pool:
 206          *  a GThreadPool
 207          * data:
 208          *  a new task for pool
 209          * error:
 210          *  return location for error
 211          */
 212         public void push(void* data, GError** error)
 213         {
 214                 // void g_thread_pool_push (GThreadPool *pool,  gpointer data,  GError **error);
 215                 g_thread_pool_push(gThreadPool, data, error);
 216         }
 217
 218         /**
 219          * Sets the maximal allowed number of threads for pool. A value of -1
 220          * means, that the maximal number of threads is unlimited.
 221          * Setting max_threads to 0 means stopping all work for pool. It is
 222          * effectively frozen until max_threads is set to a non-zero value
 223          * again.
 224          * A thread is never terminated while calling func, as supplied by
 225          * g_thread_pool_new(). Instead the maximal number of threads only
 226          * has effect for the allocation of new threads in g_thread_pool_push().
 227          * A new thread is allocated, whenever the number of currently
 228          * running threads in pool is smaller than the maximal number.
 229          * error can be NULL to ignore errors, or non-NULL to report
 230          * errors. An error can only occur when a new thread couldn't be
 231          * created.
 232          * pool:
 233          *  a GThreadPool
 234          * max_threads:
 235          *  a new maximal number of threads for pool
 236          * error:
 237          *  return location for error
 238          */
 239         public void setMaxThreads(int maxThreads, GError** error)
 240         {
 241                 // void g_thread_pool_set_max_threads (GThreadPool *pool,  gint max_threads,  GError **error);
 242                 g_thread_pool_set_max_threads(gThreadPool, maxThreads, error);
 243         }
 244
 245         /**
 246          * Returns the maximal number of threads for pool.
 247          * pool:
 248          *  a GThreadPool
 249          * Returns:
 250          *  the maximal number of threads
 251          */
 252         public int getMaxThreads()
 253         {
 254                 // gint g_thread_pool_get_max_threads (GThreadPool *pool);
 255                 return g_thread_pool_get_max_threads(gThreadPool);
 256         }
 257
 258         /**
 259          * Returns the number of threads currently running in pool.
 260          * pool:
 261          *  a GThreadPool
 262          * Returns:
 263          *  the number of threads currently running
 264          */
 265         public uint getNumThreads()
 266         {
 267                 // guint g_thread_pool_get_num_threads (GThreadPool *pool);
 268                 return g_thread_pool_get_num_threads(gThreadPool);
 269         }
 270
 271         /**
 272          * Returns the number of tasks still unprocessed in pool.
 273          * pool:
 274          *  a GThreadPool
 275          * Returns:
 276          *  the number of unprocessed tasks
 277          */
 278         public uint unprocessed()
 279         {
 280                 // guint g_thread_pool_unprocessed (GThreadPool *pool);
 281                 return g_thread_pool_unprocessed(gThreadPool);
 282         }
 283
 284         /**
 285          * Frees all resources allocated for pool.
 286          * If immediate is TRUE, no new task is processed for
 287          * pool. Otherwise pool is not freed before the last task is
 288          * processed. Note however, that no thread of this pool is
 289          * interrupted, while processing a task. Instead at least all still
 290          * running threads can finish their tasks before the pool is freed.
 291          * If wait_ is TRUE, the functions does not return before all tasks
 292          * to be processed (dependent on immediate, whether all or only the
 293          * currently running) are ready. Otherwise the function returns immediately.
 294          * After calling this function pool must not be used anymore.
 295          * pool:
 296          *  a GThreadPool
 297          * immediate:
 298          *  should pool shut down immediately?
 299          * wait_:
 300          *  should the function wait for all tasks to be finished?
 301          */
 302         public void free(int immediate, int wait)
 303         {
 304                 // void g_thread_pool_free (GThreadPool *pool,  gboolean immediate,  gboolean wait_);
 305                 g_thread_pool_free(gThreadPool, immediate, wait);
 306         }
 307
 308         /**
 309          * Sets the maximal number of unused threads to max_threads. If
 310          * max_threads is -1, no limit is imposed on the number of unused
 311          * threads.
 312          * max_threads:
 313          *  maximal number of unused threads
 314          */
 315         public static void setMaxUnusedThreads(int maxThreads)
 316         {
 317                 // void g_thread_pool_set_max_unused_threads  (gint max_threads);
 318                 g_thread_pool_set_max_unused_threads(maxThreads);
 319         }
 320
 321         /**
 322          * Returns the maximal allowed number of unused threads.
 323          * Returns:
 324          *  the maximal number of unused threads
 325          */
 326         public static int getMaxUnusedThreads()
 327         {
 328                 // gint g_thread_pool_get_max_unused_threads  (void);
 329                 return g_thread_pool_get_max_unused_threads();
 330         }
 331
 332         /**
 333          * Returns the number of currently unused threads.
 334          * Returns:
 335          *  the number of currently unused threads
 336          */
 337         public static uint getNumUnusedThreads()
 338         {
 339                 // guint g_thread_pool_get_num_unused_threads  (void);
 340                 return g_thread_pool_get_num_unused_threads();
 341         }
 342
 343         /**
 344          * Stops all currently unused threads. This does not change the
 345          * maximal number of unused threads. This function can be used to
 346          * regularly stop all unused threads e.g. from g_timeout_add().
 347          */
 348         public static void stopUnusedThreads()
 349         {
 350                 // void g_thread_pool_stop_unused_threads (void);
 351                 g_thread_pool_stop_unused_threads();
 352         }
 353
 354         /**
 355          * Sets the function used to sort the list of tasks. This allows the
 356          * tasks to be processed by a priority determined by func, and not
 357          * just in the order in which they were added to the pool.
 358          * Note, if the maximum number of threads is more than 1, the order
 359          * that threads are executed can not be guranteed 100%. Threads are
 360          * scheduled by the operating system and are executed at random. It
 361          * cannot be assumed that threads are executed in the order they are
 362          * created.
 363          * pool:
 364          *  a GThreadPool
 365          * func:
 366          *  the GCompareDataFunc used to sort the list of tasks.
 367          *  This function is passed two tasks. It should return
 368          *  0 if the order in which they are handled does not matter,
 369          *  a negative value if the first task should be processed before
 370          *  the second or a positive value if the second task should be
 371          *  processed first.
 372          * user_data:
 373          *  user data passed to func.
 374          * Since 2.10
 375          */
 376         public void setSortFunction(GCompareDataFunc func, void* userData)
 377         {
 378                 // void g_thread_pool_set_sort_function (GThreadPool *pool,  GCompareDataFunc func,  gpointer user_data);
 379                 g_thread_pool_set_sort_function(gThreadPool, func, userData);
 380         }
 381
 382         /**
 383          * This function will set the maximum interval that a thread waiting
 384          * in the pool for new tasks can be idle for before being
 385          * stopped. This function is similar to calling
 386          * g_thread_pool_stop_unused_threads() on a regular timeout, except,
 387          * this is done on a per thread basis.
 388          * By setting interval to 0, idle threads will not be stopped.
 389          * This function makes use of g_async_queue_timed_pop() using
 390          * interval.
 391          * interval:
 392          *  the maximum interval (1/1000ths of a second) a thread
 393          *  can be idle.
 394          * Since 2.10
 395          */
 396         public static void setMaxIdleTime(uint interval)
 397         {
 398                 // void g_thread_pool_set_max_idle_time (guint interval);
 399                 g_thread_pool_set_max_idle_time(interval);
 400         }
 401
 402         /**
 403          * This function will return the maximum interval that a thread will
 404          * wait in the thread pool for new tasks before being stopped.
 405          * If this function returns 0, threads waiting in the thread pool for
 406          * new work are not stopped.
 407          * Returns:
 408          *  the maximum interval to wait for new tasks in the
 409          *  thread pool before stopping the thread (1/1000ths of a second).
 410          * Since 2.10
 411          * See Also
 412          * GThread
 413          * GLib thread system.
 414          */
 415         public static uint getMaxIdleTime()
 416         {
 417                 // guint g_thread_pool_get_max_idle_time (void);
 418                 return g_thread_pool_get_max_idle_time();
 419         }
 420 }