c++-gtk-utils
|
00001 /* Copyright (C) 2010 to 2012 Chris Vine 00002 00003 The library comprised in this file or of which this file is part is 00004 distributed by Chris Vine under the GNU Lesser General Public 00005 License as follows: 00006 00007 This library is free software; you can redistribute it and/or 00008 modify it under the terms of the GNU Lesser General Public License 00009 as published by the Free Software Foundation; either version 2.1 of 00010 the License, or (at your option) any later version. 00011 00012 This library is distributed in the hope that it will be useful, but 00013 WITHOUT ANY WARRANTY; without even the implied warranty of 00014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00015 Lesser General Public License, version 2.1, for more details. 00016 00017 You should have received a copy of the GNU Lesser General Public 00018 License, version 2.1, along with this library (see the file LGPL.TXT 00019 which came with this source code package in the src/utils sub-directory); 00020 if not, write to the Free Software Foundation, Inc., 00021 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 00022 00023 However, it is not intended that the object code of a program whose 00024 source code instantiates a template from this file or uses macros or 00025 inline functions (of any length) should by reason only of that 00026 instantiation or use be subject to the restrictions of use in the GNU 00027 Lesser General Public License. With that in mind, the words "and 00028 macros, inline functions and instantiations of templates (of any 00029 length)" shall be treated as substituted for the words "and small 00030 macros and small inline functions (ten lines or less in length)" in 00031 the fourth paragraph of section 5 of that licence. This does not 00032 affect any other reason why object code may be subject to the 00033 restrictions in that licence (nor for the avoidance of doubt does it 00034 affect the application of section 2 of that licence to modifications 00035 of the source code in this file). 00036 00037 */ 00038 00039 #ifndef CGU_FUTURE_H 00040 #define CGU_FUTURE_H 00041 00042 #include <memory> 00043 #include <exception> 00044 #include <functional> // for std::function 00045 #include <utility> // for std::move and std::forward 00046 00047 #include <pthread.h> 00048 #include <glib.h> 00049 00050 #include <c++-gtk-utils/thread.h> 00051 #include <c++-gtk-utils/mutex.h> 00052 #include <c++-gtk-utils/callback.h> 00053 #include <c++-gtk-utils/intrusive_ptr.h> 00054 #include <c++-gtk-utils/shared_ptr.h> 00055 #include <c++-gtk-utils/emitter.h> 00056 #include <c++-gtk-utils/timeout.h> 00057 #include <c++-gtk-utils/cgu_config.h> 00058 00059 namespace Cgu { 00060 00061 namespace Thread { 00062 00063 struct FutureThreadError: public std::exception { 00064 virtual const char* what() const throw() {return "FutureThreadError\n";} 00065 }; 00066 00067 struct FutureWhenError: public std::exception { 00068 virtual const char* what() const throw() {return "FutureWhenError\n";} 00069 }; 00070 00071 /** 00072 * @class Cgu::Thread::Future future.h c++-gtk-utils/future.h 00073 * @brief A class representing a pthread thread which will 00074 * provide a value. 00075 * @sa Cgu::Thread::Thread Cgu::Thread::JoinableHandle Cgu::AsyncResult Cgu::Thread::make_future() 00076 * 00077 * The Thread::Future class will launch a worker thread, run the 00078 * function it represents in that thread until it returns, and store 00079 * the return value so that it can be waited on and/or extracted by 00080 * another thread. A new Thread::Future object representing the 00081 * function to be called is created by calling 00082 * Cgu::Thread::Future<>::make() (a static member function) or from 00083 * version 2.0.4 the Cgu::Thread::make_future() helper function. The 00084 * worker thread is then started by calling run(), and the value 00085 * extracted or waited for by calling get(). The run() method can 00086 * only be called once, but any number of threads can wait for and/or 00087 * extract the return value by calling the get() method. The class 00088 * also provides a SafeEmitter @ref DoneEmitterAnchor "done_emitter" 00089 * public object which emits when the worker thread has finished, and 00090 * an associated when() function. 00091 * 00092 * The template parameter type of Thread::Future is the type of the 00093 * return value of the function called by the Thread::Future object. 00094 * The return value can be any type, including any arbitrarily large 00095 * tuple or other struct or standard C++ container (but see below 00096 * about copying). 00097 * 00098 * A Thread::Future object cannot represent a function with a void 00099 * return type - a compilation error will result if that is attempted. 00100 * If no return value is wanted, then the Thread::Thread class can be 00101 * used directly. (However, if in a particular usage this class is 00102 * thought to be more convenient, the function to be represented by it 00103 * can be wrapped by another function which provides a dummy return 00104 * value, such as a dummy int. One possible case for this is where 00105 * more than one thread wants to wait for the worker thread to 00106 * terminate, as pthread_join() and so Thread::Thread::join() only 00107 * give defined behaviour when called by one thread.) In addition, a 00108 * Thread::Future object cannot represent a function with a non-const 00109 * reference argument - that would not normally be safe, and a compile 00110 * error will be generated if that is attempted. However, from 00111 * version 2.0.0-rc3, const reference arguments can be bound to 00112 * Thread::Future objects (this is safe, as the Thread::Future object 00113 * will keep its own copy of the argument passed to it). 00114 * 00115 * The make() method and make_future() functions take a plain 00116 * function, static member function or non-static member function, 00117 * which can take up to three arguments in the case of a non-static 00118 * member function, and four arguments in the case of any other 00119 * function. In the case of a non-static member function, the 00120 * referenced object whose member function is to be called must remain 00121 * in existence until the worker thread has completed. Alternatively, 00122 * a std::function object can be passed, which can have any number of 00123 * arguments using std::bind (and which can also bind the referenced 00124 * object of a non-static member function by taking a copy of it where 00125 * that is necessary). 00126 * 00127 * Where a std::function object is not passed, internal moving/copying 00128 * of arguments for the target function to be represented by the 00129 * Thread::Future object takes place (once by invoking the rvalue move 00130 * constructor or lvalue copy constructor, as appropriate, when make() 00131 * or make_future() are called and, if the argument is not a const 00132 * reference argument, once in the worker thread when run() is 00133 * called). Therefore, if a non-trivial class object is to be 00134 * received by the target function as an argument, it is best either 00135 * (a) if it has a rvalue constructor, to pass it to make() or 00136 * make_future() as a temporary and have the target function take a 00137 * const reference argument, or (b) for it to be constructed on free 00138 * store and for the target function to receive it by pointer, by 00139 * Cgu::SharedLockPtr, or by a std::shared_ptr implementation which 00140 * has a thread-safe reference count. Note also that constructing 00141 * std::function objects using std::bind can cause a number of copies 00142 * of arguments to be made, so for ordinary usage it is better to pass 00143 * a function pointer with arguments to make() or make_future() rather 00144 * than a std::function object. 00145 * 00146 * Copying of the return value of the target function represented by 00147 * the Thread::Future object also takes place. The run() method will 00148 * store the return value of that function, so that it is available to 00149 * the get() method, and therefore copy it once (unless, that is, the 00150 * target function's return value type has an assignment operator 00151 * taking an rvalue reference argument). The get() method will 00152 * indirectly cause it to be copied once more when the copy 00153 * constructor or assignment operator of the user's object which 00154 * receives the return value of get() is invoked. Therefore, for 00155 * return values comprising complex class objects, it is often better 00156 * if the function represented by the Thread::Future object allocates 00157 * the return value on free store and returns it by pointer, by 00158 * Cgu::SharedLockPtr, or by a std::shared_ptr implementation which 00159 * has a thread-safe reference count. (The example below does not do 00160 * that however.) 00161 * 00162 * This is a usage example: 00163 * 00164 * @code 00165 * class Numbers { 00166 * public: 00167 * std::vector<long> get_primes(int n); // calculates the first n primes 00168 * // and puts them in a vector 00169 * ... 00170 * }; 00171 * 00172 * Numbers obj; 00173 * 00174 * // get the first 1,000 primes 00175 * using namespace Cgu; 00176 * 00177 * auto future = Thread::make_future(obj, &Numbers::get_primes, 1000); 00178 * // Thread::make_future() is a wrapper for the equivalent long-hand version required prior to version 2.0.4: 00179 * // auto future = Thread::Future<std::vector<long>>::make(obj, &Numbers::get_primes, 1000); 00180 * 00181 * future->run(); 00182 * ... [ do something else ] ... 00183 * std::vector<long> result(future->get()); 00184 * std::for_each(result.begin(), result.end(), [](long l) {std::cout << l << std::endl;}); 00185 * @endcode 00186 * 00187 * If get_primes() were a static member function or plain function, 00188 * the syntax would be: 00189 * 00190 * @code 00191 * auto future = Thread::make_future(&Numbers::get_primes, 1000); 00192 * @endcode 00193 * 00194 * @b The @b Cgu::Thread::Future::when() @b functions 00195 * 00196 * From version 2.0.2, the return value of the thread function 00197 * represented by Cgu::Thread::Future can be obtained asynchronously 00198 * using Cgu::Thread::Future::when() to execute a function in a glib 00199 * main loop when the thread function completes. The above example 00200 * could be reimplemented as: 00201 * 00202 * @code 00203 * class Numbers { 00204 * public: 00205 * std::vector<long> get_primes(int n); // calculates the first n primes 00206 * // and puts them in a vector 00207 * ... 00208 * }; 00209 * 00210 * void print_primes(const std::vector<long>& result) { 00211 * std::for_each(result.begin(), result.end(), [](long l) {std::cout << l << std::endl;}); 00212 * } 00213 * 00214 * Numbers obj; 00215 * 00216 * using namespace Cgu; 00217 * 00218 * auto future = Thread::make_future(obj, &Numbers::get_primes, 1000); 00219 * future->when(Callback::make(&print_primes)); 00220 * future->run(); 00221 * @endcode 00222 * 00223 * In this example, the callback which prints the primes to the 00224 * console would execute in the default program main loop once the 00225 * thread function providing those primes returns. As an alternative 00226 * to a free standing print_primes() function, the callback object 00227 * could be constructed from a lambda function via a std::function 00228 * object. 00229 * 00230 * @b Overloaded @b functions 00231 * 00232 * Where a member function or ordinary function represented by a 00233 * Thread::Future object is overloaded, this will cause difficulties 00234 * in template type deduction when Thread::Future<>::make() or 00235 * Thread::make_future() are called. With Thread::Future<>::make(), 00236 * functions may be overloaded on numbers of argument without 00237 * difficulty, but not with Thread::make_future(). For example: 00238 * @code 00239 * class Numbers { 00240 * public: 00241 * int calc(int i); 00242 * int calc(int i, int j); 00243 * ... 00244 * }; 00245 * 00246 * Numbers obj; 00247 * 00248 * using namespace Cgu; 00249 * 00250 * int i = 1, j = 2; 00251 * 00252 * auto f1 = 00253 * Thread::Future<int>::make(obj, &Numbers::calc, i); // OK 00254 * auto f2 = 00255 * Thread::Future<int>::make(obj, &Numbers::calc, i, j); // OK 00256 * 00257 * // explicit is disambiguation required with Thread::make_future() 00258 * auto f3 = 00259 * Thread::make_future(obj, static_cast<int(Numbers::*)(int)>(&Numbers::calc), i); 00260 * auto f4 = 00261 * Thread::make_future(obj, static_cast<int(Numbers::*)(int, int)>(&Numbers::calc), i, j); 00262 * @endcode 00263 * Neither Thread::Future<>::make() nor Thread::make_future() can be 00264 * overloaded on types of argument without explicit disambiguation. 00265 * For example: 00266 * @code 00267 * class Numbers { 00268 * public: 00269 * int calc(int i); 00270 * int calc(double d); 00271 * ... 00272 * }; 00273 * 00274 * Numbers obj; 00275 * 00276 * using namespace Cgu; 00277 * 00278 * int i = 1; 00279 * double d = 2.0; 00280 * 00281 * auto f1 = 00282 * Thread::Future<int>::make(obj, static_cast<int (Numbers::*)(int)>(&Numbers::calc), i); 00283 * auto f2 = 00284 * Thread::Future<int>::make(obj, static_cast<int (Numbers::*)(double)>(&Numbers::calc), d); 00285 * auto f3 = 00286 * Thread::make_future(obj, static_cast<int (Numbers::*)(int)>(&Numbers::calc), i); 00287 * auto f4 = 00288 * Thread::make_future(obj, static_cast<int (Numbers::*)(double)>(&Numbers::calc), d); 00289 * @endcode 00290 */ 00291 00292 template <class Val> 00293 class Future: public IntrusiveLockCounter { 00294 00295 std::unique_ptr<Cgu::Thread::Thread> thread_u; 00296 std::unique_ptr<Cgu::Callback::Callback> cb_u; 00297 00298 mutable Mutex mutex; 00299 Cond cond; 00300 Val val; 00301 bool done; 00302 bool running; 00303 bool error; 00304 bool emitter_error; 00305 00306 template <class T, class Ret, class... Args> 00307 void run_wrapper(T*, Ret (T::*)(Args...), const Args&...); 00308 00309 template <class T, class Ret, class... Args> 00310 void run_wrapper_const(const T*, Ret (T::*)(Args...) const, const Args&...); 00311 00312 template <class Ret, class... Args> 00313 void run_wrapper_static(Ret (*)(Args...), const Args&...); 00314 00315 void run_wrapper_func(const std::function<Val(void)>&); 00316 00317 void cancel_cleanup(); 00318 00319 void execute_done(const Cgu::Callback::SafeFunctorArg<const Val&>&); 00320 void post_done(const Cgu::Callback::SafeFunctorArg<const Val&>&, 00321 gint, GMainContext*); 00322 void execute_done_rel(const Cgu::SharedLockPtr<Cgu::SafeEmitterArg<const Val&>>&); 00323 void post_done_rel(const Cgu::SharedLockPtr<Cgu::SafeEmitterArg<const Val&>>&, 00324 gint, GMainContext*); 00325 00326 // this is a static function taking the future object by IntrusivePtr to 00327 // ensure that the future object remains in existence whilst this 00328 // function might execute 00329 static void fail_cb(const Cgu::IntrusivePtr<Future<Val>>& future, 00330 const Cgu::Callback::SafeFunctor& func, 00331 bool& ret); 00332 00333 // private constructor - this class can only be created with Thread::Future::make() 00334 Future(): val(), done(false), running(false), error(false), emitter_error(false) {} 00335 00336 public: 00337 00338 // this class cannot be copied except by smart pointer 00339 /** 00340 * This class cannot be copied (except by smart pointer). The copy 00341 * constructor is deleted. 00342 */ 00343 Future(const Future&) = delete; 00344 00345 /** 00346 * This class cannot be copied (except by smart pointer). The 00347 * assignment operator is deleted. 00348 */ 00349 Future& operator=(const Future&) = delete; 00350 00351 /** 00352 * Constructs a new Cgu::Thread::Future object (returned by 00353 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00354 * Val represents the return value of the function to be represented 00355 * by the new object. From version 2.0.4, it will usually be more 00356 * convenient to call the Cgu::Thread::make_future() function, which 00357 * is a convenience wrapper for this static method. 00358 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00359 * is exhausted and the system throws in that case. (This exception 00360 * will not be thrown if the library has been installed using the 00361 * --with-glib-memory-slices-no-compat configuration option: instead 00362 * glib will terminate the program if it is unable to obtain memory 00363 * from the operating system.) It will also throw if the default 00364 * constructor of the return value type throws. 00365 */ 00366 template <class Ret, class T> 00367 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(T& t, 00368 Ret (T::*func)()); 00369 00370 /** 00371 * Constructs a new Cgu::Thread::Future object (returned by 00372 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00373 * Val represents the return value of the function to be represented 00374 * by the new object. From version 2.0.4, it will usually be more 00375 * convenient to call the Cgu::Thread::make_future() function, which 00376 * is a convenience wrapper for this static method. 00377 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00378 * is exhausted and the system throws in that case. (This exception 00379 * will not be thrown if the library has been installed using the 00380 * --with-glib-memory-slices-no-compat configuration option: instead 00381 * glib will terminate the program if it is unable to obtain memory 00382 * from the operating system.) It will also throw if the copy 00383 * constructor or assignment operator of the bound argument throws, or 00384 * the default constructor of the return value type throws. 00385 */ 00386 template <class Ret, class Param1, class Arg1, class T> 00387 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(T& t, 00388 Ret (T::*func)(Param1), 00389 Arg1&& arg1); 00390 00391 /** 00392 * Constructs a new Cgu::Thread::Future object (returned by 00393 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00394 * Val represents the return value of the function to be represented 00395 * by the new object. From version 2.0.4, it will usually be more 00396 * convenient to call the Cgu::Thread::make_future() function, which 00397 * is a convenience wrapper for this static method. 00398 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00399 * is exhausted and the system throws in that case. (This exception 00400 * will not be thrown if the library has been installed using the 00401 * --with-glib-memory-slices-no-compat configuration option: instead 00402 * glib will terminate the program if it is unable to obtain memory 00403 * from the operating system.) It will also throw if the copy 00404 * constructor or assignment operator of a bound argument throws, or 00405 * the default constructor of the return value type throws. 00406 */ 00407 template <class Ret, class Param1, class Param2, class Arg1, class Arg2, class T> 00408 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(T& t, 00409 Ret (T::*func)(Param1, Param2), 00410 Arg1&& arg1, 00411 Arg2&& arg2); 00412 00413 /** 00414 * Constructs a new Cgu::Thread::Future object (returned by 00415 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00416 * Val represents the return value of the function to be represented 00417 * by the new object. From version 2.0.4, it will usually be more 00418 * convenient to call the Cgu::Thread::make_future() function, which 00419 * is a convenience wrapper for this static method. 00420 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00421 * is exhausted and the system throws in that case. (This exception 00422 * will not be thrown if the library has been installed using the 00423 * --with-glib-memory-slices-no-compat configuration option: instead 00424 * glib will terminate the program if it is unable to obtain memory 00425 * from the operating system.) It will also throw if the copy 00426 * constructor or assignment operator of a bound argument throws, or 00427 * the default constructor of the return value type throws. 00428 */ 00429 template <class Ret, class Param1, class Param2, class Param3, 00430 class Arg1, class Arg2, class Arg3, class T> 00431 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(T& t, 00432 Ret (T::*func)(Param1, Param2, Param3), 00433 Arg1&& arg1, 00434 Arg2&& arg2, 00435 Arg3&& arg3); 00436 00437 /** 00438 * Constructs a new Cgu::Thread::Future object (returned by 00439 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00440 * Val represents the return value of the function to be represented 00441 * by the new object. From version 2.0.4, it will usually be more 00442 * convenient to call the Cgu::Thread::make_future() function, which 00443 * is a convenience wrapper for this static method. 00444 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00445 * is exhausted and the system throws in that case. (This exception 00446 * will not be thrown if the library has been installed using the 00447 * --with-glib-memory-slices-no-compat configuration option: instead 00448 * glib will terminate the program if it is unable to obtain memory 00449 * from the operating system.) It will also throw if the default 00450 * constructor of the return value type throws. 00451 */ 00452 template <class Ret, class T> 00453 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(const T& t, 00454 Ret (T::*func)() const); 00455 00456 /** 00457 * Constructs a new Cgu::Thread::Future object (returned by 00458 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00459 * Val represents the return value of the function to be represented 00460 * by the new object. From version 2.0.4, it will usually be more 00461 * convenient to call the Cgu::Thread::make_future() function, which 00462 * is a convenience wrapper for this static method. 00463 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00464 * is exhausted and the system throws in that case. (This exception 00465 * will not be thrown if the library has been installed using the 00466 * --with-glib-memory-slices-no-compat configuration option: instead 00467 * glib will terminate the program if it is unable to obtain memory 00468 * from the operating system.) It will also throw if the copy 00469 * constructor or assignment operator of the bound argument throws, or 00470 * the default constructor of the return value type throws. 00471 */ 00472 template <class Ret, class Param1, class Arg1, class T> 00473 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(const T& t, 00474 Ret (T::*func)(Param1) const, 00475 Arg1&& arg1); 00476 00477 /** 00478 * Constructs a new Cgu::Thread::Future object (returned by 00479 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00480 * Val represents the return value of the function to be represented 00481 * by the new object. From version 2.0.4, it will usually be more 00482 * convenient to call the Cgu::Thread::make_future() function, which 00483 * is a convenience wrapper for this static method. 00484 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00485 * is exhausted and the system throws in that case. (This exception 00486 * will not be thrown if the library has been installed using the 00487 * --with-glib-memory-slices-no-compat configuration option: instead 00488 * glib will terminate the program if it is unable to obtain memory 00489 * from the operating system.) It will also throw if the copy 00490 * constructor or assignment operator of a bound argument throws, or 00491 * the default constructor of the return value type throws. 00492 */ 00493 template <class Ret, class Param1, class Param2, class Arg1, class Arg2, class T> 00494 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(const T& t, 00495 Ret (T::*func)(Param1, Param2) const, 00496 Arg1&& arg1, 00497 Arg2&& arg2); 00498 00499 /** 00500 * Constructs a new Cgu::Thread::Future object (returned by 00501 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00502 * Val represents the return value of the function to be represented 00503 * by the new object. From version 2.0.4, it will usually be more 00504 * convenient to call the Cgu::Thread::make_future() function, which 00505 * is a convenience wrapper for this static method. 00506 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00507 * is exhausted and the system throws in that case. (This exception 00508 * will not be thrown if the library has been installed using the 00509 * --with-glib-memory-slices-no-compat configuration option: instead 00510 * glib will terminate the program if it is unable to obtain memory 00511 * from the operating system.) It will also throw if the copy 00512 * constructor or assignment operator of a bound argument throws, or 00513 * the default constructor of the return value type throws. 00514 */ 00515 template <class Ret, class Param1, class Param2, class Param3, 00516 class Arg1, class Arg2, class Arg3, class T> 00517 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(const T& t, 00518 Ret (T::*func)(Param1, Param2, Param3) const, 00519 Arg1&& arg1, 00520 Arg2&& arg2, 00521 Arg3&& arg3); 00522 00523 /** 00524 * Constructs a new Cgu::Thread::Future object (returned by 00525 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00526 * Val represents the return value of the function to be represented 00527 * by the new object. From version 2.0.4, it will usually be more 00528 * convenient to call the Cgu::Thread::make_future() function, which 00529 * is a convenience wrapper for this static method. 00530 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00531 * is exhausted and the system throws in that case. (This exception 00532 * will not be thrown if the library has been installed using the 00533 * --with-glib-memory-slices-no-compat configuration option: instead 00534 * glib will terminate the program if it is unable to obtain memory 00535 * from the operating system.) It will also throw if the default 00536 * constructor of the return value type throws. 00537 */ 00538 template <class Ret> 00539 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)()); 00540 00541 /** 00542 * Constructs a new Cgu::Thread::Future object (returned by 00543 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00544 * Val represents the return value of the function to be represented 00545 * by the new object. From version 2.0.4, it will usually be more 00546 * convenient to call the Cgu::Thread::make_future() function, which 00547 * is a convenience wrapper for this static method. 00548 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00549 * is exhausted and the system throws in that case. (This exception 00550 * will not be thrown if the library has been installed using the 00551 * --with-glib-memory-slices-no-compat configuration option: instead 00552 * glib will terminate the program if it is unable to obtain memory 00553 * from the operating system.) It will also throw if the copy 00554 * constructor or assignment operator of the bound argument throws, or 00555 * the default constructor of the return value type throws. 00556 */ 00557 template <class Ret, class Param1, class Arg1> 00558 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1), 00559 Arg1&& arg1); 00560 00561 /** 00562 * Constructs a new Cgu::Thread::Future object (returned by 00563 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00564 * Val represents the return value of the function to be represented 00565 * by the new object. From version 2.0.4, it will usually be more 00566 * convenient to call the Cgu::Thread::make_future() function, which 00567 * is a convenience wrapper for this static method. 00568 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00569 * is exhausted and the system throws in that case. (This exception 00570 * will not be thrown if the library has been installed using the 00571 * --with-glib-memory-slices-no-compat configuration option: instead 00572 * glib will terminate the program if it is unable to obtain memory 00573 * from the operating system.) It will also throw if the copy 00574 * constructor or assignment operator of a bound argument throws, or 00575 * the default constructor of the return value type throws. 00576 */ 00577 template <class Ret, class Param1, class Param2, class Arg1, class Arg2> 00578 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1, Param2), 00579 Arg1&& arg1, 00580 Arg2&& arg2); 00581 00582 /** 00583 * Constructs a new Cgu::Thread::Future object (returned by 00584 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00585 * Val represents the return value of the function to be represented 00586 * by the new object. From version 2.0.4, it will usually be more 00587 * convenient to call the Cgu::Thread::make_future() function, which 00588 * is a convenience wrapper for this static method. 00589 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00590 * is exhausted and the system throws in that case. (This exception 00591 * will not be thrown if the library has been installed using the 00592 * --with-glib-memory-slices-no-compat configuration option: instead 00593 * glib will terminate the program if it is unable to obtain memory 00594 * from the operating system.) It will also throw if the copy 00595 * constructor or assignment operator of a bound argument throws, or 00596 * the default constructor of the return value type throws. 00597 */ 00598 template <class Ret, class Param1, class Param2, class Param3, 00599 class Arg1, class Arg2, class Arg3> 00600 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1, Param2, Param3), 00601 Arg1&& arg1, 00602 Arg2&& arg2, 00603 Arg3&& arg3); 00604 00605 /** 00606 * Constructs a new Cgu::Thread::Future object (returned by 00607 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00608 * Val represents the return value of the function to be represented 00609 * by the new object. From version 2.0.4, it will usually be more 00610 * convenient to call the Cgu::Thread::make_future() function, which 00611 * is a convenience wrapper for this static method. 00612 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00613 * is exhausted and the system throws in that case. (This exception 00614 * will not be thrown if the library has been installed using the 00615 * --with-glib-memory-slices-no-compat configuration option: instead 00616 * glib will terminate the program if it is unable to obtain memory 00617 * from the operating system.) It will also throw if the copy 00618 * constructor or assignment operator of a bound argument throws, or 00619 * the default constructor of the return value type throws. 00620 */ 00621 template <class Ret, class Param1, class Param2, class Param3, class Param4, 00622 class Arg1, class Arg2, class Arg3, class Arg4> 00623 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(Ret (*func)(Param1, Param2, Param3, Param4), 00624 Arg1&& arg1, 00625 Arg2&& arg2, 00626 Arg3&& arg3, 00627 Arg4&& arg4); 00628 00629 /** 00630 * Constructs a new Cgu::Thread::Future object (returned by 00631 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00632 * Val represents the return value of the function to be represented 00633 * by the new object. From version 2.0.4, it will usually be more 00634 * convenient to call the Cgu::Thread::make_future() function, which 00635 * is a convenience wrapper for this static method. 00636 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00637 * is exhausted and the system throws in that case. (This exception 00638 * will not be thrown if the library has been installed using the 00639 * --with-glib-memory-slices-no-compat configuration option: instead 00640 * glib will terminate the program if it is unable to obtain memory 00641 * from the operating system.) It will also throw if the copy 00642 * constructor or assignment operator of a bound argument throws, or 00643 * the default constructor of the return value type throws. 00644 */ 00645 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(const std::function<Val(void)>& func); 00646 00647 /** 00648 * Constructs a new Cgu::Thread::Future object (returned by 00649 * Cgu::IntrusivePtr<Cgu::Thread::Future<Val>>). The type parameter 00650 * Val represents the return value of the function to be represented 00651 * by the new object. From version 2.0.4, it will usually be more 00652 * convenient to call the Cgu::Thread::make_future() function, which 00653 * is a convenience wrapper for this static method. 00654 * @exception std::bad_alloc It might throw std::bad_alloc if memory 00655 * is exhausted and the system throws in that case. (This exception 00656 * will not be thrown if the library has been installed using the 00657 * --with-glib-memory-slices-no-compat configuration option: instead 00658 * glib will terminate the program if it is unable to obtain memory 00659 * from the operating system.) It will also throw if the copy 00660 * constructor or assignment operator of a bound argument throws, or 00661 * the default constructor of the return value type throws. 00662 */ 00663 static Cgu::IntrusivePtr<Cgu::Thread::Future<Val>> make(std::function<Val(void)>&& func); 00664 00665 /** 00666 * Runs the function represented by this Cgu::Thread::Future object in 00667 * a new worker thread. That function will only be run once. If this 00668 * is the first time this method has been called, it will start the 00669 * worker thread and return true, and if it has previously been 00670 * called, this method will do nothing and return false. This method 00671 * is thread safe and may be called by a different thread from the one 00672 * which called make(). 00673 * @return true if this is the first time this method has been called, 00674 * or false if this method has previously been called. 00675 * @exception Cgu::Thread::FutureThreadError This method might throw 00676 * Cgu::Thread::FutureThreadError if it has not previously been called 00677 * and the thread did not start properly. If it does throw, this 00678 * Cgu::Thread::Future object is defunct and further attempts to call 00679 * this method will return immediately with a false value. (It is 00680 * often not worth checking for this exception, as it means either 00681 * memory is exhausted, the pthread thread limit has been reached or 00682 * pthread has run out of other resources to start new threads.) 00683 * @exception std::bad_alloc This method might throw std::bad_alloc if 00684 * it has not previously been called, and memory is exhausted and the 00685 * system throws in that case. If it does throw, this 00686 * Cgu::Thread::Future object is defunct and further attempts to call 00687 * this method will return immediately with a false value. (This 00688 * exception will not be thrown if the library has been installed 00689 * using the --with-glib-memory-slices-no-compat configuration option: 00690 * instead glib will terminate the program if it is unable to obtain 00691 * memory from the operating system.) 00692 * @note 1. Any Cgu::Thread::Exit exception, or any uncaught exception 00693 * derived from std::exception, which is thrown from the worker thread 00694 * will be caught and consumed and the error flag will be set. The 00695 * worker thread will safely terminate and unwind the stack in so 00696 * doing. 00697 * @note 2. As this wrapper class can provide error reporting in a way 00698 * that Cgu::Thread::Thread of itself cannot, it would be desirable to 00699 * consume any other uncaught exceptions. However, this cannot be 00700 * done: annoyingly, NPTL's forced stack unwinding does not allow this 00701 * if thread cancellation is to be made available. If an uncaught 00702 * exception propagates out of a thread when the thread exits, the 00703 * C++11 standard will cause std::terminate() to be called and so 00704 * terminate the entire program. Accordingly, a user must make sure 00705 * that no exceptions, other than Cgu::Thread::Exit or those derived 00706 * from std::exception or any cancellation pseudo-exception, can 00707 * propagate from the function which this Cgu::Thread::Future object 00708 * represents. 00709 * @note 3. If the worker thread is cancelled by a call to cancel() 00710 * while in the middle of executing the function which this 00711 * Cgu::Thread::Future object represents, the error flag will be set. 00712 */ 00713 bool run(); 00714 00715 /** 00716 * Gets the value obtained from the function which is represented by 00717 * this object. If the worker thread launched by the call to run() 00718 * has not completed, then this method will block until it has 00719 * completed. If run() has not been called, then run() will be called 00720 * (and this method will block until the launched worker thread 00721 * completes). If the function which is represented by this object 00722 * throws Cgu::Thread::Exit or an uncaught exception derived from 00723 * std::exception, then the exception will have been consumed by this 00724 * Cgu::Thread::Future object and the error flag will have been set. 00725 * The error flag will also have been set if the worker thread is 00726 * cancelled or the thread wrapper in this Cgu::Thread::Future object 00727 * threw std::bad_alloc. This method is thread safe and may be called 00728 * by any thread (and by more than one thread). It is also strongly 00729 * exception safe: no data will be lost if extracting the value fails. 00730 * @return The value obtained from the function which is represented 00731 * by this object 00732 * @exception Cgu::Thread::FutureThreadError This method might throw 00733 * Cgu::Thread::FutureThreadError if run() has not previously been 00734 * called and the thread did not start properly when this function 00735 * called run(). 00736 * @exception std::bad_alloc This method might throw std::bad_alloc if 00737 * run() has not previously been called, memory is exhausted and the 00738 * system throws in that case. (This exception will not be thrown if 00739 * the library has been installed using the 00740 * --with-glib-memory-slices-no-compat configuration option: instead 00741 * glib will terminate the program if it is unable to obtain memory 00742 * from the operating system.) 00743 * @note This method might also throw if the copy constructor or 00744 * assignment operator of the returned value type throws. 00745 */ 00746 Val get(); 00747 00748 /** 00749 * Cancels the worker thread in which the function represented by this 00750 * object runs, if that function has not yet finished. If this method 00751 * is called and the worker thread is still running and is cancelled 00752 * in response to a call to this method, then the error flag will be 00753 * set so that a method calling get() can examine whether the result 00754 * is valid. If run() has not yet been called or the worker thread 00755 * has already finished executing the function represented by this 00756 * object then this function does nothing and returns false. This 00757 * method is thread safe and may be called by any thread. It will not 00758 * throw. 00759 * @return true if run() has previously been called and the worker 00760 * thread has not yet finished executing the function represented by 00761 * this object, otherwise false (in which case this method does 00762 * nothing). 00763 * @note 1. Use this method with care. When cancelling a thread not 00764 * all thread implementations will unwind the stack, and so run the 00765 * destructors of local objects. This is discussed further in the 00766 * documentation on Cgu::Thread::Thread::cancel(). 00767 * @note 2. This method might return true because the worker thread 00768 * has not yet finished, but the error flag might still not be set. 00769 * This is because the worker thread may not meet a cancellation point 00770 * before it ends naturally. It is the error flag which indicates 00771 * definitively whether the worker thread terminated prematurely in 00772 * response to a call to this method. 00773 */ 00774 bool cancel(); 00775 00776 /** 00777 * A utility enabling the value returned by the thread function 00778 * represented by this Cgu::Thread::Future object to be dealt with 00779 * asynchronously rather than by (or in addition to) a call to the 00780 * get() method. It causes the callback passed as an argument to this 00781 * method (referred to below as the 'when' callback) to be executed by 00782 * a thread's main loop if and when the thread function represented by 00783 * this Cgu::Thread::Future object finishes correctly - the 'when' 00784 * callback is passed that thread function's return value when it is 00785 * invoked. This method is thread safe, and may be called by any 00786 * thread. 00787 * 00788 * This functionality is implemented by connecting an internal 00789 * dispatching callback to the done_emitter object. 00790 * 00791 * The 'when' callback should take a single unbound argument 00792 * comprising a const reference to the return type of the thread 00793 * function represented by this Cgu::Thread::Future object. (So, in 00794 * the case of a Future<int> object, the callback function should take 00795 * a const int& argument as the unbound argument.) The 'when' 00796 * callback can have any number of bound arguments, except that a 00797 * bound argument may not include a copy of this Cgu::Thread::Future 00798 * object held by intrusive pointer as returned by the make() methods 00799 * (that would result in this Cgu::Thread::Future object owning, via 00800 * done_emitter, a reference to itself and so become incapable of 00801 * being freed). The 'when' callback may, however, take a pointer to 00802 * this Cgu::Thread::Future object, as obtained by the 00803 * Cgu::IntrusivePtr::get() method, because this Cgu::Thread::Future 00804 * object is guaranteed to remain in existence until the callback has 00805 * completed executing. 00806 * 00807 * This method cannot be called after the thread function represented 00808 * by this Cgu::Thread::Future object has completed (either 00809 * successfully or unsuccessfully) so that is_done() would return 00810 * true, and if this is attempted a Cgu::Thread::FutureWhenError 00811 * exception will be thrown. Therefore, generally this method should 00812 * be called before the run() method has been called. 00813 * 00814 * Once the run() method has been called, this Cgu::Thread::Future 00815 * object will always stay in existence until the thread function 00816 * represented by it has completed (whether correctly, by cancellation 00817 * or by a thrown exception), and any 'when' callback (and any other 00818 * callbacks connected to the done_emitter object) and any 'fail' 00819 * callback have completed. Accordingly it is safe to use this method 00820 * even if the intrusive pointer object returned by the make() methods 00821 * will go out of scope before the 'when' callback has executed: the 00822 * callback will execute correctly irrespective of that. 00823 * 00824 * Summary: use of this method is safe and has been implemented in a 00825 * way which does not give rise to timing issues. 00826 * 00827 * If memory is exhausted and std::bad_alloc is thrown by the thread 00828 * wrapper of Cgu::Thread::Future after run() is called or by 00829 * done_emitter when emitting, or if the thread function represented 00830 * by this Cgu::Thread::Future object throws Cgu::Thread::Exit, exits 00831 * with an uncaught exception deriving from std::exception or is 00832 * cancelled, or if the copy constructor of a non-reference bound 00833 * argument of the 'when' callback throws, or any other callback has 00834 * been connected to done_emitter before this method is called which 00835 * exits with an uncaught exception, then the 'when' callback will not 00836 * execute (instead the exception concerned will be consumed and an 00837 * error indicated). With many systems, swap memory combined with 00838 * memory over-commit makes it pointless to check for std::bad_alloc 00839 * (and even more so in programs using glib, as glib aborts a program 00840 * where it cannot obtain memory from the operating system). So 00841 * subject to that, if the user program is designed so that the thread 00842 * function represented by this Cgu::Thread::Future object does not 00843 * exit with uncaught exceptions, does not throw Cgu::Thread::Exit and 00844 * is not cancelled, and so that the 'when' callback does not exit 00845 * with an uncaught exception and either has no non-reference bound 00846 * arguments or the copy constructors of any non-reference bound 00847 * arguments do not throw, and if this method is called before any 00848 * other callbacks are connected to done_emitter, the possibility of 00849 * failure can be disregarded. 00850 * 00851 * In cases where that is not true and detecting whether a failure has 00852 * occurred is required, a fail() method is provided. It should be 00853 * noted that a callback handed to the fail() method will not execute 00854 * in a case of error if the error comprises the 'when' callback 00855 * exiting with an uncaught exception when it is executed by the main 00856 * loop, or the copy constructor of one of its non-reference bound 00857 * arguments throwing when it executes (such an exception would be 00858 * consumed internally in order to protect the main loop and a 00859 * g_critical message issued). If the 'when' callback might exit with 00860 * an uncaught exception when executing or have the copy constructor 00861 * of a non-reference bound argument throw, and doing something other 00862 * than consuming the exception and issuing a g_critical message is 00863 * required, then a different approach is to start a new thread to 00864 * wait on the get() method which can act on the result of is_error() 00865 * directly. 00866 * 00867 * If glib < 2.32 is used, the glib main loop must have been made 00868 * thread-safe by a call to g_thread_init() before this function is 00869 * called. glib >= 2.32 does not require g_thread_init() to be called 00870 * in order to be thread safe. 00871 * 00872 * @param cb The 'when' callback (the callback to be executed when the 00873 * function represented by this Cgu::Thread::Future object has 00874 * successfully completed). Ownership is taken of this object, and it 00875 * will be deleted when it has been finished with. 00876 * @param priority The priority to be given to the 'when' callback in 00877 * the main loop after the thread function represented by this 00878 * Cgu::Thread::Future object has successfully completed. In 00879 * ascending order of priorities, priorities are G_PRIORITY_LOW, 00880 * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT 00881 * and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT. This 00882 * determines the order in which the callback will appear in the event 00883 * list in the main loop, not the priority which the OS will adopt. 00884 * @param context The glib main context of the thread in whose main 00885 * loop the 'when' callback is to be executed (the default of NULL 00886 * will cause the callback to be executed in the main program loop). 00887 * @return The internal dispatching callback created by this method 00888 * and connected to done_emitter. It is made available as a return 00889 * value so that if wanted it can be disconnected programmatically 00890 * from done_emitter, or block()/unblock() can be called on it (but if 00891 * that is to be done, it must be done before the thread function 00892 * represented by this Cgu::Thread::Future object has completed in 00893 * order for it to be effective). 00894 * @exception Cgu::Thread::FutureWhenError This method will throw 00895 * Cgu::Thread::FutureWhenError if it is called after the thread 00896 * function represented by this Cgu::Thread::Future object has 00897 * completed. If it does so, the 'when' callback will be disposed of. 00898 * @exception std::bad_alloc This method might throw std::bad_alloc if 00899 * memory is exhausted and the system throws in that case. If it does 00900 * so, the 'when' callback will be disposed of. 00901 * @note The return value of the function represented by the 00902 * Cgu::Thread::Future object is passed as an argument to the callback 00903 * by const reference. This should be taken into account if the 00904 * return value is of class type and other threads might access it 00905 * concurrently via the get() method by const reference (that is, 00906 * without copying it), where any of that return value's const methods 00907 * are not thread safe. 00908 * 00909 * Since 2.0.2 00910 */ 00911 Cgu::Callback::SafeFunctor when(const Cgu::Callback::CallbackArg<const Val&>* cb, 00912 gint priority = G_PRIORITY_DEFAULT, 00913 GMainContext* context = 0); 00914 00915 /** 00916 * This is a version of the utility enabling the value returned by the 00917 * thread function represented by this Cgu::Thread::Future object to 00918 * be dealt with asynchronously, which takes a Releaser object for 00919 * automatic disconnection of the callback passed as an argument to 00920 * this method (referred to below as the 'when' callback), if the 00921 * object having the 'when' callback function as a member is 00922 * destroyed. For this to be race free, the lifetime of that object 00923 * must be controlled by the thread in whose main loop the 'when' 00924 * callback will execute. 00925 * 00926 * If the 'when' callback has not been released, this method causes it 00927 * to be executed by a thread's main loop if and when the thread 00928 * function represented by this Cgu::Thread::Future object finishes 00929 * correctly - the 'when' callback is passed that thread function's 00930 * return value when it is invoked. This method is thread safe, and 00931 * may be called by any thread. 00932 * 00933 * This functionality is implemented by connecting an internal 00934 * dispatching callback to the done_emitter object. 00935 * 00936 * The 'when' callback should take a single unbound argument 00937 * comprising a const reference to the return type of the thread 00938 * function represented by this Cgu::Thread::Future object. (So, in 00939 * the case of a Future<int> object, the callback function should take 00940 * a const int& argument as the unbound argument.) The 'when' 00941 * callback can have any number of bound arguments, except that a 00942 * bound argument may not include a copy of this Cgu::Thread::Future 00943 * object held by intrusive pointer as returned by the make() methods 00944 * (that would result in this Cgu::Thread::Future object owning, via 00945 * done_emitter, a reference to itself and so become incapable of 00946 * being freed). The 'when' callback may, however, take a pointer to 00947 * this Cgu::Thread::Future object, as obtained by the 00948 * Cgu::IntrusivePtr::get() method, because this Cgu::Thread::Future 00949 * object is guaranteed to remain in existence until the callback has 00950 * completed executing. 00951 * 00952 * This method cannot be called after the thread function represented 00953 * by this Cgu::Thread::Future object has completed (either 00954 * successfully or unsuccessfully) so that is_done() would return 00955 * true, and if this is attempted a Cgu::Thread::FutureWhenError 00956 * exception will be thrown. Therefore, generally this method should 00957 * be called before the run() method has been called. 00958 * 00959 * The documentation for the version of this method which does not 00960 * take a Releaser object gives further details of how this method is 00961 * used. 00962 * 00963 * If glib < 2.32 is used, the glib main loop must have been made 00964 * thread-safe by a call to g_thread_init() before this function is 00965 * called. glib >= 2.32 does not require g_thread_init() to be called 00966 * in order to be thread safe. 00967 * 00968 * @param cb The 'when' callback (the callback to be executed when the 00969 * function represented by this Cgu::Thread::Future object has 00970 * successfully completed). Ownership is taken of this object, and it 00971 * will be deleted when it has been finished with. 00972 * @param r A Releaser object for automatic disconnection of the 00973 * 'when' callback if the object of which the callback function is a 00974 * member is destroyed. 00975 * @param priority The priority to be given to the 'when' callback in 00976 * the main loop after the thread function represented by this 00977 * Cgu::Thread::Future object has successfully completed. In 00978 * ascending order of priorities, priorities are G_PRIORITY_LOW, 00979 * G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT 00980 * and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT. This 00981 * determines the order in which the callback will appear in the event 00982 * list in the main loop, not the priority which the OS will adopt. 00983 * @param context The glib main context of the thread in whose main 00984 * loop the 'when' callback is to be executed (the default of NULL 00985 * will cause the callback to be executed in the main program loop). 00986 * @return The internal dispatching callback created by this method 00987 * and connected to done_emitter. It is made available as a return 00988 * value so that if wanted it can be disconnected programmatically 00989 * from done_emitter, or block()/unblock() can be called on it (but if 00990 * that is to be done, it must be done before the thread function 00991 * represented by this Cgu::Thread::Future object has completed in 00992 * order for it to be effective). 00993 * @exception Cgu::Thread::FutureWhenError This method will throw 00994 * Cgu::Thread::FutureWhenError if it is called after the thread 00995 * function represented by this Cgu::Thread::Future object has 00996 * completed. If it does so, the 'when' callback will be disposed of. 00997 * @exception std::bad_alloc This method might throw std::bad_alloc if 00998 * memory is exhausted and the system throws in that case. If it does 00999 * so, the 'when' callback will be disposed of. 01000 * @exception Cgu::Thread::MutexError This method will throw 01001 * Cgu:Thread::MutexError if initialisation of the mutex in a 01002 * SafeEmitterArg object constructed by this method fails. If it does 01003 * so, the 'when' callback will be disposed of. (It is often not 01004 * worth checking for this, as it means either memory is exhausted or 01005 * pthread has run out of other resources to create new mutexes.) 01006 * @note The return value of the function represented by the 01007 * Cgu::Thread::Future object is passed as an argument to the callback 01008 * by const reference. This should be taken into account if the 01009 * return value is of class type and other threads might access it 01010 * concurrently via the get() method by const reference (that is, 01011 * without copying it), where any of that return value's const methods 01012 * are not thread safe. 01013 * 01014 * Since 2.0.2 01015 */ 01016 Cgu::Callback::SafeFunctor when(const Cgu::Callback::CallbackArg<const Val&>* cb, 01017 Cgu::Releaser& r, 01018 gint priority = G_PRIORITY_DEFAULT, 01019 GMainContext* context = 0); 01020 01021 /** 01022 * A utility intended to be used where relevant in conjunction with 01023 * the when() methods. It enables a callback to be executed in a glib 01024 * main loop (referred to below as the 'fail' callback) if memory is 01025 * exhausted and std::bad_alloc was thrown by the thread wrapper of 01026 * Cgu::Thread::Future after calling run() or by done_emitter when 01027 * emitting, or if the thread function represented by this 01028 * Cgu::Thread::Future object threw Cgu::Thread::Exit, exited with an 01029 * uncaught exception deriving from std::exception or was cancelled, 01030 * or any callback connected to done_emitter exited with an uncaught 01031 * exception. It therefore enables errors to be detected and acted on 01032 * without having a thread wait on the get() method in order to test 01033 * is_error() or is_emitter_error(). 01034 * 01035 * It is implemented by attaching a timeout to the main loop which 01036 * polls at 100 millisecond intervals and tests is_done()/is_error() 01037 * and is_emitter_done()/is_emitter_error(). The timeout is 01038 * automatically removed by the implementation once it has been 01039 * detected that an error has occurred and the 'fail' callback is 01040 * executed, or if the thread function represented by this Cgu::Future 01041 * object and all done_emitter emissions (including execution of any 01042 * 'when' callback) have completed successfully. 01043 * 01044 * This method can be called before or after the run() method has been 01045 * called, and whether or not the thread function represented by this 01046 * Cgu::Thread::Future object has completed. 01047 * 01048 * Once this method has been called, this Cgu::Thread::Future object 01049 * will always stay in existence until the timeout has been 01050 * automatically removed by the implementation. Accordingly it is 01051 * safe to use this method even if the intrusive pointer object 01052 * returned by the make() methods will go out of scope before the 01053 * 'fail' callback has executed: the callback will execute correctly 01054 * irrespective of that. 01055 * 01056 * This method does not have a priority argument: as a polling timeout 01057 * is created, a particular priority will normally have no 01058 * significance (in fact, the 'fail' callback will execute in the main 01059 * loop with a priority of G_PRIORITY_DEFAULT). If in a special case 01060 * a different polling interval than 100 milliseconds or a different 01061 * priority is required, users can attach their own polling timeouts 01062 * to a main loop and carry out the tests by hand. 01063 * 01064 * Four other points should be noted. First, if as well as the when() 01065 * method being called some other callback has been connected to 01066 * done_emitter, and that other callback throws, the 'fail' callback 01067 * will execute. Therefore, if the particular program design requires 01068 * that the 'fail' callback should only execute if the thread function 01069 * represented by this Cgu::Thread::Future object did not complete 01070 * successfully or emitting the 'when' callback failed, no other 01071 * callbacks which throw should be connected to done_emitter. 01072 * 01073 * Secondly, as mentioned in the documentation on the when() method, 01074 * if the 'when' callback exits with an uncaught exception upon being 01075 * executed by the main loop or has a non-reference bound argument 01076 * whose copy constructor throws when it executes, the 'fail' callback 01077 * will not execute (the exception will have been consumed internally 01078 * in order to protect the main loop and a g_critical message issued). 01079 * 01080 * Thirdly, avoid if possible having the 'fail' callback represent a 01081 * function which might throw or which has a non-reference bound 01082 * argument whose copy constructor might throw (such an exception 01083 * would be consumed internally in order to protect the main loop and 01084 * a g_critical message issued, but no other error indication apart 01085 * from the g_critical message will be provided). 01086 * 01087 * Fourthly, unlike the 'when' callback, a copy of this 01088 * Cgu::Thread::Future object held by intrusive pointer as returned by 01089 * the make() methods may safely be bound to the 'fail' callback, 01090 * which would enable the 'fail' callback to determine whether it is 01091 * is_error() or is_emitter_error() which returns false. 01092 * 01093 * If glib < 2.32 is used, the glib main loop must have been made 01094 * thread-safe by a call to g_thread_init() before this function is 01095 * called. glib >= 2.32 does not require g_thread_init() to be called 01096 * in order to be thread safe. 01097 * 01098 * @param cb The 'fail' callback (the callback to be executed if the 01099 * thread function represented by this Cgu::Thread::Future object or a 01100 * done_emitter emission has failed to complete). Ownership is taken 01101 * of this object, and it will be deleted when it has been finished 01102 * with. 01103 * @param context The glib main context of the thread in whose main 01104 * loop the 'fail' callback is to be executed (the default of NULL 01105 * will cause the functor to be executed in the main program loop). 01106 * @exception std::bad_alloc This method might throw std::bad_alloc if 01107 * memory is exhausted and the system throws in that case. If it does 01108 * so, the 'fail' callback will be disposed of. 01109 * 01110 * Since 2.0.2 01111 */ 01112 void fail(const Cgu::Callback::Callback* cb, 01113 GMainContext* context = 0); 01114 01115 /** 01116 * This is a version of the fail() utility for use in conjunction with 01117 * the when() methods, which takes a Releaser object for automatic 01118 * disconnection of the callback functor passed as an argument to this 01119 * method if the object having the callback function as a member is 01120 * destroyed. 01121 * 01122 * This method enables a callback to be executed in a glib main loop 01123 * if memory is exhausted and std::bad_alloc was thrown by the thread 01124 * wrapper of Cgu::Thread::Future after calling run() or by 01125 * done_emitter when emitting, or if the thread function represented 01126 * by this Cgu::Thread::Future object threw Cgu::Thread::Exit, exited 01127 * with an uncaught exception deriving from std::exception or was 01128 * cancelled, or any callback connected to done_emitter exited with an 01129 * uncaught exception. It therefore enables errors to be detected and 01130 * acted on without having a thread wait on the get() method in order 01131 * to test is_error() or is_emitter_error(). 01132 * 01133 * This method can be called before or after the run() method has been 01134 * called, and whether or not the thread function represented by this 01135 * Cgu::Thread::Future object has completed. 01136 * 01137 * The documentation for the version of this method which does not 01138 * take a Releaser object gives further details of how this method is 01139 * used. 01140 * 01141 * If glib < 2.32 is used, the glib main loop must have been made 01142 * thread-safe by a call to g_thread_init() before this function is 01143 * called. glib >= 2.32 does not require g_thread_init() to be called 01144 * in order to be thread safe. 01145 * 01146 * @param cb The 'fail' callback (the callback to be executed if the 01147 * thread function represented by this Cgu::Thread::Future object or a 01148 * done_emitter emission has failed to complete). Ownership is taken 01149 * of this object, and it will be deleted when it has been finished 01150 * with. 01151 * @param r A Releaser object for automatic disconnection of the 01152 * 'fail' callback if the object of which the callback function is a 01153 * member is destroyed. 01154 * @param context The glib main context of the thread in whose main 01155 * loop the 'fail' callback is to be executed (the default of NULL 01156 * will cause the functor to be executed in the main program loop). 01157 * @exception std::bad_alloc This method might throw std::bad_alloc if 01158 * memory is exhausted and the system throws in that case. If it does 01159 * so, the 'fail' callback will be disposed of. 01160 * @exception Cgu::Thread::MutexError This method will throw 01161 * Cgu:Thread::MutexError if initialisation of the mutex in a 01162 * SafeEmitterArg object constructed by Cgu::start_timeout() fails. 01163 * If it does so, the 'fail' callback will be disposed of. (It is 01164 * often not worth checking for this, as it means either memory is 01165 * exhausted or pthread has run out of other resources to create new 01166 * mutexes.) 01167 * 01168 * Since 2.0.2 01169 */ 01170 void fail(const Cgu::Callback::Callback* cb, 01171 Cgu::Releaser& r, 01172 GMainContext* context = 0); 01173 01174 /** 01175 * @return true if the function represented by this 01176 * Cgu::Thread::Future object has finished, either by returning 01177 * normally, by cancellation or by virtue of having thrown 01178 * Cgu::Thread::Exit or some exception derived from std::exception. 01179 * Once this method returns true, then it is guaranteed that the get() 01180 * method will not block (except as incidental to any contention with 01181 * other threads calling get()). Once this method has returned true 01182 * or get() has unblocked, then the result of is_error() is 01183 * definitive. This method is thread safe and may be called by any 01184 * thread. It will not throw. 01185 * @note This method will return true even though any callbacks 01186 * connected to done_emitter are still executing or waiting to 01187 * execute. From version 2.0.2 the is_emitter_done() method will 01188 * indicate when done_emitter callbacks (if any) have also completed. 01189 */ 01190 bool is_done() const; 01191 01192 /** 01193 * @return true if both the function represented by this 01194 * Cgu::Thread::Future object has finished and any callbacks connected 01195 * to done_emitter have completed. Once this method returns true, 01196 * then the result of is_emitter_error() is definitive. This method 01197 * is thread safe and may be called by any thread. It will not throw. 01198 * @note This method will return true automatically if is_error() and 01199 * is_done() return true, because if the function represented by this 01200 * Cgu::Thread::Future object was cancelled or exited with an uncaught 01201 * exception, done_emitter is never emitted. In addition, if this 01202 * method returns true, then is_done() must also return true. 01203 * 01204 * Since 2.0.2 01205 */ 01206 bool is_emitter_done() const; 01207 01208 /** 01209 * @return true if (a) a Cgu::Thread::Exit exception has been thrown 01210 * by the function represented by this Cgu::Thread::Future object 01211 * (which will have been consumed by this Cgu::Thread::Future object), 01212 * (b) an exception derived from std::exception has been thrown by 01213 * that function which was not caught in that function (and which will 01214 * also have been consumed by this Cgu::Thread::Future object), (c) 01215 * the worker thread in which that function runs was cancelled in 01216 * mid-course with a call to cancel() or (d) the thread wrapper 01217 * implementing the worker thread in this Cgu::Thread::Future object 01218 * threw and then consumed std::bad_alloc (this is different from the 01219 * run() method throwing std::bad_alloc). In these cases the value 01220 * obtained by get() will not be valid. Otherwise this method returns 01221 * false. The result of this method is definitive once get() has 01222 * unblocked or is_done() returns true. This method is thread safe 01223 * and may be called by any thread. It will not throw. 01224 */ 01225 bool is_error() const; 01226 01227 /** 01228 * @return true if an uncaught exception arose in emitting @ref 01229 * DoneEmitterAnchor "done_emitter" when executing callbacks connected 01230 * to it. Otherwise this method returns false. The result of this 01231 * method is definitive once is_emitter_done() returns true. This 01232 * method is thread safe and may be called by any thread. It will not 01233 * throw. 01234 * @note This method will return false automatically if is_error() 01235 * returns true, because if the function represented by this 01236 * Cgu::Thread::Future object was cancelled or exited with an uncaught 01237 * exception, done_emitter is never emitted. It follows that if this 01238 * method returns true, is_error() must return false. 01239 */ 01240 bool is_emitter_error() const; 01241 01242 /** 01243 * A Cgu::SafeEmitter object which is emitted when the function 01244 * represented by this Cgu::Thread::Future object finishes correctly 01245 * (that is, the function is not cancelled and does not throw any 01246 * uncaught exceptions). By itself it does not do too much as it is 01247 * emitted (and connected callbacks execute in) the same worker thread 01248 * immediately after the Future function has completed. However, any 01249 * thread can connect a Callback object to this Cgu::SafeEmitter 01250 * object and a connected callback can, say, cause another Callback to 01251 * be executed in a thread's main loop using Cgu::Callback::post(), 01252 * and from version 2.0.2 when() methods are provided which will do 01253 * this for users automatically. Once the run() method has been 01254 * called, this Cgu::Thread::Future object (and so done_emitter) will 01255 * always stay in existence until the function represented by it has 01256 * completed (whether correctly, by cancellation or by a thrown 01257 * exception) and any callbacks connected to the done_emitter object 01258 * have completed, irrespective of whether the intrusive pointer 01259 * returned by the make() methods has gone out of scope. 01260 * @note 1. Cancellation is blocked while the Cgu::SafeEmitter object 01261 * emits and any connected callback executes. 01262 * @note 2. A connected callback can however terminate the worker 01263 * thread by throwing Cgu::Thread::Exit (in which case no subsequent 01264 * callbacks to be executed on that emission will execute either: the 01265 * worker thread will safely terminate and unwind the stack in so 01266 * doing). In that event, the emitter_error flag will be set. 01267 * @note 3. All other uncaught exceptions which might be thrown by the 01268 * Cgu::SafeEmitter object emitting, or by a connected callback 01269 * function executing, are consumed to retain the integrity of the 01270 * Thread::Future object. In the event of such an exception being 01271 * thrown, the emitter_error flag will be set. In summary, the 01272 * emitter_error flag will be set if (a) a callback function throws 01273 * Cgu::Thread::Exit, (b) some other uncaught exception escapes from a 01274 * callback function or (c) Cgu::SafeEmitter::emit() throws 01275 * std::bad_alloc or the copy constructor of a bound argument which is 01276 * not a reference argument has thrown. If the user knows that the 01277 * callback function does not throw Cgu::Thread::Exit and does not 01278 * allow any other exception to escape, then the cause must be a 01279 * std::bad_alloc memory exception in Cgu::SafeEmitter::emit() or the 01280 * copy constructor of a non-reference bound argument throwing. 01281 * @note 4. An emission is thread safe if the connected callback 01282 * functions are thread safe. 01283 * @anchor DoneEmitterAnchor 01284 */ 01285 SafeEmitter done_emitter; 01286 01287 /* Only has effect if --with-glib-memory-slices-compat or 01288 * --with-glib-memory-slices-no-compat option picked */ 01289 CGU_GLIB_MEMORY_SLICES_FUNCS 01290 }; 01291 01292 /** 01293 * A convenience helper function which calls 01294 * Cgu::Thread::Future::make() to obtain a Future object without the 01295 * need to specify the return value of the function represented by the 01296 * new object: that is deduced from the signature of that function. 01297 * This is useful shorthand when also employed with the C++11 'auto' 01298 * keyword. 01299 * @exception std::bad_alloc It might throw std::bad_alloc if memory 01300 * is exhausted and the system throws in that case. (This exception 01301 * will not be thrown if the library has been installed using the 01302 * --with-glib-memory-slices-no-compat configuration option: instead 01303 * glib will terminate the program if it is unable to obtain memory 01304 * from the operating system.) It will also throw if the copy 01305 * constructor or assignment operator of a bound argument throws, or 01306 * the default constructor of the return value type of the function 01307 * represented by the new object throws. 01308 * 01309 * Since 2.0.4 01310 */ 01311 template <class Obj, class Ret, class... Params, class... Args> 01312 Cgu::IntrusivePtr<Cgu::Thread::Future<Ret>> make_future(Obj& obj, 01313 Ret (Obj::*func)(Params...), 01314 Args&&... args) { 01315 return Cgu::Thread::Future<Ret>::make(obj, func, std::forward<Args>(args)...); 01316 } 01317 01318 /** 01319 * A convenience helper function which calls 01320 * Cgu::Thread::Future::make() to obtain a Future object without the 01321 * need to specify the return value of the function represented by the 01322 * new object: that is deduced from the signature of that function. 01323 * This is useful shorthand when also employed with the C++11 'auto' 01324 * keyword. 01325 * @exception std::bad_alloc It might throw std::bad_alloc if memory 01326 * is exhausted and the system throws in that case. (This exception 01327 * will not be thrown if the library has been installed using the 01328 * --with-glib-memory-slices-no-compat configuration option: instead 01329 * glib will terminate the program if it is unable to obtain memory 01330 * from the operating system.) It will also throw if the copy 01331 * constructor or assignment operator of a bound argument throws, or 01332 * the default constructor of the return value type of the function 01333 * represented by the new object throws. 01334 * 01335 * Since 2.0.4 01336 */ 01337 template <class Obj, class Ret, class... Params, class... Args> 01338 Cgu::IntrusivePtr<Cgu::Thread::Future<Ret>> make_future(const Obj& obj, 01339 Ret (Obj::*func)(Params...) const, 01340 Args&&... args) { 01341 return Cgu::Thread::Future<Ret>::make(obj, func, std::forward<Args>(args)...); 01342 } 01343 01344 /** 01345 * A convenience helper function which calls 01346 * Cgu::Thread::Future::make() to obtain a Future object without the 01347 * need to specify the return value of the function represented by the 01348 * new object: that is deduced from the signature of that function. 01349 * This is useful shorthand when also employed with the C++11 'auto' 01350 * keyword. 01351 * @exception std::bad_alloc It might throw std::bad_alloc if memory 01352 * is exhausted and the system throws in that case. (This exception 01353 * will not be thrown if the library has been installed using the 01354 * --with-glib-memory-slices-no-compat configuration option: instead 01355 * glib will terminate the program if it is unable to obtain memory 01356 * from the operating system.) It will also throw if the copy 01357 * constructor or assignment operator of a bound argument throws, or 01358 * the default constructor of the return value type of the function 01359 * represented by the new object throws. 01360 * 01361 * Since 2.0.4 01362 */ 01363 template <class Ret, class... Params, class... Args> 01364 Cgu::IntrusivePtr<Cgu::Thread::Future<Ret>> make_future(Ret (*func)(Params...), 01365 Args&&... args) { 01366 return Cgu::Thread::Future<Ret>::make(func, std::forward<Args>(args)...); 01367 } 01368 01369 /** 01370 * A convenience helper function which calls 01371 * Cgu::Thread::Future::make() to obtain a Future object without the 01372 * need to specify the return value of the function represented by the 01373 * new object: that is deduced from the signature of that function. 01374 * This is useful shorthand when also employed with the C++11 'auto' 01375 * keyword. 01376 * @exception std::bad_alloc It might throw std::bad_alloc if memory 01377 * is exhausted and the system throws in that case. (This exception 01378 * will not be thrown if the library has been installed using the 01379 * --with-glib-memory-slices-no-compat configuration option: instead 01380 * glib will terminate the program if it is unable to obtain memory 01381 * from the operating system.) It will also throw if the copy 01382 * constructor or assignment operator of a bound argument throws, or 01383 * the default constructor of the return value type of the function 01384 * represented by the new object throws. 01385 * 01386 * Since 2.0.4 01387 */ 01388 template <class Ret> 01389 Cgu::IntrusivePtr<Cgu::Thread::Future<Ret>> make_future(const std::function<Ret(void)>& func) { 01390 return Cgu::Thread::Future<Ret>::make(func); 01391 } 01392 01393 /** 01394 * A convenience helper function which calls 01395 * Cgu::Thread::Future::make() to obtain a Future object without the 01396 * need to specify the return value of the function represented by the 01397 * new object: that is deduced from the signature of that function. 01398 * This is useful shorthand when also employed with the C++11 'auto' 01399 * keyword. 01400 * @exception std::bad_alloc It might throw std::bad_alloc if memory 01401 * is exhausted and the system throws in that case. (This exception 01402 * will not be thrown if the library has been installed using the 01403 * --with-glib-memory-slices-no-compat configuration option: instead 01404 * glib will terminate the program if it is unable to obtain memory 01405 * from the operating system.) It will also throw if the copy 01406 * constructor or assignment operator of a bound argument throws, or 01407 * the default constructor of the return value type of the function 01408 * represented by the new object throws. 01409 * 01410 * Since 2.0.4 01411 */ 01412 template <class Ret> 01413 Cgu::IntrusivePtr<Cgu::Thread::Future<Ret>> make_future(std::function<Ret(void)>&& func) { 01414 return Cgu::Thread::Future<Ret>::make(std::move(func)); 01415 } 01416 01417 } // namespace Thread 01418 01419 } // namespace Cgu 01420 01421 #include <c++-gtk-utils/future.tpp> 01422 01423 #endif