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