task_manager.h

Go to the documentation of this file.

/* Copyright (C) 2012 Chris Vine

The library comprised in this file or of which this file is part is
distributed by Chris Vine under the GNU Lesser General Public
License as follows:

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public License
   as published by the Free Software Foundation; either version 2.1 of
   the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License, version 2.1, for more details.

   You should have received a copy of the GNU Lesser General Public
   License, version 2.1, along with this library (see the file LGPL.TXT
   which came with this source code package in the c++-gtk-utils
   sub-directory); if not, write to the Free Software Foundation, Inc.,
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

*/

#ifndef CGU_TASK_MANAGER_H
#define CGU_TASK_MANAGER_H

#include <deque>
#include <utility>   // for std::pair and std::move
#include <exception> // for std::exception
#include <memory>    // for std::unique_ptr

#include <c++-gtk-utils/callback.h>
#include <c++-gtk-utils/thread.h>
#include <c++-gtk-utils/mutex.h>
#include <c++-gtk-utils/async_queue.h>
#include <c++-gtk-utils/cgu_config.h>

namespace Cgu {

namespace Thread {

struct TaskError: public std::exception {
  virtual const char* what() const throw() {return "TaskError\n";}
};

/**
 * @class Cgu::Thread::TaskManager task_manager.h c++-gtk-utils/task_manager.h
 * @brief A thread-pool class for managing tasks in multi-threaded programs.
 * @sa Cgu::Thread::Future Cgu::AsyncResult Cgu::AsyncQueueDispatch Cgu::Callback::post()
 *
 * Cgu::Thread::Future operates on the principle of there being one
 * worker thread per task.  In some cases however, it may be better to
 * have a limited pool of worker threads executing a larger number of
 * tasks.  This class implements this approach via a thread pool.
 *
 * One common approach for thread pools of this kind is to set the
 * maximum number of threads to the number of cores, or one less than
 * the number of cores, available on the local machine.  How that can
 * be determined is system specific (on linux it can be obtained by,
 * for example, inspecting the 'siblings' and 'cpu cores' fields in
 * /proc/cpuinfo or by using sysconf with the glibc extension for
 * _SC_NPROCESSORS_ONLN).
 *
 * Where the task needs to provide a result, two approaches can be
 * adopted.  First, the task callback can have a Cgu::AsyncResult
 * object held by Cgu::SharedLockPtr (or by std::shared_ptr having a
 * thread safe reference count) bound to it.  Alternatively, a task
 * can provide a result asynchronously to a glib main loop by calling
 * Cgu::Callback::post() when it is ready to do so.  In addition,
 * tasks can add other tasks, enabling the composition of an arbitrary
 * number of tasks to obtain a final result.
 * 
 * TaskManager objects do not provide thread cancellation.  Thread
 * cancellation is incompatible with the task-centred thread pool
 * model.  If task cancellation is wanted, use a Cgu::Thread::Future
 * (or Cgu::Thread::Thread or Cgu::Thread::JoinableHandle) object
 * instead, and have a dedicated thread for the cancelable task.
 *
 * If glib < 2.32 is installed, g_thread_init() must be called before
 * any TaskManager objects are constructed, which in turn means that
 * with glib < 2.32 TaskManager objects may not be constructed as
 * static objects in global namespace (that is, before g_thread_init()
 * has been called in the program).
 *
 * Any exceptions which propagate from a task will be consumed to
 * protect the TaskManager object, and to detect whether this has
 * happened there is a version of the TaskManager::add_task() method
 * which takes a second argument comprising a 'fail' callback.  If an
 * exception propagates from the 'fail' callback that is also consumed
 * and a g_critical() message issued.
 *
 * Tasks can be aborted by throwing Cgu::Thread::Exit (as well as any
 * other exception).  Where a thread is managed by a TaskManager
 * object, throwing Cgu::Thread::Exit will only terminate the task and
 * not the thread on which it is running (and will cause the 'fail'
 * callback to be executed, if there is one).
 *
 * TaskManager objects have no copy constructor or copy assignment
 * operator, as copying them would have no obvious semantic meaning.
 * Whilst swapping or moving TaskManager objects would be meaningful,
 * this is not implemented either because it would require an
 * additional internal lock to be thread safe, and the circumstances
 * in which moving or swapping would be useful are limited.  Where a
 * move option is wanted, a TaskManager object can be constructed on
 * free store and held by std::unique_ptr.
 *
 * Here is a compilable example of the calculator class referred to in
 * the documentation on the AsyncResult but which uses a TaskManager
 * object so that the calculator class can run more than one thread to
 * service its calculations:
 *
 * @code 
 *   #include <vector>
 *   #include <numeric>
 *   #include <ostream>
 *   #include <iostream>
 *
 *   #include <glib.h>
 *
 *   #include <c++-gtk-utils/task_manager.h>
 *   #include <c++-gtk-utils/async_result.h>
 *   #include <c++-gtk-utils/shared_ptr.h>
 *   #include <c++-gtk-utils/callback.h>
 *
 *   using namespace Cgu;
 *
 *   class Calcs {
 *     Thread::TaskManager tm;
 *   public:
 *     SharedLockPtr<AsyncResult<double>> mean(const std::vector<double>& nums) {
 *       SharedLockPtr<AsyncResult<double>> res(new AsyncResult<double>);
 *       tm.add_task(Callback::lambda<>([=]() {
 *             if (nums.empty()) res->set(0.0);
 *             else res->set(std::accumulate(nums.begin(), nums.end(), 0.0)/nums.size());
 *           }));
 *       return res;
 *     }
 *
 *     // ... other calculation methods here
 *   };
 *
 *   int main () {
 *
 *     g_thread_init(0);
 *     Calcs calcs;
 *     auto res1 = calcs.mean(std::vector<double>({1, 2, 8, 0}));
 *     auto res2 = calcs.mean(std::vector<double>({101, 53.7, 87, 1.2}));
 *
 *     // ... do something else
 *     std::cout << res1->get() << std::endl;
 *     std::cout << res2->get() << std::endl;
 *
 *   }
 * @endcode
 */

class TaskManager {
 public:
  enum StopMode {wait_for_running, wait_for_all}; 
 private:
  typedef std::pair<std::unique_ptr<const Callback::Callback>,
                    std::unique_ptr<const Callback::Callback>> QueueItemType;

