c++-gtk-utils
future.h
Go to the documentation of this file.
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