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, std::remove_const,
46  // std::enable_if and std::is_convertible
47 
48 #include <pthread.h>
49 #include <glib.h>
50 
51 #include <c++-gtk-utils/thread.h>
52 #include <c++-gtk-utils/mutex.h>
53 #include <c++-gtk-utils/callback.h>
56 #include <c++-gtk-utils/emitter.h>
57 #include <c++-gtk-utils/timeout.h>
59 
60 namespace Cgu {
61 
62 namespace Thread {
63 
64 struct FutureThreadError: public std::exception {
65  virtual const char* what() const throw() {return "FutureThreadError\n";}
66 };
67 
68 struct FutureWhenError: public std::exception {
69  virtual const char* what() const throw() {return "FutureWhenError\n";}
70 };
71 
72 /**
73  * @class Cgu::Thread::Future future.h c++-gtk-utils/future.h
74  * @brief A class representing a pthread thread which will
75  * provide a value.
76  * @sa Cgu::Thread::Thread Cgu::Thread::JoinableHandle Cgu::AsyncResult Cgu::Thread::make_future() Cgu::Thread::TaskManager
77  *
78  * The Thread::Future class will launch a worker thread, run the
79  * function it represents in that thread until it returns, and store
80  * the return value so that it can be waited on and/or extracted by
81  * another thread. A new Thread::Future object representing the
82  * function to be called is normally created by calling
83  * Cgu::Thread::make_future() with a callable object, such as a lambda
84  * expression or the return value of std::bind. The worker thread is
85  * then started by calling run(), and the value extracted or waited
86  * for by calling get(). The run() method can only be called once,
87  * but any number of threads can wait for and/or extract the return
88  * value by calling the get() method. The class also provides a
89  * move_get() method, and a SafeEmitter @ref DoneEmitterAnchor
90  * "done_emitter" public object which emits when the worker thread has
91  * finished, and an associated when() function.
92  *
93  * The template parameter type of Thread::Future is the type of the
94  * return value of the function or callable object called by the
95  * Thread::Future object. The return value can be any type, including
96  * any arbitrarily large tuple or other struct or standard C++
97  * container.
98  *
99  * A Thread::Future object cannot represent a function with a void
100  * return type - a compilation error will result if that is attempted.
101  * If no return value is wanted, then the Thread::Thread class can be
102  * used directly. (However, if in a particular usage this class is
103  * thought to be more convenient, the function to be represented by it
104  * can be wrapped by another function which provides a dummy return
105  * value, such as a dummy int. One possible case for this is where
106  * more than one thread wants to wait for the worker thread to
107  * terminate, as pthread_join() and so Thread::Thread::join() only
108  * give defined behaviour when called by one thread.)
109  *
110  * A future object can also be constructed with Thread::make_future()
111  * and Thread::Future::make() functions which take a function pointer
112  * (or an object reference and member function pointer) with bound
113  * arguments but these are deprecated in the 2.2 series of the library
114  * as they offer little advantage over using std::bind. (Although
115  * deprecated, there is no plan to remove these functions as they are
116  * there and they work - the deprecation is in effect guidance.)
117  * These deprecated functions can take up to three bound arguments in
118  * the case of a non-static member function, and four bound arguments
119  * in the case of any other function. In the case of a non-static
120  * member function, the referenced object whose member function is to
121  * be called must remain in existence until the worker thread has
122  * completed. The target function passed by pointer (or member
123  * function pointer) can take a reference to const argument, as a copy
124  * of the object to be passed to the argument is taken to avoid
125  * dangling references, but it cannot take a reference to non-const
126  * argument.
127  *
128  * It is to be noted that the target function or callable object to be
129  * represented by a Thread::Future object must not allow any exception
130  * other than Thread::Exit, an exception deriving from std::exception
131  * or a cancellation pseudo-exception to escape from it when it is
132  * executed. This includes ensuring that, for any function's bound
133  * argument which is of class type and not taken by reference, the
134  * argument's copy constructor does not throw anything other than
135  * these, and that the move assignment operator (or if none, copy
136  * assignment operator) of the return value (if of class type) of the
137  * target function or callable object does not throw anything other
138  * than these. (If the target function or callable object, or the
139  * copy constructor of a bound value argument or the move or copy
140  * assignment operator of the return value, throws Thread::Exit or an
141  * exception deriving from std::exception, the exception is safely
142  * consumed and the Thread::Future object's error flag is set.
143  * However, if the move assignment operator or copy assignment
144  * operator, as the case may be, of the return value throws, it should
145  * leave the movee/assignee in a state in which it can safely be
146  * destroyed and in which, if that movee/assignee is further copied or
147  * moved from, the copy or move either throws an exception or produces
148  * an object which can also be destroyed -- but these are minimum
149  * requirements for any reasonable assignment operator, and met by any
150  * assignment operator offering the basic exception guarantee.)
151  *
152  * The Thread::Future object will store the return value of the target
153  * function or callable object, so that it is available to the get()
154  * and move_get() methods and any 'when' callback, and therefore
155  * either move it, or if it has no move assignment operator, copy it
156  * once.
157  *
158  * For safety reasons, the get() method returns by value and so will
159  * cause the return value to be copied once more, so for return values
160  * comprising complex class objects which are to be extracted using
161  * the get() method, it is often better if the function represented by
162  * the Thread::Future object allocates the return value on free store
163  * and returns it by pointer, by Cgu::SharedLockPtr, or by a
164  * std::shared_ptr implementation which has a thread-safe reference
165  * count. Alternatively, from version 2.0.11 a move_get() method is
166  * provided which will make a move operation instead of a copy if the
167  * return type implements a move constructor, but see the
168  * documentation on move_get() for the caveats with respect to its
169  * use: in particular, if move_get() is to be called by a thread, then
170  * get() may not normally be called by another thread, nor should the
171  * when() method be called.
172  *
173  * It should be noted that where the when() method is used, the return
174  * value is passed to the 'when' callback by reference to const and so
175  * without the copying carried out by the get() method: therefore, if
176  * the return value has a move assignment operator and the when()
177  * method is to be employed, and the 'when' callback only needs to
178  * call const methods of the return value, it may be more efficient
179  * not to allocate the return value on free store.
180  *
181  * This is a usage example:
182  *
183  * @code
184  * std::vector<long> get_primes(int n); // calculates the first n primes
185  *
186  * // get the first 1,000 primes
187  * using namespace Cgu;
188  *
189  * auto future = Thread::make_future([] () {return get_primes(1000);});
190  *
191  * future->run();
192  * ... [ do something else ] ...
193  * std::vector<long> result(future->move_get());
194  * std::for_each(result.begin(), result.end(), [](long l) {std::cout << l << std::endl;});
195  * @endcode
196  *
197  * The Cgu::Thread::Future::when() functions
198  * -----------------------------------------
199  *
200  * The return value of the thread function represented by
201  * Cgu::Thread::Future can be obtained asynchronously using
202  * Cgu::Thread::Future::when() to execute a function in a glib main
203  * loop when the thread function completes. The above example could
204  * be reimplemented as:
205  *
206  * @code
207  * std::vector<long> get_primes(int n); // calculates the first n primes
208  *
209  * using namespace Cgu;
210  *
211  * auto future = Thread::make_future([] () {return get_primes(1000);});
212  * future->when([](const std::vector<long>& vec) {
213  * for (const auto& elt: vec) {std::cout << elt << std::endl;}
214  * });
215  * future->run();
216  * @endcode
217  *
218  * The Cgu::Thread::Future::fail() functions
219  * -----------------------------------------
220  *
221  * The Thread::Future::when() functions have an associated optional
222  * Thread::Future::fail() function which causes a 'fail' callback to
223  * execute in a glib main loop in the event of certain exceptions
224  * arising in executing the thread function or a thread being
225  * cancelled (the documentation on Thread::Future::fail() gives
226  * further details). The 'fail' callback must be fully bound. Whilst
227  * a worker thread can pass error status to the 'fail' callback via
228  * shared data bound to both the thread function and the 'fail'
229  * callback (held by, say, a SharedLockPtr object), or a global error
230  * stack, 'fail' callbacks are generally best reserved either for use
231  * with entirely unexpected exceptions, where the most reasonable
232  * course is to perform some orderly logging and shutdown, or to
233  * report thread cancellation. For handlable exceptions, in an
234  * asynchronous environment the best course is often to catch them and
235  * deal with them in the thread function itself and return a value of
236  * the return type for the 'when' callback indicating no result.
237  */
238 
239 namespace FutureHelper {
240 
241 // the sole purpose of this struct is to enable a callback object to
242 // be constructed with Callback::make_ref() which takes an argument
243 // which can be mutated when the callback is executed. Normally this
244 // would be unsafe: however in this particular use it is fine as the
245 // callback is only ever executed once, via Future::run().
246 template <class Val>
248  mutable std::unique_ptr<const Cgu::Callback::CallbackArg<const Val&>> when;
249  // TODO: these constructors are a work-around for a bug in gcc <
250  // 4.6. At any API break where the required version of gcc is
251  // increased to gcc-4.6 or higher, remove them.
252  WhenWrapperArg(std::unique_ptr<const Cgu::Callback::CallbackArg<const Val&>>&& when_) :
253  when(std::move(when_)) {}
254  WhenWrapperArg(WhenWrapperArg&& w): when(std::move(w.when)) {}
255 };
256 
257 // the sole purpose of this struct is to enable a callback object to
258 // be constructed with Callback::make_ref() which takes an argument
259 // which can be mutated when the callback is executed. Normally this
260 // would be unsafe: however in this particular use it is fine as the
261 // callback is only ever executed once, via Future::run().
262 template <class Val>
264  mutable std::unique_ptr<Cgu::SafeEmitterArg<const Val&>> when;
265  // TODO: these constructors are a work-around for a bug in gcc <
266  // 4.6. At any API break where the required version of gcc is
267  // increased to gcc-4.6 or higher, remove them.
269  when(std::move(when_)) {}
270  WhenWrapperArgRel(WhenWrapperArgRel&& w): when(std::move(w.when)) {}
271 };
272 
273 } // namespace FutureHelper
274 
275 
276 template <class Val>
278 
279  std::unique_ptr<Cgu::Thread::Thread> thread_u;
280  std::unique_ptr<Cgu::Callback::Callback> cb_u;
281 
282  mutable Mutex mutex;
283  Cond cond;
284  Val val;
285  bool done;
286  bool running;
287  bool error;
288  bool emitter_error;
289 
290  template <class T, class Ret, class... Args>
291  void run_wrapper(T*, Ret (T::*)(Args...), const Args&...);
292 
293  template <class T, class Ret, class... Args>
294  void run_wrapper_const(const T*, Ret (T::*)(Args...) const, const Args&...);
295 
296  template <class Ret, class... Args>
297  void run_wrapper_static(Ret (*)(Args...), const Args&...);
298 
299  template <class Func>
300  void run_wrapper_functor(Func&);
301 
302  void cancel_cleanup();
303 
304  void execute_done(const std::unique_ptr<const Cgu::Callback::CallbackArg<const Val&>>&);
305  void post_done(const FutureHelper::WhenWrapperArg<Val>&,
306  gint, GMainContext*);
307  void execute_done_rel(const std::unique_ptr<Cgu::SafeEmitterArg<const Val&>>&);
308  void post_done_rel(const FutureHelper::WhenWrapperArgRel<Val>&,
309  gint, GMainContext*);
310 
311  // this is a static function taking the future object by IntrusivePtr to
312  // ensure that the future object remains in existence whilst this
313  // function might execute
314  static void fail_cb(const Cgu::IntrusivePtr<Future<Val>>& future,
315  const std::unique_ptr<const Cgu::Callback::Callback>& func,
316  bool& ret);
317 
318  // private constructor - this class can only be created with Thread::Future::make()
319  Future(): val(), done(false), running(false), error(false), emitter_error(false) {}
320 
321 public:
322 
323  // this class cannot be copied except by smart pointer
324 /**
325  * This class cannot be copied (except by smart pointer). The copy
326  * constructor is deleted.
327  */
328  Future(const Future&) = delete;
329 
330 /**
331  * This class cannot be copied (except by smart pointer). The
332  * assignment operator is deleted.
333  */
334  Future& operator=(const Future&) = delete;
335 
336 /**
337  * @deprecated
338  *
339  * DEPRECATED. Use the version of Future::make() which takes a
340  * callable object.
341  *
342  * Constructs a new Cgu::Thread::Future object (returned by
343  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
344  * Val represents the return value of the function to be represented
345  * by the new object. From version 2.0.4, it will usually be more
346  * convenient to call the Cgu::Thread::make_future() function, which
347  * is a convenience wrapper for this static method.
348  * @exception std::bad_alloc It might throw std::bad_alloc if memory
349  * is exhausted and the system throws in that case. (This exception
350  * will not be thrown if the library has been installed using the
351  * \--with-glib-memory-slices-no-compat configuration option: instead
352  * glib will terminate the program if it is unable to obtain memory
353  * from the operating system.)
354  * @exception Cgu::Thread::MutexError It might throw
355  * Cgu::Thread::MutexError if initialisation of the contained mutex
356  * fails. (It is often not worth checking for this, as it means
357  * either memory is exhausted or pthread has run out of other
358  * resources to create new mutexes.)
359  * @exception Cgu::Thread::CondError It might throw
360  * Cgu::Thread::CondError if initialisation of the contained condition
361  * variable fails. (It is often not worth checking for this, as it
362  * means either memory is exhausted or pthread has run out of other
363  * resources to create new condition variables.)
364  * @note This method will also throw if the default constructor of the
365  * return value type throws.
366  */
367  template <class Ret, class T>
369  Ret (T::*func)());
370 
371 /**
372  * @deprecated
373  *
374  * DEPRECATED. Use the version of Future::make() which takes a
375  * callable object.
376  *
377  * Constructs a new Cgu::Thread::Future object (returned by
378  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
379  * Val represents the return value of the function to be represented
380  * by the new object. From version 2.0.4, it will usually be more
381  * convenient to call the Cgu::Thread::make_future() function, which
382  * is a convenience wrapper for this static method.
383  * @exception std::bad_alloc It might throw std::bad_alloc if memory
384  * is exhausted and the system throws in that case. (This exception
385  * will not be thrown if the library has been installed using the
386  * \--with-glib-memory-slices-no-compat configuration option: instead
387  * glib will terminate the program if it is unable to obtain memory
388  * from the operating system.)
389  * @exception Cgu::Thread::MutexError It might throw
390  * Cgu::Thread::MutexError if initialisation of the contained mutex
391  * fails. (It is often not worth checking for this, as it means
392  * either memory is exhausted or pthread has run out of other
393  * resources to create new mutexes.)
394  * @exception Cgu::Thread::CondError It might throw
395  * Cgu::Thread::CondError if initialisation of the contained condition
396  * variable fails. (It is often not worth checking for this, as it
397  * means either memory is exhausted or pthread has run out of other
398  * resources to create new condition variables.)
399  * @note This method will also throw if the copy or move constructor
400  * of the bound argument throws, or the default constructor of the
401  * return value type throws.
402  */
403  template <class Ret, class Param1, class Arg1, class T>
405  Ret (T::*func)(Param1),
406  Arg1&& arg1);
407 
408 /**
409  * @deprecated
410  *
411  * DEPRECATED. Use the version of Future::make() which takes a
412  * callable object.
413  *
414  * Constructs a new Cgu::Thread::Future object (returned by
415  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
416  * Val represents the return value of the function to be represented
417  * by the new object. From version 2.0.4, it will usually be more
418  * convenient to call the Cgu::Thread::make_future() function, which
419  * is a convenience wrapper for this static method.
420  * @exception std::bad_alloc It might throw std::bad_alloc if memory
421  * is exhausted and the system throws in that case. (This exception
422  * will not be thrown if the library has been installed using the
423  * \--with-glib-memory-slices-no-compat configuration option: instead
424  * glib will terminate the program if it is unable to obtain memory
425  * from the operating system.)
426  * @exception Cgu::Thread::MutexError It might throw
427  * Cgu::Thread::MutexError if initialisation of the contained mutex
428  * fails. (It is often not worth checking for this, as it means
429  * either memory is exhausted or pthread has run out of other
430  * resources to create new mutexes.)
431  * @exception Cgu::Thread::CondError It might throw
432  * Cgu::Thread::CondError if initialisation of the contained condition
433  * variable fails. (It is often not worth checking for this, as it
434  * means either memory is exhausted or pthread has run out of other
435  * resources to create new condition variables.)
436  * @note This method will also throw if the copy or move constructor
437  * of a bound argument throws, or the default constructor of the
438  * return value type throws.
439  */
440  template <class Ret, class Param1, class Param2, class Arg1, class Arg2, class T>
442  Ret (T::*func)(Param1, Param2),
443  Arg1&& arg1,
444  Arg2&& arg2);
445 
446 /**
447  * @deprecated
448  *
449  * DEPRECATED. Use the version of Future::make() which takes a
450  * callable object.
451  *
452  * Constructs a new Cgu::Thread::Future object (returned by
453  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
454  * Val represents the return value of the function to be represented
455  * by the new object. From version 2.0.4, it will usually be more
456  * convenient to call the Cgu::Thread::make_future() function, which
457  * is a convenience wrapper for this static method.
458  * @exception std::bad_alloc It might throw std::bad_alloc if memory
459  * is exhausted and the system throws in that case. (This exception
460  * will not be thrown if the library has been installed using the
461  * \--with-glib-memory-slices-no-compat configuration option: instead
462  * glib will terminate the program if it is unable to obtain memory
463  * from the operating system.)
464  * @exception Cgu::Thread::MutexError It might throw
465  * Cgu::Thread::MutexError if initialisation of the contained mutex
466  * fails. (It is often not worth checking for this, as it means
467  * either memory is exhausted or pthread has run out of other
468  * resources to create new mutexes.)
469  * @exception Cgu::Thread::CondError It might throw
470  * Cgu::Thread::CondError if initialisation of the contained condition
471  * variable fails. (It is often not worth checking for this, as it
472  * means either memory is exhausted or pthread has run out of other
473  * resources to create new condition variables.)
474  * @note This method will also throw if the copy or move constructor
475  * of a bound argument throws, or the default constructor of the
476  * return value type throws.
477  */
478  template <class Ret, class Param1, class Param2, class Param3,
479  class Arg1, class Arg2, class Arg3, class T>
481  Ret (T::*func)(Param1, Param2, Param3),
482  Arg1&& arg1,
483  Arg2&& arg2,
484  Arg3&& arg3);
485 
486 /**
487  * @deprecated
488  *
489  * DEPRECATED. Use the version of Future::make() which takes a
490  * callable object.
491  *
492  * Constructs a new Cgu::Thread::Future object (returned by
493  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
494  * Val represents the return value of the function to be represented
495  * by the new object. From version 2.0.4, it will usually be more
496  * convenient to call the Cgu::Thread::make_future() function, which
497  * is a convenience wrapper for this static method.
498  * @exception std::bad_alloc It might throw std::bad_alloc if memory
499  * is exhausted and the system throws in that case. (This exception
500  * will not be thrown if the library has been installed using the
501  * \--with-glib-memory-slices-no-compat configuration option: instead
502  * glib will terminate the program if it is unable to obtain memory
503  * from the operating system.)
504  * @exception Cgu::Thread::MutexError It might throw
505  * Cgu::Thread::MutexError if initialisation of the contained mutex
506  * fails. (It is often not worth checking for this, as it means
507  * either memory is exhausted or pthread has run out of other
508  * resources to create new mutexes.)
509  * @exception Cgu::Thread::CondError It might throw
510  * Cgu::Thread::CondError if initialisation of the contained condition
511  * variable fails. (It is often not worth checking for this, as it
512  * means either memory is exhausted or pthread has run out of other
513  * resources to create new condition variables.)
514  * @note This method will also throw if the default constructor of the
515  * return value type throws.
516  */
517  template <class Ret, class T>
519  Ret (T::*func)() const);
520 
521 /**
522  * @deprecated
523  *
524  * DEPRECATED. Use the version of Future::make() which takes a
525  * callable object.
526  *
527  * Constructs a new Cgu::Thread::Future object (returned by
528  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
529  * Val represents the return value of the function to be represented
530  * by the new object. From version 2.0.4, it will usually be more
531  * convenient to call the Cgu::Thread::make_future() function, which
532  * is a convenience wrapper for this static method.
533  * @exception std::bad_alloc It might throw std::bad_alloc if memory
534  * is exhausted and the system throws in that case. (This exception
535  * will not be thrown if the library has been installed using the
536  * \--with-glib-memory-slices-no-compat configuration option: instead
537  * glib will terminate the program if it is unable to obtain memory
538  * from the operating system.)
539  * @exception Cgu::Thread::MutexError It might throw
540  * Cgu::Thread::MutexError if initialisation of the contained mutex
541  * fails. (It is often not worth checking for this, as it means
542  * either memory is exhausted or pthread has run out of other
543  * resources to create new mutexes.)
544  * @exception Cgu::Thread::CondError It might throw
545  * Cgu::Thread::CondError if initialisation of the contained condition
546  * variable fails. (It is often not worth checking for this, as it
547  * means either memory is exhausted or pthread has run out of other
548  * resources to create new condition variables.)
549  * @note This method will also throw if the copy or move constructor
550  * of the bound argument throws, or the default constructor of the
551  * return value type throws.
552  */
553  template <class Ret, class Param1, class Arg1, class T>
555  Ret (T::*func)(Param1) const,
556  Arg1&& arg1);
557 
558 /**
559  * @deprecated
560  *
561  * DEPRECATED. Use the version of Future::make() which takes a
562  * callable object.
563  *
564  * Constructs a new Cgu::Thread::Future object (returned by
565  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
566  * Val represents the return value of the function to be represented
567  * by the new object. From version 2.0.4, it will usually be more
568  * convenient to call the Cgu::Thread::make_future() function, which
569  * is a convenience wrapper for this static method.
570  * @exception std::bad_alloc It might throw std::bad_alloc if memory
571  * is exhausted and the system throws in that case. (This exception
572  * will not be thrown if the library has been installed using the
573  * \--with-glib-memory-slices-no-compat configuration option: instead
574  * glib will terminate the program if it is unable to obtain memory
575  * from the operating system.)
576  * @exception Cgu::Thread::MutexError It might throw
577  * Cgu::Thread::MutexError if initialisation of the contained mutex
578  * fails. (It is often not worth checking for this, as it means
579  * either memory is exhausted or pthread has run out of other
580  * resources to create new mutexes.)
581  * @exception Cgu::Thread::CondError It might throw
582  * Cgu::Thread::CondError if initialisation of the contained condition
583  * variable fails. (It is often not worth checking for this, as it
584  * means either memory is exhausted or pthread has run out of other
585  * resources to create new condition variables.)
586  * @note This method will also throw if the copy or move constructor
587  * of a bound argument throws, or the default constructor of the
588  * return value type throws.
589  */
590  template <class Ret, class Param1, class Param2, class Arg1, class Arg2, class T>
592  Ret (T::*func)(Param1, Param2) const,
593  Arg1&& arg1,
594  Arg2&& arg2);
595 
596 /**
597  * @deprecated
598  *
599  * DEPRECATED. Use the version of Future::make() which takes a
600  * callable object.
601  *
602  * Constructs a new Cgu::Thread::Future object (returned by
603  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
604  * Val represents the return value of the function to be represented
605  * by the new object. From version 2.0.4, it will usually be more
606  * convenient to call the Cgu::Thread::make_future() function, which
607  * is a convenience wrapper for this static method.
608  * @exception std::bad_alloc It might throw std::bad_alloc if memory
609  * is exhausted and the system throws in that case. (This exception
610  * will not be thrown if the library has been installed using the
611  * \--with-glib-memory-slices-no-compat configuration option: instead
612  * glib will terminate the program if it is unable to obtain memory
613  * from the operating system.)
614  * @exception Cgu::Thread::MutexError It might throw
615  * Cgu::Thread::MutexError if initialisation of the contained mutex
616  * fails. (It is often not worth checking for this, as it means
617  * either memory is exhausted or pthread has run out of other
618  * resources to create new mutexes.)
619  * @exception Cgu::Thread::CondError It might throw
620  * Cgu::Thread::CondError if initialisation of the contained condition
621  * variable fails. (It is often not worth checking for this, as it
622  * means either memory is exhausted or pthread has run out of other
623  * resources to create new condition variables.)
624  * @note This method will also throw if the copy or move constructor
625  * of a bound argument throws, or the default constructor of the
626  * return value type throws.
627  */
628  template <class Ret, class Param1, class Param2, class Param3,
629  class Arg1, class Arg2, class Arg3, class T>
631  Ret (T::*func)(Param1, Param2, Param3) const,
632  Arg1&& arg1,
633  Arg2&& arg2,
634  Arg3&& arg3);
635 
636 /**
637  * Constructs a new Cgu::Thread::Future object (returned by
638  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
639  * Val represents the return value of the function to be represented
640  * by the new object. From version 2.0.4, it will usually be more
641  * convenient to call the Cgu::Thread::make_future() function, which
642  * is a convenience wrapper for this static method.
643  * @exception std::bad_alloc It might throw std::bad_alloc if memory
644  * is exhausted and the system throws in that case. (This exception
645  * will not be thrown if the library has been installed using the
646  * \--with-glib-memory-slices-no-compat configuration option: instead
647  * glib will terminate the program if it is unable to obtain memory
648  * from the operating system.)
649  * @exception Cgu::Thread::MutexError It might throw
650  * Cgu::Thread::MutexError if initialisation of the contained mutex
651  * fails. (It is often not worth checking for this, as it means
652  * either memory is exhausted or pthread has run out of other
653  * resources to create new mutexes.)
654  * @exception Cgu::Thread::CondError It might throw
655  * Cgu::Thread::CondError if initialisation of the contained condition
656  * variable fails. (It is often not worth checking for this, as it
657  * means either memory is exhausted or pthread has run out of other
658  * resources to create new condition variables.)
659  * @note This method will also throw if the default constructor of the
660  * return value type throws.
661  */
662  template <class Ret>
663  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)());
664 
665 /**
666  * @deprecated
667  *
668  * DEPRECATED. Use the version of Future::make() which takes a
669  * callable object.
670  *
671  * Constructs a new Cgu::Thread::Future object (returned by
672  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
673  * Val represents the return value of the function to be represented
674  * by the new object. From version 2.0.4, it will usually be more
675  * convenient to call the Cgu::Thread::make_future() function, which
676  * is a convenience wrapper for this static method.
677  * @exception std::bad_alloc It might throw std::bad_alloc if memory
678  * is exhausted and the system throws in that case. (This exception
679  * will not be thrown if the library has been installed using the
680  * \--with-glib-memory-slices-no-compat configuration option: instead
681  * glib will terminate the program if it is unable to obtain memory
682  * from the operating system.)
683  * @exception Cgu::Thread::MutexError It might throw
684  * Cgu::Thread::MutexError if initialisation of the contained mutex
685  * fails. (It is often not worth checking for this, as it means
686  * either memory is exhausted or pthread has run out of other
687  * resources to create new mutexes.)
688  * @exception Cgu::Thread::CondError It might throw
689  * Cgu::Thread::CondError if initialisation of the contained condition
690  * variable fails. (It is often not worth checking for this, as it
691  * means either memory is exhausted or pthread has run out of other
692  * resources to create new condition variables.)
693  * @note This method will also throw if the copy or move constructor
694  * of the bound argument throws, or the default constructor of the
695  * return value type throws.
696  */
697  template <class Ret, class Param1, class Arg1>
698  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1),
699  Arg1&& arg1);
700 
701 /**
702  * @deprecated
703  *
704  * DEPRECATED. Use the version of Future::make() which takes a
705  * callable object.
706  *
707  * Constructs a new Cgu::Thread::Future object (returned by
708  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
709  * Val represents the return value of the function to be represented
710  * by the new object. From version 2.0.4, it will usually be more
711  * convenient to call the Cgu::Thread::make_future() function, which
712  * is a convenience wrapper for this static method.
713  * @exception std::bad_alloc It might throw std::bad_alloc if memory
714  * is exhausted and the system throws in that case. (This exception
715  * will not be thrown if the library has been installed using the
716  * \--with-glib-memory-slices-no-compat configuration option: instead
717  * glib will terminate the program if it is unable to obtain memory
718  * from the operating system.)
719  * @exception Cgu::Thread::MutexError It might throw
720  * Cgu::Thread::MutexError if initialisation of the contained mutex
721  * fails. (It is often not worth checking for this, as it means
722  * either memory is exhausted or pthread has run out of other
723  * resources to create new mutexes.)
724  * @exception Cgu::Thread::CondError It might throw
725  * Cgu::Thread::CondError if initialisation of the contained condition
726  * variable fails. (It is often not worth checking for this, as it
727  * means either memory is exhausted or pthread has run out of other
728  * resources to create new condition variables.)
729  * @note This method will also throw if the copy or move constructor
730  * of a bound argument throws, or the default constructor of the
731  * return value type throws.
732  */
733  template <class Ret, class Param1, class Param2, class Arg1, class Arg2>
734  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1, Param2),
735  Arg1&& arg1,
736  Arg2&& arg2);
737 
738 /**
739  * @deprecated
740  *
741  * DEPRECATED. Use the version of Future::make() which takes a
742  * callable object.
743  *
744  * Constructs a new Cgu::Thread::Future object (returned by
745  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
746  * Val represents the return value of the function to be represented
747  * by the new object. From version 2.0.4, it will usually be more
748  * convenient to call the Cgu::Thread::make_future() function, which
749  * is a convenience wrapper for this static method.
750  * @exception std::bad_alloc It might throw std::bad_alloc if memory
751  * is exhausted and the system throws in that case. (This exception
752  * will not be thrown if the library has been installed using the
753  * \--with-glib-memory-slices-no-compat configuration option: instead
754  * glib will terminate the program if it is unable to obtain memory
755  * from the operating system.)
756  * @exception Cgu::Thread::MutexError It might throw
757  * Cgu::Thread::MutexError if initialisation of the contained mutex
758  * fails. (It is often not worth checking for this, as it means
759  * either memory is exhausted or pthread has run out of other
760  * resources to create new mutexes.)
761  * @exception Cgu::Thread::CondError It might throw
762  * Cgu::Thread::CondError if initialisation of the contained condition
763  * variable fails. (It is often not worth checking for this, as it
764  * means either memory is exhausted or pthread has run out of other
765  * resources to create new condition variables.)
766  * @note This method will also throw if the copy or move constructor
767  * of a bound argument throws, or the default constructor of the
768  * return value type throws.
769  */
770  template <class Ret, class Param1, class Param2, class Param3,
771  class Arg1, class Arg2, class Arg3>
772  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1, Param2, Param3),
773  Arg1&& arg1,
774  Arg2&& arg2,
775  Arg3&& arg3);
776 
777 /**
778  * @deprecated
779  *
780  * DEPRECATED. Use the version of Future::make() which takes a
781  * callable object.
782  *
783  * Constructs a new Cgu::Thread::Future object (returned by
784  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
785  * Val represents the return value of the function to be represented
786  * by the new object. From version 2.0.4, it will usually be more
787  * convenient to call the Cgu::Thread::make_future() function, which
788  * is a convenience wrapper for this static method.
789  * @exception std::bad_alloc It might throw std::bad_alloc if memory
790  * is exhausted and the system throws in that case. (This exception
791  * will not be thrown if the library has been installed using the
792  * \--with-glib-memory-slices-no-compat configuration option: instead
793  * glib will terminate the program if it is unable to obtain memory
794  * from the operating system.)
795  * @exception Cgu::Thread::MutexError It might throw
796  * Cgu::Thread::MutexError if initialisation of the contained mutex
797  * fails. (It is often not worth checking for this, as it means
798  * either memory is exhausted or pthread has run out of other
799  * resources to create new mutexes.)
800  * @exception Cgu::Thread::CondError It might throw
801  * Cgu::Thread::CondError if initialisation of the contained condition
802  * variable fails. (It is often not worth checking for this, as it
803  * means either memory is exhausted or pthread has run out of other
804  * resources to create new condition variables.)
805  * @note This method will also throw if the copy or move constructor
806  * of a bound argument throws, or the default constructor of the
807  * return value type throws.
808  */
809  template <class Ret, class Param1, class Param2, class Param3, class Param4,
810  class Arg1, class Arg2, class Arg3, class Arg4>
811  static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1, Param2, Param3, Param4),
812  Arg1&& arg1,
813  Arg2&& arg2,
814  Arg3&& arg3,
815  Arg4&& arg4);
816 
817 /**
818  * Constructs a new Cgu::Thread::Future object (returned by
819  * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter
820  * Val represents the return value of the function to be represented
821  * by the new object. It will usually be more convenient to call the
822  * Cgu::Thread::make_future() function, which is a convenience wrapper
823  * for this static method.
824  * @param func A callable object, such as formed by a lambda
825  * expression or the result of std::bind. It must be fully bound
826  * (that is, its must take no arguments when called). It should
827  * return the Val type.
828  * @exception std::bad_alloc It might throw std::bad_alloc if memory
829  * is exhausted and the system throws in that case. (This exception
830  * will not be thrown if the library has been installed using the
831  * \--with-glib-memory-slices-no-compat configuration option: instead
832  * glib will terminate the program if it is unable to obtain memory
833  * from the operating system.)
834  * @exception Cgu::Thread::MutexError It might throw
835  * Cgu::Thread::MutexError if initialisation of the contained mutex
836  * fails. (It is often not worth checking for this, as it means
837  * either memory is exhausted or pthread has run out of other
838  * resources to create new mutexes.)
839  * @exception Cgu::Thread::CondError It might throw
840  * Cgu::Thread::CondError if initialisation of the contained condition
841  * variable fails. (It is often not worth checking for this, as it
842  * means either memory is exhausted or pthread has run out of other
843  * resources to create new condition variables.)
844  * @note 1. This method will also throw if the copy or move
845  * constructor of the callable object passed as an argument throws, or
846  * the default constructor of the return value type throws.
847  * @note 2. If the callable object passed as an argument has both
848  * const and non-const operator()() methods, the non-const version
849  * will be called even if the callable object passed is a const
850  * object.
851  *
852  * Since 2.0.14
853  */
854  template <class Func>
856 
857 /**
858  * Runs the function or callable object represented by this
859  * Cgu::Thread::Future object in a new worker thread. That function
860  * will only be run once. If this is the first time this method has
861  * been called, it will start the worker thread and return true, and
862  * if it has previously been called, this method will do nothing and
863  * return false. This method will not wait for the worker thread to
864  * complete before returning. This method is thread safe and may be
865  * called by a different thread from the one which called make().
866  * @return true if this is the first time this method has been called,
867  * or false if this method has previously been called.
868  * @exception Cgu::Thread::FutureThreadError This method might throw
869  * Cgu::Thread::FutureThreadError if it has not previously been called
870  * and the thread did not start properly. If it does throw, this
871  * Cgu::Thread::Future object is defunct and further attempts to call
872  * this method will return immediately with a false value. (It is
873  * often not worth checking for this exception, as it means either
874  * memory is exhausted, the pthread thread limit has been reached or
875  * pthread has run out of other resources to start new threads.)
876  * @exception std::bad_alloc This method might throw std::bad_alloc if
877  * it has not previously been called, and memory is exhausted and the
878  * system throws in that case. If it does throw, this
879  * Cgu::Thread::Future object is defunct and further attempts to call
880  * this method will return immediately with a false value. (This
881  * exception will not be thrown if the library has been installed
882  * using the \--with-glib-memory-slices-no-compat configuration
883  * option: instead glib will terminate the program if it is unable to
884  * obtain memory from the operating system.)
885  * @note 1. Any Cgu::Thread::Exit exception, or any uncaught exception
886  * derived from std::exception, which is thrown from the worker thread
887  * will be caught and consumed and the error flag will be set. The
888  * worker thread will safely terminate and unwind the stack in so
889  * doing.
890  * @note 2. As this wrapper class can provide error reporting in a way
891  * that Cgu::Thread::Thread of itself cannot, it would be desirable to
892  * consume any other uncaught exceptions. However, this cannot be
893  * done: annoyingly, NPTL's forced stack unwinding does not allow this
894  * if thread cancellation is to be made available. If an uncaught
895  * exception propagates out of a thread when the thread exits, the
896  * C++11/14 standard will cause std::terminate() to be called and so
897  * terminate the entire program. Accordingly, a user must make sure
898  * that no exceptions, other than Cgu::Thread::Exit or those derived
899  * from std::exception or any cancellation pseudo-exception, can
900  * propagate from the function which this Cgu::Thread::Future object
901  * represents, nor from the copy constructor of any argument type that
902  * that function takes by value nor from the move assignment operator
903  * (or if none, copy assignment operator) of the return value of that
904  * function.
905  * @note 3. If the worker thread is cancelled by a call to cancel()
906  * while in the middle of executing the function which this
907  * Cgu::Thread::Future object represents, the error flag will be set.
908  */
909  bool run();
910 
911 /**
912  * Gets the stored value obtained from the function or callable object
913  * which is represented by this object. If the worker thread launched
914  * by the call to run() has not completed, then this method will block
915  * until it has completed. If run() has not been called, then run()
916  * will be called (and this method will block until the launched
917  * worker thread completes). If the function or callable object which
918  * is represented by this Cgu::Thread::Future object throws
919  * Cgu::Thread::Exit or an uncaught exception derived from
920  * std::exception, or if any of those exceptions are thrown either by
921  * the copy constructor of an argument taken by value by that function
922  * or object, or by the move assignment operator (or if none, copy
923  * assignment operator) of the return value of that function or
924  * object, then the exception will have been consumed by this
925  * Cgu::Thread::Future object and the error flag will have been set.
926  * The error flag will also have been set if the worker thread is
927  * cancelled or the thread wrapper in this Cgu::Thread::Future object
928  * threw std::bad_alloc. On the error flag being set, this method
929  * will unblock and return a default constructed object of the return
930  * type. This method is thread safe and may be called by any thread
931  * (and by more than one thread). It is a cancellation point if it
932  * blocks, and from version 2.0.11 is cancellation safe if the stack
933  * unwinds on cancellation. It is also strongly exception safe: no
934  * data will be lost if extracting the value fails.
935  * @return The value obtained from the function which is represented
936  * by this object, or a default constructed object of the return type
937  * if the error flag has been set.
938  * @exception Cgu::Thread::FutureThreadError This method might throw
939  * Cgu::Thread::FutureThreadError if run() has not previously been
940  * called and the thread did not start properly when this function
941  * called run().
942  * @exception std::bad_alloc This method might throw std::bad_alloc if
943  * run() has not previously been called, memory is exhausted and the
944  * system throws in that case. (This exception will not be thrown if
945  * the library has been installed using the
946  * \--with-glib-memory-slices-no-compat configuration option: instead
947  * glib will terminate the program if it is unable to obtain memory
948  * from the operating system.)
949  * @note 1. This method might also throw if the copy constructor of
950  * the returned value type throws.
951  * @note 2. This method calls Thread::Cond::wait(). Between versions
952  * 2.2.3 and 2.2.13 inclusive, Thread::Cond::wait() was marked
953  * 'noexcept'. This was a mistake because it prevented a thread being
954  * cancelled while in a wait, including in this method (the
955  * cancellation pseudo-exception conflicted with the noexcept
956  * specifier). This was fixed in version 2.2.14.
957  * @note 3. Question: Couldn't this method return the stored value by
958  * lvalue reference to const? Answer: It could. However, because of
959  * return value optimization, which will be implemented by any
960  * compiler capable of compiling this library, no advantage would be
961  * gained by doing so when initializing a local variable with the
962  * return value of this method (the copy constructor will only be
963  * called once whether returning by value or const reference). The
964  * advantage of returning by value is that the call to the copy
965  * constructor is forced to be within this Thread::Future object's
966  * mutex, so different threads' calls to the copy constructor are
967  * serialized, and also with blocked cancellation, so this method is
968  * cancellation safe. All calls to this method by different threads
969  * are therefore isolated and we do not have to worry about the thread
970  * safety of direct access to the stored value via its const methods
971  * outside the mutex (which would not be thread safe if the stored
972  * value has data members declared mutable) nor about the cancellation
973  * safety of the copy constructor. Of course, for objects which do
974  * not have mutable data, a hit arises by returning by value in cases
975  * where it is not intended to initialize a local variable at all nor
976  * to cancel a thread: where, say, only const methods are to be called
977  * on the return value (which could be done directly if this method
978  * returned by const reference). However, in many use cases this will
979  * be mitigated by the move_get() method.
980  */
981  Val get();
982 
983 /**
984  * Gets the stored value obtained from the function or callable object
985  * which is represented by this object by a move operation, if the
986  * return type implements a move constructor (otherwise this method
987  * does the same as the get() method). It is provided as an option
988  * for cases where a move is required for efficiency reasons, but
989  * although it may be called by any thread, a move from this
990  * Thread::Future object may normally only be made once (except where
991  * the return type has been designed to be moved more than once for
992  * the limited purpose of inspecting a flag indicating whether its
993  * value is valid or not). If this method is to be called then no
994  * calls to get() by another thread should normally be made and no
995  * calls to when() should be made. If the worker thread launched by
996  * the call to run() has not completed, then this method will block
997  * until it has completed. If run() has not been called, then run()
998  * will be called (and this method will block until the launched
999  * worker thread completes). If the function or callable object which
1000  * is represented by this Cgu::Thread::Future object throws
1001  * Cgu::Thread::Exit or an uncaught exception derived from
1002  * std::exception, or if any of those exceptions are thrown either by
1003  * the copy constructor of an argument taken by value by that function
1004  * or object, or by the move assignment operator (or if none, copy
1005  * assignment operator) of the return value of that function or
1006  * object, then the exception will have been consumed by this
1007  * Cgu::Thread::Future object and the error flag will have been set.
1008  * The error flag will also have been set if the worker thread is
1009  * cancelled or the thread wrapper in this Cgu::Thread::Future object
1010  * threw std::bad_alloc. On the error flag being set, this method
1011  * will unblock and return a default constructed object of the return
1012  * type. This method is a cancellation point if it blocks, and is
1013  * cancellation safe if the stack unwinds on cancellation. This
1014  * method is only exception safe if the return type's move constructor
1015  * is exception safe.
1016  * @return The value obtained from the function which is represented
1017  * by this object, or a default constructed object of the return type
1018  * if the error flag has been set.
1019  * @exception Cgu::Thread::FutureThreadError This method might throw
1020  * Cgu::Thread::FutureThreadError if run() has not previously been
1021  * called and the thread did not start properly when this function
1022  * called run().
1023  * @exception std::bad_alloc This method might throw std::bad_alloc if
1024  * run() has not previously been called, memory is exhausted and the
1025  * system throws in that case. (This exception will not be thrown if
1026  * the library has been installed using the
1027  * \--with-glib-memory-slices-no-compat configuration option: instead
1028  * glib will terminate the program if it is unable to obtain memory
1029  * from the operating system.)
1030  * @note 1. This method might also throw if the copy or move
1031  * constructor of the returned value type throws.
1032  * @note 2. This method calls Thread::Cond::wait(). Between versions
1033  * 2.2.3 and 2.2.13 inclusive, Thread::Cond::wait() was marked
1034  * 'noexcept'. This was a mistake because it prevented a thread being
1035  * cancelled while in a wait, including in this method (the
1036  * cancellation pseudo-exception conflicted with the noexcept
1037  * specifier). This was fixed in version 2.2.14.
1038  * @note 3. Question: Couldn't this method return the stored value by
1039  * rvalue reference? Answer: It could. However, because of return
1040  * value optimization, which will be implemented by any compiler
1041  * capable of compiling this library, no advantage would be gained by
1042  * doing so when initializing a local variable with the return value
1043  * of this method (the move constructor will only be called once, and
1044  * no call will be made to the copy constructor, whether returning by
1045  * value or rvalue reference). The advantage of returning by value is
1046  * that the call to the move constructor is forced to be within this
1047  * Thread::Future object's mutex, so different threads' calls to the
1048  * move constructor are serialized, and also with blocked
1049  * cancellation, so this method is cancellation safe. All calls to
1050  * this method by different threads are therefore isolated and we do
1051  * not have to worry about the thread safety of the mutating first
1052  * call to this method, nor about direct access to the stored value
1053  * via a rvalue reference outside the mutex nor the cancellation
1054  * safety of the move constructor.
1055  *
1056  * Since 2.0.11
1057  */
1058  Val move_get();
1059 
1060 /**
1061  * Cancels the worker thread in which the function or callable object
1062  * represented by this object runs, if it has not yet finished. If
1063  * this method is called and the worker thread is still running and is
1064  * cancelled in response to a call to this method, then the error flag
1065  * will be set so that a method calling get() or move_get() can
1066  * examine whether the result is valid. If run() has not yet been
1067  * called or the worker thread has already finished executing the
1068  * function or callable object represented by this object then this
1069  * function does nothing and returns false. This method is thread
1070  * safe and may be called by any thread. It will not throw.
1071  * @return true if run() has previously been called and the worker
1072  * thread has not yet finished executing the function or callable
1073  * object represented by this object, otherwise false (in which case
1074  * this method does nothing).
1075  * @note 1. Use this method with care. When cancelling a thread not
1076  * all thread implementations will unwind the stack, and so run the
1077  * destructors of local objects. This is discussed further in the
1078  * documentation on Cgu::Thread::Thread::cancel().
1079  * @note 2. This method might return true because the worker thread
1080  * has not yet finished, but the error flag might still not be set.
1081  * This is because the worker thread may not meet a cancellation point
1082  * before it ends naturally. It is the error flag which indicates
1083  * definitively whether the worker thread terminated prematurely in
1084  * response to a call to this method.
1085  */
1086  bool cancel() noexcept;
1087 
1088 /**
1089  * A utility enabling the value returned by the thread function
1090  * represented by this Cgu::Thread::Future object to be dealt with
1091  * asynchronously rather than by (or in addition to) a call to the
1092  * get() method. It causes the callback passed as an argument to this
1093  * method (referred to below as the 'when' callback) to be executed by
1094  * a thread's main loop if and when the thread function represented by
1095  * this Cgu::Thread::Future object finishes correctly - the 'when'
1096  * callback is passed that thread function's return value when it is
1097  * invoked. This method is thread safe, and may be called by any
1098  * thread.
1099  *
1100  * This functionality is implemented by connecting an internal
1101  * dispatching callback to the done_emitter object.
1102  *
1103  * The 'when' callback should take a single unbound argument
1104  * comprising a const reference to the return type of the thread
1105  * function represented by this Cgu::Thread::Future object. (So, in
1106  * the case of a Future<int> object, the callback function should take
1107  * a const int& argument as the unbound argument.) The 'when'
1108  * callback can have any number of bound arguments, except that a
1109  * bound argument may not include a copy of this Cgu::Thread::Future
1110  * object held by intrusive pointer as returned by the make() methods
1111  * (that would result in this Cgu::Thread::Future object owning, via
1112  * done_emitter, a reference to itself and so become incapable of
1113  * being freed). The 'when' callback may, however, take a pointer to
1114  * this Cgu::Thread::Future object, as obtained by the
1115  * Cgu::IntrusivePtr::get() method, because this Cgu::Thread::Future
1116  * object is guaranteed to remain in existence until the callback has
1117  * completed executing.
1118  *
1119  * This method cannot be called after the thread function represented
1120  * by this Cgu::Thread::Future object has completed (either
1121  * successfully or unsuccessfully) so that is_done() would return
1122  * true, and if this is attempted a Cgu::Thread::FutureWhenError
1123  * exception will be thrown. Therefore, generally this method should
1124  * be called before the run() method has been called.
1125  *
1126  * Once the run() method has been called, this Cgu::Thread::Future
1127  * object will always stay in existence until the thread function
1128  * represented by it has completed (whether correctly, by cancellation
1129  * or by a thrown exception), and any 'when' callback (and any other
1130  * callbacks connected to the done_emitter object) and any 'fail'
1131  * callback have completed. Accordingly it is safe to use this method
1132  * even if the intrusive pointer object returned by the make() methods
1133  * will go out of scope before the 'when' callback has executed: the
1134  * callback will execute correctly irrespective of that.
1135  *
1136  * Summary: use of this method is safe and has been implemented in a
1137  * way which does not give rise to timing issues.
1138  *
1139  * If memory is exhausted and std::bad_alloc is thrown by the thread
1140  * wrapper of Cgu::Thread::Future after run() is called or by
1141  * done_emitter when emitting, or if the thread function represented
1142  * by this Cgu::Thread::Future object throws Cgu::Thread::Exit, is
1143  * cancelled, exits with an uncaught exception deriving from
1144  * std::exception, takes an argument by value whose copy constructor
1145  * throws such an exception or has a return value whose move
1146  * assignment operator (or if none, copy assignment operator) throws
1147  * such an exception, or if the 'when' callback represents a function
1148  * taking a non-reference argument whose copy constructor throws an
1149  * exception, or if any other callback has been connected to
1150  * done_emitter before this method is called which exits with an
1151  * uncaught exception, then the 'when' callback will not execute
1152  * (instead the exception concerned will be consumed and an error
1153  * indicated). With many systems, swap memory combined with memory
1154  * over-commit makes it pointless to check for std::bad_alloc (and
1155  * even more so in programs using glib, as glib aborts a program where
1156  * it cannot obtain memory from the operating system). So subject to
1157  * that, if the user program is designed so that the thread function
1158  * represented by this Cgu::Thread::Future object does not exit with
1159  * uncaught exceptions, does not take an argument by value which
1160  * throws, does not have a return value whose move assignment operator
1161  * (or if none, copy assignment operator) throws, does not throw
1162  * Cgu::Thread::Exit and is not cancelled, and so that the 'when'
1163  * callback does not exit with an uncaught exception (and a function
1164  * represented by that callback either takes no arguments of class
1165  * type by value or the copy constructors of any of its value
1166  * arguments do not throw), and if this method is called before any
1167  * other callbacks are connected to done_emitter, the possibility of
1168  * failure can be disregarded.
1169  *
1170  * In cases where that is not true and detecting whether a failure has
1171  * occurred is required, a fail() method is provided. It should be
1172  * noted that a callback handed to the fail() method will not execute
1173  * in a case of error if the error comprises the 'when' callback
1174  * exiting with an uncaught exception when it is executed by the main
1175  * loop, or the copy constructor of any value argument of a function
1176  * represented by the 'when' callback throwing (such exceptions would
1177  * be consumed internally in order to protect the main loop and a
1178  * g_critical message issued). If the 'when' callback might exit with
1179  * an uncaught exception when executing or have the copy constructor
1180  * of a value argument throw, and doing something other than consuming
1181  * the exception and issuing a g_critical message is required, then a
1182  * different approach is to start a new thread to wait on the get()
1183  * method which can act on the result of is_error() directly.
1184  *
1185  * If glib < 2.32 is used, the glib main loop must have been made
1186  * thread-safe by a call to g_thread_init() before this function is
1187  * called. glib >= 2.32 does not require g_thread_init() to be called
1188  * in order to be thread safe.
1189  *
1190  * @param cb The 'when' callback (the callback to be executed when the
1191  * function represented by this Cgu::Thread::Future object has
1192  * successfully completed). Ownership is taken of this object, and it
1193  * will be deleted when it has been finished with.
1194  * @param priority The priority to be given to the 'when' callback in
1195  * the main loop after the thread function represented by this
1196  * Cgu::Thread::Future object has successfully completed. In
1197  * ascending order of priorities, priorities are G_PRIORITY_LOW,
1198  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
1199  * and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT. This
1200  * determines the order in which the callback will appear in the event
1201  * list in the main loop, not the priority which the OS will adopt.
1202  * @param context The glib main context of the thread in whose main
1203  * loop the 'when' callback is to be executed (the default of NULL
1204  * will cause the callback to be executed in the main program loop).
1205  * @return The internal dispatching callback created by this method
1206  * and connected to done_emitter. It is made available as a return
1207  * value so that if wanted it can be disconnected programmatically
1208  * from done_emitter, or block()/unblock() can be called on it (but if
1209  * that is to be done, it must be done before the thread function
1210  * represented by this Cgu::Thread::Future object has completed in
1211  * order for it to be effective).
1212  * @exception Cgu::Thread::FutureWhenError This method will throw
1213  * Cgu::Thread::FutureWhenError if it is called after the thread
1214  * function represented by this Cgu::Thread::Future object has
1215  * completed. If it does so, the 'when' callback will be disposed of.
1216  * @exception std::bad_alloc This method might throw std::bad_alloc if
1217  * memory is exhausted and the system throws in that case. If it does
1218  * so, the 'when' callback will be disposed of.
1219  * @note The return value of the function represented by this
1220  * Cgu::Thread::Future object is stored and passed as an argument to
1221  * the 'when' callback by const reference. If other threads might
1222  * concurrently call this object's get() method, which copies the
1223  * stored value, the stored type's copy constructor must be thread
1224  * safe with respect to the stored type's const methods. This would
1225  * be relevant if the stored type has data members declared mutable
1226  * which would be copied by its copy constructor.
1227  *
1228  * Since 2.0.2
1229  */
1231  gint priority = G_PRIORITY_DEFAULT,
1232  GMainContext* context = 0);
1233 
1234 /**
1235  * A utility enabling the value returned by the thread function
1236  * represented by this Cgu::Thread::Future object to be dealt with
1237  * asynchronously rather than by (or in addition to) a call to the
1238  * get() method. It causes the callable object passed as an argument
1239  * to this method (referred to below as the 'when' callback) to be
1240  * executed by a thread's main loop if and when the thread function
1241  * represented by this Cgu::Thread::Future object finishes correctly -
1242  * the 'when' callback is passed that thread function's return value
1243  * when it is invoked. This method is thread safe, and may be called
1244  * by any thread.
1245  *
1246  * This functionality is implemented by connecting an internal
1247  * dispatching callback to the done_emitter object.
1248  *
1249  * The 'when' callback should take a single unbound argument
1250  * comprising a const reference to the return type of the thread
1251  * function represented by this Cgu::Thread::Future object. (So, in
1252  * the case of a Future<int> object, the callback function should take
1253  * a const int& argument as the unbound argument.) The 'when'
1254  * callback can have any number of bound arguments, except that a
1255  * bound argument may not include a copy of this Cgu::Thread::Future
1256  * object held by intrusive pointer as returned by the make() methods
1257  * (that would result in this Cgu::Thread::Future object owning, via
1258  * done_emitter, a reference to itself and so become incapable of
1259  * being freed). The 'when' callback may, however, take a pointer to
1260  * this Cgu::Thread::Future object, as obtained by the
1261  * Cgu::IntrusivePtr::get() method, because this Cgu::Thread::Future
1262  * object is guaranteed to remain in existence until the callback has
1263  * completed executing.
1264  *
1265  * This method cannot be called after the thread function represented
1266  * by this Cgu::Thread::Future object has completed (either
1267  * successfully or unsuccessfully) so that is_done() would return
1268  * true, and if this is attempted a Cgu::Thread::FutureWhenError
1269  * exception will be thrown. Therefore, generally this method should
1270  * be called before the run() method has been called.
1271  *
1272  * Once the run() method has been called, this Cgu::Thread::Future
1273  * object will always stay in existence until the thread function
1274  * represented by it has completed (whether correctly, by cancellation
1275  * or by a thrown exception), and any 'when' callback (and any other
1276  * callbacks connected to the done_emitter object) and any 'fail'
1277  * callback have completed. Accordingly it is safe to use this method
1278  * even if the intrusive pointer object returned by the make() methods
1279  * will go out of scope before the 'when' callback has executed: the
1280  * callback will execute correctly irrespective of that.
1281  *
1282  * Summary: use of this method is safe and has been implemented in a
1283  * way which does not give rise to timing issues.
1284  *
1285  * If memory is exhausted and std::bad_alloc is thrown by the thread
1286  * wrapper of Cgu::Thread::Future after run() is called or by
1287  * done_emitter when emitting, or if the thread function represented
1288  * by this Cgu::Thread::Future object throws Cgu::Thread::Exit, is
1289  * cancelled, exits with an uncaught exception deriving from
1290  * std::exception, takes an argument by value whose copy constructor
1291  * throws such an exception or has a return value whose move
1292  * assignment operator (or if none, copy assignment operator) throws
1293  * such an exception, or if any other callback has been connected to
1294  * done_emitter before this method is called which exits with an
1295  * uncaught exception, then the 'when' callback will not execute
1296  * (instead the exception concerned will be consumed and an error
1297  * indicated). With many systems, swap memory combined with memory
1298  * over-commit makes it pointless to check for std::bad_alloc (and
1299  * even more so in programs using glib, as glib aborts a program where
1300  * it cannot obtain memory from the operating system). So subject to
1301  * that, if the user program is designed so that the thread function
1302  * represented by this Cgu::Thread::Future object does not exit with
1303  * uncaught exceptions, does not take an argument by value which
1304  * throws, does not have a return value whose move assignment operator
1305  * (or if none, copy assignment operator) throws, does not throw
1306  * Cgu::Thread::Exit and is not cancelled, and so that the 'when'
1307  * callback does not exit with an uncaught exception, and if this
1308  * method is called before any other callbacks are connected to
1309  * done_emitter, the possibility of failure can be disregarded.
1310  *
1311  * In cases where that is not true and detecting whether a failure has
1312  * occurred is required, a fail() method is provided. It should be
1313  * noted that a callback handed to the fail() method will not execute
1314  * in a case of error if the error comprises the 'when' callback
1315  * exiting with an uncaught exception when it is executed by the main
1316  * loop (such exceptions would be consumed internally in order to
1317  * protect the main loop and a g_critical message issued). If the
1318  * 'when' callback might exit with an uncaught exception when
1319  * executing, and doing something other than consuming the exception
1320  * and issuing a g_critical message is required, then a different
1321  * approach is to start a new thread to wait on the get() method which
1322  * can act on the result of is_error() directly.
1323  *
1324  * If glib < 2.32 is used, the glib main loop must have been made
1325  * thread-safe by a call to g_thread_init() before this function is
1326  * called. glib >= 2.32 does not require g_thread_init() to be called
1327  * in order to be thread safe.
1328  *
1329  * @param w A callable object (such as formed by a lambda expression
1330  * or the result of std::bind) representing the 'when' callback (the
1331  * callback to be executed when the function represented by this
1332  * Cgu::Thread::Future object has successfully completed). It should
1333  * take a single unbound argument, namely a reference to const to the
1334  * return type of the thread function represented by this
1335  * Cgu::Thread::Future object.
1336  * @param priority The priority to be given to the 'when' callback in
1337  * the main loop after the thread function represented by this
1338  * Cgu::Thread::Future object has successfully completed. In
1339  * ascending order of priorities, priorities are G_PRIORITY_LOW,
1340  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
1341  * and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT. This
1342  * determines the order in which the callback will appear in the event
1343  * list in the main loop, not the priority which the OS will adopt.
1344  * @param context The glib main context of the thread in whose main
1345  * loop the 'when' callback is to be executed (the default of NULL
1346  * will cause the callback to be executed in the main program loop).
1347  * @return The internal dispatching callback created by this method
1348  * and connected to done_emitter. It is made available as a return
1349  * value so that if wanted it can be disconnected programmatically
1350  * from done_emitter, or block()/unblock() can be called on it (but if
1351  * that is to be done, it must be done before the thread function
1352  * represented by this Cgu::Thread::Future object has completed in
1353  * order for it to be effective).
1354  * @exception Cgu::Thread::FutureWhenError This method will throw
1355  * Cgu::Thread::FutureWhenError if it is called after the thread
1356  * function represented by this Cgu::Thread::Future object has
1357  * completed.
1358  * @exception std::bad_alloc This method might throw std::bad_alloc if
1359  * memory is exhausted and the system throws in that case.
1360  * @note 1. This method will also throw if the copy or move
1361  * constructor of the 'when' callable object throws.
1362  * @note 2. The return value of the function represented by this
1363  * Cgu::Thread::Future object is stored and passed as an argument to
1364  * the 'when' callback by const reference. If other threads might
1365  * concurrently call this object's get() method, which copies the
1366  * stored value, the stored type's copy constructor must be thread
1367  * safe with respect to the stored type's const methods. This would
1368  * be relevant if the stored type has data members declared mutable
1369  * which would be copied by its copy constructor.
1370  *
1371  * Since 2.1.0
1372  */
1373  // we need to use enable_if so that where this function is passed a
1374  // pointer to non-const Callback::CallbackArg, or some other
1375  // convertible pointer, this templated overload is dropped from the
1376  // overload set, in order to support the Callback::CallbackArg
1377  // overloads of this function. This overload calls into the version
1378  // of this function taking a pointer to const Callback::CallbackArg
1379  // in order to perform type erasure.
1380  template <class When,
1381  class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<When>::type,
1382  const Cgu::Callback::CallbackArg<const Val&>*>::value>::type>
1384  gint priority = G_PRIORITY_DEFAULT,
1385  GMainContext* context = 0) {
1386  return when(Callback::lambda<const Val&>(std::forward<When>(w)),
1387  priority,
1388  context);
1389  }
1390 
1391 /**
1392  * This is a version of the utility enabling the value returned by the
1393  * thread function represented by this Cgu::Thread::Future object to
1394  * be dealt with asynchronously, which takes a Releaser object for
1395  * automatic disconnection of the callback passed as an argument to
1396  * this method (referred to below as the 'when' callback), if the
1397  * object having the 'when' callback function as a member is
1398  * destroyed. For this to be race free, the lifetime of that object
1399  * must be controlled by the thread in whose main loop the 'when'
1400  * callback will execute.
1401  *
1402  * If the 'when' callback has not been released, this method causes it
1403  * to be executed by a thread's main loop if and when the thread
1404  * function represented by this Cgu::Thread::Future object finishes
1405  * correctly - the 'when' callback is passed that thread function's
1406  * return value when it is invoked. This method is thread safe, and
1407  * may be called by any thread.
1408  *
1409  * This functionality is implemented by connecting an internal
1410  * dispatching callback to the done_emitter object.
1411  *
1412  * The 'when' callback should take a single unbound argument
1413  * comprising a const reference to the return type of the thread
1414  * function represented by this Cgu::Thread::Future object. (So, in
1415  * the case of a Future<int> object, the callback function should take
1416  * a const int& argument as the unbound argument.) The 'when'
1417  * callback can have any number of bound arguments, except that a
1418  * bound argument may not include a copy of this Cgu::Thread::Future
1419  * object held by intrusive pointer as returned by the make() methods
1420  * (that would result in this Cgu::Thread::Future object owning, via
1421  * done_emitter, a reference to itself and so become incapable of
1422  * being freed). The 'when' callback may, however, take a pointer to
1423  * this Cgu::Thread::Future object, as obtained by the
1424  * Cgu::IntrusivePtr::get() method, because this Cgu::Thread::Future
1425  * object is guaranteed to remain in existence until the callback has
1426  * completed executing.
1427  *
1428  * This method cannot be called after the thread function represented
1429  * by this Cgu::Thread::Future object has completed (either
1430  * successfully or unsuccessfully) so that is_done() would return
1431  * true, and if this is attempted a Cgu::Thread::FutureWhenError
1432  * exception will be thrown. Therefore, generally this method should
1433  * be called before the run() method has been called.
1434  *
1435  * The documentation for the version of this method which does not
1436  * take a Releaser object gives further details of how this method is
1437  * used.
1438  *
1439  * If glib < 2.32 is used, the glib main loop must have been made
1440  * thread-safe by a call to g_thread_init() before this function is
1441  * called. glib >= 2.32 does not require g_thread_init() to be called
1442  * in order to be thread safe.
1443  *
1444  * @param cb The 'when' callback (the callback to be executed when the
1445  * function represented by this Cgu::Thread::Future object has
1446  * successfully completed). Ownership is taken of this object, and it
1447  * will be deleted when it has been finished with.
1448  * @param r A Releaser object for automatic disconnection of the
1449  * 'when' callback before it executes in a main loop (mainly relevant
1450  * if the callback represents a non-static member function of an
1451  * object which may be destroyed before the callback executes).
1452  * @param priority The priority to be given to the 'when' callback in
1453  * the main loop after the thread function represented by this
1454  * Cgu::Thread::Future object has successfully completed. In
1455  * ascending order of priorities, priorities are G_PRIORITY_LOW,
1456  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
1457  * and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT. This
1458  * determines the order in which the callback will appear in the event
1459  * list in the main loop, not the priority which the OS will adopt.
1460  * @param context The glib main context of the thread in whose main
1461  * loop the 'when' callback is to be executed (the default of NULL
1462  * will cause the callback to be executed in the main program loop).
1463  * @return The internal dispatching callback created by this method
1464  * and connected to done_emitter. It is made available as a return
1465  * value so that if wanted it can be disconnected programmatically
1466  * from done_emitter, or block()/unblock() can be called on it (but if
1467  * that is to be done, it must be done before the thread function
1468  * represented by this Cgu::Thread::Future object has completed in
1469  * order for it to be effective).
1470  * @exception Cgu::Thread::FutureWhenError This method will throw
1471  * Cgu::Thread::FutureWhenError if it is called after the thread
1472  * function represented by this Cgu::Thread::Future object has
1473  * completed. If it does so, the 'when' callback will be disposed of.
1474  * @exception std::bad_alloc This method might throw std::bad_alloc if
1475  * memory is exhausted and the system throws in that case. If it does
1476  * so, the 'when' callback will be disposed of.
1477  * @exception Cgu::Thread::MutexError This method will throw
1478  * Cgu:Thread::MutexError if initialisation of the mutex in a
1479  * SafeEmitterArg object constructed by this method fails. If it does
1480  * so, the 'when' callback will be disposed of. (It is often not
1481  * worth checking for this, as it means either memory is exhausted or
1482  * pthread has run out of other resources to create new mutexes.)
1483  * @note 1. The return value of the function represented by this
1484  * Cgu::Thread::Future object is stored and passed as an argument to
1485  * the 'when' callback by const reference. If other threads might
1486  * concurrently call this object's get() method, which copies the
1487  * stored value, the stored type's copy constructor must be thread
1488  * safe with respect to the stored type's const methods. This would
1489  * be relevant if the stored type has data members declared mutable
1490  * which would be copied by its copy constructor.
1491  * @note 2. By virtue of the Releaser object, it is in theory possible
1492  * (if memory is exhausted and the system throws in that case) that an
1493  * internal SafeEmitterArg object will throw std::bad_alloc when
1494  * emitting/executing the 'when' callback in the glib main loop, with
1495  * the result that the relevant callback will not execute (instead the
1496  * exception will be consumed and a g_critical() warning will be
1497  * issued). This is rarely of any relevance because glib will abort
1498  * the program if it is itself unable to obtain memory from the
1499  * operating system. However, where it is relevant, design the
1500  * program so that it is not necessary to provide a releaser object.
1501  *
1502  * Since 2.0.2
1503  */
1505  Cgu::Releaser& r,
1506  gint priority = G_PRIORITY_DEFAULT,
1507  GMainContext* context = 0);
1508 
1509 /**
1510  * This is a version of the utility enabling the value returned by the
1511  * thread function represented by this Cgu::Thread::Future object to
1512  * be dealt with asynchronously, which takes a Releaser object for
1513  * automatic disconnection of the callable object passed as an
1514  * argument to this method (referred to below as the 'when' callback),
1515  * if the 'when' callback represents or calls into an object which is
1516  * destroyed. For this to be race free, the lifetime of the object
1517  * called into must be controlled by the thread in whose main loop the
1518  * 'when' callback will execute.
1519  *
1520  * If the 'when' callback has not been released, this method causes it
1521  * to be executed by a thread's main loop if and when the thread
1522  * function represented by this Cgu::Thread::Future object finishes
1523  * correctly - the 'when' callback is passed that thread function's
1524  * return value when it is invoked. This method is thread safe, and
1525  * may be called by any thread.
1526  *
1527  * This functionality is implemented by connecting an internal
1528  * dispatching callback to the done_emitter object.
1529  *
1530  * The 'when' callback should take a single unbound argument
1531  * comprising a const reference to the return type of the thread
1532  * function represented by this Cgu::Thread::Future object. (So, in
1533  * the case of a Future<int> object, the callback function should take
1534  * a const int& argument as the unbound argument.) The 'when'
1535  * callback can have any number of bound arguments, except that a
1536  * bound argument may not include a copy of this Cgu::Thread::Future
1537  * object held by intrusive pointer as returned by the make() methods
1538  * (that would result in this Cgu::Thread::Future object owning, via
1539  * done_emitter, a reference to itself and so become incapable of
1540  * being freed). The 'when' callback may, however, take a pointer to
1541  * this Cgu::Thread::Future object, as obtained by the
1542  * Cgu::IntrusivePtr::get() method, because this Cgu::Thread::Future
1543  * object is guaranteed to remain in existence until the callback has
1544  * completed executing.
1545  *
1546  * This method cannot be called after the thread function represented
1547  * by this Cgu::Thread::Future object has completed (either
1548  * successfully or unsuccessfully) so that is_done() would return
1549  * true, and if this is attempted a Cgu::Thread::FutureWhenError
1550  * exception will be thrown. Therefore, generally this method should
1551  * be called before the run() method has been called.
1552  *
1553  * The documentation for the version of this method which does not
1554  * take a Releaser object gives further details of how this method is
1555  * used.
1556  *
1557  * If glib < 2.32 is used, the glib main loop must have been made
1558  * thread-safe by a call to g_thread_init() before this function is
1559  * called. glib >= 2.32 does not require g_thread_init() to be called
1560  * in order to be thread safe.
1561  *
1562  * @param w A callable object (such as formed by a lambda expression
1563  * or the result of std::bind) representing the 'when' callback (the
1564  * callback to be executed when the function represented by this
1565  * Cgu::Thread::Future object has successfully completed). It should
1566  * take a single unbound argument, namely a reference to const to the
1567  * return type of the thread function represented by this
1568  * Cgu::Thread::Future object.
1569  * @param r A Releaser object for automatic disconnection of the
1570  * 'when' callback before it executes in a main loop (mainly relevant
1571  * if the callback represents or calls into a non-static member
1572  * function of an object which may be destroyed before the callback
1573  * executes).
1574  * @param priority The priority to be given to the 'when' callback in
1575  * the main loop after the thread function represented by this
1576  * Cgu::Thread::Future object has successfully completed. In
1577  * ascending order of priorities, priorities are G_PRIORITY_LOW,
1578  * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT
1579  * and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT. This
1580  * determines the order in which the callback will appear in the event
1581  * list in the main loop, not the priority which the OS will adopt.
1582  * @param context The glib main context of the thread in whose main
1583  * loop the 'when' callback is to be executed (the default of NULL
1584  * will cause the callback to be executed in the main program loop).
1585  * @return The internal dispatching callback created by this method
1586  * and connected to done_emitter. It is made available as a return
1587  * value so that if wanted it can be disconnected programmatically
1588  * from done_emitter, or block()/unblock() can be called on it (but if
1589  * that is to be done, it must be done before the thread function
1590  * represented by this Cgu::Thread::Future object has completed in
1591  * order for it to be effective).
1592  * @exception Cgu::Thread::FutureWhenError This method will throw
1593  * Cgu::Thread::FutureWhenError if it is called after the thread
1594  * function represented by this Cgu::Thread::Future object has
1595  * completed.
1596  * @exception std::bad_alloc This method might throw std::bad_alloc if
1597  * memory is exhausted and the system throws in that case.
1598  * @exception Cgu::Thread::MutexError This method will throw
1599  * Cgu:Thread::MutexError if initialisation of the mutex in a
1600  * SafeEmitterArg object constructed by this method fails. If it does
1601  * so, the 'when' callback will be disposed of. (It is often not
1602  * worth checking for this, as it means either memory is exhausted or
1603  * pthread has run out of other resources to create new mutexes.)
1604  * @note 1. This method will also throw if the copy or move
1605  * constructor of the 'when' callable object throws.
1606  * @note 2. The return value of the function represented by this
1607  * Cgu::Thread::Future object is stored and passed as an argument to
1608  * the 'when' callback by const reference. If other threads might
1609  * concurrently call this object's get() method, which copies the
1610  * stored value, the stored type's copy constructor must be thread
1611  * safe with respect to the stored type's const methods. This would
1612  * be relevant if the stored type has data members declared mutable
1613  * which would be copied by its copy constructor.
1614  * @note 3. By virtue of the Releaser object, it is in theory possible
1615  * (if memory is exhausted and the system throws in that case) that an
1616  * internal SafeEmitterArg object will throw std::bad_alloc when
1617  * emitting/executing the 'when' callback in the glib main loop, with
1618  * the result that the relevant callback will not execute (instead the
1619  * exception will be consumed and a g_critical() warning will be
1620  * issued). This is rarely of any relevance because glib will abort
1621  * the program if it is itself unable to obtain memory from the
1622  * operating system. However, where it is relevant, design the
1623  * program so that it is not necessary to provide a releaser object.
1624  *
1625  * Since 2.1.0
1626  */
1627  // we need to use enable_if so that where this function is passed a
1628  // pointer to non-const Callback::CallbackArg, or some other
1629  // convertible pointer, this templated overload is dropped from the
1630  // overload set, in order to support the Callback::CallbackArg
1631  // overloads of this function. This overload calls into the version
1632  // of this function taking a pointer to const Callback::CallbackArg
1633  // in order to perform type erasure.
1634  template <class When,
1635  class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<When>::type,
1636  const Cgu::Callback::CallbackArg<const Val&>*>::value>::type>
1638  Cgu::Releaser& r,
1639  gint priority = G_PRIORITY_DEFAULT,
1640  GMainContext* context = 0) {
1641  return when(Callback::lambda<const Val&>(std::forward<When>(w)),
1642  r,
1643  priority,
1644  context);
1645  }
1646 
1647 /**
1648  * A utility intended to be used where relevant in conjunction with
1649  * the when() methods. It enables a callback to be executed in a glib
1650  * main loop (referred to below as the 'fail' callback) if memory is
1651  * exhausted and std::bad_alloc was thrown by the thread wrapper of
1652  * Cgu::Thread::Future after calling run() or by done_emitter when
1653  * emitting, or if the thread function represented by this
1654  * Cgu::Thread::Future object threw Cgu::Thread::Exit, exited with an
1655  * uncaught exception deriving from std::exception or was cancelled
1656  * (or that function took an argument of class type by value whose
1657  * copy constructor threw such an exception or had a return value of
1658  * class type whose move assignment operator, or if none copy
1659  * assignment operator, threw such an exception), or any callback
1660  * connected to done_emitter exited with an uncaught exception. It
1661  * therefore enables errors to be detected and acted on without having
1662  * a thread wait on the get() method in order to test is_error() or
1663  * is_emitter_error().
1664  *
1665  * It is implemented by attaching a timeout to the main loop which
1666  * polls at 100 millisecond intervals and tests is_done()/is_error()
1667  * and is_emitter_done()/is_emitter_error(). The timeout is
1668  * automatically removed by the implementation once it has been
1669  * detected that an error has occurred and the 'fail' callback is
1670  * executed, or if the thread function represented by this Cgu::Future
1671  * object and all done_emitter emissions (including execution of any
1672  * 'when' callback) have completed successfully.
1673  *
1674  * This method can be called before or after the run() method has been
1675  * called, and whether or not the thread function represented by this
1676  * Cgu::Thread::Future object has completed.
1677  *
1678  * Once this method has been called, this Cgu::Thread::Future object
1679  * will always stay in existence until the timeout has been
1680  * automatically removed by the implementation. Accordingly it is
1681  * safe to use this method even if the intrusive pointer object
1682  * returned by the make() methods will go out of scope before the
1683  * 'fail' callback has executed: the callback will execute correctly
1684  * irrespective of that.
1685  *
1686  * This method does not have a priority argument: as a polling timeout
1687  * is created, a particular priority will normally have no
1688  * significance (in fact, the 'fail' callback will execute in the main
1689  * loop with a priority of G_PRIORITY_DEFAULT). If in a special case
1690  * a different polling interval than 100 milliseconds or a different
1691  * priority is required, users can attach their own polling timeouts
1692  * to a main loop and carry out the tests by hand.
1693  *
1694  * Four other points should be noted. First, if as well as the when()
1695  * method being called some other callback has been connected to
1696  * done_emitter, and that other callback throws, the 'fail' callback
1697  * will execute. Therefore, if the particular program design requires
1698  * that the 'fail' callback should only execute if the 'when' callback
1699  * is not executed (and the 'when' callback only execute if the 'fail'
1700  * callback does not execute), no other callbacks which throw should
1701  * be connected to done_emitter.
1702  *
1703  * Secondly, as mentioned in the documentation on the when() method,
1704  * if the 'when' callback exits with an uncaught exception upon being
1705  * executed by the main loop or it represents a function which takes
1706  * an argument by value whose copy constructor throws, the 'fail'
1707  * callback will not execute (the exception will have been consumed
1708  * internally in order to protect the main loop and a g_critical
1709  * message issued).
1710  *
1711  * Thirdly, avoid if possible having a 'fail' callback which might
1712  * throw, or representing a function which takes an argument by value
1713  * whose copy constructor might throw: such an exception would be
1714  * consumed internally in order to protect the main loop and a
1715  * g_critical message issued, but no other error indication apart from
1716  * the g_critical message will be provided.
1717  *
1718  * Fourthly, unlike the 'when' callback, a copy of this
1719  * Cgu::Thread::Future object held by intrusive pointer as returned by
1720  * the make() methods may safely be bound to the 'fail' callback,
1721  * which would enable the 'fail' callback to determine whether it is
1722  * is_error() or is_emitter_error() which returns false.
1723  *
1724  * If glib < 2.32 is used, the glib main loop must have been made
1725  * thread-safe by a call to g_thread_init() before this function is
1726  * called. glib >= 2.32 does not require g_thread_init() to be called
1727  * in order to be thread safe.
1728  *
1729  * @param cb The 'fail' callback (the callback to be executed if the
1730  * thread function represented by this Cgu::Thread::Future object or a
1731  * done_emitter emission has failed to complete). Ownership is taken
1732  * of this object, and it will be deleted when it has been finished
1733  * with.
1734  * @param context The glib main context of the thread in whose main
1735  * loop the 'fail' callback is to be executed (the default of NULL
1736  * will cause the functor to be executed in the main program loop).
1737  * @exception std::bad_alloc This method might throw std::bad_alloc if
1738  * memory is exhausted and the system throws in that case. If it does
1739  * so, the 'fail' callback will be disposed of.
1740  *
1741  * Since 2.0.2
1742  */
1743  void fail(const Cgu::Callback::Callback* cb,
1744  GMainContext* context = 0);
1745 
1746 /**
1747  * A utility intended to be used where relevant in conjunction with
1748  * the when() methods. It enables a callable object to be executed in
1749  * a glib main loop (referred to below as the 'fail' callback) if
1750  * memory is exhausted and std::bad_alloc was thrown by the thread
1751  * wrapper of Cgu::Thread::Future after calling run() or by
1752  * done_emitter when emitting, or if the thread function represented
1753  * by this Cgu::Thread::Future object threw Cgu::Thread::Exit, exited
1754  * with an uncaught exception deriving from std::exception or was
1755  * cancelled (or that function took an argument of class type by value
1756  * whose copy constructor threw such an exception or had a return
1757  * value of class type whose move assignment operator, or if none copy
1758  * assignment operator, threw such an exception), or any callback
1759  * connected to done_emitter exited with an uncaught exception. It
1760  * therefore enables errors to be detected and acted on without having
1761  * a thread wait on the get() method in order to test is_error() or
1762  * is_emitter_error().
1763  *
1764  * It is implemented by attaching a timeout to the main loop which
1765  * polls at 100 millisecond intervals and tests is_done()/is_error()
1766  * and is_emitter_done()/is_emitter_error(). The timeout is
1767  * automatically removed by the implementation once it has been
1768  * detected that an error has occurred and the 'fail' callback is
1769  * executed, or if the thread function represented by this Cgu::Future
1770  * object and all done_emitter emissions (including execution of any
1771  * 'when' callback) have completed successfully.
1772  *
1773  * This method can be called before or after the run() method has been
1774  * called, and whether or not the thread function represented by this
1775  * Cgu::Thread::Future object has completed.
1776  *
1777  * Once this method has been called, this Cgu::Thread::Future object
1778  * will always stay in existence until the timeout has been
1779  * automatically removed by the implementation. Accordingly it is
1780  * safe to use this method even if the intrusive pointer object
1781  * returned by the make() methods will go out of scope before the
1782  * 'fail' callback has executed: the callback will execute correctly
1783  * irrespective of that.
1784  *
1785  * This method does not have a priority argument: as a polling timeout
1786  * is created, a particular priority will normally have no
1787  * significance (in fact, the 'fail' callback will execute in the main
1788  * loop with a priority of G_PRIORITY_DEFAULT). If in a special case
1789  * a different polling interval than 100 milliseconds or a different
1790  * priority is required, users can attach their own polling timeouts
1791  * to a main loop and carry out the tests by hand.
1792  *
1793  * Four other points should be noted. First, if as well as the when()
1794  * method being called some other callback has been connected to
1795  * done_emitter, and that other callback throws, the 'fail' callback
1796  * will execute. Therefore, if the particular program design requires
1797  * that the 'fail' callback should only execute if the 'when' callback
1798  * is not executed (and the 'when' callback only execute if the 'fail'
1799  * callback does not execute), no other callbacks which throw should
1800  * be connected to done_emitter.
1801  *
1802  * Secondly, as mentioned in the documentation on the when() method,
1803  * if the 'when' callback exits with an uncaught exception upon being
1804  * executed by the main loop or it represents a function which takes
1805  * an argument by value whose copy constructor throws, the 'fail'
1806  * callback will not execute (the exception will have been consumed
1807  * internally in order to protect the main loop and a g_critical
1808  * message issued).
1809  *
1810  * Thirdly, avoid if possible having a 'fail' callback which might
1811  * throw: such an exception would be consumed internally in order to
1812  * protect the main loop and a g_critical message issued, but no other
1813  * error indication apart from the g_critical message will be
1814  * provided.
1815  *
1816  * Fourthly, unlike the 'when' callback, a copy of this
1817  * Cgu::Thread::Future object held by intrusive pointer as returned by
1818  * the make() methods may safely be bound to the 'fail' callback,
1819  * which would enable the 'fail' callback to determine whether it is
1820  * is_error() or is_emitter_error() which returns false.
1821  *
1822  * If glib < 2.32 is used, the glib main loop must have been made
1823  * thread-safe by a call to g_thread_init() before this function is
1824  * called. glib >= 2.32 does not require g_thread_init() to be called
1825  * in order to be thread safe.
1826  * @param f A callable object (such as formed by a lambda expression
1827  * or the result of std::bind) representing the 'fail' callback (the
1828  * callback to be executed if the thread function represented by this
1829  * Cgu::Thread::Future object or a done_emitter emission has failed to
1830  * complete). The callable object should be fully bound (it should
1831  * take no arguments when called).
1832  * @param context The glib main context of the thread in whose main
1833  * loop the 'fail' callback is to be executed (the default of NULL
1834  * will cause the functor to be executed in the main program loop).
1835  * @exception std::bad_alloc This method might throw std::bad_alloc if
1836  * memory is exhausted and the system throws in that case.
1837  * @note This method will also throw if the copy or move constructor
1838  * of the 'fail' callable object throws.
1839  *
1840  * Since 2.1.0
1841  */
1842  // we need to use enable_if so that where this function is passed a
1843  // pointer to non-const Callback::Callback, or some other
1844  // convertible pointer, this templated overload is dropped from the
1845  // overload set, in order to support the Callback::Callback
1846  // overloads of this function. This overload calls into the version
1847  // of this function taking a pointer to const Callback::Callback in
1848  // order to perform type erasure.
1849  template <class Fail,
1850  class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<Fail>::type,
1851  const Cgu::Callback::Callback*>::value>::type>
1852  void fail(Fail&& f,
1853  GMainContext* context = 0) {
1854  fail(Callback::lambda<>(std::forward<Fail>(f)),
1855  context);
1856  }
1857 
1858 /**
1859  * This is a version of the fail() utility for use in conjunction with
1860  * the when() methods, which takes a Releaser object for automatic
1861  * disconnection of the callback functor passed as an argument to this
1862  * method if the object having the callback function as a member is
1863  * destroyed. For this to be race free, the lifetime of that object
1864  * must be controlled by the thread in whose main loop the 'fail'
1865  * callback will execute.
1866  *
1867  * This method enables a callback to be executed in a glib main loop
1868  * if memory is exhausted and std::bad_alloc was thrown by the thread
1869  * wrapper of Cgu::Thread::Future after calling run() or by
1870  * done_emitter when emitting, or if the thread function represented
1871  * by this Cgu::Thread::Future object threw Cgu::Thread::Exit, exited
1872  * with an uncaught exception deriving from std::exception or was
1873  * cancelled (or that function took an argument of class type by value
1874  * whose copy constructor threw such an exception or had a return
1875  * value of class type whose move assignment operator, or if none copy
1876  * assignment operator, threw such an exception), or any callback
1877  * connected to done_emitter exited with an uncaught exception. It
1878  * therefore enables errors to be detected and acted on without having
1879  * a thread wait on the get() method in order to test is_error() or
1880  * is_emitter_error().
1881  *
1882  * This method can be called before or after the run() method has been
1883  * called, and whether or not the thread function represented by this
1884  * Cgu::Thread::Future object has completed.
1885  *
1886  * The documentation for the version of this method which does not
1887  * take a Releaser object gives further details of how this method is
1888  * used.
1889  *
1890  * If glib < 2.32 is used, the glib main loop must have been made
1891  * thread-safe by a call to g_thread_init() before this function is
1892  * called. glib >= 2.32 does not require g_thread_init() to be called
1893  * in order to be thread safe.
1894  *
1895  * @param cb The 'fail' callback (the callback to be executed if the
1896  * thread function represented by this Cgu::Thread::Future object or a
1897  * done_emitter emission has failed to complete). Ownership is taken
1898  * of this object, and it will be deleted when it has been finished
1899  * with.
1900  * @param r A Releaser object for automatic disconnection of the
1901  * 'fail' callback before it executes in a main loop (mainly relevant
1902  * if the callback represents a non-static member function of an
1903  * object which may be destroyed before the callback executes).
1904  * @param context The glib main context of the thread in whose main
1905  * loop the 'fail' callback is to be executed (the default of NULL
1906  * will cause the functor to be executed in the main program loop).
1907  * @exception std::bad_alloc This method might throw std::bad_alloc if
1908  * memory is exhausted and the system throws in that case. If it does
1909  * so, the 'fail' callback will be disposed of.
1910  * @exception Cgu::Thread::MutexError This method will throw
1911  * Cgu:Thread::MutexError if initialisation of the mutex in a
1912  * SafeEmitterArg object constructed by Cgu::start_timeout() fails.
1913  * If it does so, the 'fail' callback will be disposed of. (It is
1914  * often not worth checking for this, as it means either memory is
1915  * exhausted or pthread has run out of other resources to create new
1916  * mutexes.)
1917  * @note By virtue of the Releaser object, it is in theory possible
1918  * (if memory is exhausted and the system throws in that case) that an
1919  * internal SafeEmitterArg object will throw std::bad_alloc when
1920  * emitting/executing the 'fail' callback in the glib main loop, with
1921  * the result that the relevant callback will not execute (instead the
1922  * exception will be consumed and a g_critical() warning will be
1923  * issued). This is rarely of any relevance because glib will abort
1924  * the program if it is itself unable to obtain memory from the
1925  * operating system. However, where it is relevant, design the
1926  * program so that it is not necessary to provide a releaser object.
1927  *
1928  * Since 2.0.2
1929  */
1930  void fail(const Cgu::Callback::Callback* cb,
1931  Cgu::Releaser& r,
1932  GMainContext* context = 0);
1933 
1934 /**
1935  * This is a version of the fail() utility for use in conjunction with
1936  * the when() methods, which takes a Releaser object for automatic
1937  * disconnection of the callable object passed as an argument to this
1938  * method if the 'fail' callback represents or calls into an object
1939  * which is destroyed. For this to be race free, the lifetime of the
1940  * object called into must be controlled by the thread in whose main
1941  * loop the 'fail' callback will execute.
1942  *
1943  * This method enables a callback to be executed in a glib main loop
1944  * if memory is exhausted and std::bad_alloc was thrown by the thread
1945  * wrapper of Cgu::Thread::Future after calling run() or by
1946  * done_emitter when emitting, or if the thread function represented
1947  * by this Cgu::Thread::Future object threw Cgu::Thread::Exit, exited
1948  * with an uncaught exception deriving from std::exception or was
1949  * cancelled (or that function took an argument of class type by value
1950  * whose copy constructor threw such an exception or had a return
1951  * value of class type whose move assignment operator, or if none copy
1952  * assignment operator, threw such an exception), or any callback
1953  * connected to done_emitter exited with an uncaught exception. It
1954  * therefore enables errors to be detected and acted on without having
1955  * a thread wait on the get() method in order to test is_error() or
1956  * is_emitter_error().
1957  *
1958  * This method can be called before or after the run() method has been
1959  * called, and whether or not the thread function represented by this
1960  * Cgu::Thread::Future object has completed.
1961  *
1962  * The documentation for the version of this method which does not
1963  * take a Releaser object gives further details of how this method is
1964  * used.
1965  *
1966  * If glib < 2.32 is used, the glib main loop must have been made
1967  * thread-safe by a call to g_thread_init() before this function is
1968  * called. glib >= 2.32 does not require g_thread_init() to be called
1969  * in order to be thread safe.
1970 
1971  * @param f A callable object (such as formed by a lambda expression
1972  * or the result of std::bind) representing the 'fail' callback (the
1973  * callback to be executed if the thread function represented by this
1974  * Cgu::Thread::Future object or a done_emitter emission has failed to
1975  * complete). The callable object should be fully bound (it should
1976  * take no arguments when called).
1977  * @param r A Releaser object for automatic disconnection of the
1978  * 'fail' callback before it executes in a main loop (mainly relevant
1979  * if the callback represents or calls into a non-static member
1980  * function of an object which may be destroyed before the callback
1981  * executes).
1982  * @param context The glib main context of the thread in whose main
1983  * loop the 'fail' callback is to be executed (the default of NULL
1984  * will cause the functor to be executed in the main program loop).
1985  * @exception std::bad_alloc This method might throw std::bad_alloc if
1986  * memory is exhausted and the system throws in that case.
1987  * @exception Cgu::Thread::MutexError This method will throw
1988  * Cgu:Thread::MutexError if initialisation of the mutex in a
1989  * SafeEmitterArg object constructed by Cgu::start_timeout() fails.
1990  * (It is often not worth checking for this, as it means either memory
1991  * is exhausted or pthread has run out of other resources to create
1992  * new mutexes.)
1993  * @note 1. This method will also throw if the copy or move
1994  * constructor of the 'fail' callable object throws.
1995  * @note 2. By virtue of the Releaser object, it is in theory possible
1996  * (if memory is exhausted and the system throws in that case) that an
1997  * internal SafeEmitterArg object will throw std::bad_alloc when
1998  * emitting/executing the 'fail' callback in the glib main loop, with
1999  * the result that the relevant callback will not execute (instead the
2000  * exception will be consumed and a g_critical() warning will be
2001  * issued). This is rarely of any relevance because glib will abort
2002  * the program if it is itself unable to obtain memory from the
2003  * operating system. However, where it is relevant, design the
2004  * program so that it is not necessary to provide a releaser object.
2005  *
2006  * Since 2.1.0
2007  */
2008  // we need to use enable_if so that where this function is passed a
2009  // pointer to non-const Callback::Callback, or some other
2010  // convertible pointer, this templated overload is dropped from the
2011  // overload set, in order to support the Callback::Callback
2012  // overloads of this function. This overload calls into the version
2013  // of this function taking a pointer to const Callback::Callback in
2014  // order to perform type erasure.
2015  template <class Fail,
2016  class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<Fail>::type,
2017  const Cgu::Callback::Callback*>::value>::type>
2018  void fail(Fail&& f,
2019  Cgu::Releaser& r,
2020  GMainContext* context = 0) {
2021  fail(Callback::lambda<>(std::forward<Fail>(f)),
2022  r,
2023  context);
2024  }
2025 
2026 /**
2027  * @return true if the function or callable object represented by this
2028  * Cgu::Thread::Future object has finished, either by returning
2029  * normally, by cancellation or by virtue of having thrown
2030  * Cgu::Thread::Exit or some exception derived from std::exception.
2031  * Once this method returns true, then it is guaranteed that the get()
2032  * or move_get() method will not block (except as incidental to any
2033  * contention between threads calling get()). Once this method has
2034  * returned true or get() or move_get() has unblocked, then the result
2035  * of is_error() is definitive. This method is thread safe and may be
2036  * called by any thread. It will not throw.
2037  * @note This method will return true even though any callbacks
2038  * connected to done_emitter are still executing or waiting to
2039  * execute. From version 2.0.2 the is_emitter_done() method will
2040  * indicate when done_emitter callbacks (if any) have also completed.
2041  */
2042  bool is_done() const noexcept;
2043 
2044 /**
2045  * @return true if both the function or callable object represented by
2046  * this Cgu::Thread::Future object has finished and any callbacks
2047  * connected to done_emitter have completed. Once this method returns
2048  * true, then the result of is_emitter_error() is definitive. This
2049  * method is thread safe and may be called by any thread. It will not
2050  * throw.
2051  * @note This method will return true automatically if is_error() and
2052  * is_done() return true, because if the function or callable object
2053  * represented by this Cgu::Thread::Future object was cancelled or
2054  * exited with an uncaught exception, done_emitter is never emitted.
2055  * In addition, if this method returns true, then is_done() must also
2056  * return true.
2057  *
2058  * Since 2.0.2
2059  */
2060  bool is_emitter_done() const noexcept;
2061 
2062 /**
2063  * @return true if (a) a Cgu::Thread::Exit exception has been thrown
2064  * by the function or callable object represented by this
2065  * Cgu::Thread::Future object (which will have been consumed by this
2066  * Cgu::Thread::Future object), (b) an exception derived from
2067  * std::exception has been thrown on invoking that function or object
2068  * which was not caught by it (which will have been consumed by this
2069  * Cgu::Thread::Future object), (c) any of those exceptions have been
2070  * thrown either by the copy constructor of an argument taken by value
2071  * by that function or object, or by the move assignment operator (or
2072  * if none, copy assignment operator) of the return value of that
2073  * function or object (which will have been consumed by this
2074  * Cgu::Thread::Future object), (d) the worker thread in which that
2075  * function or callable object executes was cancelled in mid-course
2076  * with a call to cancel() or (e) the thread wrapper implementing the
2077  * worker thread in this Cgu::Thread::Future object threw and then
2078  * consumed std::bad_alloc (this is different from the run() method
2079  * throwing std::bad_alloc). In these cases the value obtained by
2080  * get() or move_get() will not be valid (it will be a default
2081  * constructed object of the return type of the function represented
2082  * by this Cgu::Thread::Future object). Otherwise this method returns
2083  * false. The result of this method is definitive once get() or
2084  * move_get() has unblocked or is_done() returns true. This method is
2085  * thread safe and may be called by any thread. It will not throw.
2086  */
2087  bool is_error() const noexcept;
2088 
2089 /**
2090  * @return true if an uncaught exception arose in emitting @ref
2091  * DoneEmitterAnchor "done_emitter" when executing callbacks connected
2092  * to it. Otherwise this method returns false. The result of this
2093  * method is definitive once is_emitter_done() returns true. This
2094  * method is thread safe and may be called by any thread. It will not
2095  * throw.
2096  * @note This method will return false automatically if is_error()
2097  * returns true, because if the function or callable object
2098  * represented by this Cgu::Thread::Future object was cancelled or
2099  * exited with an uncaught exception, done_emitter is never emitted.
2100  * It follows that if this method returns true, is_error() must return
2101  * false.
2102  */
2103  bool is_emitter_error() const noexcept;
2104 
2105 /**
2106  * A Cgu::SafeEmitter object which is emitted when the function or
2107  * callable object represented by this Cgu::Thread::Future object
2108  * finishes correctly (that is, it is not cancelled and does not throw
2109  * any uncaught exceptions). By itself this emission does not do too
2110  * much as it is emitted (and connected callbacks execute in) the same
2111  * worker thread immediately after the Future function has completed.
2112  * However, any thread can connect a callback object to this
2113  * Cgu::SafeEmitter object and a connected callback can, say, cause
2114  * another callback to be executed in a thread's main loop using
2115  * Cgu::Callback::post(), and from version 2.0.2 when() methods are
2116  * provided which will do this for users automatically. Once the
2117  * run() method has been called, this Cgu::Thread::Future object (and
2118  * so done_emitter) will always stay in existence until the function
2119  * or callable object represented by it has completed (whether
2120  * correctly, by cancellation or by a thrown exception) and any
2121  * callbacks connected to the done_emitter object have completed,
2122  * irrespective of whether the intrusive pointer returned by the
2123  * make() or make_future() functions has gone out of scope.
2124  * @note 1. Cancellation is blocked while the Cgu::SafeEmitter object
2125  * emits and any connected callback executes.
2126  * @note 2. A connected callback can however terminate the worker
2127  * thread by throwing Cgu::Thread::Exit (in which case no subsequent
2128  * callbacks to be executed on that emission will execute either: the
2129  * worker thread will safely terminate and unwind the stack in so
2130  * doing). In that event, the emitter_error flag will be set.
2131  * @note 3. All other uncaught exceptions which might be thrown by the
2132  * Cgu::SafeEmitter object emitting, or by a connected callback
2133  * function executing, are consumed to retain the integrity of the
2134  * Thread::Future object. In the event of such an exception being
2135  * thrown, the emitter_error flag will be set. In summary, the
2136  * emitter_error flag will be set if (a) a connected callback function
2137  * throws Cgu::Thread::Exit, (b) some other uncaught exception escapes
2138  * from a connected callback function or (c) Cgu::SafeEmitter::emit()
2139  * throws std::bad_alloc or the copy constructor of a bound argument
2140  * which is not a reference argument has thrown. If the user knows
2141  * that the callback function does not throw Cgu::Thread::Exit and
2142  * does not allow any other exception to escape, then the cause must
2143  * be a std::bad_alloc memory exception in Cgu::SafeEmitter::emit() or
2144  * the copy constructor of a non-reference bound argument throwing.
2145  * @note 4. An emission is thread safe if the connected callback
2146  * functions are thread safe.
2147  * @note 5. This Cgu::Thread::Future object's mutex is released while
2148  * the Cgu::SafeEmitter object emits. This means that any connected
2149  * callbacks can safely call, say, the Future object's get() or
2150  * is_error() methods. However, a connected callback should not hold
2151  * a bound argument comprising a copy of this Cgu::Thread::Future
2152  * object held by intrusive pointer as returned by the make() or
2153  * make_future() methods (that would result in this
2154  * Cgu::Thread::Future object owning, via done_emitter, a reference to
2155  * itself and so become incapable of being freed). The callback may,
2156  * however, take a pointer to this Cgu::Thread::Future object as a
2157  * bound argument, as obtained by the Cgu::IntrusivePtr::get() method,
2158  * because this Cgu::Thread::Future object is guaranteed to remain in
2159  * existence until all callbacks connected to done_emitter have
2160  * completed executing.
2161  * @anchor DoneEmitterAnchor
2162  */
2164 
2165 /* Only has effect if --with-glib-memory-slices-compat or
2166  * --with-glib-memory-slices-no-compat option picked */
2168 };
2169 
2170 /**
2171  * @deprecated
2172  *
2173  * DEPRECATED. Use the version of make_future() which takes a
2174  * callable object.
2175  *
2176  * A convenience helper function which calls
2177  * Cgu::Thread::Future::make() to obtain a Future object without the
2178  * need to specify the return value of the function represented by the
2179  * new object: that is deduced from the signature of that function.
2180  * This is useful shorthand when also employed with the C++11/14
2181  * 'auto' keyword.
2182  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2183  * is exhausted and the system throws in that case. (This exception
2184  * will not be thrown if the library has been installed using the
2185  * \--with-glib-memory-slices-no-compat configuration option: instead
2186  * glib will terminate the program if it is unable to obtain memory
2187  * from the operating system.)
2188  * @exception Cgu::Thread::MutexError It might throw
2189  * Cgu::Thread::MutexError if initialisation of the contained mutex
2190  * fails. (It is often not worth checking for this, as it means
2191  * either memory is exhausted or pthread has run out of other
2192  * resources to create new mutexes.)
2193  * @exception Cgu::Thread::CondError It might throw
2194  * Cgu::Thread::CondError if initialisation of the contained condition
2195  * variable fails. (It is often not worth checking for this, as it
2196  * means either memory is exhausted or pthread has run out of other
2197  * resources to create new condition variables.)
2198  * @note This method will also throw if the copy or move constructor
2199  * of a bound argument throws, or the default constructor of the
2200  * return value type of the function represented by the new object
2201  * throws.
2202 
2203  *
2204  * Since 2.0.4
2205  */
2206 template <class Obj, class Ret, class... Params, class... Args>
2208  Ret (Obj::*func)(Params...),
2209  Args&&... args) {
2210  return Cgu::Thread::Future<Ret>::make(obj, func, std::forward<Args>(args)...);
2211 }
2212 
2213 /**
2214  * @deprecated
2215  *
2216  * DEPRECATED. Use the version of make_future() which takes a
2217  * callable object.
2218  *
2219  * A convenience helper function which calls
2220  * Cgu::Thread::Future::make() to obtain a Future object without the
2221  * need to specify the return value of the function represented by the
2222  * new object: that is deduced from the signature of that function.
2223  * This is useful shorthand when also employed with the C++11/14
2224  * 'auto' keyword.
2225  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2226  * is exhausted and the system throws in that case. (This exception
2227  * will not be thrown if the library has been installed using the
2228  * \--with-glib-memory-slices-no-compat configuration option: instead
2229  * glib will terminate the program if it is unable to obtain memory
2230  * from the operating system.)
2231  * @exception Cgu::Thread::MutexError It might throw
2232  * Cgu::Thread::MutexError if initialisation of the contained mutex
2233  * fails. (It is often not worth checking for this, as it means
2234  * either memory is exhausted or pthread has run out of other
2235  * resources to create new mutexes.)
2236  * @exception Cgu::Thread::CondError It might throw
2237  * Cgu::Thread::CondError if initialisation of the contained condition
2238  * variable fails. (It is often not worth checking for this, as it
2239  * means either memory is exhausted or pthread has run out of other
2240  * resources to create new condition variables.)
2241  * @note This method will also throw if the copy or move constructor
2242  * of a bound argument throws, or the default constructor of the
2243  * return value type of the function represented by the new object
2244  * throws.
2245  *
2246  * Since 2.0.4
2247  */
2248 template <class Obj, class Ret, class... Params, class... Args>
2250  Ret (Obj::*func)(Params...) const,
2251  Args&&... args) {
2252  return Cgu::Thread::Future<Ret>::make(obj, func, std::forward<Args>(args)...);
2253 }
2254 
2255 /**
2256  * @deprecated
2257  *
2258  * DEPRECATED. Use the version of make_future() which takes a
2259  * callable object.
2260  *
2261  * A convenience helper function which calls
2262  * Cgu::Thread::Future::make() to obtain a Future object without the
2263  * need to specify the return value of the function represented by the
2264  * new object: that is deduced from the signature of that function.
2265  * This is useful shorthand when also employed with the C++11/14
2266  * 'auto' keyword.
2267  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2268  * is exhausted and the system throws in that case. (This exception
2269  * will not be thrown if the library has been installed using the
2270  * \--with-glib-memory-slices-no-compat configuration option: instead
2271  * glib will terminate the program if it is unable to obtain memory
2272  * from the operating system.)
2273  * @exception Cgu::Thread::MutexError It might throw
2274  * Cgu::Thread::MutexError if initialisation of the contained mutex
2275  * fails. (It is often not worth checking for this, as it means
2276  * either memory is exhausted or pthread has run out of other
2277  * resources to create new mutexes.)
2278  * @exception Cgu::Thread::CondError It might throw
2279  * Cgu::Thread::CondError if initialisation of the contained condition
2280  * variable fails. (It is often not worth checking for this, as it
2281  * means either memory is exhausted or pthread has run out of other
2282  * resources to create new condition variables.)
2283  * @note This method will also throw if the copy or move constructor
2284  * of a bound argument throws, or the default constructor of the
2285  * return value type of the function represented by the new object
2286  * throws.
2287  *
2288  * Since 2.0.4
2289  */
2290 template <class Ret, class... Params, class... Args>
2292  Args&&... args) {
2293  return Cgu::Thread::Future<Ret>::make(func, std::forward<Args>(args)...);
2294 }
2295 
2296 /**
2297  * A convenience helper function which calls
2298  * Cgu::Thread::Future::make() to obtain a Future without the need to
2299  * specify the return value of the callable object to be represented
2300  * by it: that is deduced. This is useful shorthand when also
2301  * employed with the C++11/14 'auto' keyword.
2302  *
2303  * @param func A callable object, such as formed by a lambda
2304  * expression or the result of std::bind. It must be fully bound
2305  * (that is, its must take no arguments when called). It should
2306  * return a value (it cannot return void).
2307  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2308  * is exhausted and the system throws in that case. (This exception
2309  * will not be thrown if the library has been installed using the
2310  * \--with-glib-memory-slices-no-compat configuration option: instead
2311  * glib will terminate the program if it is unable to obtain memory
2312  * from the operating system.)
2313  * @exception Cgu::Thread::MutexError It might throw
2314  * Cgu::Thread::MutexError if initialisation of the contained mutex
2315  * fails. (It is often not worth checking for this, as it means
2316  * either memory is exhausted or pthread has run out of other
2317  * resources to create new mutexes.)
2318  * @exception Cgu::Thread::CondError It might throw
2319  * Cgu::Thread::CondError if initialisation of the contained condition
2320  * variable fails. (It is often not worth checking for this, as it
2321  * means either memory is exhausted or pthread has run out of other
2322  * resources to create new condition variables.)
2323  * @note 1. This method will also throw if the copy or move
2324  * constructor of the callable object passed as an argument throws, or
2325  * the default constructor of the return value type of the function
2326  * represented by the new object throws.
2327  * @note 2. If the callable object passed as an argument has both
2328  * const and non-const operator()() methods, the non-const version
2329  * will be called even if the callable object passed is a const
2330  * object.
2331  *
2332  * Since 2.0.14
2333  */
2334 // we don't need this version of make_future() for syntactic reasons -
2335 // the version taking a single template parameter will do by itself
2336 // syntactically because it can use decltype. However, we include
2337 // this version in order to be API compatible with c++-gtk-utils <
2338 // 2.0.14, which required the return type to be specified when this
2339 // method is passed something other than a std::function object.
2340 // SFINAE will take care of the rest, except with a corner case where
2341 // all of the following apply: (i) a function object is passed whose
2342 // operator()() method returns a copy of the function object (or
2343 // another function object of the same type), (ii) the function object
2344 // is passed to this method as a rvalue and not a lvalue, and (iii)
2345 // the user specifically states the return type when instantiating
2346 // this template function. This would give rise to an ambiguity, but
2347 // its happening is extremely unlikely, and cannot happen with a
2348 // lambda or the return value of std::bind, because those types are
2349 // only known to the compiler, and cannot happen with other objects if
2350 // the user lets template deduction take its course.
2351 template <class Ret, class Func>
2353  return Cgu::Thread::Future<Ret>::make(std::forward<Func>(func));
2354 }
2355 
2356 // we don't want to document this function: it provides the type
2357 // deduction of the return value of the passed functor (it deals with
2358 // cases where this is not specified expressly).
2359 #ifndef DOXYGEN_PARSING
2360 template <class Func>
2362  // this function will fail to compile if the return type is a
2363  // reference type: that is a feature, not a bug, as a function
2364  // returning a reference lacks referential transparency, is unlikely
2365  // to be thread-safe and is unsuitable for use as a task function
2366  return Cgu::Thread::Future<decltype(func())>::make(std::forward<Func>(func));
2367 }
2368 #endif
2369 
2370 } // namespace Thread
2371 
2372 } // namespace Cgu
2373 
2374 #include <c++-gtk-utils/future.tpp>
2375 
2376 #endif
Cgu::Callback::SafeFunctor when(When &&w, gint priority=G_PRIORITY_DEFAULT, GMainContext *context=0)
Definition: future.h:1383
SafeEmitter done_emitter
Definition: future.h:2163
Definition: future.h:68
std::unique_ptr< Cgu::SafeEmitterArg< const Val & > > when
Definition: future.h:264
bool is_emitter_error() const noexcept
bool cancel() noexcept
WhenWrapperArg(WhenWrapperArg &&w)
Definition: future.h:254
bool is_done() const noexcept
STL namespace.
Cgu::IntrusivePtr< Cgu::Thread::Future< Ret > > make_future(Obj &obj, Ret(Obj::*func)(Params...), Args &&...args)
Definition: future.h:2207
std::unique_ptr< const Cgu::Callback::CallbackArg< const Val & > > when
Definition: future.h:248
Cgu::Callback::SafeFunctor when(When &&w, Cgu::Releaser &r, gint priority=G_PRIORITY_DEFAULT, GMainContext *context=0)
Definition: future.h:1637
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:268
This is a smart pointer for managing objects allocated on freestore which maintain their own referenc...
Definition: intrusive_ptr.h:98
void fail(Fail &&f, Cgu::Releaser &r, GMainContext *context=0)
Definition: future.h:2018
void fail(const Cgu::Callback::Callback *cb, GMainContext *context=0)
Future & operator=(const Future &)=delete
WhenWrapperArg(std::unique_ptr< const Cgu::Callback::CallbackArg< const Val & >> &&when_)
Definition: future.h:252
bool is_emitter_done() const noexcept
A thread-safe class to execute callbacks connected to it, with provision for automatic disconnection...
Definition: emitter.h:327
A wrapper class for pthread mutexes.
Definition: mutex.h:117
void fail(Fail &&f, GMainContext *context=0)
Definition: future.h:1852
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
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:784
WhenWrapperArgRel(WhenWrapperArgRel &&w)
Definition: future.h:270
virtual const char * what() const
Definition: future.h:65
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:277
Definition: future.h:64
bool is_error() const noexcept
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:69
A class used for tracking EmitterArg and SafeEmitterArg connections.
Definition: emitter.h:352