c++-gtk-utils
future.h
Go to the documentation of this file.
1 /* Copyright (C) 2010 to 2013 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 src/utils sub-directory);
20  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_FUTURE_H
40 #define CGU_FUTURE_H
41 
42 #include <memory>
43 #include <exception>
44 #include <utility> // for std::move and std::forward
45 #include <type_traits> // for std::remove_reference and std::remove_const
46 
47 #include <pthread.h>
48 #include <glib.h>
49 
50 #include <c++-gtk-utils/thread.h>
51 #include <c++-gtk-utils/mutex.h>
52 #include <c++-gtk-utils/callback.h>
55 #include <c++-gtk-utils/emitter.h>
56 #include <c++-gtk-utils/timeout.h>
58 
59 namespace Cgu {
60 
61 namespace Thread {
62 
63 struct FutureThreadError: public std::exception {
64  virtual const char* what() const throw() {return "FutureThreadError\n";}
65 };
66 
67 struct FutureWhenError: public std::exception {
68  virtual const char* what() const throw() {return "FutureWhenError\n";}
69 };
70 
71 /**
72  * @class Cgu::Thread::Future future.h c++-gtk-utils/future.h
73  * @brief A class representing a pthread thread which will
74  * provide a value.
75  * @sa Cgu::Thread::Thread Cgu::Thread::JoinableHandle Cgu::AsyncResult Cgu::Thread::make_future() Cgu::Thread::TaskManager
76  *
77  * The Thread::Future class will launch a worker thread, run the
78  * function it represents in that thread until it returns, and store
79  * the return value so that it can be waited on and/or extracted by
80  * another thread. A new Thread::Future object representing the
81  * function to be called is created by calling
82  * Cgu::Thread::Future<>::make() (a static member function) or from
83  * version 2.0.4 the Cgu::Thread::make_future() helper function. The
84  * worker thread is then started by calling run(), and the value
85  * extracted or waited for by calling get(). The run() method can
86  * only be called once, but any number of threads can wait for and/or
87  * extract the return value by calling the get() method. The class
88  * also provides a SafeEmitter @ref DoneEmitterAnchor "done_emitter"
89  * public object which emits when the worker thread has finished, and
90  * an associated when() function. In addition, from version 2.0.11 a
91  * move_get() method is provided, which is discussed further below.
92  *
93  * The template parameter type of Thread::Future is the type of the
94  * return value of the function called by the Thread::Future object.
95  * The return value can be any type, including any arbitrarily large
96  * tuple or other struct or standard C++ container (but see below
97  * about copying).
98  *
99  * A Thread::Future object cannot represent a function with a void
100  * return type - a compilation error will result if that is attempted.
101  * If no return value is wanted, then the Thread::Thread class can be
102  * used directly. (However, if in a particular usage this class is
103  * thought to be more convenient, the function to be represented by it
104  * can be wrapped by another function which provides a dummy return
105  * value, such as a dummy int. One possible case for this is where
106  * more than one thread wants to wait for the worker thread to
107  * terminate, as pthread_join() and so Thread::Thread::join() only
108  * give defined behaviour when called by one thread.) In addition, a
109  * Thread::Future object cannot represent a function with a non-const
110  * reference argument - that would not normally be safe, and a compile
111  * error will be generated if that is attempted. However, from
112  * version 2.0.0-rc3, const reference arguments can be bound to
113  * Thread::Future objects (this is safe, as the Thread::Future object
114  * will keep its own copy of the argument passed to it).
115  *
116  * The make() method and make_future() functions take a plain
117  * function, static member function or non-static member function,
118  * which can take up to three arguments in the case of a non-static
119  * member function, and four arguments in the case of any other
120  * function. In the case of a non-static member function, the
121  * referenced object whose member function is to be called must remain
122  * in existence until the worker thread has completed. Alternatively,
123  * a callable object such as a std::function object, a lambda or the
124  * return value of std::bind can be passed, which can have any number
125  * of arguments using lambda capture or std::bind (and which can also
126  * bind the referenced object of a non-static member function by
127  * taking a copy of it where that is necessary).
128  *
129  * It is to be noted that the target function to be represented by a
130  * Thread::Future object must not allow any exception other than
131  * Thread::Exit, an exception deriving from std::exception or a
132  * cancellation pseudo-exception to escape from it when it is
133  * executed. This includes ensuring that, for any argument of that
134  * function which is of class type and not taken by reference to
135  * const, the argument type's copy constructor does not throw anything
136  * other than these. (If the target function or the copy constructor
137  * of a value argument throws Thread::Exit or an exception deriving
138  * from std::exception, the exception is safely consumed and the
139  * Thread::Future object's error flag is set.)
140  *
141  * Where a callable object is not passed, internal moving/copying of
142  * arguments for the target function to be represented by the
143  * Thread::Future object takes place (once by invoking the rvalue move
144  * constructor or lvalue copy constructor, as appropriate, when make()
145  * or make_future() are called and, if the argument is not a const
146  * reference argument, once in the worker thread when run() is
147  * called). Therefore, if a non-trivial class object is to be
148  * received by the target function as an argument, it is best either
149  * (a) if it has a move constructor, to pass it to make() or
150  * make_future() as a temporary and have the target function take a
151  * const reference argument, or (b) for it to be constructed on free
152  * store and for the target function to receive it by pointer, by
153  * Cgu::SharedLockPtr, or by a std::shared_ptr implementation which
154  * has a thread-safe reference count. Note also that constructing
155  * callable objects using std::bind will cause copies of arguments to
156  * be made, as will lambda capture, so for ordinary usage it is better
157  * to pass a function pointer with arguments to make() or
158  * make_future() rather than a function object.
159  *
160  * Copying of the return value of the target function represented by
161  * the Thread::Future object also takes place. The run() method will
162  * store the return value of that function, so that it is available to
163  * the get() and move_get() methods and any 'when' callback, and
164  * therefore copy it once (unless, that is, the target function's
165  * return value type has a move assignment operator, in which case
166  * where possible that operator is called).
167  *
168  * For safety reasons, the get() method returns by value and so will
169  * cause the return value to be copied once more, so for return values
170  * comprising complex class objects which are to be abstracted using
171  * the get() method, it is often better if the function represented by
172  * the Thread::Future object allocates the return value on free store
173  * and returns it by pointer, by Cgu::SharedLockPtr, or by a
174  * std::shared_ptr implementation which has a thread-safe reference
175  * count. Alternatively, from version 2.0.11 a move_get() method is
176  * provided which will make a move operation instead of a copy if the
177  * return value's type implements a move constructor, but see the
178  * documentation on move_get() for the caveats with respect to its
179  * use: in particular, if move_get() is to be called by a thread, then
180  * get() may not normally be called by another thread, nor should the
181  * when() method be called.
182  *
183  * It should be noted that where the when() method is used, the return
184  * value is passed to the 'when' callback by reference to const and so
185  * without the copying carried out by the get() method: therefore, if
186  * the return value has a move assignment operator and the when()
187  * method is to be employed, and the 'when' callback only needs to
188  * call const methods of the return value, it may be more efficient
189  * not to allocate the return value on free store.
190  *
191  * This is a usage example:
192  *
193  * @code
194  * class Numbers {
195  * public:
196  * std::vector<long> get_primes(int n); // calculates the first n primes
197  * // and puts them in a vector
198  * ...
199  * };
200  *
201  * Numbers obj;
202  *
203  * // get the first 1,000 primes
204  * using namespace Cgu;
205  *
206  * auto future = Thread::make_future(obj, &Numbers::get_primes, 1000);
207  * // Thread::make_future() is a wrapper for the equivalent long-hand version required prior to version 2.0.4:
208  * // auto future = Thread::Future<std::vector<long>>::make(obj, &Numbers::get_primes, 1000);
209  *
210  * future->run();
211  * ... [ do something else ] ...
212  * std::vector<long> result(future->move_get());
213  * std::for_each(result.begin(), result.end(), [](long l) {std::cout << l << std::endl;});
214  * @endcode
215  *
216  * If get_primes() were a static member function or plain function,
217  * the syntax would be:
218  *
219  * @code
220  * auto future = Thread::make_future(&Numbers::get_primes, 1000);
221  * @endcode
222  *
223  * @b The @b Cgu::Thread::Future::when() @b functions
224  *
225  * From version 2.0.2, the return value of the thread function
226  * represented by Cgu::Thread::Future can be obtained asynchronously
227  * using Cgu::Thread::Future::when() to execute a function in a glib
228  * main loop when the thread function completes. The above example
229  * could be reimplemented as:
230  *
231  * @code
232  * class Numbers {
233  * public:
234  * std::vector<long> get_primes(int n); // calculates the first n primes
235  * // and puts them in a vector
236  * ...
237  * };
238  *
239  * void print_primes(const std::vector<long>& result) {
240  * std::for_each(result.begin(), result.end(), [](long l) {std::cout << l << std::endl;});
241  * }
242  *
243  * Numbers obj;
244  *
245  * using namespace Cgu;
246  *
247  * auto future = Thread::make_future(obj, &Numbers::get_primes, 1000);
248  * future->when(Callback::make(&print_primes));
249  * future->run();
250  * @endcode
251  *
252  * In this example, the callback which prints the primes to the
253  * console would execute in the default program main loop once the
254  * thread function providing those primes returns. As an alternative
255  * to a free standing print_primes() function, the callback object
256  * could be constructed from a C++11 lambda expression using
257  * Cgu::Callback::lambda() (available from version 2.0.9).
258  *
259  * @b Lambda @b functions
260  *
261  * As mentioned above, Cgu::Thread::Future objects can be constructed
262  * from any callable object. For example:
263  *
264  * @code
265  * using namespace Cgu;
266  * int i = 1;
267  * auto f = Thread::Future<int>::make([=]() {return i + 10;});
268  * f->run();
269  * std::cout << f->get() << std::endl;
270  * @endcode
271  *
272  * However, if make_future() is used, prior to version 2.0.14 of the
273  * library, the return type parameter had to be be explicitly stated
274  * if the callable object was not a std::function object. From
275  * version 2.0.14 this is no longer necessary, as the return value
276  * will be deduced automatically if it is not stated:
277  *
278  * @code
279  * using namespace Cgu;
280  * int i = 1;
281  * auto f = Thread::make_future<int>([=]() {return i + 10;}); // prior to version 2.0.14
282  * //auto f = Thread::make_future([=]() {return i + 10;}); // this is fine from version 2.0.14
283  * f->run();
284  * std::cout << f->get() << std::endl;
285  * @endcode
286  *
287  * @b Overloaded @b functions
288  *
289  * Where a member function or ordinary function represented by a
290  * Thread::Future object is overloaded, this will cause difficulties
291  * in template type deduction when Thread::Future<>::make() or
292  * Thread::make_future() are called. With Thread::Future<>::make(),
293  * functions may be overloaded on numbers of argument without
294  * difficulty, but not with Thread::make_future(). For example:
295  * @code
296  * class Numbers {
297  * public:
298  * int calc(int i);
299  * int calc(int i, int j);
300  * ...
301  * };
302  *
303  * Numbers obj;
304  *
305  * using namespace Cgu;
306  *
307  * int i = 1, j = 2;
308  *
309  * auto f1 =
310  * Thread::Future<int>::make(obj, &Numbers::calc, i); // OK
311  * auto f2 =
312  * Thread::Future<int>::make(obj, &Numbers::calc, i, j); // OK
313  *
314  * // explicit is disambiguation required with Thread::make_future()
315  * auto f3 =
316  * Thread::make_future(obj, static_cast<int(Numbers::*)(int)>(&Numbers::calc), i);
317  * auto f4 =
318  * Thread::make_future(obj, static_cast<int(Numbers::*)(int, int)>(&Numbers::calc), i, j);
319  * @endcode
320  * Neither Thread::Future<>::make() nor Thread::make_future() can be
321  * overloaded on types of argument without explicit disambiguation.
322  * For example:
323  * @code
324  * class Numbers {
325  * public:
326  * int calc(int i);
327  * int calc(double d);
328  * ...
329  * };
330  *
331  * Numbers obj;
332  *
333  * using namespace Cgu;
334  *
335  * int i = 1;
336  * double d = 2.0;
337  *
338  * auto f1 =
339  * Thread::Future<int>::make(obj, static_cast<int (Numbers::*)(int)>(&Numbers::calc), i);
340  * auto f2 =
341  * Thread::Future<int>::make(obj, static_cast<int (Numbers::*)(double)>(&Numbers::calc), d);
342  * auto f3 =
343  * Thread::make_future(obj, static_cast<int (Numbers::*)(int)>(&Numbers::calc), i);
344  * auto f4 =
345  * Thread::make_future(obj, static_cast<int (Numbers::*)(double)>(&Numbers::calc), d);
346  * @endcode
347  */
348 
349 namespace FutureHelper {
350 
351 // the sole purpose of this struct is to enable a callback object to
352 // be constructed with Callback::make_ref() which takes an argument
353 // which can be mutated when the callback is executed. Normally this
354 // would be unsafe: however in this particular use it is fine as the
355 // callback is only ever executed once, via Future::run().
356 template <class Val>
358  mutable std::unique_ptr<const Cgu::Callback::CallbackArg<const Val&>> when;
359  // TODO: these constructors are a work-around for a bug in gcc <
360  // 4.6. At any API break where the required version of gcc is
361  // increased to gcc-4.6 or higher, remove them.
362  WhenWrapperArg(std::unique_ptr<const Cgu::Callback::CallbackArg<const Val&>>&& when_) :
363  when(std::move(when_)) {}
364  WhenWrapperArg(WhenWrapperArg&& w): when(std::move(w.when)) {}
365 };
366 
367 // the sole purpose of this struct is to enable a callback object to
368 // be constructed with Callback::make_ref() which takes an argument
369 // which can be mutated when the callback is executed. Normally this
370 // would be unsafe: however in this particular use it is fine as the
371 // callback is only ever executed once, via Future::run().
372 template <class Val>
374  mutable std::unique_ptr<Cgu::SafeEmitterArg<const Val&>> when;
375  // TODO: these constructors are a work-around for a bug in gcc <
376  // 4.6. At any API break where the required version of gcc is
377  // increased to gcc-4.6 or higher, remove them.
379  when(std::move(when_)) {}
381 };
382 
383 } // namespace FutureHelper
384 
385 
386 template <class Val>
388 
389  std::unique_ptr<Cgu::Thread::Thread> thread_u;
390  std::unique_ptr<Cgu::Callback::Callback> cb_u;
391 
392  mutable Mutex mutex;
393  Cond cond;
394  Val val;
395  bool done;
396  bool running;
397  bool error;
398  bool emitter_error;
399 
400  template <class T, class Ret, class... Args>
401  void run_wrapper(T*, Ret (T::*)(Args...), const Args&...);
402 
403  template <class T, class Ret, class... Args>
404  void run_wrapper_const(const T*, Ret (T::*)(Args...) const, const Args&...);
405 
406  template <class Ret, class... Args>
407  void run_wrapper_static(Ret (*)(Args...), const Args&...);
408 
409  template <class Func>
410  void run_wrapper_functor(Func&);
411 
412  void cancel_cleanup();
413 
414  void execute_done(const std::unique_ptr<const Cgu::Callback::CallbackArg<const Val&>>&);
415  void post_done(const FutureHelper::WhenWrapperArg<Val>&,
416  gint, GMainContext*);
417  void execute_done_rel(const std::unique_ptr<Cgu::SafeEmitterArg<const Val&>>&);
418  void post_done_rel(const FutureHelper::WhenWrapperArgRel<Val>&,
419  gint, GMainContext*);
420 
421  // this is a static function taking the future object by IntrusivePtr to
422  // ensure that the future object remains in existence whilst this
423  // function might execute
424  static void fail_cb(const Cgu::IntrusivePtr<Future<Val>>& future,
425  const std::unique_ptr<const Cgu::Callback::Callback>& func,
426  bool& ret);
427 
428  // private constructor - this class can only be created with Thread::Future::make()
429  Future(): val(), done(false), running(false), error(false), emitter_error(false) {}
430 
431 public:
432 
433  // this class cannot be copied except by smart pointer
434 /**
435  * This class cannot be copied (except by smart pointer). The copy
436  * constructor is deleted.
437  */
438  Future(const Future&) = delete;
439 
440 /**
441  * This class cannot be copied (except by smart pointer). The
442  * assignment operator is deleted.
443  */
444  Future& operator=(const Future&) = delete;
445 
446 /**
447  * Constructs a new Cgu::Thread::Future object (returned by
448  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
449  * Val represents the return value of the function to be represented
450  * by the new object. From version 2.0.4, it will usually be more
451  * convenient to call the Cgu::Thread::make_future() function, which
452  * is a convenience wrapper for this static method.
453  * @exception std::bad_alloc It might throw std::bad_alloc if memory
454  * is exhausted and the system throws in that case. (This exception
455  * will not be thrown if the library has been installed using the
456  * --with-glib-memory-slices-no-compat configuration option: instead
457  * glib will terminate the program if it is unable to obtain memory
458  * from the operating system.)
459  * @exception Cgu::Thread::MutexError It might throw
460  * Cgu::Thread::MutexError if initialisation of the contained mutex
461  * fails. (It is often not worth checking for this, as it means
462  * either memory is exhausted or pthread has run out of other
463  * resources to create new mutexes.)
464  * @exception Cgu::Thread::CondError It might throw
465  * Cgu::Thread::CondError if initialisation of the contained condition
466  * variable fails. (It is often not worth checking for this, as it
467  * means either memory is exhausted or pthread has run out of other
468  * resources to create new condition variables.)
469  * @note This method will also throw if the default constructor of the
470  * return value type throws.
471  */
472  template <class Ret, class T>
474  Ret (T::*func)());
475 
476 /**
477  * Constructs a new Cgu::Thread::Future object (returned by
478  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
479  * Val represents the return value of the function to be represented
480  * by the new object. From version 2.0.4, it will usually be more
481  * convenient to call the Cgu::Thread::make_future() function, which
482  * is a convenience wrapper for this static method.
483  * @exception std::bad_alloc It might throw std::bad_alloc if memory
484  * is exhausted and the system throws in that case. (This exception
485  * will not be thrown if the library has been installed using the
486  * --with-glib-memory-slices-no-compat configuration option: instead
487  * glib will terminate the program if it is unable to obtain memory
488  * from the operating system.)
489  * @exception Cgu::Thread::MutexError It might throw
490  * Cgu::Thread::MutexError if initialisation of the contained mutex
491  * fails. (It is often not worth checking for this, as it means
492  * either memory is exhausted or pthread has run out of other
493  * resources to create new mutexes.)
494  * @exception Cgu::Thread::CondError It might throw
495  * Cgu::Thread::CondError if initialisation of the contained condition
496  * variable fails. (It is often not worth checking for this, as it
497  * means either memory is exhausted or pthread has run out of other
498  * resources to create new condition variables.)
499  * @note This method will also throw if the copy or move constructor
500  * of the bound argument throws, or the default constructor of the
501  * return value type throws.
502  */
503  template <class Ret, class Param1, class Arg1, class T>
505  Ret (T::*func)(Param1),
506  Arg1&& arg1);
507 
508 /**
509  * Constructs a new Cgu::Thread::Future object (returned by
510  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
511  * Val represents the return value of the function to be represented
512  * by the new object. From version 2.0.4, it will usually be more
513  * convenient to call the Cgu::Thread::make_future() function, which
514  * is a convenience wrapper for this static method.
515  * @exception std::bad_alloc It might throw std::bad_alloc if memory
516  * is exhausted and the system throws in that case. (This exception
517  * will not be thrown if the library has been installed using the
518  * --with-glib-memory-slices-no-compat configuration option: instead
519  * glib will terminate the program if it is unable to obtain memory
520  * from the operating system.)
521  * @exception Cgu::Thread::MutexError It might throw
522  * Cgu::Thread::MutexError if initialisation of the contained mutex
523  * fails. (It is often not worth checking for this, as it means
524  * either memory is exhausted or pthread has run out of other
525  * resources to create new mutexes.)
526  * @exception Cgu::Thread::CondError It might throw
527  * Cgu::Thread::CondError if initialisation of the contained condition
528  * variable fails. (It is often not worth checking for this, as it
529  * means either memory is exhausted or pthread has run out of other
530  * resources to create new condition variables.)
531  * @note This method will also throw if the copy or move constructor
532  * of a bound argument throws, or the default constructor of the
533  * return value type throws.
534  */
535  template <class Ret, class Param1, class Param2, class Arg1, class Arg2, class T>
537  Ret (T::*func)(Param1, Param2),
538  Arg1&& arg1,
539  Arg2&& arg2);
540 
541 /**
542  * Constructs a new Cgu::Thread::Future object (returned by
543  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
544  * Val represents the return value of the function to be represented
545  * by the new object. From version 2.0.4, it will usually be more
546  * convenient to call the Cgu::Thread::make_future() function, which
547  * is a convenience wrapper for this static method.
548  * @exception std::bad_alloc It might throw std::bad_alloc if memory
549  * is exhausted and the system throws in that case. (This exception
550  * will not be thrown if the library has been installed using the
551  * --with-glib-memory-slices-no-compat configuration option: instead
552  * glib will terminate the program if it is unable to obtain memory
553  * from the operating system.)
554  * @exception Cgu::Thread::MutexError It might throw
555  * Cgu::Thread::MutexError if initialisation of the contained mutex
556  * fails. (It is often not worth checking for this, as it means
557  * either memory is exhausted or pthread has run out of other
558  * resources to create new mutexes.)
559  * @exception Cgu::Thread::CondError It might throw
560  * Cgu::Thread::CondError if initialisation of the contained condition
561  * variable fails. (It is often not worth checking for this, as it
562  * means either memory is exhausted or pthread has run out of other
563  * resources to create new condition variables.)
564  * @note This method will also throw if the copy or move constructor
565  * of a bound argument throws, or the default constructor of the
566  * return value type throws.
567  */
568  template <class Ret, class Param1, class Param2, class Param3,
569  class Arg1, class Arg2, class Arg3, class T>
571  Ret (T::*func)(Param1, Param2, Param3),
572  Arg1&& arg1,
573  Arg2&& arg2,
574  Arg3&& arg3);
575 
576 /**
577  * Constructs a new Cgu::Thread::Future object (returned by
578  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
579  * Val represents the return value of the function to be represented
580  * by the new object. From version 2.0.4, it will usually be more
581  * convenient to call the Cgu::Thread::make_future() function, which
582  * is a convenience wrapper for this static method.
583  * @exception std::bad_alloc It might throw std::bad_alloc if memory
584  * is exhausted and the system throws in that case. (This exception
585  * will not be thrown if the library has been installed using the
586  * --with-glib-memory-slices-no-compat configuration option: instead
587  * glib will terminate the program if it is unable to obtain memory
588  * from the operating system.)
589  * @exception Cgu::Thread::MutexError It might throw
590  * Cgu::Thread::MutexError if initialisation of the contained mutex
591  * fails. (It is often not worth checking for this, as it means
592  * either memory is exhausted or pthread has run out of other
593  * resources to create new mutexes.)
594  * @exception Cgu::Thread::CondError It might throw
595  * Cgu::Thread::CondError if initialisation of the contained condition
596  * variable fails. (It is often not worth checking for this, as it
597  * means either memory is exhausted or pthread has run out of other
598  * resources to create new condition variables.)
599  * @note This method will also throw if the default constructor of the
600  * return value type throws.
601  */
602  template <class Ret, class T>
604  Ret (T::*func)() const);
605 
606 /**
607  * Constructs a new Cgu::Thread::Future object (returned by
608  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
609  * Val represents the return value of the function to be represented
610  * by the new object. From version 2.0.4, it will usually be more
611  * convenient to call the Cgu::Thread::make_future() function, which
612  * is a convenience wrapper for this static method.
613  * @exception std::bad_alloc It might throw std::bad_alloc if memory
614  * is exhausted and the system throws in that case. (This exception
615  * will not be thrown if the library has been installed using the
616  * --with-glib-memory-slices-no-compat configuration option: instead
617  * glib will terminate the program if it is unable to obtain memory
618  * from the operating system.)
619  * @exception Cgu::Thread::MutexError It might throw
620  * Cgu::Thread::MutexError if initialisation of the contained mutex
621  * fails. (It is often not worth checking for this, as it means
622  * either memory is exhausted or pthread has run out of other
623  * resources to create new mutexes.)
624  * @exception Cgu::Thread::CondError It might throw
625  * Cgu::Thread::CondError if initialisation of the contained condition
626  * variable fails. (It is often not worth checking for this, as it
627  * means either memory is exhausted or pthread has run out of other
628  * resources to create new condition variables.)
629  * @note This method will also throw if the copy or move constructor
630  * of the bound argument throws, or the default constructor of the
631  * return value type throws.
632  */
633  template <class Ret, class Param1, class Arg1, class T>
635  Ret (T::*func)(Param1) const,
636  Arg1&& arg1);
637 
638 /**
639  * Constructs a new Cgu::Thread::Future object (returned by
640  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
641  * Val represents the return value of the function to be represented
642  * by the new object. From version 2.0.4, it will usually be more
643  * convenient to call the Cgu::Thread::make_future() function, which
644  * is a convenience wrapper for this static method.
645  * @exception std::bad_alloc It might throw std::bad_alloc if memory
646  * is exhausted and the system throws in that case. (This exception
647  * will not be thrown if the library has been installed using the
648  * --with-glib-memory-slices-no-compat configuration option: instead
649  * glib will terminate the program if it is unable to obtain memory
650  * from the operating system.)
651  * @exception Cgu::Thread::MutexError It might throw
652  * Cgu::Thread::MutexError if initialisation of the contained mutex
653  * fails. (It is often not worth checking for this, as it means
654  * either memory is exhausted or pthread has run out of other
655  * resources to create new mutexes.)
656  * @exception Cgu::Thread::CondError It might throw
657  * Cgu::Thread::CondError if initialisation of the contained condition
658  * variable fails. (It is often not worth checking for this, as it
659  * means either memory is exhausted or pthread has run out of other
660  * resources to create new condition variables.)
661  * @note This method will also throw if the copy or move constructor
662  * of a bound argument throws, or the default constructor of the
663  * return value type throws.
664  */
665  template <class Ret, class Param1, class Param2, class Arg1, class Arg2, class T>
667  Ret (T::*func)(Param1, Param2) const,
668  Arg1&& arg1,
669  Arg2&& arg2);
670 
671 /**
672  * Constructs a new Cgu::Thread::Future object (returned by
673  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
674  * Val represents the return value of the function to be represented
675  * by the new object. From version 2.0.4, it will usually be more
676  * convenient to call the Cgu::Thread::make_future() function, which
677  * is a convenience wrapper for this static method.
678  * @exception std::bad_alloc It might throw std::bad_alloc if memory
679  * is exhausted and the system throws in that case. (This exception
680  * will not be thrown if the library has been installed using the
681  * --with-glib-memory-slices-no-compat configuration option: instead
682  * glib will terminate the program if it is unable to obtain memory
683  * from the operating system.)
684  * @exception Cgu::Thread::MutexError It might throw
685  * Cgu::Thread::MutexError if initialisation of the contained mutex
686  * fails. (It is often not worth checking for this, as it means
687  * either memory is exhausted or pthread has run out of other
688  * resources to create new mutexes.)
689  * @exception Cgu::Thread::CondError It might throw
690  * Cgu::Thread::CondError if initialisation of the contained condition
691  * variable fails. (It is often not worth checking for this, as it
692  * means either memory is exhausted or pthread has run out of other
693  * resources to create new condition variables.)
694  * @note This method will also throw if the copy or move constructor
695  * of a bound argument throws, or the default constructor of the
696  * return value type throws.
697  */
698  template <class Ret, class Param1, class Param2, class Param3,
699  class Arg1, class Arg2, class Arg3, class T>
701  Ret (T::*func)(Param1, Param2, Param3) const,
702  Arg1&& arg1,
703  Arg2&& arg2,
704  Arg3&& arg3);
705 
706 /**
707  * Constructs a new Cgu::Thread::Future object (returned by
708  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
709  * Val represents the return value of the function to be represented
710  * by the new object. From version 2.0.4, it will usually be more
711  * convenient to call the Cgu::Thread::make_future() function, which
712  * is a convenience wrapper for this static method.
713  * @exception std::bad_alloc It might throw std::bad_alloc if memory
714  * is exhausted and the system throws in that case. (This exception
715  * will not be thrown if the library has been installed using the
716  * --with-glib-memory-slices-no-compat configuration option: instead
717  * glib will terminate the program if it is unable to obtain memory
718  * from the operating system.)
719  * @exception Cgu::Thread::MutexError It might throw
720  * Cgu::Thread::MutexError if initialisation of the contained mutex
721  * fails. (It is often not worth checking for this, as it means
722  * either memory is exhausted or pthread has run out of other
723  * resources to create new mutexes.)
724  * @exception Cgu::Thread::CondError It might throw
725  * Cgu::Thread::CondError if initialisation of the contained condition
726  * variable fails. (It is often not worth checking for this, as it
727  * means either memory is exhausted or pthread has run out of other
728  * resources to create new condition variables.)
729  * @note This method will also throw if the default constructor of the
730  * return value type throws.
731  */
732  template <class Ret>
733  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)());
734 
735 /**
736  * Constructs a new Cgu::Thread::Future object (returned by
737  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
738  * Val represents the return value of the function to be represented
739  * by the new object. From version 2.0.4, it will usually be more
740  * convenient to call the Cgu::Thread::make_future() function, which
741  * is a convenience wrapper for this static method.
742  * @exception std::bad_alloc It might throw std::bad_alloc if memory
743  * is exhausted and the system throws in that case. (This exception
744  * will not be thrown if the library has been installed using the
745  * --with-glib-memory-slices-no-compat configuration option: instead
746  * glib will terminate the program if it is unable to obtain memory
747  * from the operating system.)
748  * @exception Cgu::Thread::MutexError It might throw
749  * Cgu::Thread::MutexError if initialisation of the contained mutex
750  * fails. (It is often not worth checking for this, as it means
751  * either memory is exhausted or pthread has run out of other
752  * resources to create new mutexes.)
753  * @exception Cgu::Thread::CondError It might throw
754  * Cgu::Thread::CondError if initialisation of the contained condition
755  * variable fails. (It is often not worth checking for this, as it
756  * means either memory is exhausted or pthread has run out of other
757  * resources to create new condition variables.)
758  * @note This method will also throw if the copy or move constructor
759  * of the bound argument throws, or the default constructor of the
760  * return value type throws.
761  */
762  template <class Ret, class Param1, class Arg1>
763  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1),
764  Arg1&& arg1);
765 
766 /**
767  * Constructs a new Cgu::Thread::Future object (returned by
768  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
769  * Val represents the return value of the function to be represented
770  * by the new object. From version 2.0.4, it will usually be more
771  * convenient to call the Cgu::Thread::make_future() function, which
772  * is a convenience wrapper for this static method.
773  * @exception std::bad_alloc It might throw std::bad_alloc if memory
774  * is exhausted and the system throws in that case. (This exception
775  * will not be thrown if the library has been installed using the
776  * --with-glib-memory-slices-no-compat configuration option: instead
777  * glib will terminate the program if it is unable to obtain memory
778  * from the operating system.)
779  * @exception Cgu::Thread::MutexError It might throw
780  * Cgu::Thread::MutexError if initialisation of the contained mutex
781  * fails. (It is often not worth checking for this, as it means
782  * either memory is exhausted or pthread has run out of other
783  * resources to create new mutexes.)
784  * @exception Cgu::Thread::CondError It might throw
785  * Cgu::Thread::CondError if initialisation of the contained condition
786  * variable fails. (It is often not worth checking for this, as it
787  * means either memory is exhausted or pthread has run out of other
788  * resources to create new condition variables.)
789  * @note This method will also throw if the copy or move constructor
790  * of a bound argument throws, or the default constructor of the
791  * return value type throws.
792  */
793  template <class Ret, class Param1, class Param2, class Arg1, class Arg2>
794  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1, Param2),
795  Arg1&& arg1,
796  Arg2&& arg2);
797 
798 /**
799  * Constructs a new Cgu::Thread::Future object (returned by
800  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
801  * Val represents the return value of the function to be represented
802  * by the new object. From version 2.0.4, it will usually be more
803  * convenient to call the Cgu::Thread::make_future() function, which
804  * is a convenience wrapper for this static method.
805  * @exception std::bad_alloc It might throw std::bad_alloc if memory
806  * is exhausted and the system throws in that case. (This exception
807  * will not be thrown if the library has been installed using the
808  * --with-glib-memory-slices-no-compat configuration option: instead
809  * glib will terminate the program if it is unable to obtain memory
810  * from the operating system.)
811  * @exception Cgu::Thread::MutexError It might throw
812  * Cgu::Thread::MutexError if initialisation of the contained mutex
813  * fails. (It is often not worth checking for this, as it means
814  * either memory is exhausted or pthread has run out of other
815  * resources to create new mutexes.)
816  * @exception Cgu::Thread::CondError It might throw
817  * Cgu::Thread::CondError if initialisation of the contained condition
818  * variable fails. (It is often not worth checking for this, as it
819  * means either memory is exhausted or pthread has run out of other
820  * resources to create new condition variables.)
821  * @note This method will also throw if the copy or move constructor
822  * of a bound argument throws, or the default constructor of the
823  * return value type throws.
824  */
825  template <class Ret, class Param1, class Param2, class Param3,
826  class Arg1, class Arg2, class Arg3>
827  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1, Param2, Param3),
828  Arg1&& arg1,
829  Arg2&& arg2,
830  Arg3&& arg3);
831 
832 /**
833  * Constructs a new Cgu::Thread::Future object (returned by
834  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
835  * Val represents the return value of the function to be represented
836  * by the new object. From version 2.0.4, it will usually be more
837  * convenient to call the Cgu::Thread::make_future() function, which
838  * is a convenience wrapper for this static method.
839  * @exception std::bad_alloc It might throw std::bad_alloc if memory
840  * is exhausted and the system throws in that case. (This exception
841  * will not be thrown if the library has been installed using the
842  * --with-glib-memory-slices-no-compat configuration option: instead
843  * glib will terminate the program if it is unable to obtain memory
844  * from the operating system.)
845  * @exception Cgu::Thread::MutexError It might throw
846  * Cgu::Thread::MutexError if initialisation of the contained mutex
847  * fails. (It is often not worth checking for this, as it means
848  * either memory is exhausted or pthread has run out of other
849  * resources to create new mutexes.)
850  * @exception Cgu::Thread::CondError It might throw
851  * Cgu::Thread::CondError if initialisation of the contained condition
852  * variable fails. (It is often not worth checking for this, as it
853  * means either memory is exhausted or pthread has run out of other
854  * resources to create new condition variables.)
855  * @note This method will also throw if the copy or move constructor
856  * of a bound argument throws, or the default constructor of the
857  * return value type throws.
858  */
859  template <class Ret, class Param1, class Param2, class Param3, class Param4,
860  class Arg1, class Arg2, class Arg3, class Arg4>
861  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1, Param2, Param3, Param4),
862  Arg1&& arg1,
863  Arg2&& arg2,
864  Arg3&& arg3,
865  Arg4&& arg4);
866 
867 /**
868  * Constructs a new Cgu::Thread::Future object (returned by
869  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
870  * Val represents the return value of the function to be represented
871  * by the new object. From version 2.0.4, it will usually be more
872  * convenient to call the Cgu::Thread::make_future() function, which
873  * is a convenience wrapper for this static method.
874  * @exception std::bad_alloc It might throw std::bad_alloc if memory
875  * is exhausted and the system throws in that case. (This exception
876  * will not be thrown if the library has been installed using the
877  * --with-glib-memory-slices-no-compat configuration option: instead
878  * glib will terminate the program if it is unable to obtain memory
879  * from the operating system.)
880  * @exception Cgu::Thread::MutexError It might throw
881  * Cgu::Thread::MutexError if initialisation of the contained mutex
882  * fails. (It is often not worth checking for this, as it means
883  * either memory is exhausted or pthread has run out of other
884  * resources to create new mutexes.)
885  * @exception Cgu::Thread::CondError It might throw
886  * Cgu::Thread::CondError if initialisation of the contained condition
887  * variable fails. (It is often not worth checking for this, as it
888  * means either memory is exhausted or pthread has run out of other
889  * resources to create new condition variables.)
890  * @note 1. This method will also throw if the copy or move
891  * constructor of the callable object passed as an argument throws, or
892  * the default constructor of the return value type throws.
893  * @note 2. If the callable object passed as an argument has both
894  * const and non-const operator()() methods, the non-const version
895  * will be called even if the callable object passed is a const
896  * object.
897  */
898  template <class Func>
899  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Func&& functor);
900 
901 /**
902  * Runs the function represented by this Cgu::Thread::Future object in
903  * a new worker thread. That function will only be run once. If this
904  * is the first time this method has been called, it will start the
905  * worker thread and return true, and if it has previously been
906  * called, this method will do nothing and return false. This method
907  * is thread safe and may be called by a different thread from the one
908  * which called make().
909  * @return true if this is the first time this method has been called,
910  * or false if this method has previously been called.
911  * @exception Cgu::Thread::FutureThreadError This method might throw
912  * Cgu::Thread::FutureThreadError if it has not previously been called
913  * and the thread did not start properly. If it does throw, this
914  * Cgu::Thread::Future object is defunct and further attempts to call
915  * this method will return immediately with a false value. (It is
916  * often not worth checking for this exception, as it means either
917  * memory is exhausted, the pthread thread limit has been reached or
918  * pthread has run out of other resources to start new threads.)
919  * @exception std::bad_alloc This method might throw std::bad_alloc if
920  * it has not previously been called, and memory is exhausted and the
921  * system throws in that case. If it does throw, this
922  * Cgu::Thread::Future object is defunct and further attempts to call
923  * this method will return immediately with a false value. (This
924  * exception will not be thrown if the library has been installed
925  * using the --with-glib-memory-slices-no-compat configuration option:
926  * instead glib will terminate the program if it is unable to obtain
927  * memory from the operating system.)
928  * @note 1. Any Cgu::Thread::Exit exception, or any uncaught exception
929  * derived from std::exception, which is thrown from the worker thread
930  * will be caught and consumed and the error flag will be set. The
931  * worker thread will safely terminate and unwind the stack in so
932  * doing.
933  * @note 2. As this wrapper class can provide error reporting in a way
934  * that Cgu::Thread::Thread of itself cannot, it would be desirable to
935  * consume any other uncaught exceptions. However, this cannot be
936  * done: annoyingly, NPTL's forced stack unwinding does not allow this
937  * if thread cancellation is to be made available. If an uncaught
938  * exception propagates out of a thread when the thread exits, the
939  * C++11 standard will cause std::terminate() to be called and so
940  * terminate the entire program. Accordingly, a user must make sure
941  * that no exceptions, other than Cgu::Thread::Exit or those derived
942  * from std::exception or any cancellation pseudo-exception, can
943  * propagate from the function which this Cgu::Thread::Future object
944  * represents.
945  * @note 3. If the worker thread is cancelled by a call to cancel()
946  * while in the middle of executing the function which this
947  * Cgu::Thread::Future object represents, the error flag will be set.
948  */
949  bool run();
950 
951 /**
952  * Gets the stored value obtained from the function which is
953  * represented by this object. If the worker thread launched by the
954  * call to run() has not completed, then this method will block until
955  * it has completed. If run() has not been called, then run() will be
956  * called (and this method will block until the launched worker thread
957  * completes). If the function which is represented by this object
958  * throws Cgu::Thread::Exit or an uncaught exception derived from
959  * std::exception, then the exception will have been consumed by this
960  * Cgu::Thread::Future object and the error flag will have been set.
961  * The error flag will also have been set if the worker thread is
962  * cancelled or the thread wrapper in this Cgu::Thread::Future object
963  * threw std::bad_alloc. This method is thread safe and may be called
964  * by any thread (and by more than one thread). It is a cancellation
965  * point if it blocks, and from version 2.0.11 is cancellation safe if
966  * the stack unwinds on cancellation. It is also strongly exception
967  * safe: no data will be lost if extracting the value fails.
968  * @return The value obtained from the function which is represented
969  * by this object
970  * @exception Cgu::Thread::FutureThreadError This method might throw
971  * Cgu::Thread::FutureThreadError if run() has not previously been
972  * called and the thread did not start properly when this function
973  * called run().
974  * @exception std::bad_alloc This method might throw std::bad_alloc if
975  * run() has not previously been called, memory is exhausted and the
976  * system throws in that case. (This exception will not be thrown if
977  * the library has been installed using the
978  * --with-glib-memory-slices-no-compat configuration option: instead
979  * glib will terminate the program if it is unable to obtain memory
980  * from the operating system.)
981  * @note 1. This method might also throw if the copy constructor of
982  * the returned value type throws.
983  * @note 2. Question: Couldn't this method return the stored value by
984  * lvalue reference to const? Answer: It could. However, because of
985  * return value optimization, which will be implemented by any
986  * compiler capable of compiling this library, no advantage would be
987  * gained by doing so when initializing a local variable with the
988  * return value of this method (the copy constructor will only be
989  * called once whether returning by value or const reference). The
990  * advantage of returning by value is that the call to the copy
991  * constructor is forced to be within this Thread::Future object's
992  * mutex, so different threads' calls to the copy constructor are
993  * serialized, and also with blocked cancellation, so this method is
994  * cancellation safe. All calls to this method by different threads
995  * are therefore isolated and we do not have to worry about the thread
996  * safety of direct access to the stored value via its const methods
997  * outside the mutex (which would not be thread safe if the stored
998  * value has data members declared mutable) nor about the cancellation
999  * safety of the copy constructor. Of course, for objects which do
1000  * not have mutable data, a hit arises by returning by value in cases
1001  * where it is not intended to initialize a local variable at all nor
1002  * to cancel a thread: where, say, only const methods are to be called
1003  * on the return value (which could be done directly if this method
1004  * returned by const reference). However, in many use cases this will
1005  * be mitigated by the move_get() method.
1006  */
1007  Val get();
1008 
1009 /**
1010  * Gets the stored value obtained from the function which is
1011  * represented by this object by a move operation, if the return type
1012  * implements a move constructor (otherwise this method does the same
1013  * as the get() method). It is provided as an option for cases where
1014  * a move is required for efficiency reasons, but although it may be
1015  * called by any thread, a move from this Thread::Future object may
1016  * normally only be made once (except where the return type has been
1017  * designed to be moved more than once for the limited purpose of
1018  * inspecting a flag indicating whether its value is valid or not).
1019  * If this method is to be called then no calls to get() by another
1020  * thread should normally be made and no calls to when() should be
1021  * made. If the worker thread launched by the call to run() has not
1022  * completed, then this method will block until it has completed. If
1023  * run() has not been called, then run() will be called (and this
1024  * method will block until the launched worker thread completes). If
1025  * the function which is represented by this object throws
1026  * Cgu::Thread::Exit or an uncaught exception derived from
1027  * std::exception, then the exception will have been consumed by this
1028  * Cgu::Thread::Future object and the error flag will have been set.
1029  * The error flag will also have been set if the worker thread is
1030  * cancelled or the thread wrapper in this Cgu::Thread::Future object
1031  * threw std::bad_alloc. This method is a cancellation point if it
1032  * blocks, and is cancellation safe if the stack unwinds on
1033  * cancellation. This method is only exception safe if the return
1034  * type's move constructor is exception safe.
1035  * @return The value obtained from the function which is represented
1036  * by this object
1037  * @exception Cgu::Thread::FutureThreadError This method might throw
1038  * Cgu::Thread::FutureThreadError if run() has not previously been
1039  * called and the thread did not start properly when this function
1040  * called run().
1041  * @exception std::bad_alloc This method might throw std::bad_alloc if
1042  * run() has not previously been called, memory is exhausted and the
1043  * system throws in that case. (This exception will not be thrown if
1044  * the library has been installed using the
1045  * --with-glib-memory-slices-no-compat configuration option: instead
1046  * glib will terminate the program if it is unable to obtain memory
1047  * from the operating system.)
1048  * @note 1. This method might also throw if the copy or move
1049  * constructor of the returned value type throws.
1050  * @note 2. Question: Couldn't this method return the stored value by
1051  * rvalue reference? Answer: It could. However, because of return
1052  * value optimization, which will be implemented by any compiler
1053  * capable of compiling this library, no advantage would be gained by
1054  * doing so when initializing a local variable with the return value
1055  * of this method (the move constructor will only be called once, and
1056  * no call will be made to the copy constructor, whether returning by
1057  * value or rvalue reference). The advantage of returning by value is
1058  * that the call to the move constructor is forced to be within this
1059  * Thread::Future object's mutex, so different threads' calls to the
1060  * move constructor are serialized, and also with blocked
1061  * cancellation, so this method is cancellation safe. All calls to
1062  * this method by different threads are therefore isolated and we do
1063  * not have to worry about the thread safety of the mutating first
1064  * call to this method, nor about direct access to the stored value
1065  * via a rvalue reference outside the mutex nor the cancellation
1066  * safety of the move constructor.
1067  *
1068  * Since 2.0.11
1069  */
1070  Val move_get();
1071 
1072 /**
1073  * Cancels the worker thread in which the function represented by this
1074  * object runs, if that function has not yet finished. If this method
1075  * is called and the worker thread is still running and is cancelled
1076  * in response to a call to this method, then the error flag will be
1077  * set so that a method calling get() or move_get() can examine
1078  * whether the result is valid. If run() has not yet been called or
1079  * the worker thread has already finished executing the function
1080  * represented by this object then this function does nothing and
1081  * returns false. This method is thread safe and may be called by any
1082  * thread. It will not throw.
1083  * @return true if run() has previously been called and the worker
1084  * thread has not yet finished executing the function represented by
1085  * this object, otherwise false (in which case this method does
1086  * nothing).
1087  * @note 1. Use this method with care. When cancelling a thread not
1088  * all thread implementations will unwind the stack, and so run the
1089  * destructors of local objects. This is discussed further in the
1090  * documentation on Cgu::Thread::Thread::cancel().
1091  * @note 2. This method might return true because the worker thread
1092  * has not yet finished, but the error flag might still not be set.
1093  * This is because the worker thread may not meet a cancellation point
1094  * before it ends naturally. It is the error flag which indicates
1095  * definitively whether the worker thread terminated prematurely in
1096  * response to a call to this method.
1097  */
1098  bool cancel();
1099 
1100 /**
1101  * A utility enabling the value returned by the thread function
1102  * represented by this Cgu::Thread::Future object to be dealt with
1103  * asynchronously rather than by (or in addition to) a call to the
1104  * get() method. It causes the callback passed as an argument to this
1105  * method (referred to below as the 'when' callback) to be executed by
1106  * a thread's main loop if and when the thread function represented by
1107  * this Cgu::Thread::Future object finishes correctly - the 'when'
1108  * callback is passed that thread function's return value when it is
1109  * invoked. This method is thread safe, and may be called by any
1110  * thread.
1111  *
1112  * This functionality is implemented by connecting an internal
1113  * dispatching callback to the done_emitter object.
1114  *
1115  * The 'when' callback should take a single unbound argument
1116  * comprising a const reference to the return type of the thread
1117  * function represented by this Cgu::Thread::Future object. (So, in
1118  * the case of a Future<int> object, the callback function should take
1119  * a const int& argument as the unbound argument.) The 'when'
1120  * callback can have any number of bound arguments, except that a
1121  * bound argument may not include a copy of this Cgu::Thread::Future
1122  * object held by intrusive pointer as returned by the make() methods
1123  * (that would result in this Cgu::Thread::Future object owning, via
1124  * done_emitter, a reference to itself and so become incapable of
1125  * being freed). The 'when' callback may, however, take a pointer to
1126  * this Cgu::Thread::Future object, as obtained by the
1127  * Cgu::IntrusivePtr::get() method, because this Cgu::Thread::Future
1128  * object is guaranteed to remain in existence until the callback has
1129  * completed executing.
1130  *
1131  * This method cannot be called after the thread function represented
1132  * by this Cgu::Thread::Future object has completed (either
1133  * successfully or unsuccessfully) so that is_done() would return
1134  * true, and if this is attempted a Cgu::Thread::FutureWhenError
1135  * exception will be thrown. Therefore, generally this method should
1136  * be called before the run() method has been called.
1137  *
1138  * Once the run() method has been called, this Cgu::Thread::Future
1139  * object will always stay in existence until the thread function
1140  * represented by it has completed (whether correctly, by cancellation
1141  * or by a thrown exception), and any 'when' callback (and any other
1142  * callbacks connected to the done_emitter object) and any 'fail'
1143  * callback have completed. Accordingly it is safe to use this method
1144  * even if the intrusive pointer object returned by the make() methods
1145  * will go out of scope before the 'when' callback has executed: the
1146  * callback will execute correctly irrespective of that.
1147  *
1148  * Summary: use of this method is safe and has been implemented in a
1149  * way which does not give rise to timing issues.
1150  *
1151  * If memory is exhausted and std::bad_alloc is thrown by the thread
1152  * wrapper of Cgu::Thread::Future after run() is called or by
1153  * done_emitter when emitting, or if the thread function represented
1154  * by this Cgu::Thread::Future object throws Cgu::Thread::Exit, exits
1155  * with an uncaught exception deriving from std::exception or is
1156  * cancelled, or if the copy constructor of a non-reference argument
1157  * of the function represented by the 'when' callback throws, or any
1158  * other callback has been connected to done_emitter before this
1159  * method is called which exits with an uncaught exception, then the
1160  * 'when' callback will not execute (instead the exception concerned
1161  * will be consumed and an error indicated). With many systems, swap
1162  * memory combined with memory over-commit makes it pointless to check
1163  * for std::bad_alloc (and even more so in programs using glib, as
1164  * glib aborts a program where it cannot obtain memory from the
1165  * operating system). So subject to that, if the user program is
1166  * designed so that the thread function represented by this
1167  * Cgu::Thread::Future object does not exit with uncaught exceptions,
1168  * does not throw Cgu::Thread::Exit and is not cancelled, and so that
1169  * the 'when' callback does not exit with an uncaught exception (and
1170  * the function represented by that callback either takes no arguments
1171  * of class type by value or the copy constructors of any of its value
1172  * arguments do not throw), and if this method is called before any
1173  * other callbacks are connected to done_emitter, the possibility of
1174  * failure can be disregarded.
1175  *
1176  * In cases where that is not true and detecting whether a failure has
1177  * occurred is required, a fail() method is provided. It should be
1178  * noted that a callback handed to the fail() method will not execute
1179  * in a case of error if the error comprises the 'when' callback
1180  * exiting with an uncaught exception when it is executed by the main
1181  * loop, or the copy constructor of any value argument of the function
1182  * represented by the 'when' callback throwing (such exceptions would
1183  * be consumed internally in order to protect the main loop and a
1184  * g_critical message issued). If the 'when' callback might exit with
1185  * an uncaught exception when executing or have the copy constructor
1186  * of a value argument throw, and doing something other than consuming
1187  * the exception and issuing a g_critical message is required, then a
1188  * different approach is to start a new thread to wait on the get()
1189  * method which can act on the result of is_error() directly.
1190  *
1191  * If glib < 2.32 is used, the glib main loop must have been made
1192  * thread-safe by a call to g_thread_init() before this function is
1193  * called. glib >= 2.32 does not require g_thread_init() to be called
1194  * in order to be thread safe.
1195  *
1196  * @param cb The 'when' callback (the callback to be executed when the
1197  * function represented by this Cgu::Thread::Future object has
1198  * successfully completed). Ownership is taken of this object, and it
1199  * will be deleted when it has been finished with.
1200  * @param priority The priority to be given to the 'when' callback in
1201  * the main loop after the thread function represented by this
1202  * Cgu::Thread::Future object has successfully completed. In
1203  * ascending order of priorities, priorities are G_PRIORITY_LOW,
1204  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
1205  * and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT. This
1206  * determines the order in which the callback will appear in the event
1207  * list in the main loop, not the priority which the OS will adopt.
1208  * @param context The glib main context of the thread in whose main
1209  * loop the 'when' callback is to be executed (the default of NULL
1210  * will cause the callback to be executed in the main program loop).
1211  * @return The internal dispatching callback created by this method
1212  * and connected to done_emitter. It is made available as a return
1213  * value so that if wanted it can be disconnected programmatically
1214  * from done_emitter, or block()/unblock() can be called on it (but if
1215  * that is to be done, it must be done before the thread function
1216  * represented by this Cgu::Thread::Future object has completed in
1217  * order for it to be effective).
1218  * @exception Cgu::Thread::FutureWhenError This method will throw
1219  * Cgu::Thread::FutureWhenError if it is called after the thread
1220  * function represented by this Cgu::Thread::Future object has
1221  * completed. If it does so, the 'when' callback will be disposed of.
1222  * @exception std::bad_alloc This method might throw std::bad_alloc if
1223  * memory is exhausted and the system throws in that case. If it does
1224  * so, the 'when' callback will be disposed of.
1225  * @note The return value of the function represented by this
1226  * Cgu::Thread::Future object is stored and passed as an argument to
1227  * the 'when' callback by const reference. If other threads might
1228  * concurrently call this object's get() method, which copies the
1229  * stored value, the stored type's copy constructor must be thread
1230  * safe with respect to the stored type's const methods. This would
1231  * be relevant if the stored type has data members declared mutable
1232  * which would be copied by its copy constructor.
1233  *
1234  * Since 2.0.2
1235  */
1237  gint priority = G_PRIORITY_DEFAULT,
1238  GMainContext* context = 0);
1239 
1240 /**
1241  * This is a version of the utility enabling the value returned by the
1242  * thread function represented by this Cgu::Thread::Future object to
1243  * be dealt with asynchronously, which takes a Releaser object for
1244  * automatic disconnection of the callback passed as an argument to
1245  * this method (referred to below as the 'when' callback), if the
1246  * object having the 'when' callback function as a member is
1247  * destroyed. For this to be race free, the lifetime of that object
1248  * must be controlled by the thread in whose main loop the 'when'
1249  * callback will execute.
1250  *
1251  * If the 'when' callback has not been released, this method causes it
1252  * to be executed by a thread's main loop if and when the thread
1253  * function represented by this Cgu::Thread::Future object finishes
1254  * correctly - the 'when' callback is passed that thread function's
1255  * return value when it is invoked. This method is thread safe, and
1256  * may be called by any thread.
1257  *
1258  * This functionality is implemented by connecting an internal
1259  * dispatching callback to the done_emitter object.
1260  *
1261  * The 'when' callback should take a single unbound argument
1262  * comprising a const reference to the return type of the thread
1263  * function represented by this Cgu::Thread::Future object. (So, in
1264  * the case of a Future<int> object, the callback function should take
1265  * a const int& argument as the unbound argument.) The 'when'
1266  * callback can have any number of bound arguments, except that a
1267  * bound argument may not include a copy of this Cgu::Thread::Future
1268  * object held by intrusive pointer as returned by the make() methods
1269  * (that would result in this Cgu::Thread::Future object owning, via
1270  * done_emitter, a reference to itself and so become incapable of
1271  * being freed). The 'when' callback may, however, take a pointer to
1272  * this Cgu::Thread::Future object, as obtained by the
1273  * Cgu::IntrusivePtr::get() method, because this Cgu::Thread::Future
1274  * object is guaranteed to remain in existence until the callback has
1275  * completed executing.
1276  *
1277  * This method cannot be called after the thread function represented
1278  * by this Cgu::Thread::Future object has completed (either
1279  * successfully or unsuccessfully) so that is_done() would return
1280  * true, and if this is attempted a Cgu::Thread::FutureWhenError
1281  * exception will be thrown. Therefore, generally this method should
1282  * be called before the run() method has been called.
1283  *
1284  * The documentation for the version of this method which does not
1285  * take a Releaser object gives further details of how this method is
1286  * used.
1287  *
1288  * If glib < 2.32 is used, the glib main loop must have been made
1289  * thread-safe by a call to g_thread_init() before this function is
1290  * called. glib >= 2.32 does not require g_thread_init() to be called
1291  * in order to be thread safe.
1292  *
1293  * @param cb The 'when' callback (the callback to be executed when the
1294  * function represented by this Cgu::Thread::Future object has
1295  * successfully completed). Ownership is taken of this object, and it
1296  * will be deleted when it has been finished with.
1297  * @param r A Releaser object for automatic disconnection of the
1298  * 'when' callback if the object of which the callback function is a
1299  * member is destroyed.
1300  * @param priority The priority to be given to the 'when' callback in
1301  * the main loop after the thread function represented by this
1302  * Cgu::Thread::Future object has successfully completed. In
1303  * ascending order of priorities, priorities are G_PRIORITY_LOW,
1304  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
1305  * and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT. This
1306  * determines the order in which the callback will appear in the event
1307  * list in the main loop, not the priority which the OS will adopt.
1308  * @param context The glib main context of the thread in whose main
1309  * loop the 'when' callback is to be executed (the default of NULL
1310  * will cause the callback to be executed in the main program loop).
1311  * @return The internal dispatching callback created by this method
1312  * and connected to done_emitter. It is made available as a return
1313  * value so that if wanted it can be disconnected programmatically
1314  * from done_emitter, or block()/unblock() can be called on it (but if
1315  * that is to be done, it must be done before the thread function
1316  * represented by this Cgu::Thread::Future object has completed in
1317  * order for it to be effective).
1318  * @exception Cgu::Thread::FutureWhenError This method will throw
1319  * Cgu::Thread::FutureWhenError if it is called after the thread
1320  * function represented by this Cgu::Thread::Future object has
1321  * completed. If it does so, the 'when' callback will be disposed of.
1322  * @exception std::bad_alloc This method might throw std::bad_alloc if
1323  * memory is exhausted and the system throws in that case. If it does
1324  * so, the 'when' callback will be disposed of.
1325  * @exception Cgu::Thread::MutexError This method will throw
1326  * Cgu:Thread::MutexError if initialisation of the mutex in a
1327  * SafeEmitterArg object constructed by this method fails. If it does
1328  * so, the 'when' callback will be disposed of. (It is often not
1329  * worth checking for this, as it means either memory is exhausted or
1330  * pthread has run out of other resources to create new mutexes.)
1331  * @note 1. The return value of the function represented by this
1332  * Cgu::Thread::Future object is stored and passed as an argument to
1333  * the 'when' callback by const reference. If other threads might
1334  * concurrently call this object's get() method, which copies the
1335  * stored value, the stored type's copy constructor must be thread
1336  * safe with respect to the stored type's const methods. This would
1337  * be relevant if the stored type has data members declared mutable
1338  * which would be copied by its copy constructor.
1339  * @note 2. By virtue of the Releaser object, it is in theory possible
1340  * (if memory is exhausted and the system throws in that case) that an
1341  * internal SafeEmitterArg object will throw std::bad_alloc when
1342  * emitting/executing the 'when' callback in the glib main loop, with
1343  * the result that the relevant callback will not execute (instead the
1344  * exception will be consumed and a g_critical() warning will be
1345  * issued). This is rarely of any relevance because glib will abort
1346  * the program if it is itself unable to obtain memory from the
1347  * operating system. However, where it is relevant, design the
1348  * program so that it is not necessary to provide a releaser object.
1349  *
1350  * Since 2.0.2
1351  */
1353  Cgu::Releaser& r,
1354  gint priority = G_PRIORITY_DEFAULT,
1355  GMainContext* context = 0);
1356 
1357 /**
1358  * A utility intended to be used where relevant in conjunction with
1359  * the when() methods. It enables a callback to be executed in a glib
1360  * main loop (referred to below as the 'fail' callback) if memory is
1361  * exhausted and std::bad_alloc was thrown by the thread wrapper of
1362  * Cgu::Thread::Future after calling run() or by done_emitter when
1363  * emitting, or if the thread function represented by this
1364  * Cgu::Thread::Future object threw Cgu::Thread::Exit, exited with an
1365  * uncaught exception deriving from std::exception or was cancelled
1366  * (or that function took an argument of class type by value whose
1367  * copy constructor threw such an exception), or any callback
1368  * connected to done_emitter exited with an uncaught exception. It
1369  * therefore enables errors to be detected and acted on without having
1370  * a thread wait on the get() method in order to test is_error() or
1371  * is_emitter_error().
1372  *
1373  * It is implemented by attaching a timeout to the main loop which
1374  * polls at 100 millisecond intervals and tests is_done()/is_error()
1375  * and is_emitter_done()/is_emitter_error(). The timeout is
1376  * automatically removed by the implementation once it has been
1377  * detected that an error has occurred and the 'fail' callback is
1378  * executed, or if the thread function represented by this Cgu::Future
1379  * object and all done_emitter emissions (including execution of any
1380  * 'when' callback) have completed successfully.
1381  *
1382  * This method can be called before or after the run() method has been
1383  * called, and whether or not the thread function represented by this
1384  * Cgu::Thread::Future object has completed.
1385  *
1386  * Once this method has been called, this Cgu::Thread::Future object
1387  * will always stay in existence until the timeout has been
1388  * automatically removed by the implementation. Accordingly it is
1389  * safe to use this method even if the intrusive pointer object
1390  * returned by the make() methods will go out of scope before the
1391  * 'fail' callback has executed: the callback will execute correctly
1392  * irrespective of that.
1393  *
1394  * This method does not have a priority argument: as a polling timeout
1395  * is created, a particular priority will normally have no
1396  * significance (in fact, the 'fail' callback will execute in the main
1397  * loop with a priority of G_PRIORITY_DEFAULT). If in a special case
1398  * a different polling interval than 100 milliseconds or a different
1399  * priority is required, users can attach their own polling timeouts
1400  * to a main loop and carry out the tests by hand.
1401  *
1402  * Four other points should be noted. First, if as well as the when()
1403  * method being called some other callback has been connected to
1404  * done_emitter, and that other callback throws, the 'fail' callback
1405  * will execute. Therefore, if the particular program design requires
1406  * that the 'fail' callback should only execute if the 'when' callback
1407  * is not executed (and the 'when' callback only execute if the 'fail'
1408  * callback does not execute), no other callbacks which throw should
1409  * be connected to done_emitter.
1410  *
1411  * Secondly, as mentioned in the documentation on the when() method,
1412  * if the 'when' callback exits with an uncaught exception upon being
1413  * executed by the main loop or the function it represents takes an
1414  * argument by value whose copy constructor throws, the 'fail'
1415  * callback will not execute (the exception will have been consumed
1416  * internally in order to protect the main loop and a g_critical
1417  * message issued).
1418  *
1419  * Thirdly, avoid if possible having the 'fail' callback represent a
1420  * function which either might throw or takes an argument by value
1421  * whose copy constructor might throw (such an exception would be
1422  * consumed internally in order to protect the main loop and a
1423  * g_critical message issued, but no other error indication apart from
1424  * the g_critical message will be provided).
1425  *
1426  * Fourthly, unlike the 'when' callback, a copy of this
1427  * Cgu::Thread::Future object held by intrusive pointer as returned by
1428  * the make() methods may safely be bound to the 'fail' callback,
1429  * which would enable the 'fail' callback to determine whether it is
1430  * is_error() or is_emitter_error() which returns false.
1431  *
1432  * If glib < 2.32 is used, the glib main loop must have been made
1433  * thread-safe by a call to g_thread_init() before this function is
1434  * called. glib >= 2.32 does not require g_thread_init() to be called
1435  * in order to be thread safe.
1436  *
1437  * @param cb The 'fail' callback (the callback to be executed if the
1438  * thread function represented by this Cgu::Thread::Future object or a
1439  * done_emitter emission has failed to complete). Ownership is taken
1440  * of this object, and it will be deleted when it has been finished
1441  * with.
1442  * @param context The glib main context of the thread in whose main
1443  * loop the 'fail' callback is to be executed (the default of NULL
1444  * will cause the functor to be executed in the main program loop).
1445  * @exception std::bad_alloc This method might throw std::bad_alloc if
1446  * memory is exhausted and the system throws in that case. If it does
1447  * so, the 'fail' callback will be disposed of.
1448  *
1449  * Since 2.0.2
1450  */
1451  void fail(const Cgu::Callback::Callback* cb,
1452  GMainContext* context = 0);
1453 
1454 /**
1455  * This is a version of the fail() utility for use in conjunction with
1456  * the when() methods, which takes a Releaser object for automatic
1457  * disconnection of the callback functor passed as an argument to this
1458  * method if the object having the callback function as a member is
1459  * destroyed. For this to be race free, the lifetime of that object
1460  * must be controlled by the thread in whose main loop the 'fail'
1461  * callback will execute.
1462  *
1463  * This method enables a callback to be executed in a glib main loop
1464  * if memory is exhausted and std::bad_alloc was thrown by the thread
1465  * wrapper of Cgu::Thread::Future after calling run() or by
1466  * done_emitter when emitting, or if the thread function represented
1467  * by this Cgu::Thread::Future object threw Cgu::Thread::Exit, exited
1468  * with an uncaught exception deriving from std::exception or was
1469  * cancelled (or that function took an argument of class type by value
1470  * whose copy constructor threw such an exception), or any callback
1471  * connected to done_emitter exited with an uncaught exception. It
1472  * therefore enables errors to be detected and acted on without having
1473  * a thread wait on the get() method in order to test is_error() or
1474  * is_emitter_error().
1475  *
1476  * This method can be called before or after the run() method has been
1477  * called, and whether or not the thread function represented by this
1478  * Cgu::Thread::Future object has completed.
1479  *
1480  * The documentation for the version of this method which does not
1481  * take a Releaser object gives further details of how this method is
1482  * used.
1483  *
1484  * If glib < 2.32 is used, the glib main loop must have been made
1485  * thread-safe by a call to g_thread_init() before this function is
1486  * called. glib >= 2.32 does not require g_thread_init() to be called
1487  * in order to be thread safe.
1488  *
1489  * @param cb The 'fail' callback (the callback to be executed if the
1490  * thread function represented by this Cgu::Thread::Future object or a
1491  * done_emitter emission has failed to complete). Ownership is taken
1492  * of this object, and it will be deleted when it has been finished
1493  * with.
1494  * @param r A Releaser object for automatic disconnection of the
1495  * 'fail' callback if the object of which the callback function is a
1496  * member is destroyed.
1497  * @param context The glib main context of the thread in whose main
1498  * loop the 'fail' callback is to be executed (the default of NULL
1499  * will cause the functor to be executed in the main program loop).
1500  * @exception std::bad_alloc This method might throw std::bad_alloc if
1501  * memory is exhausted and the system throws in that case. If it does
1502  * so, the 'fail' callback will be disposed of.
1503  * @exception Cgu::Thread::MutexError This method will throw
1504  * Cgu:Thread::MutexError if initialisation of the mutex in a
1505  * SafeEmitterArg object constructed by Cgu::start_timeout() fails.
1506  * If it does so, the 'fail' callback will be disposed of. (It is
1507  * often not worth checking for this, as it means either memory is
1508  * exhausted or pthread has run out of other resources to create new
1509  * mutexes.)
1510  * @note By virtue of the Releaser object, it is in theory possible
1511  * (if memory is exhausted and the system throws in that case) that an
1512  * internal SafeEmitterArg object will throw std::bad_alloc when
1513  * emitting/executing the 'fail' callback in the glib main loop, with
1514  * the result that the relevant callback will not execute (instead the
1515  * exception will be consumed and a g_critical() warning will be
1516  * issued). This is rarely of any relevance because glib will abort
1517  * the program if it is itself unable to obtain memory from the
1518  * operating system. However, where it is relevant, design the
1519  * program so that it is not necessary to provide a releaser object.
1520  *
1521  * Since 2.0.2
1522  */
1523  void fail(const Cgu::Callback::Callback* cb,
1524  Cgu::Releaser& r,
1525  GMainContext* context = 0);
1526 
1527 /**
1528  * @return true if the function represented by this
1529  * Cgu::Thread::Future object has finished, either by returning
1530  * normally, by cancellation or by virtue of having thrown
1531  * Cgu::Thread::Exit or some exception derived from std::exception.
1532  * Once this method returns true, then it is guaranteed that the get()
1533  * or move_get() method will not block (except as incidental to any
1534  * contention between threads calling get()). Once this method has
1535  * returned true or get() or move_get() has unblocked, then the result
1536  * of is_error() is definitive. This method is thread safe and may be
1537  * called by any thread. It will not throw.
1538  * @note This method will return true even though any callbacks
1539  * connected to done_emitter are still executing or waiting to
1540  * execute. From version 2.0.2 the is_emitter_done() method will
1541  * indicate when done_emitter callbacks (if any) have also completed.
1542  */
1543  bool is_done() const;
1544 
1545 /**
1546  * @return true if both the function represented by this
1547  * Cgu::Thread::Future object has finished and any callbacks connected
1548  * to done_emitter have completed. Once this method returns true,
1549  * then the result of is_emitter_error() is definitive. This method
1550  * is thread safe and may be called by any thread. It will not throw.
1551  * @note This method will return true automatically if is_error() and
1552  * is_done() return true, because if the function represented by this
1553  * Cgu::Thread::Future object was cancelled or exited with an uncaught
1554  * exception, done_emitter is never emitted. In addition, if this
1555  * method returns true, then is_done() must also return true.
1556  *
1557  * Since 2.0.2
1558  */
1559  bool is_emitter_done() const;
1560 
1561 /**
1562  * @return true if (a) a Cgu::Thread::Exit exception has been thrown
1563  * by the function represented by this Cgu::Thread::Future object
1564  * (which will have been consumed by this Cgu::Thread::Future object),
1565  * (b) an exception derived from std::exception has been thrown by
1566  * that function which was not caught in that function (and which will
1567  * also have been consumed by this Cgu::Thread::Future object), (c)
1568  * the worker thread in which that function runs was cancelled in
1569  * mid-course with a call to cancel() or (d) the thread wrapper
1570  * implementing the worker thread in this Cgu::Thread::Future object
1571  * threw and then consumed std::bad_alloc (this is different from the
1572  * run() method throwing std::bad_alloc). In these cases the value
1573  * obtained by get() or move_get() will not be valid (it will be a
1574  * default constructed object of the return type of the function
1575  * represented by this Cgu::Thread::Future object). Otherwise this
1576  * method returns false. The result of this method is definitive once
1577  * get() or move_get() has unblocked or is_done() returns true. This
1578  * method is thread safe and may be called by any thread. It will not
1579  * throw.
1580  */
1581  bool is_error() const;
1582 
1583 /**
1584  * @return true if an uncaught exception arose in emitting @ref
1585  * DoneEmitterAnchor "done_emitter" when executing callbacks connected
1586  * to it. Otherwise this method returns false. The result of this
1587  * method is definitive once is_emitter_done() returns true. This
1588  * method is thread safe and may be called by any thread. It will not
1589  * throw.
1590  * @note This method will return false automatically if is_error()
1591  * returns true, because if the function represented by this
1592  * Cgu::Thread::Future object was cancelled or exited with an uncaught
1593  * exception, done_emitter is never emitted. It follows that if this
1594  * method returns true, is_error() must return false.
1595  */
1596  bool is_emitter_error() const;
1597 
1598 /**
1599  * A Cgu::SafeEmitter object which is emitted when the function
1600  * represented by this Cgu::Thread::Future object finishes correctly
1601  * (that is, the function is not cancelled and does not throw any
1602  * uncaught exceptions). By itself it does not do too much as it is
1603  * emitted (and connected callbacks execute in) the same worker thread
1604  * immediately after the Future function has completed. However, any
1605  * thread can connect a Callback object to this Cgu::SafeEmitter
1606  * object and a connected callback can, say, cause another Callback to
1607  * be executed in a thread's main loop using Cgu::Callback::post(),
1608  * and from version 2.0.2 when() methods are provided which will do
1609  * this for users automatically. Once the run() method has been
1610  * called, this Cgu::Thread::Future object (and so done_emitter) will
1611  * always stay in existence until the function represented by it has
1612  * completed (whether correctly, by cancellation or by a thrown
1613  * exception) and any callbacks connected to the done_emitter object
1614  * have completed, irrespective of whether the intrusive pointer
1615  * returned by the make() methods has gone out of scope.
1616  * @note 1. Cancellation is blocked while the Cgu::SafeEmitter object
1617  * emits and any connected callback executes.
1618  * @note 2. A connected callback can however terminate the worker
1619  * thread by throwing Cgu::Thread::Exit (in which case no subsequent
1620  * callbacks to be executed on that emission will execute either: the
1621  * worker thread will safely terminate and unwind the stack in so
1622  * doing). In that event, the emitter_error flag will be set.
1623  * @note 3. All other uncaught exceptions which might be thrown by the
1624  * Cgu::SafeEmitter object emitting, or by a connected callback
1625  * function executing, are consumed to retain the integrity of the
1626  * Thread::Future object. In the event of such an exception being
1627  * thrown, the emitter_error flag will be set. In summary, the
1628  * emitter_error flag will be set if (a) a callback function throws
1629  * Cgu::Thread::Exit, (b) some other uncaught exception escapes from a
1630  * callback function or (c) Cgu::SafeEmitter::emit() throws
1631  * std::bad_alloc or the copy constructor of a bound argument which is
1632  * not a reference argument has thrown. If the user knows that the
1633  * callback function does not throw Cgu::Thread::Exit and does not
1634  * allow any other exception to escape, then the cause must be a
1635  * std::bad_alloc memory exception in Cgu::SafeEmitter::emit() or the
1636  * copy constructor of a non-reference bound argument throwing.
1637  * @note 4. An emission is thread safe if the connected callback
1638  * functions are thread safe.
1639  * @note 5. This Cgu::Thread::Future object's mutex is released while
1640  * the Cgu::SafeEmitter object emits. This means that any connected
1641  * callbacks can safely call, say, the Future object's get() or
1642  * is_error() methods. However, a connected callback should not have
1643  * a bound argument comprising a copy of this Cgu::Thread::Future
1644  * object held by intrusive pointer as returned by the make() methods
1645  * (that would result in this Cgu::Thread::Future object owning, via
1646  * done_emitter, a reference to itself and so become incapable of
1647  * being freed). The callback may, however, take a pointer to this
1648  * Cgu::Thread::Future object as a bound argument, as obtained by the
1649  * Cgu::IntrusivePtr::get() method, because this Cgu::Thread::Future
1650  * object is guaranteed to remain in existence until all callbacks
1651  * connected to done_emitter have completed executing.
1652  * @anchor DoneEmitterAnchor
1653  */
1655 
1656 /* Only has effect if --with-glib-memory-slices-compat or
1657  * --with-glib-memory-slices-no-compat option picked */
1659 };
1660 
1661 /**
1662  * A convenience helper function which calls
1663  * Cgu::Thread::Future::make() to obtain a Future object without the
1664  * need to specify the return value of the function represented by the
1665  * new object: that is deduced from the signature of that function.
1666  * This is useful shorthand when also employed with the C++11 'auto'
1667  * keyword.
1668  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1669  * is exhausted and the system throws in that case. (This exception
1670  * will not be thrown if the library has been installed using the
1671  * --with-glib-memory-slices-no-compat configuration option: instead
1672  * glib will terminate the program if it is unable to obtain memory
1673  * from the operating system.)
1674  * @exception Cgu::Thread::MutexError It might throw
1675  * Cgu::Thread::MutexError if initialisation of the contained mutex
1676  * fails. (It is often not worth checking for this, as it means
1677  * either memory is exhausted or pthread has run out of other
1678  * resources to create new mutexes.)
1679  * @exception Cgu::Thread::CondError It might throw
1680  * Cgu::Thread::CondError if initialisation of the contained condition
1681  * variable fails. (It is often not worth checking for this, as it
1682  * means either memory is exhausted or pthread has run out of other
1683  * resources to create new condition variables.)
1684  * @note This method will also throw if the copy or move constructor
1685  * of a bound argument throws, or the default constructor of the
1686  * return value type of the function represented by the new object
1687  * throws.
1688 
1689  *
1690  * Since 2.0.4
1691  */
1692 template <class Obj, class Ret, class... Params, class... Args>
1694  Ret (Obj::*func)(Params...),
1695  Args&&... args) {
1696  return Cgu::Thread::Future<Ret>::make(obj, func, std::forward<Args>(args)...);
1697 }
1698 
1699 /**
1700  * A convenience helper function which calls
1701  * Cgu::Thread::Future::make() to obtain a Future object without the
1702  * need to specify the return value of the function represented by the
1703  * new object: that is deduced from the signature of that function.
1704  * This is useful shorthand when also employed with the C++11 'auto'
1705  * keyword.
1706  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1707  * is exhausted and the system throws in that case. (This exception
1708  * will not be thrown if the library has been installed using the
1709  * --with-glib-memory-slices-no-compat configuration option: instead
1710  * glib will terminate the program if it is unable to obtain memory
1711  * from the operating system.)
1712  * @exception Cgu::Thread::MutexError It might throw
1713  * Cgu::Thread::MutexError if initialisation of the contained mutex
1714  * fails. (It is often not worth checking for this, as it means
1715  * either memory is exhausted or pthread has run out of other
1716  * resources to create new mutexes.)
1717  * @exception Cgu::Thread::CondError It might throw
1718  * Cgu::Thread::CondError if initialisation of the contained condition
1719  * variable fails. (It is often not worth checking for this, as it
1720  * means either memory is exhausted or pthread has run out of other
1721  * resources to create new condition variables.)
1722  * @note This method will also throw if the copy or move constructor
1723  * of a bound argument throws, or the default constructor of the
1724  * return value type of the function represented by the new object
1725  * throws.
1726  *
1727  * Since 2.0.4
1728  */
1729 template <class Obj, class Ret, class... Params, class... Args>
1731  Ret (Obj::*func)(Params...) const,
1732  Args&&... args) {
1733  return Cgu::Thread::Future<Ret>::make(obj, func, std::forward<Args>(args)...);
1734 }
1735 
1736 /**
1737  * A convenience helper function which calls
1738  * Cgu::Thread::Future::make() to obtain a Future object without the
1739  * need to specify the return value of the function represented by the
1740  * new object: that is deduced from the signature of that function.
1741  * This is useful shorthand when also employed with the C++11 'auto'
1742  * keyword.
1743  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1744  * is exhausted and the system throws in that case. (This exception
1745  * will not be thrown if the library has been installed using the
1746  * --with-glib-memory-slices-no-compat configuration option: instead
1747  * glib will terminate the program if it is unable to obtain memory
1748  * from the operating system.)
1749  * @exception Cgu::Thread::MutexError It might throw
1750  * Cgu::Thread::MutexError if initialisation of the contained mutex
1751  * fails. (It is often not worth checking for this, as it means
1752  * either memory is exhausted or pthread has run out of other
1753  * resources to create new mutexes.)
1754  * @exception Cgu::Thread::CondError It might throw
1755  * Cgu::Thread::CondError if initialisation of the contained condition
1756  * variable fails. (It is often not worth checking for this, as it
1757  * means either memory is exhausted or pthread has run out of other
1758  * resources to create new condition variables.)
1759  * @note This method will also throw if the copy or move constructor
1760  * of a bound argument throws, or the default constructor of the
1761  * return value type of the function represented by the new object
1762  * throws.
1763  *
1764  * Since 2.0.4
1765  */
1766 template <class Ret, class... Params, class... Args>
1768  Args&&... args) {
1769  return Cgu::Thread::Future<Ret>::make(func, std::forward<Args>(args)...);
1770 }
1771 
1772 
1773 /**
1774  * A convenience helper function which calls
1775  * Cgu::Thread::Future::make() to obtain a Future object without the
1776  * need to specify the return value of the function represented by the
1777  * new object: that is deduced from the signature of that function.
1778  * This is useful shorthand when also employed with the C++11 'auto'
1779  * keyword.
1780  *
1781  * From version 2.0.14, this method takes the callable object as a
1782  * template parameter, and in prior versions it took it as a
1783  * std::function object. Before version 2.0.14 it was necessary to
1784  * specify the return value of any callable object which was not a
1785  * std::function object as a specific template parameter: this is not
1786  * necessary in version 2.0.14, as it is deduced automatically.
1787  *
1788  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1789  * is exhausted and the system throws in that case. (This exception
1790  * will not be thrown if the library has been installed using the
1791  * --with-glib-memory-slices-no-compat configuration option: instead
1792  * glib will terminate the program if it is unable to obtain memory
1793  * from the operating system.)
1794  * @exception Cgu::Thread::MutexError It might throw
1795  * Cgu::Thread::MutexError if initialisation of the contained mutex
1796  * fails. (It is often not worth checking for this, as it means
1797  * either memory is exhausted or pthread has run out of other
1798  * resources to create new mutexes.)
1799  * @exception Cgu::Thread::CondError It might throw
1800  * Cgu::Thread::CondError if initialisation of the contained condition
1801  * variable fails. (It is often not worth checking for this, as it
1802  * means either memory is exhausted or pthread has run out of other
1803  * resources to create new condition variables.)
1804  * @note 1. This method will also throw if the copy or move
1805  * constructor of the callable object passed as an argument throws, or
1806  * the default constructor of the return value type of the function
1807  * represented by the new object throws.
1808  * @note 2. If the callable object passed as an argument has both
1809  * const and non-const operator()() methods, the non-const version
1810  * will be called even if the callable object passed is a const
1811  * object.
1812  *
1813  * Since 2.0.4
1814  */
1815 // we don't need this version of make_future() for syntactic reasons -
1816 // the version taking a single template parameter will do by itself
1817 // syntactically because it can use decltype. However, we include
1818 // this version in order to be API compatible with c++-gtk-utils <
1819 // 2.0.14, which required the return type to be specified when this
1820 // method is passed something other than a std::function object.
1821 // SFINAE will take care of the rest, except with a corner case where
1822 // all of the following apply: (i) a function object is passed whose
1823 // operator()() method returns a copy of the function object (or
1824 // another function object of the same type), (ii) the function object
1825 // is passed to this method as a rvalue and not a lvalue, and (iii)
1826 // the user specifically states the return type when instantiating
1827 // this template function. This would give rise to an ambiguity, but
1828 // its happening is extremely unlikely, and cannot happen with a
1829 // lambda or the return value of std::bind, because those types are
1830 // only known to the compiler, and cannot happen with other objects if
1831 // the user lets template deduction take its course.
1832 template <class Ret, class Func>
1834  return Cgu::Thread::Future<Ret>::make(std::forward<Func>(functor));
1835 }
1836 
1837 // we don't want to document this function: it provides the type
1838 // deduction of the return value of the passed functor (it deals with
1839 // cases where this is not specified expressly).
1840 #ifndef DOXYGEN_PARSING
1841 template <class Func>
1843  return Cgu::Thread::Future<decltype(functor())>::make(std::forward<Func>(functor));
1844 }
1845 #endif
1846 
1847 } // namespace Thread
1848 
1849 } // namespace Cgu
1850 
1851 #include <c++-gtk-utils/future.tpp>
1852 
1853 #endif