  struct RefImpl; // reference counted implementation class

  // it is fine holding RefImpl by plain pointer and not by
  // IntrusivePtr: it is the only data member this class has, so it
  // can safely manage that member in its own destructor and other
  // methods
  RefImpl* ref_impl;

 public:
/**
 * This class cannot be copied.  The copy constructor is deleted.
 */
  TaskManager(const TaskManager&) = delete;

/**
 * This class cannot be copied.  The assignment operator is deleted.
 */
  TaskManager& operator=(const TaskManager&) = delete;

 /**
  * Gets the maximum number of threads which the TaskManager object is
  * currently set to run in the thread pool. This value is established
  * initially by the 'max' argument passed to the TaskManager
  * constructor and can subequently be changed by calling
  * set_max_threads().  The default value is 8.  This method will not
  * throw and is thread safe.
  * @return The maximum number of threads.
  *
  * Since 2.0.12
  */
  unsigned int get_max_threads() const;

 /**
  * Gets the minimum number of threads which the TaskManager object
  * will run in the thread pool (these threads will last until
  * stop_all() is called or the TaskManager object is destroyed).
  * This value is established by the 'min' argument passed to the
  * TaskManager constructor and cannot subequently be changed.  The
  * default is 0.  This method will not throw and is thread safe.
  * @return The minimum number of threads.
  *
  * Since 2.0.12
  */
  unsigned int get_min_threads() const;

 /**
  * Gets the number of threads which the TaskManager object is
  * currently running in the thread pool.  This value could be greater
  * than the number returned by get_max_threads() if set_max_threads()
  * has recently been called with a value which is less than that
  * number but not enough tasks have since completed to reduce the
  * number of running threads to the new value set.  This method will
  * not throw and is thread safe.
  * @return The number of threads running.
  *
  * Since 2.0.12
  */
  unsigned int get_used_threads() const;

 /**
  * Gets the number of tasks which the TaskManager object is at
  * present either running in the thread pool or has queued for
  * execution.  This value will be less than the number returned by
  * get_used_threads() if threads in the thread pool are currently
  * waiting to receive tasks for execution.  This method will not
  * throw and is thread safe.
  * @return The number of threads running.
  *
  * Since 2.0.12
  */
  unsigned int get_tasks() const;

