c++-gtk-utils: future.h Source File

c++-gtk-utils

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

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