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