 /**
  * Sets the maximum number of threads which the TaskManager object
  * will currently run in the thread pool.  If this is less than the
  * current number of running threads, the number of threads actually
  * running will only be reduced as tasks complete, or as idle
  * timeouts expire.  This method does nothing if stop_all() has
  * previously been called.  This method is thread safe.
  * @param max The maximum number of threads which the TaskManager
  * object will currently run in the thread pool.  This method will
  * not set the maximum value of threads to a value less than that
  * returned by get_min_threads().
  * @exception std::bad_alloc If this call is passed a value for 'max'
  * which increases the maximum number of threads from its previous
  * setting and tasks are currently queued for execution, new threads
  * will be started for the queued tasks, so this exception may be
  * thrown on starting the new threads if memory is exhausted and the
  * system throws in that case.  (On systems with
  * over-commit/lazy-commit combined with virtual memory (swap), it is
  * rarely useful to check for memory exhaustion).
  * @exception Cgu::Thread::TaskError If this call is passed a value
  * for 'max' which increases the maximum number of threads from its
  * previous setting and tasks are currently queued for execution, new
  * threads will be started for the queued tasks, so this exception
  * may be thrown on starting the new threads if a thread fails to
  * start correctly (this would mean that memory is exhausted, the
  * pthread thread limit has been reached or pthread has run out of
  * other resources to start new threads).
  *
  * Since 2.0.12
  */
  void set_max_threads(unsigned int max);

 /**
  * Gets the length of time in milliseconds that threads greater in
  * number than the minimum and not executing any tasks will remain in
  * existence waiting for new tasks.  This value is established
  * initially by the 'idle' argument passed to the TaskManager
  * constructor and can subequently be changed by calling
  * set_idle_time().  The default value is 10000 (10 seconds).  This
  * method will not throw and is thread safe.
  * @return The idle time in milliseconds.
  *
  * Since 2.0.12
  */
  unsigned int get_idle_time() const;

 /**
  * Sets the length of time in milliseconds that threads greater in
  * number than the minimum and not executing any tasks will remain in
  * existence waiting for new tasks.  This will only have effect for
  * threads in the pool which begin waiting for new tasks after this
  * method is called.  This method will not throw and is thread safe.
  * @param idle The length of the idle time in milliseconds during
  * which threads will remain waiting for new tasks.
  *
  * Since 2.0.12
  */
  void set_idle_time(unsigned int idle);

 /**
  * Gets the current blocking setting, which determines whether calls
  * to stop_all() and the destructor will block waiting for all
  * remaining tasks to complete.  This value is established initially
  * by the 'blocking' argument passed to the TaskManager constructor
  * and can subequently be changed by calling set_blocking().  This
  * method will not throw and is thread safe.
  * @return The current blocking setting.
  *
  * Since 2.0.12
  */
  bool get_blocking() const;

 /**
  * Sets the current blocking setting, which determines whether calls
  * to stop_all() and the destructor will block waiting for all
  * remaining tasks to complete.  This method cannot be called after
  * stop_all() has been called (if that is attempted,
  * Cgu::Thread::TaskError will be thrown).  It is thread safe.
  * @param blocking The new blocking setting.
  * @exception Cgu::Thread::TaskError This exception will be thrown if
  * stop_all() has previously been called.
  *
  * Since 2.0.12
  */
  void set_blocking(bool blocking);

 /**
  * Gets the current StopMode setting (either
  * Cgu::Thread::TaskManager::wait_for_running or
  * Cgu::Thread::TaskManager::wait_for_all) executed when running
  * stop_all() or when the destructor is called.  See the
  * documentation on stop_all() for an explanation of the setting.
  * This value is established initially by the 'mode' argument passed
  * to the TaskManager constructor and can subequently be changed by
  * calling set_stop_mode().  This method will not throw and is thread
  * safe.
  * @return The current StopMode setting.
  *
  * Since 2.0.12
  */
  StopMode get_stop_mode() const;

 /**
  * Sets the current StopMode setting (either
  * Cgu::Thread::TaskManager::wait_for_running or
  * Cgu::Thread::TaskManager::wait_for_all) executed when running
  * stop_all() or when the destructor is called.  See the
  * documentation on stop_all() for an explanation of the setting.
  * This method will not throw and is thread safe.
  * @param mode The new StopMode setting.
  *
  * Since 2.0.12
  */
  void set_stop_mode(StopMode mode);

