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