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