 /**
  * This will cause the TaskManager object to stop running tasks.  The
  * precise effect depends on the current StopMode and blocking
  * settings.  If StopMode is set to
  * Cgu::Thread::TaskManager::wait_for_running, all queued tasks which
  * are not yet running on a thread will be dispensed with, but any
  * already running will be left to complete normally.  If StopMode is
  * set to Cgu::Thread::TaskManager::wait_for_all, both already
  * running tasks and all tasks already queued will be permitted to
  * execute and complete normally.  If the blocking setting is set to
  * true, this method will wait until all the tasks still to execute
  * have finished before returning, and if false it will return
  * straight away.
  *
  * After this method has been called, any attempt to add further
  * tasks with the add_task() method will fail, and add_task() will
  * throw Cgu::Thread::TaskError.
  *
  * This method is thread safe (any thread may call it) unless the
  * blocking setting is true, in which case no task running on the
  * TaskManager object may call this method.
  * @exception std::bad_alloc This exception will be thrown if memory
  * is exhausted and the system throws in that case.  (On systems with
  * over-commit/lazy-commit combined with virtual memory (swap), it is
  * rarely useful to check for memory exhaustion).
  * @exception Cgu::Thread::TaskError This exception will be thrown if
  * stop_all() has previously been called, unless that previous call
  * threw std::bad_alloc: if std::bad_alloc is thrown, this method may
  * be called again to stop all threads, once the memory deficiency is
  * dealt with, but no other methods of the TaskManager object should
  * be called.
  *
  * Since 2.0.12
  */
  void stop_all();

 /**
  * This method adds a new task.  If one or more threads in the pool
  * are currently blocking and waiting for a task, then the task will
  * begin executing immediately in one of the threads.  If not, and
  * the value returned by get_used_threads() is less than the value
  * returned by get_max_threads(), a new thread will start and the
  * task will execute immediately in the new thread.  Otherwise, the
  * task will be queued for execution as soon as a thread becomes
  * available.  Tasks will be executed in the order in which they are
  * added to the ThreadManager object.  This method is thread safe
  * (any thread may call it, including any task running on the
  * TaskManager object).
  *
  * A task may terminate itself prematurely by throwing
  * Cgu::Thread::Exit.  In addition, the implementation of TaskManager
  * will consume any other exception escaping from the task callback
  * and safely terminate the task concerned in order to protect the
  * integrity of the TaskManager object.  Where detecting any of these
  * outcomes is important (usually it won't be), the two argument
  * version of this method is available so that a 'fail' callback can
  * be executed in these circumstances.
  *
  * @param task A callback representing the new task, as constructed
  * by the Callback::make(), Callback::make_ref() or
  * Callback::lambda() factory functions.  Ownership is taken of this
  * callback, and it will be disposed of when it has been finished
  * with.  The destructors of any bound arguments in the callback must
  * not throw.
  * @exception std::bad_alloc This exception will be thrown if memory
  * is exhausted and the sytem throws in that case.  (On systems with
  * over-commit/lazy-commit combined with virtual memory (swap), it is
  * rarely useful to check for memory exhaustion).  If this exception
  * is thrown, the 'task' callback will be disposed of.
  * @exception Cgu::Thread::TaskError This exception will be thrown if
  * stop_all() has previously been called.  It will also be thrown if
  * is_error() would return true because this class's internal thread
  * pool loop implementation has thrown std::bad_alloc, or a thread
  * has failed to start correctly.  (On systems with
  * over-commit/lazy-commit combined with virtual memory (swap), it is
  * rarely useful to check for memory exhaustion, but there may be
  * some specialized cases where the return value of is_error() is
  * useful.)  If this exception is thrown, the 'task' callback will be
  * disposed of.
  * 
  * Since 2.0.12
  */
  void add_task(const Callback::Callback* task) {
#ifdef CGU_USE_AUTO_PTR
    add_task(std::auto_ptr<const Callback::Callback>(task),
             std::auto_ptr<const Callback::Callback>());
#else
    add_task(std::unique_ptr<const Callback::Callback>(task),
             std::unique_ptr<const Callback::Callback>());
#endif
  }

