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