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