 /**
  * This method adds a new task.  If one or more threads in the pool
  * are currently blocking and waiting for a task, then the task will
  * begin executing immediately in one of the threads.  If not, and
  * the value returned by get_used_threads() is less than the value
  * returned by get_max_threads(), a new thread will start and the
  * task will execute immediately in the new thread.  Otherwise, the
  * task will be queued for execution as soon as a thread becomes
  * available.  Tasks will be executed in the order in which they are
  * added to the ThreadManager object.  This method is thread safe
  * (any thread may call it, including any task running on the
  * TaskManager object).
  *
  * A task may terminate itself prematurely by throwing
  * Cgu::Thread::Exit.  In addition, the implementation of TaskManager
  * will consume any other exception escaping from the task callback
  * and safely terminate the task concerned in order to protect the
  * integrity of the TaskManager object.  Where detecting any of these
  * outcomes is important (usually it won't be), a callback can be
  * passed to the 'fail' argument which will execute if, and only if,
  * either Cgu::Thread::Exit is thrown or some other exception has
  * propagated from the task.  This 'fail' callback is different from
  * the 'fail' callback of Cgu::Thread::Future objects (programming
  * for many tasks to a lesser number of threads requires different
  * approaches from programming for one thread per task), and it
  * executes in the task thread rather than executing in a glib main
  * loop (however, the 'fail' callback can of course call
  * Cgu::Callback::post() to execute another callback in a main loop,
  * if that is what is wanted).
  *
  * @param task A callback representing the new task, as constructed
  * by the Callback::make(), Callback::make_ref() or
  * Callback::lambda() factory functions.
  * @param fail A callback which will be executed if the function
  * executed by the 'task' callback exits by throwing Thread::Exit or
  * some other exception.  If an exception propagates from the
  * function represented by this callback, this will be consumed to
  * protect the TaskManager object, and a g_critical() warning will be
  * issued.
  * @exception std::bad_alloc This exception will be thrown if memory
  * is exhausted and the sytem throws in that case.  (On systems with
  * over-commit/lazy-commit combined with virtual memory (swap), it is
  * rarely useful to check for memory exhaustion).
  * @exception Cgu::Thread::TaskError This exception will be thrown if
  * stop_all() has previously been called.  It will also be thrown if
  * is_error() would return true because this class's internal thread
  * pool loop implementation has thrown std::bad_alloc, or a thread
  * has failed to start correctly.  (On systems with
  * over-commit/lazy-commit combined with virtual memory (swap), it is
  * rarely useful to check for memory exhaustion, but there may be
  * some specialized cases where the return value of is_error() is
  * useful.)
  * @note 1. Question: why does the single argument version of
  * add_task() take a pointer, and this version take the callbacks by
  * std::unique_ptr?  Answer: The two argument version of add_task()
  * takes its arguments by std::unique_ptr in order to be exception
  * safe if the first callback to be constructed is constructed
  * correctly but construction of the second callback object throws.
  * @note 2. If the library is compiled using the --with-auto-ptr
  * configuration option, then this method's signature is
  * add_task(std::auto_ptr<const Callback::Callback>,
  * std::auto_ptr<const Callback::Callback>) in order to retain
  * compatibility with the 1.2 series of the library
  * 
  * Since 2.0.12
  */
#ifdef CGU_USE_AUTO_PTR
  void add_task(std::auto_ptr<const Callback::Callback> task,
                std::auto_ptr<const Callback::Callback> fail);
#else
  void add_task(std::unique_ptr<const Callback::Callback> task,
                std::unique_ptr<const Callback::Callback> fail);
#endif

 /**
  * This will return true if a thread required by the thread pool has
  * failed to start correctly because of memory exhaustion or because
  * pthread has run out of other resources to start new threads, or
  * because an internal operation has thrown std::bad_alloc.  (On
  * systems with over-commit/lazy-commit combined with virtual memory
  * (swap), it is rarely useful to check for memory exhaustion, and
  * even more so where glib is used, as that terminates a program if
  * memory cannot be obtained from the operating system, but there may
  * be some specialized cases where the return value of this method is
  * useful - this class does not use any glib functions which might
  * cause such termination.)  This method will not throw and is thread
  * safe.
  * 
  * Since 2.0.12
  */
  bool is_error() const;

