c++-gtk-utils
task_manager.h
Go to the documentation of this file.
1 /* Copyright (C) 2012 to 2014 Chris Vine
2 
3 The library comprised in this file or of which this file is part is
4 distributed by Chris Vine under the GNU Lesser General Public
5 License as follows:
6 
7  This library is free software; you can redistribute it and/or
8  modify it under the terms of the GNU Lesser General Public License
9  as published by the Free Software Foundation; either version 2.1 of
10  the License, or (at your option) any later version.
11 
12  This library is distributed in the hope that it will be useful, but
13  WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  Lesser General Public License, version 2.1, for more details.
16 
17  You should have received a copy of the GNU Lesser General Public
18  License, version 2.1, along with this library (see the file LGPL.TXT
19  which came with this source code package in the c++-gtk-utils
20  sub-directory); if not, write to the Free Software Foundation, Inc.,
21  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22 
23 However, it is not intended that the object code of a program whose
24 source code instantiates a template from this file or uses macros or
25 inline functions (of any length) should by reason only of that
26 instantiation or use be subject to the restrictions of use in the GNU
27 Lesser General Public License. With that in mind, the words "and
28 macros, inline functions and instantiations of templates (of any
29 length)" shall be treated as substituted for the words "and small
30 macros and small inline functions (ten lines or less in length)" in
31 the fourth paragraph of section 5 of that licence. This does not
32 affect any other reason why object code may be subject to the
33 restrictions in that licence (nor for the avoidance of doubt does it
34 affect the application of section 2 of that licence to modifications
35 of the source code in this file).
36 
37 */
38 
39 #ifndef CGU_TASK_MANAGER_H
40 #define CGU_TASK_MANAGER_H
41 
42 #include <deque>
43 #include <utility> // for std::pair, std::move and std::forward
44 #include <exception> // for std::exception
45 #include <memory> // for std::unique_ptr
46 #include <future> // for std::future and std::packaged_task
47 #include <type_traits> // for std::remove_reference, std::remove_const, std::enable_if,
48  // std::is_convertible and std::result_of
49 
50 #include <c++-gtk-utils/callback.h>
51 #include <c++-gtk-utils/thread.h>
52 #include <c++-gtk-utils/mutex.h>
56 #include <c++-gtk-utils/emitter.h>
58 
59 namespace Cgu {
60 
61 namespace Thread {
62 
63 struct TaskError: public std::exception {
64  virtual const char* what() const throw() {return "TaskError\n";}
65 };
66 
67 /**
68  * @class Cgu::Thread::TaskManager task_manager.h c++-gtk-utils/task_manager.h
69  * @brief A thread-pool class for managing tasks in multi-threaded programs.
70  * @sa Cgu::Thread::Future Cgu::AsyncResult Cgu::AsyncQueueDispatch Cgu::Callback::post() Cgu::Thread::TaskManager::IncHandle Cgu::Thread::parallel_for_each() Cgu::Thread::parallel_for_each_partial() Cgu::Thread::parallel_transform() Cgu::Thread::parallel_transform_partial()
71  *
72  * Cgu::Thread::Future operates on the principle of there being one
73  * worker thread per task. In some cases however, it may be better to
74  * have a limited pool of worker threads executing a larger number of
75  * tasks. This class implements this approach via a thread pool.
76  *
77  * One common approach for thread pools of this kind is to set the
78  * maximum number of threads to the number of cores, or some number
79  * less than the number of cores, available on the local machine. How
80  * that can be determined is system specific (on linux it can be
81  * obtained by, for example, counting the 'processor' fields in
82  * /proc/cpuinfo or by using sysconf with the glibc extension for
83  * _SC_NPROCESSORS_ONLN). From version 2.36, glib has a
84  * g_get_num_processors() function. From gcc-4.7, C++11's
85  * std::thread::hardware_concurrency() static member function is also
86  * available.
87  *
88  * The most general way of creating a new task is to call
89  * TaskManager::add_task() with a callable object (such as a lambda
90  * expression or the return value of std::bind) which returns void,
91  * although add_task() will also take a Callback::Callback object.
92  * Where the task needs to provide a result, two approaches can be
93  * adopted. First, the task callback can have a Cgu::AsyncResult
94  * object held by Cgu::SharedLockPtr (or by std::shared_ptr having a
95  * thread safe reference count) bound to it, or it can execute a
96  * std::packaged_task object from which it can obtain a std::future
97  * object. Alternatively, a task can provide a result asynchronously
98  * to a glib main loop by calling Cgu::Callback::post() when it is
99  * ready to do so. The TaskManager::make_task_result(),
100  * TaskManager::make_task_packaged(), TaskManager::make_task_when(),
101  * TaskManager::make_task_when_full(),
102  * TaskManager::make_task_compose(),
103  * TaskManager::make_task_packaged_when() and
104  * TaskManager::make_task_packaged_compose() convenience wrapper
105  * methods are provided which will set this up for you (including
106  * constructing appropriate task callbacks). This would normally be
107  * done by passing one of those functions a callable object which
108  * returns a value, such as a lambda expression or the return value of
109  * std::bind. Tasks can add other tasks, enabling the composition of
110  * an arbitrary number of tasks to obtain a final result.
111  *
112  * Overloads of TaskManager::make_task_result(),
113  * TaskManager::make_task_when() and
114  * TaskManager::make_task_when_full() also exist which take a function
115  * pointer (or an object reference and member function pointer) to a
116  * function which returns a value, with bound arguments, but these are
117  * deprecated in the 2.2 series of the library as they offer little
118  * advantage over using std::bind. (Although deprecated, there is no
119  * plan to remove these functions as they are there and they work -
120  * the deprecation is in effect guidance.) These deprecated functions
121  * can take up to three bound arguments in the case of a non-static
122  * member function, and four bound arguments in the case of any other
123  * function. In the case of a non-static member function, the
124  * referenced object whose member function is to be called must remain
125  * in existence until the task has completed. The target function
126  * passed by pointer (or member function pointer) can take a reference
127  * to const argument, as a copy of the object to be passed to the
128  * argument is taken to avoid dangling references, but it cannot take
129  * a reference to non-const argument.
130  *
131  * Copying of the return value of the target function or callable
132  * object represented by the task may take place. When a task
133  * completes, the return value will be stored, either in a
134  * Cgu::AsyncResult object (if TaskManager::make_task_result() is
135  * called) or in the shared state of a std::packaged_task object (if
136  * TaskManager::make_task_packaged(),
137  * TaskManager::make_task_packaged_when() or
138  * TaskManager::make_task_packaged_compose() is called) or for the
139  * purposes of executing the 'when' callback in a glib main loop (if
140  * TaskManager::make_task_when(), TaskManager::make_task_when_full()
141  * or TaskManager::make_task_compose() are called). This storage will
142  * therefore cause the return value type's assignment operator or copy
143  * constructor to be called once unless that type has a move
144  * assignment operator or move constructor, in which case a move
145  * operation will be made where possible. Note that a 'when' callback
146  * takes the stored return value by reference and so without any
147  * additional copying upon the 'when' callback being executed in the
148  * main loop.
149  *
150  * TaskManager objects do not provide thread cancellation. Thread
151  * cancellation is incompatible with the task-centred thread pool
152  * model. If task cancellation is wanted, use a Cgu::Thread::Future
153  * (or Cgu::Thread::Thread or Cgu::Thread::JoinableHandle) object
154  * instead, and have a dedicated thread for the cancelable task.
155  *
156  * If glib < 2.32 is installed, g_thread_init() must be called before
157  * any TaskManager objects are constructed, which in turn means that
158  * with glib < 2.32 TaskManager objects may not be constructed as
159  * static objects in global namespace (that is, before g_thread_init()
160  * has been called in the program).
161  *
162  * Any exceptions which propagate from a task will be consumed to
163  * protect the TaskManager object, and to detect whether this has
164  * happened there is a version of the TaskManager::add_task() method
165  * which takes a second argument comprising a 'fail' callback. If an
166  * exception propagates from the 'fail' callback that is also consumed
167  * and a g_critical() message issued.
168  * TaskManager::make_task_when_full() also provides for a 'fail'
169  * callback. TaskManager::make_task_packaged(),
170  * TaskManager::make_task_packaged_when() and
171  * TaskManager::make_task_packaged_compose() instead store an
172  * exception thrown by a task in the shared state of a
173  * std::packaged_task object, so that it is assessible from the
174  * associated std::future object.
175  *
176  * Tasks can be aborted by throwing Cgu::Thread::Exit (as well as any
177  * other exception). Where a task is managed by a TaskManager object,
178  * throwing Cgu::Thread::Exit will only terminate the task and not the
179  * thread on which it is running (and will cause the 'fail' callback
180  * to be executed, if there is one).
181  *
182  * Any 'fail' callback passed to TaskManager::add_task() or
183  * TaskManager::make_task_when_full() must be fully bound. Whilst a
184  * task can pass error status to the 'fail' callback via shared data
185  * bound to both the task and the 'fail' callback (held by, say, a
186  * SharedLockPtr object), or a global error stack, 'fail' callbacks
187  * are generally best reserved for use with entirely unexpected
188  * exceptions, where the most reasonable course is to perform some
189  * orderly logging and shutdown. For handlable exceptions, in an
190  * asynchronous environment the best course is often to catch them and
191  * deal with them in the task itself and (where
192  * TaskManager::make_task_when_full(), TaskManager::make_task_when()
193  * or TaskManager::make_task_compose() is employed) return a value of
194  * the task function's return type indicating no result.
195  * Alternatively, as mentioned above,
196  * TaskManager::make_task_packaged(),
197  * TaskManager::make_task_packaged_when() and
198  * TaskManager::make_task_packaged_compose() store an exception thrown
199  * by a task in the shared state of a std::packaged_task object
200  *
201  * TaskManager objects have no copy constructor or copy assignment
202  * operator, as copying them would have no obvious semantic meaning.
203  * Whilst swapping or moving TaskManager objects would be meaningful,
204  * this is not implemented either because it would require an
205  * additional internal lock to be thread safe, and the circumstances
206  * in which moving or swapping would be useful are limited. Where a
207  * move option is wanted, a TaskManager object can be constructed on
208  * free store and held by std::unique_ptr.
209  *
210  * Here is a compilable example of the calculator class referred to in
211  * the documentation on the AsyncResult but which uses a TaskManager
212  * object so that the calculator class can run more than one thread to
213  * service its calculations, using TaskManager::make_task_result():
214  *
215  * @code
216  * #include <vector>
217  * #include <numeric>
218  * #include <ostream>
219  * #include <iostream>
220  *
221  * #include <glib.h>
222  *
223  * #include <c++-gtk-utils/task_manager.h>
224  * #include <c++-gtk-utils/async_result.h>
225  * #include <c++-gtk-utils/shared_ptr.h>
226  *
227  * using namespace Cgu;
228  *
229  * class Calcs {
230  * Thread::TaskManager tm;
231  * public:
232  * SharedLockPtr<AsyncResult<double>> mean(const std::vector<double>& nums) {
233  * return tm.make_task_result([=]() -> double {
234  * if (nums.empty()) return 0.0;
235  * return std::accumulate(nums.begin(), nums.end(), 0.0)/nums.size();
236  * });
237  * }
238  *
239  * // ... other calculation methods here
240  * };
241  *
242  * int main () {
243  *
244  * g_thread_init(0);
245  * Calcs calcs;
246  * auto res1 = calcs.mean({1, 2, 8, 0});
247  * auto res2 = calcs.mean({101, 53.7, 87, 1.2});
248  *
249  * // ... do something else
250  * std::cout << res1->get() << std::endl;
251  * std::cout << res2->get() << std::endl;
252  *
253  * }
254  * @endcode
255  *
256  * The same could be done using TaskManager::make_task_packaged() as follows:
257  *
258  * @code
259  * #include <vector>
260  * #include <numeric>
261  * #include <ostream>
262  * #include <iostream>
263  * #include <future>
264  *
265  * #include <glib.h>
266  *
267  * #include <c++-gtk-utils/task_manager.h>
268  * #include <c++-gtk-utils/async_result.h>
269  * #include <c++-gtk-utils/shared_ptr.h>
270  *
271  * using namespace Cgu;
272  *
273  * class Calcs {
274  * Thread::TaskManager tm;
275  * public:
276  * std::future<double> mean(const std::vector<double>& nums) {
277  * return tm.make_task_packaged([=]() -> double {
278  * if (nums.empty()) return 0.0;
279  * return std::accumulate(nums.begin(), nums.end(), 0.0)/nums.size();
280  * });
281  * }
282  *
283  * // ... other calculation methods here
284  * };
285  *
286  * int main () {
287  *
288  * g_thread_init(0);
289  * Calcs calcs;
290  * auto res1 = calcs.mean({1, 2, 8, 0});
291  * auto res2 = calcs.mean({101, 53.7, 87, 1.2});
292  *
293  * // ... do something else
294  * std::cout << res1.get() << std::endl;
295  * std::cout << res2.get() << std::endl;
296  *
297  * }
298  * @endcode
299  *
300  * Here is a reimplementation, using TaskManager::make_task_when(), of
301  * the example using a get_primes() function given in the
302  * documentation for Cgu::Thread::Future:
303  * @code
304  * std::vector<long> get_primes(int n); // calculates the first n primes
305  *
306  * // get the first 1,000 primes
307  * using namespace Cgu;
308  *
309  * Thread::TaskManager tm;
310  * tm.make_task_when([] (const std::vector<long>& result) {
311  * for (const auto& elt: result) {std::cout << elt << std::endl;}
312  * },
313  * 0, // default main loop context
314  * [] () {return get_primes(1000);});
315  * @endcode
316  *
317  * Where a task running on a TaskManager object is to block, the
318  * TaskManager::IncHandle scoped handle class can be used to increment
319  * the maximum number of threads running on the object's thread pool
320  * temporarily while blocking takes place, so as to enable another
321  * thread to keep a core active. This can be useful where a task is
322  * to 'join' on another task when composing tasks: and it is usually
323  * essential to increment the maximum thread count temporarily where a
324  * task is to block on one of its sub-tasks, to avoid any possibility
325  * of deadlock through thread starvation (thread starvation occurs
326  * where all threads on a thread pool are occupied by tasks blocking
327  * on sub-tasks which have still to run on the thread pool, and which
328  * cannot run because the maximum thread count has been reached).
329  * Here is a compilable example:
330  *
331  * @code
332  * #include <iostream>
333  * #include <ostream>
334  *
335  * #include <glib.h>
336  *
337  * #include <c++-gtk-utils/task_manager.h>
338  *
339  * using namespace Cgu;
340  *
341  * // simulate a blocking operation, say from a server, with g_usleep()
342  * int mult(int x, int y) {
343  * g_usleep(100000);
344  * return x * y;
345  * }
346  *
347  * int main(int argc, char* argv[]) {
348  *
349  * g_thread_init(0);
350  * Thread::TaskManager tm{1}; // only one thread available unless blocking!
351  * GMainLoop* loop = g_main_loop_new(0, true);
352  *
353  * tm.make_task_when(
354  * [loop] (const int& res) {
355  * std::cout << res << std::endl;
356  * g_main_loop_quit(loop);
357  * },
358  * 0, // default main loop
359  * [&tm] () -> int {
360  * // this task multiplies 'a' by 2 and 'b' by 3, and adds the products
361  * int a = 10;
362  * int b = 12;
363  *
364  * // increment maximum thread count before launching sub-task and
365  * // then blocking
366  * Thread::TaskManager::IncHandle h{tm};
367  * // start a sub-task
368  * auto sub = tm.make_task_result([a, &tm] () -> int {
369  * // increment maximum thread count again before blocking in
370  * // this task (pretend that some other task in the program
371  * // may also want to run while both the parent task and this
372  * // task block on mult())
373  * Thread::TaskManager::IncHandle h{tm};
374  * return mult(a, 2);
375  * });
376  *
377  * int res = mult(b, 3)
378  * return sub->get() + res;
379  * }
380  * );
381  *
382  * g_main_loop_run(loop);
383  * }
384  * @endcode
385  *
386  * An alternative to using TaskManager::IncHandle for sub-tasks is to
387  * run the sub-tasks on their own threads via Thread::Future or
388  * std::async().
389  */
390 
391 // TODO: this is a work-around for gcc < 4.7, which has a bug which
392 // requires a function whose return value is determined by decltype,
393 // such as make_task_result(Func&&), to be inline. At a suitable
394 // API/ABI break when gcc requirements are updated, this should be
395 // moved to task_manager.tpp.
396 namespace TaskManagerHelper2 {
397 
398 template <class Ret, class FType>
400  static void exec(FType& f,
401  const SharedLockPtr<AsyncResult<Ret>>& ret) {
402  ret->set(f());
403  }
404  static void do_fail(const SharedLockPtr<AsyncResult<Ret>>& ret) {
405  ret->set_error(); // won't throw
406  }
407 };
408 
409 /*
410  * The FunctorResultExec class is a specialised class which is
411  * necessary because the 'functor' member needs to be declared mutable
412  * so that it can bind to the reference to non-const argument of
413  * FunctorResultWrapper::exec(), and thus so that a mutable lambda can
414  * be executed by that function. Because it is so specialised, it is
415  * not suitable for inclusion in the generic interfaces provided in
416  * callback.h. (Except in this specialised usage, it can also be
417  * dangerous, as it allows a member of the callback object to be
418  * mutated: normally this would be undesirable.) An alternative would
419  * have been to put the 'functor' member in a wrapper struct like
420  * MemfunWhenWrapperArgs or FunWhenWrapperArgs, but if 'functor' were
421  * an lvalue that would mean it being copied twice. This is the most
422  * efficient implementation.
423  */
424 template <class Ret, class FType>
426  mutable FType functor;
428 public:
429  void dispatch() const {FunctorResultWrapper<Ret, FType>::exec(functor, ret);}
430  // we don't need to templatize 'ret_' for perfect forwarding - it is
431  // always passed as a lvalue
432  template <class FunctorArg>
433  FunctorResultExec(FunctorArg&& functor_,
434  const SharedLockPtr<AsyncResult<Ret>>& ret_): functor(std::forward<FunctorArg>(functor_)),
435  ret(ret_) {}
436 };
437 
438 } // namespace TaskManagerHelper2
439 
440 
441 class TaskManager {
442  public:
444  class IncHandle;
445  private:
446  typedef std::pair<std::unique_ptr<const Callback::Callback>,
447  std::unique_ptr<const Callback::Callback>> QueueItemType;
448 
449  struct RefImpl; // reference counted implementation class
450  // it is fine holding RefImpl by plain pointer and not by
451  // IntrusivePtr: it is the only data member this class has, so it
452  // can safely manage that member in its own destructor and other
453  // methods
454  RefImpl* ref_impl;
455 
456  void set_max_threads_impl(unsigned int max, Mutex::TrackLock& lock);
457  public:
458 /**
459  * This class cannot be copied. The copy constructor is deleted.
460  */
461  TaskManager(const TaskManager&) = delete;
462 
463 /**
464  * This class cannot be copied. The assignment operator is deleted.
465  */
466  TaskManager& operator=(const TaskManager&) = delete;
467 
468  /**
469  * Gets the maximum number of threads which the TaskManager object is
470  * currently set to run in the thread pool. This value is established
471  * initially by the 'max' argument passed to the TaskManager
472  * constructor and can subequently be changed by calling
473  * set_max_threads() or change_max_threads(). The default value is
474  * 8. This method will not throw and is thread safe. However, if a
475  * blocking task might use the TaskManager::IncHandle class (or
476  * increase and then decrease the number by hand by calling
477  * change_max_threads()), this method will not usually be of any
478  * particular value.
479  * @return The maximum number of threads.
480  *
481  * Since 2.0.12
482  */
483  unsigned int get_max_threads() const;
484 
485  /**
486  * Gets the minimum number of threads which the TaskManager object
487  * will run in the thread pool (these threads will last until
488  * stop_all() is called or the TaskManager object is destroyed).
489  * This value is established by the 'min' argument passed to the
490  * TaskManager constructor and cannot subequently be changed. The
491  * default is 0. This method will not throw and is thread safe.
492  * @return The minimum number of threads.
493  *
494  * Since 2.0.12
495  */
496  unsigned int get_min_threads() const;
497 
498  /**
499  * Gets the number of threads which the TaskManager object is
500  * currently running in the thread pool, including those blocking
501  * waiting for a task. This value could be greater than the number
502  * returned by get_max_threads() if change_max_threads() has recently
503  * been called with a negative number but not enough tasks have since
504  * completed to reduce the number of running threads to the new value
505  * set. This method will not throw and is thread safe.
506  * @return The number of threads running in the thread pool,
507  * including those blocking waiting for a task.
508  *
509  * Since 2.0.12
510  */
511  unsigned int get_used_threads() const;
512 
513  /**
514  * Gets the number of tasks which the TaskManager object is at
515  * present either running in the thread pool or has queued for
516  * execution. This value will be less than the number returned by
517  * get_used_threads() if threads in the thread pool are currently
518  * waiting to receive tasks for execution. This method will not
519  * throw and is thread safe.
520  * @return The number of tasks either running or queued for
521  * execution.
522  *
523  * Since 2.0.12
524  */
525  unsigned int get_tasks() const;
526 
527  /**
528  * @deprecated
529  *
530  * DEPRECATED. Use change_max_threads() instead. This method will
531  * interfere with the intended operation of the
532  * ThreadManager::IncHandle class if one task constructs a IncHandle
533  * object and another calls this method.
534  *
535  * Sets the maximum number of threads which the TaskManager object
536  * will currently run in the thread pool. If this is less than the
537  * current number of running threads, the number of threads actually
538  * running will only be reduced as tasks complete, or as idle
539  * timeouts expire. This method does nothing if stop_all() has
540  * previously been called. This method is thread safe.
541  * @param max The maximum number of threads which the TaskManager
542  * object will currently run in the thread pool. This method will
543  * not set the maximum value of threads to a value less than that
544  * returned by get_min_threads(), nor to a value less than 1.
545  * @exception std::bad_alloc If this call is passed a value for 'max'
546  * which increases the maximum number of threads from its previous
547  * setting and tasks are currently queued for execution, new threads
548  * will be started for the queued tasks, so this exception may be
549  * thrown on starting the new threads if memory is exhausted and the
550  * system throws in that case. (On systems with
551  * over-commit/lazy-commit combined with virtual memory (swap), it is
552  * rarely useful to check for memory exhaustion).
553  * @exception Cgu::Thread::TaskError If this call is passed a value
554  * for 'max' which increases the maximum number of threads from its
555  * previous setting and tasks are currently queued for execution, new
556  * threads will be started for the queued tasks, so this exception
557  * may be thrown on starting the new threads if a thread fails to
558  * start correctly (this would mean that memory is exhausted, the
559  * pthread thread limit has been reached or pthread has run out of
560  * other resources to start new threads).
561  *
562  * Since 2.0.12
563  */
564  void set_max_threads(unsigned int max);
565 
566  /**
567  * This will increase, or if 'delta' is negative reduce, the maximum
568  * number of threads which the TaskManager object will currently run
569  * in the thread pool by the value of 'delta'. The purpose of this
570  * is to enable a task to increment the maximum thread number where
571  * it is about to enter a call which may block for some time, with a
572  * view to decrementing it later when it has finished making blocking
573  * calls, so as to enable another thread to keep a core active. If
574  * 'delta' is negative and results in a max_threads value of less
575  * than the current number of running threads, the number of threads
576  * actually running will only be reduced as tasks complete, or as
577  * idle timeouts expire. This method does nothing if stop_all() has
578  * previously been called. This method is thread safe. Since
579  * version 2.2.1, the scoped handle class TaskManager::IncHandle is
580  * available which calls this method.
581  * @param delta The change (positive or negative) to the maximum
582  * number of threads which the TaskManager object will currently run
583  * in the thread pool. This method will not set the maximum value of
584  * threads to a value less than that returned by get_min_threads(),
585  * nor to a value less than 1.
586  * @exception std::bad_alloc If this call is passed a positive value
587  * and tasks are currently queued for execution, a new thread or
588  * threads will be started for the queued tasks, so this exception
589  * may be thrown on starting a new thread if memory is exhausted and
590  * the system throws in that case. (On systems with
591  * over-commit/lazy-commit combined with virtual memory (swap), it is
592  * rarely useful to check for memory exhaustion).
593  * @exception Cgu::Thread::TaskError If this call is passed a
594  * positive value and tasks are currently queued for execution, a new
595  * thread or threads will be started for the queued tasks, so this
596  * exception may be thrown on starting a new thread if it fails to
597  * start correctly (this would mean that memory is exhausted, the
598  * pthread thread limit has been reached or pthread has run out of
599  * other resources to start new threads).
600  *
601  * Since 2.0.14
602  */
603  void change_max_threads(int delta);
604 
605  /**
606  * Gets the length of time in milliseconds that threads greater in
607  * number than the minimum and not executing any tasks will remain in
608  * existence waiting for new tasks. This value is established
609  * initially by the 'idle' argument passed to the TaskManager
610  * constructor and can subequently be changed by calling
611  * set_idle_time(). The default value is 10000 (10 seconds). This
612  * method will not throw and is thread safe.
613  * @return The idle time in milliseconds.
614  *
615  * Since 2.0.12
616  */
617  unsigned int get_idle_time() const;
618 
619  /**
620  * Sets the length of time in milliseconds that threads greater in
621  * number than the minimum and not executing any tasks will remain in
622  * existence waiting for new tasks. This will only have effect for
623  * threads in the pool which begin waiting for new tasks after this
624  * method is called. This method will not throw and is thread safe.
625  * @param idle The length of the idle time in milliseconds during
626  * which threads will remain waiting for new tasks.
627  *
628  * Since 2.0.12
629  */
630  void set_idle_time(unsigned int idle);
631 
632  /**
633  * Gets the current blocking setting, which determines whether calls
634  * to stop_all() and the destructor will block waiting for all
635  * remaining tasks to complete. This value is established initially
636  * by the 'blocking' argument passed to the TaskManager constructor
637  * and can subequently be changed by calling set_blocking(). This
638  * method will not throw and is thread safe.
639  * @return The current blocking setting.
640  *
641  * Since 2.0.12
642  */
643  bool get_blocking() const;
644 
645  /**
646  * Sets the current blocking setting, which determines whether calls
647  * to stop_all() and the destructor will block waiting for all
648  * remaining tasks to complete. This method cannot be called after
649  * stop_all() has been called (if that is attempted,
650  * Cgu::Thread::TaskError will be thrown). It is thread safe.
651  * @param blocking The new blocking setting.
652  * @exception Cgu::Thread::TaskError This exception will be thrown if
653  * stop_all() has previously been called.
654  *
655  * Since 2.0.12
656  */
657  void set_blocking(bool blocking);
658 
659  /**
660  * Gets the current StopMode setting (either
661  * Cgu::Thread::TaskManager::wait_for_running or
662  * Cgu::Thread::TaskManager::wait_for_all) executed when running
663  * stop_all() or when the destructor is called. See the
664  * documentation on stop_all() for an explanation of the setting.
665  * This value is established initially by the 'mode' argument passed
666  * to the TaskManager constructor and can subequently be changed by
667  * calling set_stop_mode(). This method will not throw and is thread
668  * safe.
669  * @return The current StopMode setting.
670  *
671  * Since 2.0.12
672  */
673  StopMode get_stop_mode() const;
674 
675  /**
676  * Sets the current StopMode setting (either
677  * Cgu::Thread::TaskManager::wait_for_running or
678  * Cgu::Thread::TaskManager::wait_for_all) executed when running
679  * stop_all() or when the destructor is called. See the
680  * documentation on stop_all() for an explanation of the setting.
681  * This method will not throw and is thread safe.
682  * @param mode The new StopMode setting.
683  *
684  * Since 2.0.12
685  */
686  void set_stop_mode(StopMode mode);
687 
688  /**
689  * This will cause the TaskManager object to stop running tasks. The
690  * precise effect depends on the current StopMode and blocking
691  * settings. If StopMode is set to
692  * Cgu::Thread::TaskManager::wait_for_running, all queued tasks which
693  * are not yet running on a thread will be dispensed with, but any
694  * already running will be left to complete normally. If StopMode is
695  * set to Cgu::Thread::TaskManager::wait_for_all, both already
696  * running tasks and all tasks already queued will be permitted to
697  * execute and complete normally. If the blocking setting is set to
698  * true, this method will wait until all the tasks still to execute
699  * have finished before returning, and if false it will return
700  * straight away.
701  *
702  * The StopMode setting should not be set to
703  * Cgu::Thread::TaskManager::wait_for_running if, when this method is
704  * called, another thread may be waiting on the get() or move_get()
705  * method of a Cgu::AsyncResult object returned by
706  * Cgu::Thread::TaskManager::make_task_result(), as otherwise that
707  * wait may never end - choose the
708  * Cgu::Thread::TaskManager::wait_for_all setting instead in such
709  * cases. This restriction does not apply to a thread waiting on a
710  * std::future object returned by
711  * Cgu::Thread::TaskManager::make_task_packaged(): instead
712  * std::future::get() will unblock and throw an exception upon the
713  * associated std::packaged_task object being destroyed as unexecuted
714  * queued tasks are dispensed with.
715  *
716  * After this method has been called, any attempt to add further
717  * tasks with the add_task() method will fail, and add_task() will
718  * throw Cgu::Thread::TaskError.
719  *
720  * This method is thread safe (any thread may call it) unless the
721  * blocking setting is true, in which case no task running on the
722  * TaskManager object may call this method.
723  *
724  * @exception std::bad_alloc This exception will be thrown if memory
725  * is exhausted and the system throws in that case. (On systems with
726  * over-commit/lazy-commit combined with virtual memory (swap), it is
727  * rarely useful to check for memory exhaustion).
728  * @exception Cgu::Thread::TaskError This exception will be thrown if
729  * stop_all() has previously been called, unless that previous call
730  * threw std::bad_alloc: if std::bad_alloc is thrown, this method may
731  * be called again to stop all threads, once the memory deficiency is
732  * dealt with, but no other methods of the TaskManager object should
733  * be called.
734  *
735  * Since 2.0.12
736  */
737  void stop_all();
738 
739  /**
740  * This method adds a new task. If one or more threads in the pool
741  * are currently blocking and waiting for a task, then the task will
742  * begin executing immediately in one of the threads. If not, and
743  * the value returned by get_used_threads() is less than the value
744  * returned by get_max_threads(), a new thread will start and the
745  * task will execute immediately in the new thread. Otherwise, the
746  * task will be queued for execution as soon as a thread becomes
747  * available. Tasks will be executed in the order in which they are
748  * added to the ThreadManager object. This method is thread safe
749  * (any thread may call it, including any task running on the
750  * TaskManager object).
751  *
752  * A task may terminate itself prematurely by throwing
753  * Cgu::Thread::Exit. In addition, the implementation of TaskManager
754  * will consume any other exception escaping from the task callback
755  * and safely terminate the task concerned in order to protect the
756  * integrity of the TaskManager object. Where detecting any of these
757  * outcomes is important (usually it won't be), the two argument
758  * version of this method is available so that a 'fail' callback can
759  * be executed in these circumstances.
760  *
761  * @param task A callback representing the new task, as constructed
762  * by the Callback::lambda(), Callback::make() or
763  * Callback::make_ref() factory functions. Ownership is taken of
764  * this callback, and it will be disposed of when it has been
765  * finished with. If an exception propagates from the task, the
766  * exception will be consumed and (if the thrown object's type is not
767  * Cgu::Thread::Exit) a g_critical() warning will be issued. The
768  * destructors of any bound arguments in the callback must not throw.
769  * @exception std::bad_alloc This exception will be thrown if memory
770  * is exhausted and the system throws in that case. (On systems with
771  * over-commit/lazy-commit combined with virtual memory (swap), it is
772  * rarely useful to check for memory exhaustion). If this exception
773  * is thrown, the task will not start and the 'task' callback will be
774  * disposed of.
775  * @exception Cgu::Thread::TaskError This exception will be thrown if
776  * stop_all() has previously been called. It will also be thrown if
777  * is_error() would return true because this class's internal thread
778  * pool loop implementation has thrown std::bad_alloc, or a thread
779  * has failed to start correctly. (On systems with
780  * over-commit/lazy-commit combined with virtual memory (swap), it is
781  * rarely useful to check for memory exhaustion, but there may be
782  * some specialized cases where the return value of is_error() is
783  * useful.) If this exception is thrown, the task will not start and
784  * the 'task' callback will be disposed of.
785  *
786  * Since 2.0.12
787  */
788  void add_task(const Callback::Callback* task) {
789  add_task(std::unique_ptr<const Callback::Callback>(task),
790  std::unique_ptr<const Callback::Callback>());
791  }
792 
793  /**
794  * This method adds a new task. If one or more threads in the pool
795  * are currently blocking and waiting for a task, then the task will
796  * begin executing immediately in one of the threads. If not, and
797  * the value returned by get_used_threads() is less than the value
798  * returned by get_max_threads(), a new thread will start and the
799  * task will execute immediately in the new thread. Otherwise, the
800  * task will be queued for execution as soon as a thread becomes
801  * available. Tasks will be executed in the order in which they are
802  * added to the ThreadManager object. This method is thread safe
803  * (any thread may call it, including any task running on the
804  * TaskManager object).
805  *
806  * A task may terminate itself prematurely by throwing
807  * Cgu::Thread::Exit. In addition, the implementation of TaskManager
808  * will consume any other exception escaping from the task callback
809  * and safely terminate the task concerned in order to protect the
810  * integrity of the TaskManager object. Where detecting any of these
811  * outcomes is important (usually it won't be), a callback can be
812  * passed to the 'fail' argument which will execute if, and only if,
813  * either Cgu::Thread::Exit is thrown or some other exception has
814  * propagated from the task. This 'fail' callback is different from
815  * the 'fail' callback of Cgu::Thread::Future objects (programming
816  * for many tasks to a lesser number of threads requires different
817  * approaches from programming for one thread per task), and it
818  * executes in the task thread rather than executing in a glib main
819  * loop (however, the 'fail' callback can of course call
820  * Cgu::Callback::post() to execute another callback in a main loop,
821  * if that is what is wanted).
822  *
823  * @param task A callback representing the new task, as constructed
824  * by the Callback::lambda(), Callback::make() or
825  * Callback::make_ref() factory functions. If an exception
826  * propagates from the task, the exception will be consumed and the
827  * 'fail' callback will execute.
828  * @param fail A callback (as constructed by the Callback::lambda(),
829  * Callback::make() or Callback::make_ref() factory functions) which
830  * will be executed if the function or callable object executed by
831  * the 'task' callback exits by throwing Thread::Exit or some other
832  * exception. If an exception propagates from the 'fail' callback,
833  * this will be consumed to protect the TaskManager object, and a
834  * g_critical() warning will be issued.
835  * @exception std::bad_alloc This exception will be thrown if memory
836  * is exhausted and the system throws in that case. (On systems with
837  * over-commit/lazy-commit combined with virtual memory (swap), it is
838  * rarely useful to check for memory exhaustion). If this exception
839  * is thrown, the task will not start (which also means that the
840  * 'fail' callback will not execute).
841  * @exception Cgu::Thread::TaskError This exception will be thrown if
842  * stop_all() has previously been called. It will also be thrown if
843  * is_error() would return true because this class's internal thread
844  * pool loop implementation has thrown std::bad_alloc, or a thread
845  * has failed to start correctly. (On systems with
846  * over-commit/lazy-commit combined with virtual memory (swap), it is
847  * rarely useful to check for memory exhaustion, but there may be
848  * some specialized cases where the return value of is_error() is
849  * useful.) If this exception is thrown, the task will not start
850  * (which also means that the 'fail' callback will not execute).
851  *
852  * Since 2.0.12
853  */
854  void add_task(std::unique_ptr<const Callback::Callback> task,
855  std::unique_ptr<const Callback::Callback> fail);
856 
857  /**
858  * This method adds a new task. If one or more threads in the pool
859  * are currently blocking and waiting for a task, then the task will
860  * begin executing immediately in one of the threads. If not, and
861  * the value returned by get_used_threads() is less than the value
862  * returned by get_max_threads(), a new thread will start and the
863  * task will execute immediately in the new thread. Otherwise, the
864  * task will be queued for execution as soon as a thread becomes
865  * available. Tasks will be executed in the order in which they are
866  * added to the ThreadManager object. This method is thread safe
867  * (any thread may call it, including any task running on the
868  * TaskManager object).
869  *
870  * A task may terminate itself prematurely by throwing
871  * Cgu::Thread::Exit. In addition, the implementation of TaskManager
872  * will consume any other exception escaping from the task callback
873  * and safely terminate the task concerned in order to protect the
874  * integrity of the TaskManager object. Where detecting any of these
875  * outcomes is important (usually it won't be), the two argument
876  * version of this method is available so that a 'fail' callback can
877  * be executed in these circumstances.
878  *
879  * @param task A callable object representing the new task, such as
880  * formed by a lambda expression or the result of std::bind. It must
881  * be fully bound (that is, it must take no arguments when called).
882  * If an exception propagates from the task, the exception will be
883  * consumed and (if the thrown object's type is not
884  * Cgu::Thread::Exit) a g_critical() warning will be issued. The
885  * destructors of any bound values must not throw.
886  * @exception std::bad_alloc This exception will be thrown if memory
887  * is exhausted and the system throws in that case. (On systems with
888  * over-commit/lazy-commit combined with virtual memory (swap), it is
889  * rarely useful to check for memory exhaustion). If this exception
890  * is thrown, the task will not start.
891  * @exception Cgu::Thread::TaskError This exception will be thrown if
892  * stop_all() has previously been called. It will also be thrown if
893  * is_error() would return true because this class's internal thread
894  * pool loop implementation has thrown std::bad_alloc, or a thread
895  * has failed to start correctly. (On systems with
896  * over-commit/lazy-commit combined with virtual memory (swap), it is
897  * rarely useful to check for memory exhaustion, but there may be
898  * some specialized cases where the return value of is_error() is
899  * useful.) If this exception is thrown, the task will not start.
900  * @note An exception might also be thrown if the copy or move
901  * constructor of the callable object throws. If such an exception
902  * is thrown, the task will not start.
903  *
904  * Since 2.1.0
905  */
906  // we need to use enable_if so that where this function is passed a
907  // pointer to non-const Callback::Callback, or some other
908  // convertible pointer, this templated overload is dropped from the
909  // overload set, in order to support the Callback::Callback
910  // overloads of this function. This overload calls into the version
911  // of this function taking a pointer to const Callback::Callback in
912  // order to perform type erasure.
913  template <class Task,
914  class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<Task>::type,
915  const Callback::Callback*>::value>::type>
916  void add_task(Task&& task) {
917  add_task(std::unique_ptr<const Callback::Callback>(Callback::lambda<>(std::forward<Task>(task))),
918  std::unique_ptr<const Callback::Callback>());
919  }
920 
921  /**
922  * This method adds a new task. If one or more threads in the pool
923  * are currently blocking and waiting for a task, then the task will
924  * begin executing immediately in one of the threads. If not, and
925  * the value returned by get_used_threads() is less than the value
926  * returned by get_max_threads(), a new thread will start and the
927  * task will execute immediately in the new thread. Otherwise, the
928  * task will be queued for execution as soon as a thread becomes
929  * available. Tasks will be executed in the order in which they are
930  * added to the ThreadManager object. This method is thread safe
931  * (any thread may call it, including any task running on the
932  * TaskManager object).
933  *
934  * A task may terminate itself prematurely by throwing
935  * Cgu::Thread::Exit. In addition, the implementation of TaskManager
936  * will consume any other exception escaping from the task callback
937  * and safely terminate the task concerned in order to protect the
938  * integrity of the TaskManager object. Where detecting any of these
939  * outcomes is important (usually it won't be), a callback can be
940  * passed to the 'fail' argument which will execute if, and only if,
941  * either Cgu::Thread::Exit is thrown or some other exception has
942  * propagated from the task. This 'fail' callback is different from
943  * the 'fail' callback of Cgu::Thread::Future objects (programming
944  * for many tasks to a lesser number of threads requires different
945  * approaches from programming for one thread per task), and it
946  * executes in the task thread rather than executing in a glib main
947  * loop (however, the 'fail' callback can of course call
948  * Cgu::Callback::post() to execute another callback in a main loop,
949  * if that is what is wanted).
950  *
951  * @param task A callable object representing the new task, such as
952  * formed by a lambda expression or the result of std::bind. It must
953  * be fully bound (that is, it must take no arguments when called).
954  * The destructors of any bound values must not throw. If an exception
955  * propagates from the task, the exception will be consumed and the
956  * 'fail' callback will execute.
957  * @param fail A callable object (such as formed by a lambda
958  * expression or the result of std::bind) which will be executed if
959  * the callable object represented by the 'task' callback exits by
960  * throwing Thread::Exit or some other exception. It must be fully
961  * bound (that is, it must take no arguments when called). The
962  * destructors of any bound values must not throw. If an exception
963  * propagates from the 'fail' callback, this will be consumed to
964  * protect the TaskManager object, and a g_critical() warning will be
965  * issued.
966  * @exception std::bad_alloc This exception will be thrown if memory
967  * is exhausted and the system throws in that case. (On systems with
968  * over-commit/lazy-commit combined with virtual memory (swap), it is
969  * rarely useful to check for memory exhaustion). If this exception
970  * is thrown, the task will not start (which also means that the
971  * 'fail' callback will not execute).
972  * @exception Cgu::Thread::TaskError This exception will be thrown if
973  * stop_all() has previously been called. It will also be thrown if
974  * is_error() would return true because this class's internal thread
975  * pool loop implementation has thrown std::bad_alloc, or a thread
976  * has failed to start correctly. (On systems with
977  * over-commit/lazy-commit combined with virtual memory (swap), it is
978  * rarely useful to check for memory exhaustion, but there may be
979  * some specialized cases where the return value of is_error() is
980  * useful.) If this exception is thrown, the task will not start
981  * (which also means that the 'fail' callback will not execute).
982  * @note An exception might also be thrown if the copy or move
983  * constructor of the 'task' or 'fail' callable objects throws. If
984  * such an exception is thrown, the task will not start (which also
985  * means that the 'fail' callback will not execute)
986  *
987  * Since 2.1.0
988  */
989  // we need to use enable_if so that where this function is passed
990  // unique_ptr's holding non-const Callback::Callback objects, or
991  // some other convertible object, this templated overload is dropped
992  // from the overload set, in order to support the unique_ptr
993  // overloads of this function. This overload calls into the version
994  // of this function taking Callback objects by unique_ptr in order
995  // to perform type erasure.
996  template <class Task, class Fail,
997  class = typename std::enable_if<!std::is_convertible<Task, std::unique_ptr<const Callback::Callback>>::value
998  && !std::is_convertible<Fail, std::unique_ptr<const Callback::Callback>>::value>::type>
999  void add_task(Task&& task, Fail&& fail) {
1000  std::unique_ptr<const Callback::Callback> task_cb(
1001  Callback::lambda<>(std::forward<Task>(task))
1002  );
1003  std::unique_ptr<const Callback::Callback> fail_cb(
1004  Callback::lambda<>(std::forward<Fail>(fail))
1005  );
1006  add_task(std::move(task_cb), std::move(fail_cb));
1007  }
1008 
1009  /**
1010  * This will return true if a thread required by the thread pool has
1011  * failed to start correctly because of memory exhaustion or because
1012  * pthread has run out of other resources to start new threads, or
1013  * because an internal operation has thrown std::bad_alloc. (On
1014  * systems with over-commit/lazy-commit combined with virtual memory
1015  * (swap), it is rarely useful to check for memory exhaustion, and
1016  * even more so where glib is used, as that terminates a program if
1017  * memory cannot be obtained from the operating system, but there may
1018  * be some specialized cases where the return value of this method is
1019  * useful - this class does not use any glib functions which might
1020  * cause such termination.) This method will not throw and is thread
1021  * safe.
1022  *
1023  * Since 2.0.12
1024  */
1025  bool is_error() const;
1026 
1027  /**
1028  * @deprecated
1029  *
1030  * DEPRECATED. Use the versions of make_task_result() which take
1031  * callable objects.
1032  *
1033  * This is a wrapper which takes a member function pointer to a
1034  * member function which returns a value, together with arguments,
1035  * and constructs a TaskManager task which will execute that function
1036  * by calling add_task() with an appropriate callback object, and
1037  * returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr)
1038  * which will provide the value that the function returns. Apart
1039  * from the absence of a 'one thread per task' model, this method
1040  * therefore provides a similar interface to the one provided by
1041  * Cgu::Thread::Future. It is thread safe: any thread may call this
1042  * method, including another task running on the TaskManager object,
1043  * but see the introductory remarks about the use of the
1044  * TaskManager::IncHandle scoped handle class where a task running on
1045  * a TaskManager object is to block on one of its sub-tasks. See
1046  * also the documentation on add_task() for further information about
1047  * how task execution works.
1048  *
1049  * This method can take up to three bound arguments for the target
1050  * member function.
1051  *
1052  * If the function passed to this method exits by throwing
1053  * Thread::Exit or some other exception, then the exception will be
1054  * consumed and the returned Cgu::AsyncResult object's get() or
1055  * move_get() method will unblock and its get_error() method will
1056  * return -1.
1057  *
1058  * @param t The object whose member function passed to this method is
1059  * to execute as a task.
1060  * @param func The member function to be executed as a task.
1061  * @param args The arguments to be passed to that member function.
1062  * @exception std::bad_alloc This exception will be thrown if memory
1063  * is exhausted and the system throws in that case. (On systems with
1064  * over-commit/lazy-commit combined with virtual memory (swap), it is
1065  * rarely useful to check for memory exhaustion). If this exception
1066  * is thrown, the task will not start.
1067  * @exception Cgu::Thread::TaskError This exception will be thrown if
1068  * stop_all() has previously been called. It will also be thrown if
1069  * is_error() would return true because this class's internal thread
1070  * pool loop implementation has thrown std::bad_alloc, or a thread
1071  * has failed to start correctly. (On systems with
1072  * over-commit/lazy-commit combined with virtual memory (swap), it is
1073  * rarely useful to check for memory exhaustion, but there may be
1074  * some specialized cases where the return value of is_error() is
1075  * useful.) If this exception is thrown, the task will not start.
1076  * @note This method will also throw if the copy or move constructor
1077  * of a bound argument throws. If such an exception is thrown, the
1078  * task will not start.
1079  *
1080  * Since 2.0.13
1081  */
1082 
1083  template <class Ret, class... Params, class... Args, class T>
1085  Ret (T::*func)(Params...),
1086  Args&&... args);
1087 
1088  /**
1089  * @deprecated
1090  *
1091  * DEPRECATED. Use the versions of make_task_when_full() which take
1092  * callable objects.
1093  *
1094  * This is a wrapper which takes a member function pointer to a
1095  * member function which returns a value, together with arguments,
1096  * and constructs a TaskManager task which will execute that function
1097  * by calling add_task() with an appropriate callback object, and
1098  * causes the 'when' callback passed as an argument to this method to
1099  * be executed by a glib main loop if and when the task finishes
1100  * correctly - the 'when' callback is passed the member function's
1101  * return value when it is invoked. It is thread safe (any thread
1102  * may call this method, including another task running on the
1103  * TaskManager object). Apart from the absence of a 'one thread per
1104  * task' model, this method therefore provides a similar interface to
1105  * the one provided by Cgu::Thread::Future. See the documentation on
1106  * add_task() for further information about how task execution works.
1107  *
1108  * This method can take up to three bound arguments for the target
1109  * member function.
1110  *
1111  * Note that unlike add_task(), but like the 'fail' callback of
1112  * Cgu::Thread::Future objects, if a fail callback is provided to
1113  * this method and it executes, it will execute in the glib main loop
1114  * whose GMainContext object is passed to the 'context' argument of
1115  * this method.
1116  *
1117  * Note also that if releasers are provided for the 'when' or 'fail'
1118  * callbacks, these are passed by pointer and not by reference (this
1119  * is so that a NULL pointer can indicate that no releaser is to be
1120  * provided). If provided, a releaser will enable automatic
1121  * disconnection of the 'when' or 'fail' callback, if the object
1122  * having the callback function as a member is destroyed. For this to
1123  * be race free, the lifetime of that object must be controlled by
1124  * the thread in whose main loop the 'when' or 'fail' callback will
1125  * execute.
1126  *
1127  * The make_task_when() method is similar to this method but provides
1128  * an abbreviated set of paramaters suitable for most cases. This
1129  * method is for use where releasers or a 'fail' callback are
1130  * required.
1131  *
1132  * @param when A callback which will be executed if and when the
1133  * function passed to this method finishes correctly. The callback is
1134  * passed that function's return value when it is invoked. If an
1135  * exception propagates from the 'when' callback, this will be
1136  * consumed and a g_critical() warning will be issued. The callback
1137  * will execute in the glib main loop whose GMainContext object is
1138  * passed to the 'context' argument of this method.
1139  * @param when_releaser A pointer to a Releaser object for automatic
1140  * disconnection of the 'when' callback before it executes in a main
1141  * loop (mainly relevant if the callback represents a non-static
1142  * member function of an object which may be destroyed before the
1143  * callback executes). A value of 0/NULL/nullptr indicates no
1144  * releaser.
1145  * @param fail A callback which will be executed if the 'when'
1146  * callback does not execute. This would happen if the function
1147  * passed to this method exits by throwing Thread::Exit or some other
1148  * exception or the copy constructor of a non-reference argument of
1149  * that function throws, or if the 'when' callback does not execute
1150  * because the internal implementation of this wrapper throws
1151  * std::bad_alloc (which will not happen if the library has been
1152  * installed using the \--with-glib-memory-slices-no-compat
1153  * configuration option: instead glib will terminate the program if
1154  * it is unable to obtain memory from the operating system). If an
1155  * exception propagates from the 'fail' callback, this will be
1156  * consumed and a g_critical() warning will be issued. The callback
1157  * will execute in the glib main loop whose GMainContext object is
1158  * passed to the 'context' argument of this method. An empty
1159  * std::unique_ptr object indicates no 'fail' callback.
1160  * @param fail_releaser A pointer to a Releaser object for automatic
1161  * disconnection of the 'fail' callback before it executes in a main
1162  * loop (mainly relevant if the callback represents a non-static
1163  * member function of an object which may be destroyed before the
1164  * callback executes). A value of 0/NULL/nullptr indicates no
1165  * releaser.
1166  * @param priority The priority to be given in the main loop to the
1167  * 'when' callback or any 'fail' callback. In ascending order of
1168  * priorities, priorities are G_PRIORITY_LOW,
1169  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
1170  * and G_PRIORITY_HIGH. This determines the order in which the
1171  * callback will appear in the event list in the main loop, not the
1172  * priority which the OS will adopt.
1173  * @param context The glib main context of the main loop in which the
1174  * 'when' callback or any 'fail' callback is to be executed. A value
1175  * 0/NULL/nullptr will cause the callback to be executed in the main
1176  * program loop.
1177  * @param t The object whose member function passed to this method is
1178  * to execute as a task.
1179  * @param func The member function to be executed as a task. If an
1180  * exception propagates from the task, the exception will be consumed
1181  * and the 'fail' callback will execute.
1182  * @param args The arguments to be passed to that member function.
1183  * @exception std::bad_alloc This exception will be thrown if memory
1184  * is exhausted and the system throws in that case. (On systems with
1185  * over-commit/lazy-commit combined with virtual memory (swap), it is
1186  * rarely useful to check for memory exhaustion). If this exception
1187  * is thrown, the task will not start (which also means that the
1188  * 'when' and 'fail' callbacks will not execute).
1189  * @exception Cgu::Thread::TaskError This exception will be thrown if
1190  * stop_all() has previously been called. It will also be thrown if
1191  * is_error() would return true because this class's internal thread
1192  * pool loop implementation has thrown std::bad_alloc, or a thread
1193  * has failed to start correctly. (On systems with
1194  * over-commit/lazy-commit combined with virtual memory (swap), it is
1195  * rarely useful to check for memory exhaustion, but there may be
1196  * some specialized cases where the return value of is_error() is
1197  * useful.) If this exception is thrown, the task will not start
1198  * (which also means that the 'when' and 'fail' callbacks will not
1199  * execute).
1200  * @note 1. This method will also throw if the copy or move
1201  * constructor of a bound argument throws. If such an exception is
1202  * thrown, the task will not start (which also means that the 'when'
1203  * and 'fail' callbacks will not execute).
1204  * @note 2. If a 'when_releaser' or a 'fail_releaser' object is
1205  * provided, it is in theory possible (if memory is exhausted and the
1206  * system throws in that case) that an internal SafeEmitterArg object
1207  * will throw std::bad_alloc when emitting/executing the 'when' or
1208  * 'fail' callback in the glib main loop, with the result that the
1209  * relevant callback will not execute (instead the exception will be
1210  * consumed and a g_critical() warning will be issued). This is
1211  * rarely of any relevance because glib will abort the program if it
1212  * is itself unable to obtain memory from the operating system.
1213  * However, where it is relevant, design the program so that it is
1214  * not necessary to provide a releaser object.
1215  *
1216  * Since 2.0.13
1217  */
1218  template <class Ret, class... Params, class... Args, class T>
1219  void make_task_when_full(std::unique_ptr<const Cgu::Callback::CallbackArg<const Ret&>> when,
1220  Cgu::Releaser* when_releaser,
1221  std::unique_ptr<const Cgu::Callback::Callback> fail,
1222  Cgu::Releaser* fail_releaser,
1223  gint priority,
1224  GMainContext* context,
1225  T& t,
1226  Ret (T::*func)(Params...),
1227  Args&&... args);
1228 
1229  /**
1230  * @deprecated
1231  *
1232  * DEPRECATED. Use the versions of make_task_when() which take
1233  * callable objects.
1234  *
1235  * This is an abbreviated version of make_task_when_full(), which is
1236  * for use when it is known that the member function passed to this
1237  * method, and the copy constructors of any non-reference bound
1238  * arguments passed to it, do not throw, and the user is not
1239  * interested in std::bad_alloc and does not need a Cgu::Releaser
1240  * object for the 'when' callback (which is likely to cover the
1241  * majority of uses, particularly when composing tasks using glib
1242  * because glib terminates the program if it is unable to obtain
1243  * memory).
1244  *
1245  * This method can take up to three bound arguments for the target
1246  * member function.
1247  *
1248  * Like make_task_when_full(), this method is a wrapper which takes a
1249  * member function pointer to a member function which returns a
1250  * value, together with arguments, and constructs a TaskManager task
1251  * which will execute that function by calling add_task() with an
1252  * appropriate callback object, and causes the 'when' callback passed
1253  * as an argument to this method to be executed by a glib main loop
1254  * if and when the task finishes correctly - the 'when' callback is
1255  * passed the member function's return value when it is invoked. It
1256  * is thread safe (any thread may call this method, including another
1257  * task running on the TaskManager object). Apart from the absence
1258  * of a 'one thread per task' model, this method therefore provides a
1259  * similar interface to the one provided by Cgu::Thread::Future. See
1260  * the documentation on add_task() for further information about how
1261  * task execution works.
1262  *
1263  * The 'when' callback will execute with G_PRIORITY_DEFAULT priority
1264  * in the main loop.
1265  *
1266  * @param when A callback which will be executed if and when the
1267  * function passed to this method finishes correctly. The callback is
1268  * passed that function's return value when it is invoked. If an
1269  * exception propagates from the 'when' callback, this will be
1270  * consumed and a g_critical() warning will be issued. The callback
1271  * will execute in the glib main loop whose GMainContext object is
1272  * passed to the 'context' argument of this method.
1273  * @param context The glib main context of the main loop in which the
1274  * 'when' callback is to be executed. A value 0/NULL/nullptr will
1275  * cause the callback to be executed in the main program loop.
1276  * @param t The object whose member function passed to this method is
1277  * to execute as a task.
1278  * @param func The member function to be executed as a task. If an
1279  * exception propagates from the task, the exception will be consumed
1280  * and (if the thrown object's type is not Cgu::Thread::Exit) a
1281  * g_critical() warning will be issued.
1282  * @param args The arguments to be passed to that member function.
1283  * @exception std::bad_alloc This exception will be thrown if memory
1284  * is exhausted and the system throws in that case. (On systems with
1285  * over-commit/lazy-commit combined with virtual memory (swap), it is
1286  * rarely useful to check for memory exhaustion). If this exception
1287  * is thrown, the task will not start (which also means that the
1288  * 'when' callback will not execute).
1289  * @exception Cgu::Thread::TaskError This exception will be thrown if
1290  * stop_all() has previously been called. It will also be thrown if
1291  * is_error() would return true because this class's internal thread
1292  * pool loop implementation has thrown std::bad_alloc, or a thread
1293  * has failed to start correctly. (On systems with
1294  * over-commit/lazy-commit combined with virtual memory (swap), it is
1295  * rarely useful to check for memory exhaustion, but there may be
1296  * some specialized cases where the return value of is_error() is
1297  * useful.) If this exception is thrown, the task will not start
1298  * (which also means that the 'when' callback will not execute).
1299  * @note This method will also throw if the copy or move constructor
1300  * of a bound argument throws. If such an exception is thrown, the
1301  * task will not start (which also means that the 'when' callback
1302  * will not execute).
1303  *
1304  * Since 2.0.13
1305  */
1306  template <class Ret, class... Params, class... Args, class T>
1307  void make_task_when(std::unique_ptr<const Cgu::Callback::CallbackArg<const Ret&>> when,
1308  GMainContext* context,
1309  T& t,
1310  Ret (T::*func)(Params...),
1311  Args&&... args) {
1312  static_assert(sizeof...(Args) < 4,
1313  "No greater than three bound arguments can be passed to "
1314  "TaskManager::make_task_when() taking a member function.");
1315 
1316  make_task_when_full(std::move(when),
1317  0,
1318  std::unique_ptr<const Cgu::Callback::Callback>(),
1319  0,
1320  G_PRIORITY_DEFAULT,
1321  context,
1322  t,
1323  func,
1324  std::forward<Args>(args)...);
1325  }
1326 
1327  /**
1328  * @deprecated
1329  *
1330  * DEPRECATED. Use the versions of make_task_result() which take
1331  * callable objects.
1332  *
1333  * This is a wrapper which takes a member function pointer to a
1334  * member function which returns a value, together with arguments,
1335  * and constructs a TaskManager task which will execute that function
1336  * by calling add_task() with an appropriate callback object, and
1337  * returns a Cgu::AsyncResult object (held by Cgu::SharedLockPtr)
1338  * which will provide the value that the function returns. Apart
1339  * from the absence of a 'one thread per task' model, this method
1340  * therefore provides a similar interface to the one provided by
1341  * Cgu::Thread::Future. It is thread safe: any thread may call this
1342  * method, including another task running on the TaskManager object,
1343  * but see the introductory remarks about the use of the
1344  * TaskManager::IncHandle scoped handle class where a task running on
1345  * a TaskManager object is to block on one of its sub-tasks. See
1346  * also the documentation on add_task() for further information about
1347  * how task execution works.
1348  *
1349  * This method can take up to three bound arguments for the target
1350  * member function.
1351  *
1352  * If the function passed to this method exits by throwing
1353  * Thread::Exit or some other exception, then the exception will be
1354  * consumed and the returned Cgu::AsyncResult object's get() or
1355  * move_get() method will unblock and its get_error() method will
1356  * return -1.
1357  *
1358  * @param t The object whose member function passed to this method is
1359  * to execute as a task.
1360  * @param func The member function to be executed as a task.
1361  * @param args The arguments to be passed to that member function.
1362  * @exception std::bad_alloc This exception will be thrown if memory
1363  * is exhausted and the system throws in that case. (On systems with
1364  * over-commit/lazy-commit combined with virtual memory (swap), it is
1365  * rarely useful to check for memory exhaustion). If this exception
1366  * is thrown, the task will not start.
1367  * @exception Cgu::Thread::TaskError This exception will be thrown if
1368  * stop_all() has previously been called. It will also be thrown if
1369  * is_error() would return true because this class's internal thread
1370  * pool loop implementation has thrown std::bad_alloc, or a thread
1371  * has failed to start correctly. (On systems with
1372  * over-commit/lazy-commit combined with virtual memory (swap), it is
1373  * rarely useful to check for memory exhaustion, but there may be
1374  * some specialized cases where the return value of is_error() is
1375  * useful.) If this exception is thrown, the task will not start.
1376  * @note This method will also throw if the copy or move constructor
1377  * of a bound argument throws. If such an exception is thrown, the
1378  * task will not start.
1379  *
1380  * Since 2.0.13
1381  */
1382 
1383  template <class Ret, class... Params, class... Args, class T>
1385  Ret (T::*func)(Params...) const,
1386  Args&&... args);
1387 
1388  /**
1389  * @deprecated
1390  *
1391  * DEPRECATED. Use the versions of make_task_when_full() which take
1392  * callable objects.
1393  *
1394  * This is a wrapper which takes a member function pointer to a
1395  * member function which returns a value, together with arguments,
1396  * and constructs a TaskManager task which will execute that function
1397  * by calling add_task() with an appropriate callback object, and
1398  * causes the 'when' callback passed as an argument to this method to
1399  * be executed by a glib main loop if and when the task finishes
1400  * correctly - the 'when' callback is passed the member function's
1401  * return value when it is invoked. It is thread safe (any thread
1402  * may call this method, including another task running on the
1403  * TaskManager object). Apart from the absence of a 'one thread per
1404  * task' model, this method therefore provides a similar interface to
1405  * the one provided by Cgu::Thread::Future. See the documentation on
1406  * add_task() for further information about how task execution works.
1407  *
1408  * This method can take up to three bound arguments for the target
1409  * member function.
1410  *
1411  * Note that unlike add_task(), but like the 'fail' callback of
1412  * Cgu::Thread::Future objects, if a fail callback is provided to
1413  * this method and it executes, it will execute in the glib main loop
1414  * whose GMainContext object is passed to the 'context' argument of
1415  * this method.
1416  *
1417  * Note also that if releasers are provided for the 'when' or 'fail'
1418  * callbacks, these are passed by pointer and not by reference (this
1419  * is so that a NULL pointer can indicate that no releaser is to be
1420  * provided). If provided, a releaser will enable automatic
1421  * disconnection of the 'when' or 'fail' callback, if the object
1422  * having the callback function as a member is destroyed. For this to
1423  * be race free, the lifetime of that object must be controlled by
1424  * the thread in whose main loop the 'when' or 'fail' callback will
1425  * execute.
1426  *
1427  * The make_task_when() method is similar to this method but provides
1428  * an abbreviated set of paramaters suitable for most cases. This
1429  * method is for use where releasers or a 'fail' callback are
1430  * required.
1431  *
1432  * @param when A callback which will be executed if and when the
1433  * function passed to this method finishes correctly. The callback is
1434  * passed that function's return value when it is invoked. If an
1435  * exception propagates from the 'when' callback, this will be
1436  * consumed and a g_critical() warning will be issued. The callback
1437  * will execute in the glib main loop whose GMainContext object is
1438  * passed to the 'context' argument of this method.
1439  * @param when_releaser A pointer to a Releaser object for automatic
1440  * disconnection of the 'when' callback before it executes in a main
1441  * loop (mainly relevant if the callback represents a non-static
1442  * member function of an object which may be destroyed before the
1443  * callback executes). A value of 0/NULL/nullptr indicates no
1444  * releaser.
1445  * @param fail A callback which will be executed if the 'when'
1446  * callback does not execute. This would happen if the function
1447  * passed to this method exits by throwing Thread::Exit or some other
1448  * exception or the copy constructor of a non-reference argument of
1449  * that function throws, or if the 'when' callback does not execute
1450  * because the internal implementation of this wrapper throws
1451  * std::bad_alloc (which will not happen if the library has been
1452  * installed using the \--with-glib-memory-slices-no-compat
1453  * configuration option: instead glib will terminate the program if
1454  * it is unable to obtain memory from the operating system). If an
1455  * exception propagates from the 'fail' callback, this will be
1456  * consumed and a g_critical() warning will be issued. The callback
1457  * will execute in the glib main loop whose GMainContext object is
1458  * passed to the 'context' argument of this method. An empty
1459  * std::unique_ptr object indicates no 'fail' callback.
1460  * @param fail_releaser A pointer to a Releaser object for automatic
1461  * disconnection of the 'fail' callback before it executes in a main
1462  * loop (mainly relevant if the callback represents a non-static
1463  * member function of an object which may be destroyed before the
1464  * callback executes). A value of 0/NULL/nullptr indicates no
1465  * releaser.
1466  * @param priority The priority to be given in the main loop to the
1467  * 'when' callback or any 'fail' callback. In ascending order of
1468  * priorities, priorities are G_PRIORITY_LOW,
1469  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
1470  * and G_PRIORITY_HIGH. This determines the order in which the
1471  * callback will appear in the event list in the main loop, not the
1472  * priority which the OS will adopt.
1473  * @param context The glib main context of the main loop in which the
1474  * 'when' callback or any 'fail' callback is to be executed. A value
1475  * 0/NULL/nullptr will cause the callback to be executed in the main
1476  * program loop.
1477  * @param t The object whose member function passed to this method is
1478  * to execute as a task.
1479  * @param func The member function to be executed as a task. If an
1480  * exception propagates from the task, the exception will be consumed
1481  * and the 'fail' callback will execute.
1482  * @param args The arguments to be passed to that member function.
1483  * @exception std::bad_alloc This exception will be thrown if memory
1484  * is exhausted and the system throws in that case. (On systems with
1485  * over-commit/lazy-commit combined with virtual memory (swap), it is
1486  * rarely useful to check for memory exhaustion). If this exception
1487  * is thrown, the task will not start (which also means that the
1488  * 'when' and 'fail' callbacks will not execute).
1489  * @exception Cgu::Thread::TaskError This exception will be thrown if
1490  * stop_all() has previously been called. It will also be thrown if
1491  * is_error() would return true because this class's internal thread
1492  * pool loop implementation has thrown std::bad_alloc, or a thread
1493  * has failed to start correctly. (On systems with
1494  * over-commit/lazy-commit combined with virtual memory (swap), it is
1495  * rarely useful to check for memory exhaustion, but there may be
1496  * some specialized cases where the return value of is_error() is
1497  * useful.) If this exception is thrown, the task will not start
1498  * (which also means that the 'when' and 'fail' callbacks will not
1499  * execute).
1500  * @note 1. This method will also throw if the copy or move
1501  * constructor of a bound argument throws. If such an exception is
1502  * thrown, the task will not start (which also means that the 'when'
1503  * and 'fail' callbacks will not execute).
1504  * @note 2. If a 'when_releaser' or a 'fail_releaser' object is
1505  * provided, it is in theory possible (if memory is exhausted and the
1506  * system throws in that case) that an internal SafeEmitterArg object
1507  * will throw std::bad_alloc when emitting/executing the 'when' or
1508  * 'fail' callback in the glib main loop, with the result that the
1509  * relevant callback will not execute (instead the exception will be
1510  * consumed and a g_critical() warning will be issued). This is
1511  * rarely of any relevance because glib will abort the program if it
1512  * is itself unable to obtain memory from the operating system.
1513  * However, where it is relevant, design the program so that it is
1514  * not necessary to provide a releaser object.
1515  *
1516  * Since 2.0.13
1517  */
1518  template <class Ret, class... Params, class... Args, class T>
1519  void make_task_when_full(std::unique_ptr<const Cgu::Callback::CallbackArg<const Ret&>> when,
1520  Cgu::Releaser* when_releaser,
1521  std::unique_ptr<const Cgu::Callback::Callback> fail,
1522  Cgu::Releaser* fail_releaser,
1523  gint priority,
1524  GMainContext* context,
1525  const T& t,
1526  Ret (T::*func)(Params...) const,
1527  Args&&... args);
1528 
1529  /**
1530  * @deprecated
1531  *
1532  * DEPRECATED. Use the versions of make_task_when() which take
1533  * callable objects.
1534  *
1535  * This is an abbreviated version of make_task_when_full(), which is
1536  * for use when it is known that the member function passed to this
1537  * method, and the copy constructors of any non-reference bound
1538  * arguments passed to it, do not throw, and the user is not
1539  * interested in std::bad_alloc and does not need a Cgu::Releaser
1540  * object for the 'when' callback (which is likely to cover the
1541  * majority of uses, particularly when composing tasks using glib
1542  * because glib terminates the program if it is unable to obtain
1543  * memory).
1544  *
1545  * This method can take up to three bound arguments for the target
1546  * member function.
1547  *
1548  * Like make_task_when_full(), this method is a wrapper which takes a
1549  * member function pointer to a member function which returns a
1550  * value, together with arguments, and constructs a TaskManager task
1551  * which will execute that function by calling add_task() with an
1552  * appropriate callback object, and causes the 'when' callback passed
1553  * as an argument to this method to be executed by a glib main loop
1554  * if and when the task finishes correctly - the 'when' callback is
1555  * passed the member function's return value when it is invoked. It
1556  * is thread safe (any thread may call this method, including another
1557  * task running on the TaskManager object). Apart from the absence
1558  * of a 'one thread per task' model, this method therefore provides a
1559  * similar interface to the one provided by Cgu::Thread::Future. See
1560  * the documentation on add_task() for further information about how
1561  * task execution works.
1562  *
1563  * The 'when' callback will execute with G_PRIORITY_DEFAULT priority
1564  * in the main loop.
1565  *
1566  * @param when A callback which will be executed if and when the
1567  * function passed to this method finishes correctly. The callback is
1568  * passed that function's return value when it is invoked. If an
1569  * exception propagates from the 'when' callback, this will be
1570  * consumed and a g_critical() warning will be issued. The callback
1571  * will execute in the glib main loop whose GMainContext object is
1572  * passed to the 'context' argument of this method.
1573  * @param context The glib main context of the main loop in which the
1574  * 'when' callback is to be executed. A value 0/NULL/nullptr will
1575  * cause the callback to be executed in the main program loop.
1576  * @param t The object whose member function passed to this method is
1577  * to execute as a task.
1578  * @param func The member function to be executed as a task. If an
1579  * exception propagates from the task, the exception will be consumed
1580  * and (if the thrown object's type is not Cgu::Thread::Exit) a
1581  * g_critical() warning will be issued.
1582  * @param args The arguments to be passed to that member function.
1583  * @exception std::bad_alloc This exception will be thrown if memory
1584  * is exhausted and the system throws in that case. (On systems with
1585  * over-commit/lazy-commit combined with virtual memory (swap), it is
1586  * rarely useful to check for memory exhaustion). If this exception
1587  * is thrown, the task will not start (which also means that the
1588  * 'when' callback will not execute).
1589  * @exception Cgu::Thread::TaskError This exception will be thrown if
1590  * stop_all() has previously been called. It will also be thrown if
1591  * is_error() would return true because this class's internal thread
1592  * pool loop implementation has thrown std::bad_alloc, or a thread
1593  * has failed to start correctly. (On systems with
1594  * over-commit/lazy-commit combined with virtual memory (swap), it is
1595  * rarely useful to check for memory exhaustion, but there may be
1596  * some specialized cases where the return value of is_error() is
1597  * useful.) If this exception is thrown, the task will not start
1598  * (which also means that the 'when' callback will not execute).
1599  * @note This method will also throw if the copy or move constructor
1600  * of a bound argument throws. If such an exception is thrown, the
1601  * task will not start (which also means that the 'when' callback
1602  * will not execute).
1603  *
1604  * Since 2.0.13
1605  */
1606  template <class Ret, class... Params, class... Args, class T>
1607  void make_task_when(std::unique_ptr<const Cgu::Callback::CallbackArg<const Ret&>> when,
1608  GMainContext* context,
1609  const T& t,
1610  Ret (T::*func)(Params...) const,
1611  Args&&... args) {
1612  static_assert(sizeof...(Args) < 4,
1613  "No greater than three bound arguments can be passed to "
1614  "TaskManager::make_task_when() taking a member function.");
1615 
1616  make_task_when_full(std::move(when),
1617  0,
1618  std::unique_ptr<const Cgu::Callback::Callback>(),
1619  0,
1620  G_PRIORITY_DEFAULT,
1621  context,
1622  t,
1623  func,
1624  std::forward<Args>(args)...);
1625  }
1626 
1627  /**
1628  * @deprecated
1629  *
1630  * DEPRECATED. Use the versions of make_task_result() which take
1631  * callable objects.
1632  *
1633  * This is a wrapper which takes a pointer to a function which
1634  * returns a value, together with arguments, and constructs a
1635  * TaskManager task which will execute that function by calling
1636  * add_task() with an appropriate callback object, and returns a
1637  * Cgu::AsyncResult object (held by Cgu::SharedLockPtr) which will
1638  * provide the value that the function returns. Apart from the
1639  * absence of a 'one thread per task' model, this method therefore
1640  * provides a similar interface to the one provided by
1641  * Cgu::Thread::Future. It is thread safe: any thread may call this
1642  * method, including another task running on the TaskManager object,
1643  * but see the introductory remarks about the use of the
1644  * TaskManager::IncHandle scoped handle class where a task running on
1645  * a TaskManager object is to block on one of its sub-tasks. See
1646  * also the documentation on add_task() for further information about
1647  * how task execution works.
1648  *
1649  * This method can take up to four bound arguments for the target
1650  * function.
1651  *
1652  * If the function passed to this method exits by throwing
1653  * Thread::Exit or some other exception, then the exception will be
1654  * consumed and the returned Cgu::AsyncResult object's get() or
1655  * move_get() method will unblock and its get_error() method will
1656  * return -1.
1657  *
1658  * @param func The function to be executed as a task.
1659  * @param args The arguments to be passed to that function.
1660  * @exception std::bad_alloc This exception will be thrown if memory
1661  * is exhausted and the system throws in that case. (On systems with
1662  * over-commit/lazy-commit combined with virtual memory (swap), it is
1663  * rarely useful to check for memory exhaustion). If this exception
1664  * is thrown, the task will not start.
1665  * @exception Cgu::Thread::TaskError This exception will be thrown if
1666  * stop_all() has previously been called. It will also be thrown if
1667  * is_error() would return true because this class's internal thread
1668  * pool loop implementation has thrown std::bad_alloc, or a thread
1669  * has failed to start correctly. (On systems with
1670  * over-commit/lazy-commit combined with virtual memory (swap), it is
1671  * rarely useful to check for memory exhaustion, but there may be
1672  * some specialized cases where the return value of is_error() is
1673  * useful.) If this exception is thrown, the task will not start.
1674  * @note This method will also throw if the copy or move constructor
1675  * of a bound argument throws. If such an exception is thrown, the
1676  * task will not start.
1677  *
1678  * Since 2.0.13
1679  */
1680  template <class Ret, class... Params, class... Args>
1682  Args&&... args);
1683 
1684  /**
1685  * @deprecated
1686  *
1687  * DEPRECATED. Use the versions of make_task_when_full() which take
1688  * callable objects.
1689  *
1690  * This is a wrapper which takes a pointer to a function which
1691  * returns a value, together with arguments, and constructs a
1692  * TaskManager task which will execute that function by calling
1693  * add_task() with an appropriate callback object, and causes the
1694  * 'when' callback passed as an argument to this method to be
1695  * executed by a glib main loop if and when the task finishes
1696  * correctly - the 'when' callback is passed the function's return
1697  * value when it is invoked. It is thread safe (any thread may call
1698  * this method, including another task running on the TaskManager
1699  * object). Apart from the absence of a 'one thread per task' model,
1700  * this method therefore provides a similar interface to the one
1701  * provided by Cgu::Thread::Future. See the documentation on
1702  * add_task() for further information about how task execution works.
1703  *
1704  * This method can take up to four bound arguments for the target
1705  * function.
1706  *
1707  * Note that unlike add_task(), but like the 'fail' callback of
1708  * Cgu::Thread::Future objects, if a fail callback is provided to
1709  * this method and it executes, it will execute in the glib main loop
1710  * whose GMainContext object is passed to the 'context' argument of
1711  * this method.
1712  *
1713  * Note also that if releasers are provided for the 'when' or 'fail'
1714  * callbacks, these are passed by pointer and not by reference (this
1715  * is so that a NULL pointer can indicate that no releaser is to be
1716  * provided). If provided, a releaser will enable automatic
1717  * disconnection of the 'when' or 'fail' callback, if the object of
1718  * which the releaser is a member is destroyed. For this to be race
1719  * free, the lifetime of that object must be controlled by the thread
1720  * in whose main loop the 'when' or 'fail' callback will execute.
1721  *
1722  * The make_task_when() method is similar to this method but provides
1723  * an abbreviated set of paramaters suitable for most cases. This
1724  * method is for use where releasers or a 'fail' callback are
1725  * required.
1726  *
1727  * @param when A callback which will be executed if and when the
1728  * function passed to this method finishes correctly. The callback is
1729  * passed that function's return value when it is invoked. If an
1730  * exception propagates from the 'when' callback, this will be
1731  * consumed and a g_critical() warning will be issued. The callback
1732  * will execute in the glib main loop whose GMainContext object is
1733  * passed to the 'context' argument of this method.
1734  * @param when_releaser A pointer to a Releaser object for automatic
1735  * disconnection of the 'when' callback before it executes in a main
1736  * loop (mainly relevant if the callback represents a non-static
1737  * member function of an object which may be destroyed before the
1738  * callback executes). A value of 0/NULL/nullptr indicates no
1739  * releaser.
1740  * @param fail A callback which will be executed if the 'when'
1741  * callback does not execute. This would happen if the function
1742  * passed to this method exits by throwing Thread::Exit or some other
1743  * exception or the copy constructor of a non-reference argument of
1744  * that function throws, or if the 'when' callback does not execute
1745  * because the internal implementation of this wrapper throws
1746  * std::bad_alloc (which will not happen if the library has been
1747  * installed using the \--with-glib-memory-slices-no-compat
1748  * configuration option: instead glib will terminate the program if
1749  * it is unable to obtain memory from the operating system). If an
1750  * exception propagates from the 'fail' callback, this will be
1751  * consumed and a g_critical() warning will be issued. The callback
1752  * will execute in the glib main loop whose GMainContext object is
1753  * passed to the 'context' argument of this method. An empty
1754  * std::unique_ptr object indicates no 'fail' callback.
1755  * @param fail_releaser A pointer to a Releaser object for automatic
1756  * disconnection of the 'fail' callback before it executes in a main
1757  * loop (mainly relevant if the callback represents a non-static
1758  * member function of an object which may be destroyed before the
1759  * callback executes). A value of 0/NULL/nullptr indicates no
1760  * releaser.
1761  * @param priority The priority to be given in the main loop to the
1762  * 'when' callback or any 'fail' callback. In ascending order of
1763  * priorities, priorities are G_PRIORITY_LOW,
1764  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
1765  * and G_PRIORITY_HIGH. This determines the order in which the
1766  * callback will appear in the event list in the main loop, not the
1767  * priority which the OS will adopt.
1768  * @param context The glib main context of the main loop in which the
1769  * 'when' callback or any 'fail' callback is to be executed. A value
1770  * 0/NULL/nullptr will cause the callback to be executed in the main
1771  * program loop.
1772  * @param func The function to be executed as a task. If an
1773  * exception propagates from the task, the exception will be consumed
1774  * and the 'fail' callback will execute.
1775  * @param args The arguments to be passed to that function.
1776  * @exception std::bad_alloc This exception will be thrown if memory
1777  * is exhausted and the system throws in that case. (On systems with
1778  * over-commit/lazy-commit combined with virtual memory (swap), it is
1779  * rarely useful to check for memory exhaustion). If this exception
1780  * is thrown, the task will not start (which also means that the
1781  * 'when' and 'fail' callbacks will not execute).
1782  * @exception Cgu::Thread::TaskError This exception will be thrown if
1783  * stop_all() has previously been called. It will also be thrown if
1784  * is_error() would return true because this class's internal thread
1785  * pool loop implementation has thrown std::bad_alloc, or a thread
1786  * has failed to start correctly. (On systems with
1787  * over-commit/lazy-commit combined with virtual memory (swap), it is
1788  * rarely useful to check for memory exhaustion, but there may be
1789  * some specialized cases where the return value of is_error() is
1790  * useful.) If this exception is thrown, the task will not start
1791  * (which also means that the 'when' and 'fail' callbacks will not
1792  * execute).
1793  * @note 1. This method will also throw if the copy or move
1794  * constructor of a bound argument throws. If such an exception is
1795  * thrown, the task will not start (which also means that the 'when'
1796  * and 'fail' callbacks will not execute).
1797  * @note 2. If a 'when_releaser' or a 'fail_releaser' object is
1798  * provided, it is in theory possible (if memory is exhausted and the
1799  * system throws in that case) that an internal SafeEmitterArg object
1800  * will throw std::bad_alloc when emitting/executing the 'when' or
1801  * 'fail' callback in the glib main loop, with the result that the
1802  * relevant callback will not execute (instead the exception will be
1803  * consumed and a g_critical() warning will be issued). This is
1804  * rarely of any relevance because glib will abort the program if it
1805  * is itself unable to obtain memory from the operating system.
1806  * However, where it is relevant, design the program so that it is
1807  * not necessary to provide a releaser object.
1808  *
1809  * Since 2.0.13
1810  */
1811  template <class Ret, class... Params, class... Args>
1812  void make_task_when_full(std::unique_ptr<const Cgu::Callback::CallbackArg<const Ret&>> when,
1813  Cgu::Releaser* when_releaser,
1814  std::unique_ptr<const Cgu::Callback::Callback> fail,
1815  Cgu::Releaser* fail_releaser,
1816  gint priority,
1817  GMainContext* context,
1818  Ret (*func)(Params...),
1819  Args&&... args);
1820 
1821  /**
1822  * @deprecated
1823  *
1824  * DEPRECATED. Use the versions of make_task_when() which take
1825  * callable objects.
1826  *
1827  * This is an abbreviated version of make_task_when_full(), which is
1828  * for use when it is known that the function passed to this method,
1829  * and the copy constructors of any non-reference bound arguments
1830  * passed to it, do not throw, and the user is not interested in
1831  * std::bad_alloc and does not need a Cgu::Releaser object for the
1832  * 'when' callback (which is likely to cover the majority of uses,
1833  * particularly when composing tasks using glib because glib
1834  * terminates the program if it is unable to obtain memory).
1835  *
1836  * This method can take up to four bound arguments for the target
1837  * function.
1838  *
1839  * Like make_task_when_full(), this method is a wrapper which takes a
1840  * pointer to a function which returns a value, together with
1841  * arguments, and constructs a TaskManager task which will execute
1842  * that function by calling add_task() with an appropriate callback
1843  * object, and causes the 'when' callback passed as an argument to
1844  * this method to be executed by a glib main loop if and when the
1845  * task finishes correctly - the 'when' callback is passed the
1846  * function's return value when it is invoked. It is thread safe
1847  * (any thread may call this method, including another task running
1848  * on the TaskManager object). Apart from the absence of a 'one
1849  * thread per task' model, this method therefore provides a similar
1850  * interface to the one provided by Cgu::Thread::Future. See the
1851  * documentation on add_task() for further information about how task
1852  * execution works.
1853  *
1854  * The 'when' callback will execute with G_PRIORITY_DEFAULT priority
1855  * in the main loop.
1856  *
1857  * @param when A callback which will be executed if and when the
1858  * function passed to this method finishes correctly. The callback is
1859  * passed that function's return value when it is invoked. If an
1860  * exception propagates from the 'when' callback, this will be
1861  * consumed and a g_critical() warning will be issued. The callback
1862  * will execute in the glib main loop whose GMainContext object is
1863  * passed to the 'context' argument of this method.
1864  * @param context The glib main context of the main loop in which the
1865  * 'when' callback is to be executed. A value 0/NULL/nullptr will
1866  * cause the callback to be executed in the main program loop.
1867  * @param func The function to be executed as a task. If an
1868  * exception propagates from the task, the exception will be consumed
1869  * and (if the thrown object's type is not Cgu::Thread::Exit) a
1870  * g_critical() warning will be issued.
1871  * @param args The arguments to be passed to that function.
1872  * @exception std::bad_alloc This exception will be thrown if memory
1873  * is exhausted and the system throws in that case. (On systems with
1874  * over-commit/lazy-commit combined with virtual memory (swap), it is
1875  * rarely useful to check for memory exhaustion). If this exception
1876  * is thrown, the task will not start (which also means that the
1877  * 'when' callback will not execute).
1878  * @exception Cgu::Thread::TaskError This exception will be thrown if
1879  * stop_all() has previously been called. It will also be thrown if
1880  * is_error() would return true because this class's internal thread
1881  * pool loop implementation has thrown std::bad_alloc, or a thread
1882  * has failed to start correctly. (On systems with
1883  * over-commit/lazy-commit combined with virtual memory (swap), it is
1884  * rarely useful to check for memory exhaustion, but there may be
1885  * some specialized cases where the return value of is_error() is
1886  * useful.) If this exception is thrown, the task will not start
1887  * (which also means that the 'when' callback will not execute).
1888  * @note This method will also throw if the copy or move constructor
1889  * of a bound argument throws. If such an exception is thrown, the
1890  * task will not start (which also means that the 'when' callback
1891  * will not execute).
1892  *
1893  * Since 2.0.13
1894  */
1895  template <class Ret, class... Params, class... Args>
1896  void make_task_when(std::unique_ptr<const Cgu::Callback::CallbackArg<const Ret&>> when,
1897  GMainContext* context,
1898  Ret (*func)(Params...),
1899  Args&&... args) {
1900  static_assert(sizeof...(Args) < 5,
1901  "No greater than four bound arguments can be passed to "
1902  "TaskManager::make_task_when() taking a function.");
1903 
1904  make_task_when_full(std::move(when),
1905  0,
1906  std::unique_ptr<const Cgu::Callback::Callback>(),
1907  0,
1908  G_PRIORITY_DEFAULT,
1909  context,
1910  func,
1911  std::forward<Args>(args)...);
1912  }
1913 
1914  /**
1915  * This is a wrapper which takes a callable object which returns a
1916  * value (such as a std::function object, a lambda or the return
1917  * value of std::bind), and constructs a TaskManager task which will
1918  * execute that object by calling add_task() with an appropriate
1919  * callback object, and returns a Cgu::AsyncResult object (held by
1920  * Cgu::SharedLockPtr) which will provide the value that it returns.
1921  * Apart from the absence of a 'one thread per task' model, this
1922  * method therefore provides a similar interface to the one provided
1923  * by Cgu::Thread::Future. It is thread safe: any thread may call
1924  * this method, including another task running on the TaskManager
1925  * object, but see the introductory remarks about the use of the
1926  * TaskManager::IncHandle scoped handle class where a task running on
1927  * a TaskManager object is to block on one of its sub-tasks. See
1928  * also the documentation on add_task() for further information about
1929  * how task execution works.
1930  *
1931  * If the callable object passed to this method exits by throwing
1932  * Thread::Exit or some other exception, then the exception will be
1933  * consumed and the returned Cgu::AsyncResult object's get() or
1934  * move_get() method will unblock and its get_error() method will
1935  * return -1.
1936  *
1937  * @param f The callable object to be executed as a task, such as
1938  * formed by a lambda expression or the result of std::bind. It
1939  * should return a value (it cannot return void).
1940  * @exception std::bad_alloc This exception will be thrown if memory
1941  * is exhausted and the system throws in that case. (On systems with
1942  * over-commit/lazy-commit combined with virtual memory (swap), it is
1943  * rarely useful to check for memory exhaustion). If this exception
1944  * is thrown, the task will not start.
1945  * @exception Cgu::Thread::TaskError This exception will be thrown if
1946  * stop_all() has previously been called. It will also be thrown if
1947  * is_error() would return true because this class's internal thread
1948  * pool loop implementation has thrown std::bad_alloc, or a thread
1949  * has failed to start correctly. (On systems with
1950  * over-commit/lazy-commit combined with virtual memory (swap), it is
1951  * rarely useful to check for memory exhaustion, but there may be
1952  * some specialized cases where the return value of is_error() is
1953  * useful.) If this exception is thrown, the task will not start.
1954  * @note 1. This method will also throw if the copy or move
1955  * constructor of the callable object throws. If such an exception
1956  * is thrown, the task will not start.
1957  * @note 2. If the callable object passed as an argument has both
1958  * const and non-const operator()() methods, the non-const version
1959  * will be called even if the callable object passed is a const
1960  * object.
1961  *
1962  * Since 2.0.14
1963  */
1964  // we don't need this version of make_task_result() for syntactic
1965  // reasons - the version taking a single template parameter will do
1966  // by itself syntactically because it can use decltype. However, we
1967  // include this version in order to be API compatible with
1968  // c++-gtk-utils < 2.0.14, which required the return type to be
1969  // specified when this method is passed something other than a
1970  // std::function object. SFINAE will take care of the rest, except
1971  // with a corner case where all of the following apply: (i) a
1972  // function object is passed whose operator()() method returns a
1973  // copy of the function object (or another function object of the
1974  // same type), (ii) the function object is passed to this method as
1975  // a rvalue and not a lvalue, and (iii) the user specifically states
1976  // the return type when instantiating this template function. This
1977  // would give rise to an ambiguity, but its happening is extremely
1978  // unlikely, and cannot happen with a lambda or the return value of
1979  // std::bind, because those types are only known to the compiler,
1980  // and cannot happen with other objects if the user lets template
1981  // deduction take its course.
1982  template <class Ret, class Func>
1984 
1985  // we don't want to document this function: it provides the type
1986  // deduction of the return value of the passed functor (it deals
1987  // with cases where this is not specified expressly).
1988 #ifndef DOXYGEN_PARSING
1989  template <class Func>
1991 
1992  // TODO: this is a work-around for gcc < 4.7, which has a bug
1993  // which requires a function whose return value is determined by
1994  // decltype, such as make_task_result(Func&&), to be inline. At a
1995  // suitable API/ABI break when gcc requirements are updated, this
1996  // should be moved to task_manager.tpp.
1997 
1998  // there are two types related to the functor to be executed by
1999  // the task. 'Func' is the transient type provided by argument
2000  // deduction for forwarding, and will vary depending on whether
2001  // the functor object is a lvalue (which will deduce it as a
2002  // reference type) or rvalue (which will not). 'FType' is the
2003  // type to be held by the callback object generated in this
2004  // function, and is never a reference type. It is also never
2005  // const, because the FType member is marked mutable in the
2006  // callback object so that it can execute mutable lambdas (or
2007  // other functors with a non-const operator()() method).
2008  typedef typename std::remove_const<typename std::remove_reference<Func>::type>::type FType;
2009  typedef decltype(f()) Ret;
2010  typedef std::unique_ptr<const Callback::Callback> CbPtr;
2011 
2013  CbPtr exec_cb(new TaskManagerHelper2::FunctorResultExec<Ret, FType>(std::forward<Func>(f), ret));
2014  CbPtr do_fail_cb(Callback::make_ref(&TaskManagerHelper2::FunctorResultWrapper<Ret, FType>::do_fail,
2015  ret));
2016  add_task(std::move(exec_cb), std::move(do_fail_cb));
2017 
2018  return ret;
2019  }
2020 #endif
2021 
2022  /**
2023  * This is a wrapper which takes a callable object which returns a
2024  * value (such as a std::function object, a lambda or the return
2025  * value of std::bind), and constructs a TaskManager task which will
2026  * execute that object by calling add_task() with an appropriate
2027  * callback object, and causes the 'when' callback passed as an
2028  * argument to this method to be executed by a glib main loop if and
2029  * when the task finishes correctly - the 'when' callback is passed
2030  * the callable object's return value when it is invoked. It is
2031  * thread safe (any thread may call this method, including another
2032  * task running on the TaskManager object). Apart from the absence
2033  * of a 'one thread per task' model, this method therefore provides a
2034  * similar interface to the one provided by Cgu::Thread::Future. See
2035  * the documentation on add_task() for further information about how
2036  * task execution works.
2037  *
2038  * Note that unlike add_task(), but like the 'fail' callback of
2039  * Cgu::Thread::Future objects, if a fail callback is provided to
2040  * this method and it executes, it will execute in the glib main loop
2041  * whose GMainContext object is passed to the 'context' argument of
2042  * this method.
2043  *
2044  * Note also that if releasers are provided for the 'when' or 'fail'
2045  * callbacks, these are passed by pointer and not by reference (this
2046  * is so that a NULL pointer can indicate that no releaser is to be
2047  * provided). If provided, a releaser will enable automatic
2048  * disconnection of the 'when' or 'fail' callback, if the object of
2049  * which the releaser is a member is destroyed. For this to be race
2050  * free, the lifetime of that object must be controlled by the thread
2051  * in whose main loop the 'when' or 'fail' callback will execute.
2052  *
2053  * The make_task_when() method is similar to this method but provides
2054  * an abbreviated set of parameters suitable for most cases. This
2055  * method is for use where releasers or a 'fail' callback are
2056  * required.
2057  *
2058  * @param when A callback which will be executed if and when the
2059  * callable object passed as 'func' to this method finishes
2060  * correctly. The callback is passed that object's return value when
2061  * it is invoked. If an exception propagates from the 'when'
2062  * callback, this will be consumed and a g_critical() warning will be
2063  * issued. The callback will execute in the glib main loop whose
2064  * GMainContext object is passed to the 'context' argument of this
2065  * method.
2066  * @param when_releaser A pointer to a Releaser object for automatic
2067  * disconnection of the 'when' callback before it executes in a main
2068  * loop (mainly relevant if the callback represents a non-static
2069  * member function of an object which may be destroyed before the
2070  * callback executes). A value of 0/NULL/nullptr indicates no
2071  * releaser.
2072  * @param fail A callback which will be executed if the 'when'
2073  * callback does not execute. This would happen if the callable
2074  * object passed as 'func' to this method exits by throwing
2075  * Thread::Exit or some other exception (or if that object represents
2076  * a function taking a non-reference argument whose copy constructor
2077  * throws), or if the 'when' callback does not execute because the
2078  * internal implementation of this wrapper throws std::bad_alloc
2079  * (which will not happen if the library has been installed using the
2080  * \--with-glib-memory-slices-no-compat configuration option: instead
2081  * glib will terminate the program if it is unable to obtain memory
2082  * from the operating system). If an exception propagates from the
2083  * 'fail' callback, this will be consumed and a g_critical() warning
2084  * will be issued. The callback will execute in the glib main loop
2085  * whose GMainContext object is passed to the 'context' argument of
2086  * this method. An empty std::unique_ptr object indicates no 'fail'
2087  * callback.
2088  * @param fail_releaser A pointer to a Releaser object for automatic
2089  * disconnection of the 'fail' callback before it executes in a main
2090  * loop (mainly relevant if the callback represents a non-static
2091  * member function of an object which may be destroyed before the
2092  * callback executes). A value of 0/NULL/nullptr indicates no
2093  * releaser.
2094  * @param priority The priority to be given in the main loop to the
2095  * 'when' callback or any 'fail' callback. In ascending order of
2096  * priorities, priorities are G_PRIORITY_LOW,
2097  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
2098  * and G_PRIORITY_HIGH. This determines the order in which the
2099  * callback will appear in the event list in the main loop, not the
2100  * priority which the OS will adopt.
2101  * @param context The glib main context of the main loop in which the
2102  * 'when' callback or any 'fail' callback is to be executed. A value
2103  * 0/NULL/nullptr will cause the callback to be executed in the main
2104  * program loop.
2105  * @param func The callable object to be executed as a task, such as
2106  * formed by a lambda expression or the result of std::bind. It
2107  * should return a value (it cannot return void). It must be fully
2108  * bound (that is, it must take no arguments when called). If an
2109  * exception propagates from the task, the exception will be consumed
2110  * and the 'fail' callback will execute.
2111  * @exception std::bad_alloc This exception will be thrown if memory
2112  * is exhausted and the system throws in that case. (On systems with
2113  * over-commit/lazy-commit combined with virtual memory (swap), it is
2114  * rarely useful to check for memory exhaustion). If this exception
2115  * is thrown, the task will not start (which also means that the
2116  * 'when' and 'fail' callbacks will not execute).
2117  * @exception Cgu::Thread::TaskError This exception will be thrown if
2118  * stop_all() has previously been called. It will also be thrown if
2119  * is_error() would return true because this class's internal thread
2120  * pool loop implementation has thrown std::bad_alloc, or a thread
2121  * has failed to start correctly. (On systems with
2122  * over-commit/lazy-commit combined with virtual memory (swap), it is
2123  * rarely useful to check for memory exhaustion, but there may be
2124  * some specialized cases where the return value of is_error() is
2125  * useful.) If this exception is thrown, the task will not start
2126  * (which also means that the 'when' and 'fail' callbacks will not
2127  * execute).
2128  * @note 1. This method will also throw if the copy or move
2129  * constructor of the callable object throws. If such an exception
2130  * is thrown, the task will not start (which also means that the
2131  * 'when' and 'fail' callbacks will not execute).
2132  * @note 2. If the callable object passed as an argument has both
2133  * const and non-const operator()() methods, the non-const version
2134  * will be called even if the callable object passed is a const
2135  * object.
2136  * @note 3. If a 'when_releaser' or a 'fail_releaser' object is
2137  * provided, it is in theory possible (if memory is exhausted and the
2138  * system throws in that case) that an internal SafeEmitterArg object
2139  * will throw std::bad_alloc when emitting/executing the 'when' or
2140  * 'fail' callback in the glib main loop, with the result that the
2141  * relevant callback will not execute (instead the exception will be
2142  * consumed and a g_critical() warning will be issued). This is
2143  * rarely of any relevance because glib will abort the program if it
2144  * is itself unable to obtain memory from the operating system.
2145  * However, where it is relevant, design the program so that it is
2146  * not necessary to provide a releaser object.
2147  *
2148  * Since 2.0.14
2149  */
2150  template <class Ret, class Func>
2151  void make_task_when_full(std::unique_ptr<const Cgu::Callback::CallbackArg<const Ret&>> when,
2152  Cgu::Releaser* when_releaser,
2153  std::unique_ptr<const Cgu::Callback::Callback> fail,
2154  Cgu::Releaser* fail_releaser,
2155  gint priority,
2156  GMainContext* context,
2157  Func&& func);
2158 
2159  /**
2160  * This is a wrapper which takes a callable object which returns a
2161  * value as its 'func' argument (such as a std::function object, a
2162  * lambda or the return value of std::bind), and constructs a
2163  * TaskManager task which will execute that object by calling
2164  * add_task() with an appropriate callback object, and causes the
2165  * 'when' callback passed as an argument to this method to be
2166  * executed by a glib main loop if and when the task finishes
2167  * correctly - the 'when' callback is passed the return value of the
2168  * 'func' argument when it is invoked. It is thread safe (any thread
2169  * may call this method, including another task running on the
2170  * TaskManager object). Apart from the absence of a 'one thread per
2171  * task' model, this method therefore provides a similar interface to
2172  * the one provided by Cgu::Thread::Future. See the documentation on
2173  * add_task() for further information about how task execution works.
2174  *
2175  * Note that unlike add_task(), but like the 'fail' callback of
2176  * Cgu::Thread::Future objects, if a fail callback is provided to
2177  * this method and it executes, it will execute in the glib main loop
2178  * whose GMainContext object is passed to the 'context' argument of
2179  * this method.
2180  *
2181  * Note also that if releasers are provided for the 'when' or 'fail'
2182  * callbacks, these are passed by pointer and not by reference (this
2183  * is so that a NULL pointer can indicate that no releaser is to be
2184  * provided). If provided, a releaser will enable automatic
2185  * disconnection of the 'when' or 'fail' callback, if the object of
2186  * which the releaser is a member is destroyed. For this to be race
2187  * free, the lifetime of that object must be controlled by the thread
2188  * in whose main loop the 'when' or 'fail' callback will execute.
2189  *
2190  * The make_task_when() method is similar to this method but provides
2191  * an abbreviated set of parameters suitable for most cases. This
2192  * method is for use where releasers or a 'fail' callback are
2193  * required.
2194  *
2195  * @param when A callable object (such as formed by a lambda
2196  * expression or the result of std::bind) which will be executed if
2197  * and when the 'func' object passed to this method finishes
2198  * correctly. The 'when' callback is passed that objects's return
2199  * value when invoked, and should take a single unbound argument,
2200  * namely a reference to const of the type of that return value. If
2201  * an exception propagates from the 'when' callback, this will be
2202  * consumed and a g_critical() warning will be issued. The callback
2203  * will execute in the glib main loop whose GMainContext object is
2204  * passed to the 'context' argument of this method.
2205  * @param when_releaser A pointer to a Releaser object for automatic
2206  * disconnection of the 'when' callback before it executes in a main
2207  * loop (mainly relevant if the callback calls a non-static member
2208  * function of an object which may be destroyed before the callback
2209  * executes). A value of 0/NULL/nullptr indicates no releaser.
2210  * @param fail A callable object (such as formed by a lambda
2211  * expression or the result of std::bind) which will be executed if
2212  * the 'when' callback does not execute. This would happen if the
2213  * callable object passed as 'func' to this method exits by throwing
2214  * Thread::Exit or some other exception, or if the 'when' callback
2215  * does not execute because the internal implementation of this
2216  * wrapper throws std::bad_alloc (which will not happen if the
2217  * library has been installed using the
2218  * \--with-glib-memory-slices-no-compat configuration option: instead
2219  * glib will terminate the program if it is unable to obtain memory
2220  * from the operating system). The callable object must be fully
2221  * bound (that is, it must take no arguments when called). If an
2222  * exception propagates from the 'fail' callback, this will be
2223  * consumed and a g_critical() warning will be issued. The callback
2224  * will execute in the glib main loop whose GMainContext object is
2225  * passed to the 'context' argument of this method. If no 'fail'
2226  * callback is wanted, pass a lambda which does nothing.
2227  * @param fail_releaser A pointer to a Releaser object for automatic
2228  * disconnection of the 'fail' callback before it executes in a main
2229  * loop (mainly relevant if the callback calls a non-static member
2230  * function of an object which may be destroyed before the callback
2231  * executes). A value of 0/NULL/nullptr indicates no releaser.
2232  * @param priority The priority to be given in the main loop to the
2233  * 'when' callback or any 'fail' callback. In ascending order of
2234  * priorities, priorities are G_PRIORITY_LOW,
2235  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
2236  * and G_PRIORITY_HIGH. This determines the order in which the
2237  * callback will appear in the event list in the main loop, not the
2238  * priority which the OS will adopt.
2239  * @param context The glib main context of the main loop in which the
2240  * 'when' callback or any 'fail' callback is to be executed. A value
2241  * 0/NULL/nullptr will cause the callback to be executed in the main
2242  * program loop.
2243  * @param func The callable object to be executed as a task, such as
2244  * formed by a lambda expression or the result of std::bind. It
2245  * should return a value (it cannot return void). It must be fully
2246  * bound (that is, it must take no arguments when called). If an
2247  * exception propagates from the task, the exception will be consumed
2248  * and the 'fail' callback will execute.
2249  * @exception std::bad_alloc This exception will be thrown if memory
2250  * is exhausted and the system throws in that case. (On systems with
2251  * over-commit/lazy-commit combined with virtual memory (swap), it is
2252  * rarely useful to check for memory exhaustion). If this exception
2253  * is thrown, the task will not start (which also means that the
2254  * 'when' and 'fail' callbacks will not execute).
2255  * @exception Cgu::Thread::TaskError This exception will be thrown if
2256  * stop_all() has previously been called. It will also be thrown if
2257  * is_error() would return true because this class's internal thread
2258  * pool loop implementation has thrown std::bad_alloc, or a thread
2259  * has failed to start correctly. (On systems with
2260  * over-commit/lazy-commit combined with virtual memory (swap), it is
2261  * rarely useful to check for memory exhaustion, but there may be
2262  * some specialized cases where the return value of is_error() is
2263  * useful.) If this exception is thrown, the task will not start
2264  * (which also means that the 'when' and 'fail' callbacks will not
2265  * execute).
2266  * @note 1. This method will also throw if the copy or move
2267  * constructor of the 'func', 'when' or 'fail' callable objects
2268  * throws. If such an exception is thrown, the task will not start
2269  * (which also means that the 'when' and 'fail' callbacks will not
2270  * execute).
2271  * @note 2. If any of the callable objects passed to this method have
2272  * both const and non-const operator()() methods, the non-const
2273  * version will be called even if the callable object passed is a
2274  * const object.
2275  * @note 3. If a 'when_releaser' or a 'fail_releaser' object is
2276  * provided, it is in theory possible (if memory is exhausted and the
2277  * system throws in that case) that an internal SafeEmitterArg object
2278  * will throw std::bad_alloc when emitting/executing the 'when' or
2279  * 'fail' callback in the glib main loop, with the result that the
2280  * relevant callback will not execute (instead the exception will be
2281  * consumed and a g_critical() warning will be issued). This is
2282  * rarely of any relevance because glib will abort the program if it
2283  * is itself unable to obtain memory from the operating system.
2284  * However, where it is relevant, design the program so that it is
2285  * not necessary to provide a releaser object.
2286  *
2287  * Since 2.1.0
2288  */
2289  // we need to use enable_if so that where this function is passed
2290  // unique_ptr's holding non-const Callback::CallbackArg objects, or
2291  // some other convertible object, this templated overload is dropped
2292  // from the overload set, in order to support the unique_ptr
2293  // overloads of this function. This overload calls into the version
2294  // of this function taking CallbackArg objects by unique_ptr in
2295  // order to perform type erasure.
2296  template <class When, class Fail, class Func,
2297  class = typename std::enable_if<!std::is_convertible<When, std::unique_ptr<const Callback::CallbackArg<const typename std::result_of<Func()>::type&>>>::value
2298  && !std::is_convertible<Fail, std::unique_ptr<const Callback::Callback>>::value>::type>
2299  void make_task_when_full(When&& when,
2300  Cgu::Releaser* when_releaser,
2301  Fail&& fail,
2302  Cgu::Releaser* fail_releaser,
2303  gint priority,
2304  GMainContext* context,
2305  Func&& func) {
2306  typedef decltype(func()) Ret;
2307  std::unique_ptr<const Callback::CallbackArg<const Ret&>> when_ptr(
2308  Callback::lambda<const Ret&>(std::forward<When>(when))
2309  );
2310  std::unique_ptr<const Callback::Callback> fail_ptr(
2311  Callback::lambda<>(std::forward<Fail>(fail))
2312  );
2313  make_task_when_full(std::move(when_ptr),
2314  when_releaser,
2315  std::move(fail_ptr),
2316  fail_releaser,
2317  priority,
2318  context,
2319  std::forward<Func>(func));
2320  }
2321 
2322  /**
2323  * This is an abbreviated version of make_task_when_full(), which is
2324  * for use when it is known that the callable object passed to this
2325  * method does not throw, and the user is not interested in
2326  * std::bad_alloc and does not need a Cgu::Releaser object for the
2327  * 'when' callback (which is likely to cover the majority of uses,
2328  * particularly when composing tasks using glib because glib
2329  * terminates the program if it is unable to obtain memory).
2330  *
2331  * Like make_task_when_full(), this method is a wrapper which takes a
2332  * callable object which returns a value, and constructs a
2333  * TaskManager task which will execute that object by calling
2334  * add_task() with an appropriate callback object, and causes the
2335  * 'when' callback passed as an argument to this method to be
2336  * executed by a glib main loop if and when the task finishes
2337  * correctly - the 'when' callback is passed the callable object's
2338  * return value when it is invoked. It is thread safe (any thread
2339  * may call this method, including another task running on the
2340  * TaskManager object). Apart from the absence of a 'one thread per
2341  * task' model, this method therefore provides a similar interface to
2342  * the one provided by Cgu::Thread::Future. See the documentation on
2343  * add_task() for further information about how task execution works.
2344  *
2345  * The 'when' callback will execute with G_PRIORITY_DEFAULT priority
2346  * in the main loop.
2347  *
2348  * There is a similar make_task_compose() function which has the
2349  * callable object to be executed as a task as its first argument and
2350  * the 'when' callback as its last argument, in order to aid task
2351  * composition.
2352  *
2353  * @param when A callback which will be executed if and when the
2354  * callable object passed to this method finishes correctly. The
2355  * callback is passed that object's return value when it is invoked.
2356  * If an exception propagates from the 'when' callback, this will be
2357  * consumed and a g_critical() warning will be issued. The callback
2358  * will execute in the glib main loop whose GMainContext object is
2359  * passed to the 'context' argument of this method.
2360  * @param context The glib main context of the main loop in which the
2361  * 'when' callback is to be executed. A value 0/NULL/nullptr will
2362  * cause the callback to be executed in the main program loop.
2363  * @param f The callable object to be executed as a task, such as
2364  * formed by a lambda expression or the result of std::bind. It
2365  * should return a value (it cannot return void). It must be fully
2366  * bound (that is, it must take no arguments when called). If an
2367  * exception propagates from the task, the exception will be consumed
2368  * and (if the thrown object's type is not Cgu::Thread::Exit) a
2369  * g_critical() warning will be issued.
2370  * @exception std::bad_alloc This exception will be thrown if memory
2371  * is exhausted and the system throws in that case. (On systems with
2372  * over-commit/lazy-commit combined with virtual memory (swap), it is
2373  * rarely useful to check for memory exhaustion). If this exception
2374  * is thrown, the task will not start (which also means that the
2375  * 'when' callback will not execute).
2376  * @exception Cgu::Thread::TaskError This exception will be thrown if
2377  * stop_all() has previously been called. It will also be thrown if
2378  * is_error() would return true because this class's internal thread
2379  * pool loop implementation has thrown std::bad_alloc, or a thread
2380  * has failed to start correctly. (On systems with
2381  * over-commit/lazy-commit combined with virtual memory (swap), it is
2382  * rarely useful to check for memory exhaustion, but there may be
2383  * some specialized cases where the return value of is_error() is
2384  * useful.) If this exception is thrown, the task will not start
2385  * (which also means that the 'when' callback will not execute).
2386  * @note 1. This method will also throw if the copy or move
2387  * constructor of the callable object throws. If such an exception
2388  * is thrown, the task will not start (which also means that the
2389  * 'when' callback will not execute).
2390  * @note 2. If the callable object passed as an argument has both
2391  * const and non-const operator()() methods, the non-const version
2392  * will be called even if the callable object passed is a const
2393  * object.
2394  *
2395  * Since 2.0.14
2396  */
2397  template <class Ret, class Func>
2398  void make_task_when(std::unique_ptr<const Cgu::Callback::CallbackArg<const Ret&>> when,
2399  GMainContext* context,
2400  Func&& f) {
2401  make_task_when_full(std::move(when),
2402  0,
2403  std::unique_ptr<const Cgu::Callback::Callback>(),
2404  0,
2405  G_PRIORITY_DEFAULT,
2406  context,
2407  std::forward<Func>(f));
2408  }
2409 
2410  /**
2411  * This is an abbreviated version of make_task_when_full(), which is
2412  * for use when it is known that the callable object passed to the
2413  * 'func' argument of this method does not throw, and the user is not
2414  * interested in std::bad_alloc and does not need a Cgu::Releaser
2415  * object for the 'when' callback (which is likely to cover the
2416  * majority of uses, particularly when composing tasks using glib
2417  * because glib terminates the program if it is unable to obtain
2418  * memory).
2419  *
2420  * Like make_task_when_full(), this method is a wrapper which takes a
2421  * callable object which returns a value as its 'func' argument, and
2422  * constructs a TaskManager task which will execute that object by
2423  * calling add_task() with an appropriate callback object, and causes
2424  * the 'when' callback passed as an argument to this method to be
2425  * executed by a glib main loop if and when the task finishes
2426  * correctly - the 'when' callback is passed the return value of the
2427  * 'func' argument when it is invoked. It is thread safe (any thread
2428  * may call this method, including another task running on the
2429  * TaskManager object). Apart from the absence of a 'one thread per
2430  * task' model, this method therefore provides a similar interface to
2431  * the one provided by Cgu::Thread::Future. See the documentation on
2432  * add_task() for further information about how task execution works.
2433  *
2434  * The 'when' callback will execute with G_PRIORITY_DEFAULT priority
2435  * in the main loop.
2436  *
2437  * There is a similar make_task_compose() function which has the
2438  * callable object to be executed as a task as its first argument and
2439  * the 'when' callback as its last argument, in order to aid task
2440  * composition.
2441  *
2442  * @param when A callable object (such as formed by a lambda
2443  * expression or the result of std::bind) which will be executed if
2444  * and when the 'func' object passed to this method finishes
2445  * correctly. The 'when' callback is passed that objects's return
2446  * value when invoked, and should take a single unbound argument,
2447  * namely a reference to const of the type of that return value. If
2448  * an exception propagates from the 'when' callback, this will be
2449  * consumed and a g_critical() warning will be issued. The callback
2450  * will execute in the glib main loop whose GMainContext object is
2451  * passed to the 'context' argument of this method.
2452  * @param context The glib main context of the main loop in which the
2453  * 'when' callback is to be executed. A value 0/NULL/nullptr will
2454  * cause the callback to be executed in the main program loop.
2455  * @param func The callable object to be executed as a task, such as
2456  * formed by a lambda expression or the result of std::bind. It
2457  * should return a value (it cannot return void). It must be fully
2458  * bound (that is, it must take no arguments when called). If an
2459  * exception propagates from the task, the exception will be consumed
2460  * and (if the thrown object's type is not Cgu::Thread::Exit) a
2461  * g_critical() warning will be issued.
2462  * @exception std::bad_alloc This exception will be thrown if memory
2463  * is exhausted and the system throws in that case. (On systems with
2464  * over-commit/lazy-commit combined with virtual memory (swap), it is
2465  * rarely useful to check for memory exhaustion). If this exception
2466  * is thrown, the task will not start (which also means that the
2467  * 'when' callback will not execute).
2468  * @exception Cgu::Thread::TaskError This exception will be thrown if
2469  * stop_all() has previously been called. It will also be thrown if
2470  * is_error() would return true because this class's internal thread
2471  * pool loop implementation has thrown std::bad_alloc, or a thread
2472  * has failed to start correctly. (On systems with
2473  * over-commit/lazy-commit combined with virtual memory (swap), it is
2474  * rarely useful to check for memory exhaustion, but there may be
2475  * some specialized cases where the return value of is_error() is
2476  * useful.) If this exception is thrown, the task will not start
2477  * (which also means that the 'when' callback will not execute).
2478  * @note 1. This method will also throw if the copy or move
2479  * constructor of the 'func' or 'when' callable objects throws. If
2480  * such an exception is thrown, the task will not start (which also
2481  * means that the 'when' callback will not execute).
2482  * @note 2. If any of the callable objects passed to this method have
2483  * both const and non-const operator()() methods, the non-const
2484  * version will be called even if the callable object passed is a
2485  * const object.
2486  *
2487  * Since 2.1.0
2488  */
2489  // we need to use enable_if so that where this function is passed a
2490  // unique_ptr holding a non-const Callback::CallbackArg object, or
2491  // some other convertible object, this templated overload is dropped
2492  // from the overload set, in order to support the unique_ptr
2493  // overloads of this function. This overload calls into the version
2494  // of this function taking a CallbackArg object by unique_ptr in
2495  // order to perform type erasure.
2496  template <class When, class Func,
2497  class = typename std::enable_if<!std::is_convertible<When, std::unique_ptr<const Callback::CallbackArg<const typename std::result_of<Func()>::type&>>>::value>::type>
2498  void make_task_when(When&& when,
2499  GMainContext* context,
2500  Func&& func) {
2501  typedef decltype(func()) Ret;
2502  std::unique_ptr<const Callback::CallbackArg<const Ret&>> when_ptr(
2503  Callback::lambda<const Ret&>(std::forward<When>(when))
2504  );
2505  make_task_when_full(std::move(when_ptr),
2506  0,
2507  std::unique_ptr<const Cgu::Callback::Callback>(),
2508  0,
2509  G_PRIORITY_DEFAULT,
2510  context,
2511  std::forward<Func>(func));
2512  }
2513 
2514  /**
2515  * This is an abbreviated version of make_task_when_full(), which is
2516  * for use when it is known that the callable object passed to this
2517  * method does not throw, and the user is not interested in
2518  * std::bad_alloc and does not need a Cgu::Releaser object for the
2519  * 'when' callback (which is likely to cover the majority of uses,
2520  * particularly when composing tasks using glib because glib
2521  * terminates the program if it is unable to obtain memory).
2522  *
2523  * This method does the same as the version of make_task_when()
2524  * taking a callable object, except that this method takes that
2525  * object as its first argument and the 'when' callback as its last
2526  * argument in order to aid task composition, and in particular so
2527  * tasks compose in user code in a visually ordered manner.
2528  *
2529  * More particularly, like make_task_when_full(), this method is a
2530  * wrapper which takes a callable object which returns a value, and
2531  * constructs a TaskManager task which will execute that object by
2532  * calling add_task() with an appropriate callback object, and causes
2533  * the 'when' callback passed as an argument to this method to be
2534  * executed by a glib main loop if and when the task finishes
2535  * correctly - the 'when' callback is passed the callable object's
2536  * return value when it is invoked. It is thread safe (any thread
2537  * may call this method, including another task running on the
2538  * TaskManager object). Apart from the absence of a 'one thread per
2539  * task' model, this method therefore provides a similar interface to
2540  * the one provided by Cgu::Thread::Future. See the documentation on
2541  * add_task() for further information about how task execution works.
2542  *
2543  * The 'when' callback will execute with G_PRIORITY_DEFAULT priority
2544  * in the main loop.
2545  *
2546  * @param f The callable object to be executed as a task, such as
2547  * formed by a lambda expression or the result of std::bind. It
2548  * should return a value (it cannot return void). It must be fully
2549  * bound (that is, it must take no arguments when called). If an
2550  * exception propagates from the task, the exception will be consumed
2551  * and (if the thrown object's type is not Cgu::Thread::Exit) a
2552  * g_critical() warning will be issued.
2553  * @param context The glib main context of the main loop in which the
2554  * 'when' callback is to be executed. A value 0/NULL/nullptr will
2555  * cause the callback to be executed in the main program loop.
2556  * @param when A callback which will be executed if and when the
2557  * callable object passed to this method finishes correctly. The
2558  * callback is passed that object's return value when it is invoked.
2559  * If an exception propagates from the 'when' callback, this will be
2560  * consumed and a g_critical() warning will be issued. The callback
2561  * will execute in the glib main loop whose GMainContext object is
2562  * passed to the 'context' argument of this method.
2563  * @exception std::bad_alloc This exception will be thrown if memory
2564  * is exhausted and the system throws in that case. (On systems with
2565  * over-commit/lazy-commit combined with virtual memory (swap), it is
2566  * rarely useful to check for memory exhaustion). If this exception
2567  * is thrown, the task will not start (which also means that the
2568  * 'when' callback will not execute).
2569  * @exception Cgu::Thread::TaskError This exception will be thrown if
2570  * stop_all() has previously been called. It will also be thrown if
2571  * is_error() would return true because this class's internal thread
2572  * pool loop implementation has thrown std::bad_alloc, or a thread
2573  * has failed to start correctly. (On systems with
2574  * over-commit/lazy-commit combined with virtual memory (swap), it is
2575  * rarely useful to check for memory exhaustion, but there may be
2576  * some specialized cases where the return value of is_error() is
2577  * useful.) If this exception is thrown, the task will not start
2578  * (which also means that the 'when' callback will not execute).
2579  * @note 1. This method will also throw if the copy or move
2580  * constructor of the callable object throws. If such an exception
2581  * is thrown, the task will not start (which also means that the
2582  * 'when' callback will not execute).
2583  * @note 2. If the callable object passed as an argument has both
2584  * const and non-const operator()() methods, the non-const version
2585  * will be called even if the callable object passed is a const
2586  * object.
2587  *
2588  * Since 2.0.14
2589  */
2590  template <class Ret, class Func>
2591  void make_task_compose(Func&& f,
2592  GMainContext* context,
2593  std::unique_ptr<const Cgu::Callback::CallbackArg<const Ret&>> when) {
2594  make_task_when_full(std::move(when),
2595  0,
2596  std::unique_ptr<const Cgu::Callback::Callback>(),
2597  0,
2598  G_PRIORITY_DEFAULT,
2599  context,
2600  std::forward<Func>(f));
2601  }
2602 
2603  /**
2604  * This is an abbreviated version of make_task_when_full(), which is
2605  * for use when it is known that the callable object passed to the
2606  * 'func' argument of this method does not throw, and the user is not
2607  * interested in std::bad_alloc and does not need a Cgu::Releaser
2608  * object for the 'when' callback (which is likely to cover the
2609  * majority of uses, particularly when composing tasks using glib
2610  * because glib terminates the program if it is unable to obtain
2611  * memory).
2612  *
2613  * This method does the same as make_task_when(), except that this
2614  * method takes the callable object to be executed as a task as its
2615  * first argument and the 'when' callback as its last argument in
2616  * order to aid task composition, and in particular so tasks compose
2617  * in user code in a visually ordered manner.
2618  *
2619  * More particularly, like make_task_when_full(), this method is a
2620  * wrapper which takes a callable object which returns a value as its
2621  * 'func' argument, and constructs a TaskManager task which will
2622  * execute that object by calling add_task() with an appropriate
2623  * callback object, and causes the 'when' callback passed as an
2624  * argument to this method to be executed by a glib main loop if and
2625  * when the task finishes correctly - the 'when' callback is passed
2626  * the return value of the 'func' argument when it is invoked. It is
2627  * thread safe (any thread may call this method, including another
2628  * task running on the TaskManager object). Apart from the absence
2629  * of a 'one thread per task' model, this method therefore provides a
2630  * similar interface to the one provided by Cgu::Thread::Future. See
2631  * the documentation on add_task() for further information about how
2632  * task execution works.
2633  *
2634  * The 'when' callback will execute with G_PRIORITY_DEFAULT priority
2635  * in the main loop.
2636  *
2637  * @param func The callable object to be executed as a task, such as
2638  * formed by a lambda expression or the result of std::bind. It
2639  * should return a value (it cannot return void). It must be fully
2640  * bound (that is, it must take no arguments when called). If an
2641  * exception propagates from the task, the exception will be consumed
2642  * and (if the thrown object's type is not Cgu::Thread::Exit) a
2643  * g_critical() warning will be issued.
2644  * @param context The glib main context of the main loop in which the
2645  * 'when' callback is to be executed. A value 0/NULL/nullptr will
2646  * cause the callback to be executed in the main program loop.
2647  * @param when A callable object (such as formed by a lambda
2648  * expression or the result of std::bind) which will be executed if
2649  * and when the 'func' object passed to this method finishes
2650  * correctly. The 'when' callback is passed that objects's return
2651  * value when invoked, and should take a single unbound argument,
2652  * namely a reference to const of the type of that return value. If
2653  * an exception propagates from the 'when' callback, this will be
2654  * consumed and a g_critical() warning will be issued. The callback
2655  * will execute in the glib main loop whose GMainContext object is
2656  * passed to the 'context' argument of this method.
2657  * @exception std::bad_alloc This exception will be thrown if memory
2658  * is exhausted and the system throws in that case. (On systems with
2659  * over-commit/lazy-commit combined with virtual memory (swap), it is
2660  * rarely useful to check for memory exhaustion). If this exception
2661  * is thrown, the task will not start (which also means that the
2662  * 'when' callback will not execute).
2663  * @exception Cgu::Thread::TaskError This exception will be thrown if
2664  * stop_all() has previously been called. It will also be thrown if
2665  * is_error() would return true because this class's internal thread
2666  * pool loop implementation has thrown std::bad_alloc, or a thread
2667  * has failed to start correctly. (On systems with
2668  * over-commit/lazy-commit combined with virtual memory (swap), it is
2669  * rarely useful to check for memory exhaustion, but there may be
2670  * some specialized cases where the return value of is_error() is
2671  * useful.) If this exception is thrown, the task will not start
2672  * (which also means that the 'when' callback will not execute).
2673  * @note 1. This method will also throw if the copy or move
2674  * constructor of the 'func' or 'when' callable objects throws. If
2675  * such an exception is thrown, the task will not start (which also
2676  * means that the 'when' callback will not execute).
2677  * @note 2. If any of the callable objects passed to this method have
2678  * both const and non-const operator()() methods, the non-const
2679  * version will be called even if the callable object passed is a
2680  * const object.
2681  *
2682  * Since 2.1.0
2683  */
2684  // we need to use enable_if so that where this function is passed a
2685  // unique_ptr holding a non-const Callback::CallbackArg object, or
2686  // some other convertible object, this templated overload is dropped
2687  // from the overload set, in order to support the unique_ptr
2688  // overloads of this function. This overload calls into the version
2689  // of this function taking a CallbackArg object by unique_ptr in
2690  // order to perform type erasure.
2691  template <class Func, class When,
2692  class = typename std::enable_if<!std::is_convertible<When, std::unique_ptr<const Callback::CallbackArg<const typename std::result_of<Func()>::type&>>>::value>::type>
2693  void make_task_compose(Func&& func,
2694  GMainContext* context,
2695  When&& when) {
2696  typedef decltype(func()) Ret;
2697  std::unique_ptr<const Callback::CallbackArg<const Ret&>> when_ptr(
2698  Callback::lambda<const Ret&>(std::forward<When>(when))
2699  );
2700  make_task_when_full(std::move(when_ptr),
2701  0,
2702  std::unique_ptr<const Cgu::Callback::Callback>(),
2703  0,
2704  G_PRIORITY_DEFAULT,
2705  context,
2706  std::forward<Func>(func));
2707  }
2708 
2709  /**
2710  * This is a wrapper which takes a callable object (such as a
2711  * std::function object, a lambda or the return value of std::bind),
2712  * and constructs a TaskManager task which will execute that object
2713  * by calling add_task() with an appropriate callback representing a
2714  * std::packaged_task object, and returns a std::future object which
2715  * will provide the value (if any) that the the callable object
2716  * returns. It is thread safe: any thread may call this method,
2717  * including another task running on the TaskManager object, but see
2718  * the introductory remarks about the use of the
2719  * TaskManager::IncHandle scoped handle class where a task running on
2720  * a TaskManager object is to block on one of its sub-tasks. See
2721  * also the documentation on add_task() for further information about
2722  * how task execution works.
2723  *
2724  * If the callable object passed to this method exits by throwing an
2725  * exception (including Thread::Exit), that exception is stored in
2726  * the shared state of std::packaged_task, and will be rethrown when
2727  * get() is called on the returned std::future object. The callable
2728  * object may return void, in which case the std::future<void> object
2729  * returned by this method would be used for the purpose only of
2730  * obtaining an exception, or of "joining" on the completed task.
2731  *
2732  * @param f The callable object, such as formed by a lambda
2733  * expression or the result of std::bind, to be executed via
2734  * std::packaged_task by the TaskManager object.
2735  * @return A std::future object representing the shared state of a
2736  * std::packaged_task object constructed to execute the task, from
2737  * which the result of the task can be obtained.
2738  * @exception std::bad_alloc This exception will be thrown if memory
2739  * is exhausted and the system throws in that case. (On systems with
2740  * over-commit/lazy-commit combined with virtual memory (swap), it is
2741  * rarely useful to check for memory exhaustion). If this exception
2742  * is thrown, the task will not start.
2743  * @exception Cgu::Thread::TaskError This exception will be thrown if
2744  * stop_all() has previously been called. It will also be thrown if
2745  * is_error() would return true because this class's internal thread
2746  * pool loop implementation has thrown std::bad_alloc, or a thread
2747  * has failed to start correctly. (On systems with
2748  * over-commit/lazy-commit combined with virtual memory (swap), it is
2749  * rarely useful to check for memory exhaustion, but there may be
2750  * some specialized cases where the return value of is_error() is
2751  * useful.) If this exception is thrown, the task will not start.
2752  * @note This method will also throw if the copy or move
2753  * constructor of the callable object throws, or the move constructor
2754  * of std::packaged_task throws. If such an exception is thrown, the
2755  * task will not start.
2756  *
2757  * Since 2.2.4
2758  */
2759  template <class Func>
2760  auto make_task_packaged(Func&& f) -> std::future<decltype(f())> {
2761 
2762  // TODO: this is a work-around for gcc < 4.7, which has a bug
2763  // which requires a function whose return value is determined by
2764  // decltype, such as make_task_packaged(Func&&), to be inline. At
2765  // a suitable API/ABI break when gcc requirements are updated,
2766  // this should be moved to task_manager.tpp.
2767 
2768  typedef decltype(f()) Ret;
2769 
2770  std::packaged_task<Ret()> task{std::forward<Func>(f)};
2771  std::future<Ret> ret{task.get_future()};
2772  add_task(std::move(task));
2773 
2774  return ret;
2775  }
2776 
2777  /**
2778  * This method is similar to make_task_when_full(): it takes a
2779  * callable object as its 'func' argument (such as a std::function
2780  * object, a lambda or the return value of std::bind), and constructs
2781  * a TaskManager task which will execute that object by calling
2782  * add_task() with an appropriate callback object, and causes the
2783  * 'when' callback passed as an argument to this method to be
2784  * executed by a glib main loop when the task finishes. However,
2785  * unlike make_task_when_full(), it constructs a std::packaged_task
2786  * object to execute the task, and instead of passing the return
2787  * value of 'func' directly as an argument to the 'when' callback, it
2788  * passes a non-const reference to a std::future object of the return
2789  * type: so if 'func' returns a std::string object, the 'when'
2790  * callback should take a 'std::future<std::string>&' argument. The
2791  * main purpose of this is to store any exception thrown by 'func' in
2792  * the std::packaged_task object's shared state, so that it can be
2793  * obtained by the 'when' callback by calling std::future::get(). In
2794  * addition, subject to note 3 below this method's task wrapper will
2795  * never be in the position of consuming an internal std::bad_alloc
2796  * exception (although this method might throw std::bad_alloc).
2797  * Amongst other things, this dispenses with the need for a 'fail'
2798  * callback (at a very slight cost to efficiency compared with
2799  * make_task_when_full()).
2800  *
2801  * The callable object comprising the 'func' argument may return
2802  * void, if the purpose of the 'when' callback is only to deal in the
2803  * glib main loop with any exception thrown by 'func', or to do
2804  * something in the glib main loop dependent on the task having
2805  * finished but not on a value returned by it.
2806  *
2807  * A call to std::future::get() on the passed std::future object will
2808  * never block, because the 'when' callback is only invoked after the
2809  * task has finished (successfully or by throwing an exception).
2810  *
2811  * This method is thread safe (any thread may call it, including
2812  * another task running on the TaskManager object). See the
2813  * documentation on add_task() for further information about how task
2814  * execution works.
2815  *
2816  * Note that if a releaser is provided for the 'when' callback, this
2817  * is passed by pointer and not by reference (this is so that a NULL
2818  * pointer can indicate that no releaser is to be provided). If
2819  * provided, a releaser will enable automatic disconnection of the
2820  * 'when' callback if the object of which the releaser is a member is
2821  * destroyed. For this to be race free, the lifetime of that object
2822  * must be controlled by the thread in whose main loop the 'when'
2823  * callback will execute.
2824  *
2825  * There is an overload of this method which takes only three
2826  * arguments - the 'when' callback, a context argument and the
2827  * callable object to be run as a task, which is analogous to
2828  * make_task_when(). It is shorthand for cases where the 'when'
2829  * callback is to be executed without a releaser and with
2830  * G_PRIORITY_DEFAULT priority.
2831  *
2832  * @param when A callable object (such as formed by a lambda
2833  * expression or the result of std::bind) which will be executed when
2834  * the 'func' object passed to this method finishes, either by
2835  * executing normally or by throwing an exception. The 'when'
2836  * callback should take a single unbound argument, namely a non-const
2837  * reference to a std::future object for the type of the return value
2838  * of the 'func' object. If an exception propagates from the 'when'
2839  * callback, this will be consumed and a g_critical() warning will be
2840  * issued. The callback will execute in the glib main loop whose
2841  * GMainContext object is passed to the 'context' argument of this
2842  * method.
2843  * @param when_releaser A pointer to a Releaser object for automatic
2844  * disconnection of the 'when' callback before it executes in a main
2845  * loop (mainly relevant if the callback calls a non-static member
2846  * function of an object which may be destroyed before the callback
2847  * executes). A value of 0/NULL/nullptr indicates no releaser.
2848  * @param priority The priority to be given in the main loop to the
2849  * 'when' callback. In ascending order of priorities, priorities are
2850  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
2851  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. This determines the order
2852  * in which the callback will appear in the event list in the main
2853  * loop, not the priority which the OS will adopt.
2854  * @param context The glib main context of the main loop in which the
2855  * 'when' callback is to be executed. A value 0/NULL/nullptr will
2856  * cause the callback to be executed in the main program loop.
2857  * @param func The callable object to be executed as a task, such as
2858  * formed by a lambda expression or the result of std::bind. It must
2859  * be fully bound (that is, it must take no arguments when called).
2860  * If an exception propagates from the task, the exception will be
2861  * stored in the shared state of a std::packaged_task object and made
2862  * available to the 'when' callback via std::future::get().
2863  * @exception std::bad_alloc This exception will be thrown if memory
2864  * is exhausted and the system throws in that case. (On systems with
2865  * over-commit/lazy-commit combined with virtual memory (swap), it is
2866  * rarely useful to check for memory exhaustion). If this exception
2867  * is thrown, the task will not start (which also means that the
2868  * 'when' callback will not execute).
2869  * @exception Cgu::Thread::TaskError This exception will be thrown if
2870  * stop_all() has previously been called. It will also be thrown if
2871  * is_error() would return true because this class's internal thread
2872  * pool loop implementation has thrown std::bad_alloc, or a thread
2873  * has failed to start correctly. (On systems with
2874  * over-commit/lazy-commit combined with virtual memory (swap), it is
2875  * rarely useful to check for memory exhaustion, but there may be
2876  * some specialized cases where the return value of is_error() is
2877  * useful.) If this exception is thrown, the task will not start
2878  * (which also means that the 'when' callback will not execute).
2879  * @note 1. This method will also throw if the copy or move
2880  * constructor of the 'func' or 'when' callable objects throws. If
2881  * such an exception is thrown, the task will not start (which also
2882  * means that the 'when' callback will not execute).
2883  * @note 2. If any of the callable objects passed to this method have
2884  * both const and non-const operator()() methods, the non-const
2885  * version will be called even if the callable object passed is a
2886  * const object.
2887  * @note 3. If a 'when_releaser' object is provided, it is in theory
2888  * possible (if memory is exhausted and the system throws in that
2889  * case) that an internal SafeEmitterArg object will throw
2890  * std::bad_alloc when emitting/executing the 'when' callback in the
2891  * glib main loop, with the result that the relevant callback will
2892  * not execute (instead the exception will be consumed and a
2893  * g_critical() warning will be issued). This is rarely of any
2894  * relevance because glib will abort the program if it is itself
2895  * unable to obtain memory from the operating system. However, where
2896  * it is relevant, design the program so that it is not necessary to
2897  * provide a releaser object.
2898  *
2899  * Since 2.2.5
2900  */
2901  template <class When, class Func>
2902  void make_task_packaged_when(When&& when,
2903  Cgu::Releaser* when_releaser,
2904  gint priority,
2905  GMainContext* context,
2906  Func&& func);
2907 
2908  /**
2909  * This overload of make_task_packaged_when() taking three arguments
2910  * is an abbreviated version of the one taking five arguments. It is
2911  * for use where the 'when' callback is to be executed without a
2912  * releaser and with G_PRIORITY_DEFAULT priority.
2913  *
2914  * It is similar to make_task_when(): it takes a callable object as
2915  * its 'func' argument (such as a std::function object, a lambda or
2916  * the return value of std::bind), and constructs a TaskManager task
2917  * which will execute that object by calling add_task() with an
2918  * appropriate callback object, and causes the 'when' callback passed
2919  * as an argument to this method to be executed by a glib main loop
2920  * when the task finishes. However, unlike make_task_when(), it
2921  * constructs a std::packaged_task object to execute the task, and
2922  * instead of passing the return value of 'func' directly as an
2923  * argument to the 'when' callback, it passes a non-const reference
2924  * to a std::future object of the return type: so if 'func' returns a
2925  * std::string object, the 'when' callback should take a
2926  * 'std::future<std::string>&' argument. The main purpose of this is
2927  * to store any exception thrown by 'func' in the std::packaged_task
2928  * object's shared state, so that it can be obtained by the 'when'
2929  * callback by calling std::future::get(). In addition, this
2930  * method's task wrapper will never be in the position of consuming
2931  * an internal std::bad_alloc exception (although this method might
2932  * throw std::bad_alloc).
2933  *
2934  * The callable object comprising the 'func' argument may return
2935  * void, if the purpose of the 'when' callback is only to deal in the
2936  * glib main loop with any exception thrown by 'func', or to do
2937  * something in the glib main loop dependent on the task having
2938  * finished but not on a value returned by it.
2939  *
2940  * A call to std::future::get() on the passed std::future object will
2941  * never block, because the 'when' callback is only invoked after the
2942  * task has finished (successfully or by throwing an exception).
2943  *
2944  * This method is thread safe (any thread may call it, including
2945  * another task running on the TaskManager object). See the
2946  * documentation on add_task() for further information about how task
2947  * execution works.
2948  *
2949  * @param when A callable object (such as formed by a lambda
2950  * expression or the result of std::bind) which will be executed when
2951  * the 'func' object passed to this method finishes, either by
2952  * executing normally or by throwing an exception. The 'when'
2953  * callback should take a single unbound argument, namely a non-const
2954  * reference to a std::future object for the type of the return value
2955  * of the 'func' object. If an exception propagates from the 'when'
2956  * callback, this will be consumed and a g_critical() warning will be
2957  * issued. The callback will execute in the glib main loop whose
2958  * GMainContext object is passed to the 'context' argument of this
2959  * method.
2960  * @param context The glib main context of the main loop in which the
2961  * 'when' callback is to be executed. A value 0/NULL/nullptr will
2962  * cause the callback to be executed in the main program loop.
2963  * @param func The callable object to be executed as a task, such as
2964  * formed by a lambda expression or the result of std::bind. It must
2965  * be fully bound (that is, it must take no arguments when called).
2966  * If an exception propagates from the task, the exception will be
2967  * stored in the shared state of a std::packaged_task object and made
2968  * available to the 'when' callback via std::future::get().
2969  * @exception std::bad_alloc This exception will be thrown if memory
2970  * is exhausted and the system throws in that case. (On systems with
2971  * over-commit/lazy-commit combined with virtual memory (swap), it is
2972  * rarely useful to check for memory exhaustion). If this exception
2973  * is thrown, the task will not start (which also means that the
2974  * 'when' callback will not execute).
2975  * @exception Cgu::Thread::TaskError This exception will be thrown if
2976  * stop_all() has previously been called. It will also be thrown if
2977  * is_error() would return true because this class's internal thread
2978  * pool loop implementation has thrown std::bad_alloc, or a thread
2979  * has failed to start correctly. (On systems with
2980  * over-commit/lazy-commit combined with virtual memory (swap), it is
2981  * rarely useful to check for memory exhaustion, but there may be
2982  * some specialized cases where the return value of is_error() is
2983  * useful.) If this exception is thrown, the task will not start
2984  * (which also means that the 'when' callback will not execute).
2985  * @note 1. This method will also throw if the copy or move
2986  * constructor of the 'func' or 'when' callable objects throws. If
2987  * such an exception is thrown, the task will not start (which also
2988  * means that the 'when' callback will not execute).
2989  * @note 2. If any of the callable objects passed to this method have
2990  * both const and non-const operator()() methods, the non-const
2991  * version will be called even if the callable object passed is a
2992  * const object.
2993  *
2994  * Since 2.2.5
2995  */
2996  template <class When, class Func>
2997  void make_task_packaged_when(When&& when,
2998  GMainContext* context,
2999  Func&& func) {
3000  make_task_packaged_when(std::forward<When>(when),
3001  0,
3002  G_PRIORITY_DEFAULT,
3003  context,
3004  std::forward<Func>(func));
3005  }
3006 
3007  /**
3008  * This is the same as the version of make_task_packaged_when()
3009  * taking three arguments, except that it takes the callable object
3010  * to be executed as a task as its first argument and the 'when'
3011  * callback as its last argument in order to aid task composition,
3012  * and in particular so tasks compose in user code in a visually
3013  * ordered manner. It is for use where the 'when' callback is to be
3014  * executed without a releaser and with G_PRIORITY_DEFAULT priority.
3015  *
3016  * It is similar to make_task_compose(): it takes a callable object
3017  * as its 'func' argument (such as a std::function object, a lambda
3018  * or the return value of std::bind), and constructs a TaskManager
3019  * task which will execute that object by calling add_task() with an
3020  * appropriate callback object, and causes the 'when' callback passed
3021  * as an argument to this method to be executed by a glib main loop
3022  * when the task finishes. However, unlike make_task_when(), it
3023  * constructs a std::packaged_task object to execute the task, and
3024  * instead of passing the return value of 'func' directly as an
3025  * argument to the 'when' callback, it passes a non-const reference
3026  * to a std::future object of the return type: so if 'func' returns a
3027  * std::string object, the 'when' callback should take a
3028  * 'std::future<std::string>&' argument. The main purpose of this is
3029  * to store any exception thrown by 'func' in the std::packaged_task
3030  * object's shared state, so that it can be obtained by the 'when'
3031  * callback by calling std::future::get(). In addition, this
3032  * method's task wrapper will never be in the position of consuming
3033  * an internal std::bad_alloc exception (although this method might
3034  * throw std::bad_alloc).
3035  *
3036  * The callable object comprising the 'func' argument may return
3037  * void, if the purpose of the 'when' callback is only to deal in the
3038  * glib main loop with any exception thrown by 'func', or to do
3039  * something in the glib main loop dependent on the task having
3040  * finished but not on a value returned by it.
3041  *
3042  * A call to std::future::get() on the passed std::future object will
3043  * never block, because the 'when' callback is only invoked after the
3044  * task has finished (successfully or by throwing an exception).
3045  *
3046  * This method is thread safe (any thread may call it, including
3047  * another task running on the TaskManager object). See the
3048  * documentation on add_task() for further information about how task
3049  * execution works.
3050  *
3051  * @param func The callable object to be executed as a task, such as
3052  * formed by a lambda expression or the result of std::bind. It must
3053  * be fully bound (that is, it must take no arguments when called).
3054  * If an exception propagates from the task, the exception will be
3055  * stored in the shared state of a std::packaged_task object and made
3056  * available to the 'when' callback via std::future::get().
3057  * @param context The glib main context of the main loop in which the
3058  * 'when' callback is to be executed. A value 0/NULL/nullptr will
3059  * cause the callback to be executed in the main program loop.
3060  * @param when A callable object (such as formed by a lambda
3061  * expression or the result of std::bind) which will be executed when
3062  * the 'func' object passed to this method finishes, either by
3063  * executing normally or by throwing an exception. The 'when'
3064  * callback should take a single unbound argument, namely a non-const
3065  * reference to a std::future object for the type of the return value
3066  * of the 'func' object. If an exception propagates from the 'when'
3067  * callback, this will be consumed and a g_critical() warning will be
3068  * issued. The callback will execute in the glib main loop whose
3069  * GMainContext object is passed to the 'context' argument of this
3070  * method.
3071  * @exception std::bad_alloc This exception will be thrown if memory
3072  * is exhausted and the system throws in that case. (On systems with
3073  * over-commit/lazy-commit combined with virtual memory (swap), it is
3074  * rarely useful to check for memory exhaustion). If this exception
3075  * is thrown, the task will not start (which also means that the
3076  * 'when' callback will not execute).
3077  * @exception Cgu::Thread::TaskError This exception will be thrown if
3078  * stop_all() has previously been called. It will also be thrown if
3079  * is_error() would return true because this class's internal thread
3080  * pool loop implementation has thrown std::bad_alloc, or a thread
3081  * has failed to start correctly. (On systems with
3082  * over-commit/lazy-commit combined with virtual memory (swap), it is
3083  * rarely useful to check for memory exhaustion, but there may be
3084  * some specialized cases where the return value of is_error() is
3085  * useful.) If this exception is thrown, the task will not start
3086  * (which also means that the 'when' callback will not execute).
3087  * @note 1. This method will also throw if the copy or move
3088  * constructor of the 'func' or 'when' callable objects throws. If
3089  * such an exception is thrown, the task will not start (which also
3090  * means that the 'when' callback will not execute).
3091  * @note 2. If any of the callable objects passed to this method have
3092  * both const and non-const operator()() methods, the non-const
3093  * version will be called even if the callable object passed is a
3094  * const object.
3095  *
3096  * Since 2.2.5
3097  */
3098  template <class When, class Func>
3099  void make_task_packaged_compose(Func&& func,
3100  GMainContext* context,
3101  When&& when) {
3102  make_task_packaged_when(std::forward<When>(when),
3103  0,
3104  G_PRIORITY_DEFAULT,
3105  context,
3106  std::forward<Func>(func));
3107  }
3108 
3109  /**
3110  * If the specified minimum number of threads is greater than 0, this
3111  * constructor will start the required minimum number of threads. If
3112  * glib < 2.32 is installed, g_thread_init() must be called before
3113  * any TaskManager objects are constructed
3114  * @param max The maximum number of threads which the TaskManager
3115  * object will run in the thread pool. If the value passed as this
3116  * argument is less than the value passed as 'min', the maximum
3117  * number of threads will be set to 'min'. A value of 0 is not
3118  * valid, and if this is passed the number will be set to the greater
3119  * of 1 and 'min'.
3120  * @param min The minimum number of threads which the TaskManager
3121  * object will run in the thread pool.
3122  * @param idle The length of time in milliseconds that threads
3123  * greater in number than 'min' and not executing any tasks will
3124  * remain in existence. The default is 10000 (10 seconds).
3125  * @param blocking If true, calls to stop_all() and the destructor
3126  * will not return until the tasks remaining to be executed have
3127  * finished (what is meant by "the tasks remaining to be executed"
3128  * depends on the StopMode setting, for which see the documentation
3129  * on the stop_all() method). If false, stop_all() and the
3130  * destructor will return straight away (which in terms of the
3131  * TaskManager class implementation is safe for the reasons explained
3132  * in the documentation on the destructor).
3133  * @param mode The StopMode setting (either
3134  * Cgu::Thread::TaskManager::wait_for_running or
3135  * Cgu::Thread::TaskManager::wait_for_all) executed when running
3136  * stop_all() or when the destructor is called. See the
3137  * documentation on stop_all() for an explanation of the setting.
3138  * @exception std::bad_alloc This exception might be thrown if memory
3139  * is exhausted and the system throws in that case.
3140  * @exception Cgu::Thread::TaskError This exception will be thrown if
3141  * starting the specified minimum number of threads fails.
3142  * @exception Cgu::Thread::MutexError This exception might be thrown
3143  * if initialisation of the contained mutex fails. (It is often not
3144  * worth checking for this, as it means either memory is exhausted or
3145  * pthread has run out of other resources to create new mutexes.)
3146  * @exception Cgu::Thread::CondError This exception might be thrown
3147  * if initialisation of the contained condition variable fails. (It
3148  * is often not worth checking for this, as it means either memory is
3149  * exhausted or pthread has run out of other resources to create new
3150  * condition variables.)
3151  *
3152  * Since 2.0.12
3153  */
3154  TaskManager(unsigned int max = 8, unsigned int min = 0,
3155  unsigned int idle = 10000, bool blocking = true,
3157 
3158  /**
3159  * The destructor will call stop_all(), unless that method has
3160  * previously been called explicitly without throwing std::bad_alloc.
3161  * If the blocking setting is true, the destructor will not return
3162  * until the tasks remaining to be executed have finished (what is
3163  * meant by "the tasks remaining to be executed" depends on the
3164  * StopMode setting, for which see the documentation on the
3165  * stop_all() method.) If the blocking setting is false, the
3166  * destructor will return straight away: this is safe, because
3167  * TaskManager's internals for running tasks have been implemented
3168  * using reference counting and will not be deleted until all threads
3169  * running on the TaskManager object have finished, although the
3170  * remaining tasks should not attempt to call any of TaskManager's
3171  * methods once the TaskManager object itself has been destroyed.
3172  *
3173  * The destructor is thread safe (any thread can destroy a
3174  * TaskManager object) unless the blocking setting is true, in which
3175  * case no task running on the TaskManager object may destroy the
3176  * TaskManager object. Subject to that, it is not an error for a
3177  * thread to destroy a TaskManager object and so invoke this
3178  * destructor while another thread is already blocking in (if the
3179  * blocking setting is true) or already out of (if the blocking
3180  * setting is false) a call to stop_all() and remaining tasks are
3181  * executing: if blocking, both calls (to stop_all() and to this
3182  * destructor) would safely block together. Any given thread can
3183  * similarly safely follow a non-blocking call to stop_all() by a
3184  * non-blocking call to this destructor even though remaining tasks
3185  * are executing. However, it is an error for a thread to call
3186  * stop_all() after another thread has begun destruction of the
3187  * TaskManager object (that is, after this destructor has been
3188  * entered): there would then be an unresolvable race with the
3189  * destructor.
3190  *
3191  * The destructor will not throw.
3192  *
3193  * If stop_all() has not previously been called explicitly and throws
3194  * std::bad_alloc() when called in this destructor, the exception
3195  * will be caught and consumed, but then the destructor will not
3196  * block even if the blocking setting is true, and if the minimum
3197  * number of threads is not 0 some threads might remain running
3198  * during the entire program duration (albeit safely). Where the
3199  * throwing of std::bad_alloc is a meaningful event (usually it
3200  * isn't) and needs to be guarded against, call stop_all() explicitly
3201  * before this destructor is entered, or use a minimum thread value
3202  * of 0 and allow for the case of the destructor not blocking.
3203  *
3204  * Since 2.0.12
3205  */
3206  ~TaskManager();
3207 
3208 /* Only has effect if --with-glib-memory-slices-compat or
3209  * --with-glib-memory-slices-no-compat option picked */
3211 };
3212 
3213  /**
3214  * @class TaskManager::IncHandle task_manager.h c++-gtk-utils/task_manager.h
3215  * @brief A scoped handle for exception safe incrementing of the
3216  * maximum number of threads that a TaskManager object will run.
3217  * @sa Thread::TaskManager
3218  *
3219  * This class is for use where a task running on a TaskManager object
3220  * is about to make a blocking call. It enables the task to
3221  * increment in an exception safe way the maximum number of tasks
3222  * which the TaskManager object will currently run in its thread pool
3223  * to enable another thread to keep a core active, so that the number
3224  * is automatically decremented again when the
3225  * ThreadManager::IncHandle object has gone out of scope after the
3226  * task has finished making blocking calls or something has thrown.
3227  *
3228  * The documentation on Thread::TaskManager gives an example of its
3229  * use.
3230  *
3231  * This class is available since version 2.2.1 of the library.
3232  */
3234  TaskManager& tm;
3235 public:
3236  /**
3237  * This class cannot be copied. The copy constructor is deleted.
3238  *
3239  * Since 2.0.18/2.2.1
3240  */
3241  IncHandle(const TaskManager::IncHandle&) = delete;
3242 
3243  /**
3244  * This class cannot be copied. The assignment operator is deleted.
3245  *
3246  * Since 2.0.18/2.2.1
3247  */
3249 
3250  /**
3251  * This class requires initialisation with a TaskManager object. The
3252  * default constructor is deleted.
3253  *
3254  * Since 2.0.18/2.2.1
3255  */
3256  IncHandle() = delete;
3257 
3258  /**
3259  * This constructor calls TaskManager::change_max_threads() to
3260  * increment the maximum number of threads a TaskManager object will
3261  * currently run in its thread pool.
3262  * @param tm_ The TaskManager object whose maximum thread limit is to
3263  * be incremented.
3264  * @exception std::bad_alloc If tasks are currently queued for
3265  * execution, a new thread will be started, so this exception may be
3266  * thrown on starting the thread if memory is exhausted and the
3267  * system throws in that case. (On systems with
3268  * over-commit/lazy-commit combined with virtual memory (swap), it is
3269  * rarely useful to check for memory exhaustion).
3270  * @exception Cgu::Thread::TaskError If tasks are currently queued
3271  * for execution, a new thread will be started, so this exception may
3272  * be thrown on starting the thread if it fails to start correctly
3273  * (this would mean that memory is exhausted, the pthread thread
3274  * limit has been reached or pthread has run out of other resources
3275  * to start new threads).
3276  *
3277  * Since 2.0.18/2.2.1
3278  */
3279  explicit IncHandle(TaskManager& tm_): tm(tm_) {
3280  tm_.change_max_threads(1);
3281  }
3282 
3283  /**
3284  * This destructor calls TaskManager::change_max_threads() to
3285  * decrement the maximum number of threads a TaskManager object will
3286  * currently run in its thread pool. It will not throw.
3287  *
3288  * Since 2.0.18/2.2.1
3289  */
3290  ~IncHandle() {tm.change_max_threads(-1);}
3291 };
3292 
3293 } // namespace Thread
3294 
3295 } // namespace Cgu
3296 
3297 #include <c++-gtk-utils/task_manager.tpp>
3298 
3299 #endif