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