 /**
  * If the specified minimum number of threads is greater than 0, this
  * constructor will start the required minimum number of threads.  If
  * glib < 2.32 is installed, g_thread_init() must be called before
  * any TaskManager objects are constructed
  * @param max The maximum number of threads which the TaskManager
  * object will run in the thread pool.  If the value passed as this
  * argument is less than the value passed as 'min', the maximum
  * number of threads will be set to 'min'.  A value of 0 is not
  * valid, and if this is passed the number will be set to the greater
  * of 1 and 'min'.
  * @param min The minimum number of threads which the TaskManager
  * object will run in the thread pool.
  * @param idle The length of time in milliseconds that threads
  * greater in number than 'min' and not executing any tasks will
  * remain in existence.  The default is 10000 (10 seconds).
  * @param blocking If true, calls to stop_all() and the destructor
  * will not return until the tasks remaining to be executed have
  * finished (what is mean by "the tasks remaining to be executed"
  * depends on the StopMode setting, for which see the documentation
  * on the stop_all() method).  If false, stop_all() and the
  * destructor will return straight away (which in terms of the
  * TaskManager class implementation is safe for the reasons explained
  * in the documentation on the destructor).
  * @param mode The StopMode setting (either
  * Cgu::Thread::TaskManager::wait_for_running or
  * Cgu::Thread::TaskManager::wait_for_all) executed when running
  * stop_all() or when the destructor is called.  See the
  * documentation on stop_all() for an explanation of the setting.
  * @exception std::bad_alloc This exception might be thrown if memory
  * is exhausted and the system throws in that case.
  * @exception Cgu::Thread::TaskError This exception will be thrown if
  * starting the specified minimum number of threads fails.
  * @exception Cgu::Thread::MutexError This exception might be thrown
  * if initialisation of the contained mutex fails. (It is often not
  * worth checking for this, as it means either memory is exhausted or
  * pthread has run out of other resources to create new mutexes.)
  * @exception Cgu::Thread::CondError This exception might be thrown
  * if initialisation of the contained condition variable fails. (It
  * is often not worth checking for this, as it means either memory is
  * exhausted or pthread has run out of other resources to create new
  * condition variables.)
  *
  * Since 2.0.12
  */
  TaskManager(unsigned int max = 8, unsigned int min = 0,
              unsigned int idle = 10000, bool blocking = true,
              StopMode mode = TaskManager::wait_for_all);

 /**
  * The destructor will call stop_all(), unless that method has
  * previously been called explicitly without throwing std::bad_alloc.
  * If the blocking setting is true, the destructor will not return
  * until the tasks remaining to be executed have finished (what is
  * mean by "the tasks remaining to be executed" depends on the
  * StopMode setting, for which see the documentation on the
  * stop_all() method.)  If the blocking setting is false, the
  * destructor will return straight away: this is safe, because
  * TaskManager's internals for running tasks have been implemented
  * using reference counting and will not be deleted until all threads
  * running on the TaskManager object have finished, although the
  * remaining tasks should not attempt to call any of TaskManager's
  * methods once the TaskManager object itself has been destroyed.
  *
  * The destructor is thread safe (any thread can destroy a
  * TaskManager object) unless the blocking setting is true, in which
  * case no task running on the TaskManager object may destroy the
  * TaskManager object.  Subject to that, it is not an error for a
  * thread to destroy a TaskManager object and so invoke this
  * destructor while another thread is already blocking in (if the
  * blocking setting is true) or already out of (if the blocking
  * setting is false) a call to stop_all() and remaining tasks are
  * executing: if blocking, both calls (to stop_all() and to this
  * destructor) would safely block together.  Any given thread can
  * similarly safely follow a non-blocking call to stop_all() by a
  * non-blocking call to this destructor even though remaining tasks
  * are executing.  However, it is an error for a thread to call
  * stop_all() after another thread has begun destruction of the
  * TaskManager object (that is, after this destructor has been
  * entered): there would then be an unresolvable race with the
  * destructor.
  *
  * The destructor will not throw.
  *
  * If stop_all() has not previously been called explicitly and throws
  * std::bad_alloc() when called in this destructor, the exception
  * will be caught and consumed, but then the destructor will not
  * block even if the blocking setting is true, and if the minimum
  * number of threads is not 0 some threads might remain running
  * during the entire program duration (albeit safely).  Where the
  * throwing of std::bad_alloc is a meaningful event (usually it
  * isn't) and needs to be guarded against, call stop_all() explicitly
  * before this destructor is entered, or use a minimum thread value
  * of 0 and allow for the case of the destructor not blocking.
  *
  * Since 2.0.12
  */
  ~TaskManager();

/* Only has effect if --with-glib-memory-slices-compat or
 * --with-glib-memory-slices-no-compat option picked */
  CGU_GLIB_MEMORY_SLICES_FUNCS
};

} // namespace Thread

} // namespace Cgu

#endif