libs/glibmm2/glib/glibmm/threadpool.h

   1 // -*- c++ -*-
   2 #ifndef _GLIBMM_THREADPOOL_H
   3 #define _GLIBMM_THREADPOOL_H
   4
   5 /* $Id: threadpool.h 72 2004-02-10 14:26:07Z murrayc $ */
   6
   7 /* Copyright (C) 2002 The gtkmm Development Team
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Library General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Library General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Library General Public
  20  * License along with this library; if not, write to the Free
  21  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  22  */
  23
  24 #include <glibmm/thread.h>
  25
  26 extern "C" { typedef struct _GThreadPool GThreadPool; }
  27
  28
  29 namespace Glib
  30 {
  31
  32 /** @defgroup ThreadPools Thread Pools
  33  * Pools of threads to execute work concurrently.
  34  * @{
  35  */
  36
  37 /** A pool of threads to execute work concurrently.
  38  */
  39 class ThreadPool
  40 {
  41 public:
  42   /** Constructs a new thread pool.
  43    * Whenever you call ThreadPool::push(), either a new thread is created or an
  44    * unused one is reused. At most @a max_threads threads are running
  45    * concurrently for this thread pool. @a max_threads&nbsp;=&nbsp;-1 allows
  46    * unlimited threads to be created for this thread pool.
  47    *
  48    * The parameter @a exclusive determines, whether the thread pool owns all
  49    * threads exclusive or whether the threads are shared globally. If @a
  50    * exclusive is <tt>true</tt>, @a max_threads threads are started immediately
  51    * and they will run exclusively for this thread pool until it is destroyed
  52    * by ~ThreadPool(). If @a exclusive is <tt>false</tt>, threads are created
  53    * when needed and shared between all non-exclusive thread pools.  This
  54    * implies that @a max_threads may not be -1 for exclusive thread pools.
  55    *
  56    * @param max_threads The maximal number of threads to execute concurrently
  57    * in the new thread pool, -1 means no limit.
  58    * @param exclusive Should this thread pool be exclusive?
  59    * @throw Glib::ThreadError An error can only occur when @a exclusive is
  60    * set to <tt>true</tt> and not all @a max_threads threads could be created.
  61    */
  62   explicit ThreadPool(int max_threads = -1, bool exclusive = false);
  63   virtual ~ThreadPool();
  64
  65   /** Inserts @a slot into the list of tasks to be executed by the pool.
  66    * When the number of currently running threads is lower than the maximal
  67    * allowed number of threads, a new thread is started (or reused).  Otherwise
  68    * @a slot stays in the queue until a thread in this pool finishes its
  69    * previous task and processes @a slot.
  70    * @param slot A new task for the thread pool.
  71    * @throw Glib::ThreadError An error can only occur when a new thread
  72    * couldn't be created. In that case @a slot is simply appended to the
  73    * queue of work to do.
  74    */
  75   void push(const sigc::slot<void>& slot);
  76
  77   /** Sets the maximal allowed number of threads for the pool.
  78    * A value of -1 means that the maximal number of threads is unlimited.
  79    * Setting @a max_threads to 0 means stopping all work for pool. It is
  80    * effectively frozen until @a max_threads is set to a non-zero value again.
  81    *
  82    * A thread is never terminated while it is still running. Instead the
  83    * maximal number of threads only has effect for the allocation of new
  84    * threads in ThreadPool::push().  A new thread is allocated whenever the
  85    * number of currently running threads in the pool is smaller than the
  86    * maximal number.
  87    *
  88    * @param max_threads A new maximal number of threads for the pool.
  89    * @throw Glib::ThreadError An error can only occur when a new thread
  90    * couldn't be created.
  91    */
  92   void set_max_threads(int max_threads);
  93
  94   /** Returns the maximal number of threads for the pool.
  95    * @return The maximal number of threads.
  96    */
  97   int get_max_threads() const;
  98
  99   /** Returns the number of threads currently running in the pool.
 100    * @return The number of threads currently running.
 101    */
 102   unsigned int get_num_threads() const;
 103
 104   /** Returns the number of tasks still unprocessed in the pool.
 105    * @return The number of unprocessed tasks.
 106    */
 107   unsigned int unprocessed() const;
 108
 109   /** Returns whether all threads are exclusive to this pool.
 110    * @return Whether all threads are exclusive to this pool.
 111    */
 112   bool get_exclusive() const;
 113
 114   /** Frees all resources allocated for the pool.
 115    * If @a immediately is <tt>true</tt>, no new task is processed.  Otherwise the
 116    * pool is not freed before the last task is processed.  Note however, that no
 117    * thread of this pool is interrupted while processing a task. Instead at least
 118    * all still running threads can finish their tasks before the pool is freed.
 119    *
 120    * This method does not return before all tasks to be processed (dependent on
 121    * @a immediately, whether all or only the currently running) are ready.
 122    * After calling shutdown() the pool must not be used anymore.
 123    *
 124    * @param immediately Should the pool shut down immediately?
 125    */
 126   void shutdown(bool immediately = false);
 127
 128   /** Sets the maximal number of unused threads to @a max_threads.
 129    * If @a max_threads is -1, no limit is imposed on the number of unused threads.
 130    * @param max_threads Maximal number of unused threads.
 131    */
 132   static void set_max_unused_threads(int max_threads);
 133
 134   /** Returns the maximal allowed number of unused threads.
 135    * @return The maximal number of unused threads.
 136    */
 137   static int get_max_unused_threads();
 138
 139   /** Returns the number of currently unused threads.
 140    * @return The number of currently unused threads.
 141    */
 142   static unsigned int get_num_unused_threads();
 143
 144   /** Stops all currently unused threads.
 145    * This does not change the maximal number of unused threads.  This function can
 146    * be used to regularly stop all unused threads e.g. from Glib::signal_timeout().
 147    */
 148   static void stop_unused_threads();
 149
 150   GThreadPool*       gobj()       { return gobject_; }
 151   const GThreadPool* gobj() const { return gobject_; }
 152
 153 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 154   class SlotList;
 155 #endif
 156
 157 private:
 158   GThreadPool* gobject_;
 159   SlotList*    slot_list_;
 160
 161   ThreadPool(const ThreadPool&);
 162   ThreadPool& operator=(const ThreadPool&);
 163 };
 164
 165 /** @} group ThreadPools */
 166
 167
 168 /***************************************************************************/
 169 /*  inline implementation                                                  */
 170 /***************************************************************************/
 171
 172 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 173
 174 /**** Glib::Private ********************************************************/
 175
 176
 177 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 178
 179 } // namespace Glib
 180
 181
 182 #endif /* _GLIBMM_THREADPOOL_H */
 183