c++-gtk-utils

callback.h

Go to the documentation of this file.
00001 /* Copyright (C) 2008 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 c++-gtk-utils
00020    sub-directory); 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_CALLBACK_H
00040 #define CGU_CALLBACK_H
00041 
00042 /**
00043  * @file callback.h
00044  * @brief This file provides classes encapsulating callbacks.
00045  *
00046  * \#include <c++-gtk-utils/callback.h>
00047  *
00048  * These classes encapsulate callbacks (they are closures).  They
00049  * comprise a generic callback creation and execution interface.
00050  * There is a basic Callback::Callback type, which is an entire
00051  * closure or 'thunk', where all the arguments are bound in the
00052  * constructor and is completely opaque.  Callback::CallbackArg<T...>
00053  * is a class which takes unbound arguments of the template types when
00054  * the callback is dispatched, with any other arguments being bound at
00055  * construction time.  (The opaque Callback::Callback type is in fact
00056  * just a typedef for Callback::CallbackArg<>: the two types are
00057  * interchangeable.)
00058  *
00059  * The classes can represent static and non-static member functions
00060  * and plain functions.  In the case of a non-static member function,
00061  * the object whose member function the callback represents must
00062  * remain in existence until any invocations of the callback have
00063  * completed.  The function referred to must be one of void return
00064  * type.  A callback object can also be constructed from a
00065  * std::function object, provided that it is of void return type
00066  * (which would amongst other things enable, where necessary, the
00067  * binding of the referenced object of a non-static member function by
00068  * taking an internal copy of it using std::bind).
00069  *
00070  * They are particularly useful where a callback object may need to be
00071  * handed between threads.
00072  *
00073  * The classes can also be useful for general event passing when used
00074  * together with the Callback::post() functions, or as the data
00075  * argument of a call to g_signal_connect_data() in a case where a
00076  * better design arises when passing arguments known at connect time
00077  * by storing them in the callback object itself (say, where otherwise
00078  * you would pass a plain struct as the data argument).
00079  *
00080  * These classes are also used in the Emitter/EmitterArg classes in
00081  * emitter.h, which enable callbacks to be connected to an emitter and
00082  * provide for automatic disconnection where a class object whose
00083  * member a callback represents ceases to exist.
00084  *
00085  * @b The @b Callback::make() @b functions
00086  *
00087  * The templated helper Callback::make() functions make it trivial to
00088  * create a callback object of the correct type.  The ordinary
00089  * Callback::make() functions (that is, those not taking a
00090  * std::function object) provide for a maximum of five bound arguments
00091  * to pass to the relevant function or class method, and an unlimited
00092  * number of unbound arguments, but unbound arguments must be the last
00093  * (trailing) arguments of the relevant function or method to be
00094  * called if there is a bound argument.  Callback/CallbackArg classes
00095  * do not provide for a return value.  If a result is wanted, users
00096  * should pass an unbound argument by reference or pointer (or pointer
00097  * to pointer).
00098  *
00099  * Although as mentioned above only five bound arguments are provided
00100  * for by callbacks constructed by the ordinary Callback::make()
00101  * functions, as any of those arguments can be a struct, any number of
00102  * arguments can be passed as members of a struct or a std::tuple.  In
00103  * addition, a callback object can be constructed from a std::function
00104  * object, which can have any number of arguments bound to it, and in
00105  * any order (that is, unbound arguments may precede bound arguments).
00106  *
00107  * The Callback::make() functions not taking a std::function object do
00108  * a direct type mapping from the bound arguments of the function or
00109  * method represented by the callback object to the arguments stored
00110  * by the callback object.  Bound value arguments of the relevant
00111  * function or method to be called are therefore stored by value in
00112  * the callback object.  A bound argument can comprise a reference
00113  * argument (T& or const T&) if the template parameters of the
00114  * Callback::make() call are qualified by hand to avoid a type
00115  * mismatch: see under "Usage" below for further particulars, and if
00116  * the reference argument is non-const this allows the referenced
00117  * argument to be mutated.  However as this would result in the
00118  * lifetime of the argument not being controlled by the callback
00119  * object (it would not keep its own copy), it will often be unsafe to
00120  * do so.  (The documentation on Thread::JoinableHandle gives a usage
00121  * where where binding a reference argument would be safe.)
00122  *
00123  * From version 2.0.0-rc3, the library also provides
00124  * Callback::make_ref() functions, which force the callback object to
00125  * keep a copy of the value passed where a target function argument is
00126  * a const reference.  It is therefore safe with const reference
00127  * arguments.  No explicit type qualification is required by
00128  * Callback::make_ref().  In addition the Callback::make_ref()
00129  * functions provide for more efficient passing of class type bound
00130  * arguments (by l-value or r-value reference) than does
00131  * Callback::make(): see further below.
00132  *
00133  * @b The @b Callback::make_ref() @b functions
00134  *
00135  * In order to enable the widest variety of types to be accepted as
00136  * arguments (including reference arguments in those cases where it is
00137  * safe, and also string literals), as mentioned above when
00138  * constructing a callback object from other than a std::function
00139  * object, Callback::make() receives non-reference bound arguments by
00140  * value, and if unoptimised these may be copied up to two times, and
00141  * once more when the target function is dispatched.  Where a bound
00142  * argument is a pointer or a fundamental type (an integral or
00143  * floating-point type), optimization by copy elision will reduce the
00144  * number of times argument copying takes place when constructing a
00145  * callback object to once, but the standard does not permit that with
00146  * class types where the constructor or destructor have side effects
00147  * or it cannot be ascertained whether they have side effects.
00148  *
00149  * Therefore, to cater for cases where a target function takes a class
00150  * type argument by const reference or value, from version 2.0.0-rc3
00151  * the Callback::make_ref() functions are provided.  Unlike
00152  * Callback::make(), when constructing a callback for a target
00153  * function taking a const reference bound argument,
00154  * Callback::make_ref() will force the callback object to keep a copy
00155  * of the argument instead of a reference to that argument.  This
00156  * makes the use of const reference arguments safe (at the cost of the
00157  * storing of that copy).  It cannot be used with non-const
00158  * references.  In addition Callback::make_ref() automatically chooses
00159  * the most efficient means of passing class type arguments for
00160  * storage by the callback object, that is by l-value reference or
00161  * r-value reference, as appropriate.
00162  *
00163  * In the case of a value argument, at callback dispatch time one
00164  * additional copy will be made in the normal way when the target
00165  * function is called, but in the case of a const reference argument
00166  * no such additional copy will be made.  What all this means is that,
00167  * where bound arguments include a non-trivial class type, the most
00168  * efficient and exception safe strategy is usually:
00169  *
00170  * 1.  If that class type has a rvalue constructor, to have the target
00171  * function take that type by const reference argument, and pass a
00172  * newly constructed object of that type to Callback::make_ref() as a
00173  * temporary (so that it is passed by r-value reference and stored in
00174  * the callback object without any copying at all), or
00175  *
00176  * 2. To construct the object of the class type on free store and held
00177  * by Cgu::SharedPtr, Cgu::SharedLockPtr or std::shared_ptr, have the
00178  * target function take it by const Cgu::SharedPtr&, const
00179  * Cgu::SharedLockPtr& or const std::shared_ptr&, and construct the
00180  * callback object using Callback::make_ref().
00181  *
00182  * This flexibility of Callback::make_ref() has a downside: unlike
00183  * Callback::make(), Callback::make_ref() cannot resolve overloaded
00184  * functions by argument type.  Where a function has two or more
00185  * overloads taking the same number of arguments, explicit
00186  * disambiguation by the user is required (see further below under
00187  * Overloaded Functions).
00188  *
00189  * Summary: If a callback object's bound arguments are all simple
00190  * fundamental types such as pointers (including C strings), integers
00191  * or floating points, use Callback::make().  Where bound arguments
00192  * include class types, use Callback::make_ref().
00193  *
00194  * @b The @b Callback::make_val() @b functions
00195  *
00196  * The library also provides Callback::make_val() functions.  These
00197  * are provided to retain code compatibility with version 1.2 of the
00198  * library.  They were optimised for use where a target function takes
00199  * bound arguments of class type by value, but are now deprecated and
00200  * superseded by the automatic variable type mapping of
00201  * Callback::make_ref().  Callback::make_ref() should now be used
00202  * instead of Callback::make_val().
00203  *
00204  * @b Constructing @b callbacks @b from @b std::function @b objects
00205  *
00206  * The Callback::make() factory functions can also construct a
00207  * callback object from a std::function object, which would enable a
00208  * callback to take more than 5 bound arguments, or to have a bound
00209  * argument which is passed after (or mixed with) unbound arguments,
00210  * or to have its own copy of the referenced object of a non-static
00211  * member function bound to it.
00212  *
00213  * However, the genericity of the binding of arguments implemented in
00214  * std::function and std::bind comes at a cost.  Arguments bound to a
00215  * std::function object can be copied a significant number of times
00216  * (libstdc++ for example can copy class types four times when
00217  * constructing a std::function object and two more times when
00218  * executing the function, unless they have a r-value constructor, in
00219  * which case they are copied twice and once respectively with two and
00220  * one additional calls to the r-value constructor).  Non-trivial
00221  * class types should therefore only be passed as bound arguments to
00222  * std::function objects by pointer or smart pointer.
00223  *
00224  * Note that the overload of Callback::make() for std::function
00225  * objects has a version taking a r-value reference for the lossless
00226  * passing through of temporaries to the callback object, and a
00227  * version taking a const reference for std::function objects which
00228  * are l-values.  For std::function objects, Callback::make() and
00229  * Callback::make_ref() are all synonyms (the way arguments are dealt
00230  * with for std::function objects is determined by std::bind() and
00231  * std::ref()).
00232  *
00233  * @b The @b Callback::lambda() @b functions
00234  * 
00235  * Callback objects for C++11 lambda functions can be constructed
00236  * using Callback::make() by passing the lambda object via a temporary
00237  * std::function object (see under Usage below for an example).
00238  * However, from version 2.0.9 the Callback::lambda() factory function
00239  * is provided enabling callbacks for C++11 lambda functions to be
00240  * constructed more directly.  This is nice, as by using
00241  * Callback::lambda() a callback can, for example, be executed by a
00242  * glib main loop using Callback::post() with:
00243  * @code 
00244  *   using namespace Cgu;
00245  *   post(Callback::lambda<>([]() {std::cout << "Hello glib\n";})); // post() found by argument dependent lookup
00246  * @endcode
00247  * Further examples are given under Usage below.
00248  *
00249  * Using Callback::lambda() to construct a callback object from a
00250  * C++11 lambda function, rather than using Callback::make() with a
00251  * temporary std::function object, will also be more efficient, as
00252  * when executed it would normally avoid the additional virtual
00253  * function call that would arise with std::function.
00254  *
00255  * When using Callback::lambda(), the unbound argument types must be
00256  * specified explicitly (they cannot be deduced from the lambda
00257  * expression).
00258  *
00259  * Callback::lambda() can be used to construct a callback object from
00260  * any arbitrary callable object.  It could therefore be used to
00261  * construct callback objects from plain function pointers where no
00262  * arguments are to be bound, and from std::function objects.
00263  * However, that is rarely useful as employing Callback::make() with
00264  * function pointers and std::function objects provides the benefit of
00265  * automatic type deduction of the arguments.  One possible case where
00266  * Callback::lambda() might be useful with non-lambda callable objects
00267  * relates to another feature of Callback::lambda(), namely that the
00268  * callable object passed to it need not be of void return type.
00269  * However, if the callable object does return a value, that value is
00270  * discarded.  If a result is wanted, an unbound reference or pointer
00271  * argument should be passed when the callback is executed, to which
00272  * the result can be assigned.
00273  *
00274  * If using lambda expressions with gcc, gcc-4.5 or greater is needed.
00275  * The header file callback.h can be included without error with
00276  * gcc-4.4, but callable objects cannot be constructed using C++11
00277  * lambda syntax.
00278  *
00279  * @b Functors
00280  *
00281  * If a functor class of void return type is required (say for passing
00282  * to a c++ algorithm or container, or for automatic lifetime
00283  * management of the Callback object), the Callback::Functor and
00284  * Callback::FunctorArg wrapper classes can be used.  However, for
00285  * many c++ algorithms where anonymous functors created as temporaries
00286  * can be used, the std::ptr_fun(), std::mem_fn() and std::bind()
00287  * factory functions or a lambda function will be a more obvious
00288  * choice.  Callback::Functor and Callback::FunctorArg are to be
00289  * preferred to std::function where value arguments are to be bound
00290  * (see above), unless something other than a void return type is
00291  * required.
00292  *
00293  * Callback::SafeFunctor and Callback::SafeFunctorArg classes are the
00294  * same as Callback::Functor and Callback::FunctorArg classes, except
00295  * that objects of the safe version may be passed and copied between
00296  * threads and put in different containers in different threads (that
00297  * is, the reference count maintained with respect to the contained
00298  * callback object is thread-safe).  They use a SharedLockPtr object
00299  * to hold the referenced callback object.
00300  *
00301  * @b Memory @b allocation
00302  *
00303  * If the library is installed using the
00304  * --with-glib-memory-slices-compat or
00305  * --with-glib-memory-slices-no-compat configuration options, any
00306  * Callback::Functor, Callback::FunctorArg, Callback::SafeFunctor or
00307  * Callback::SafeFunctorArg objects constructed on free store (usually
00308  * they won't be) will be constructed in glib memory slices.  A
00309  * contained Callback::Callback or Callback::CallbackArg object, which
00310  * will always be constructed on free store, will be constructed in
00311  * glib memory slices if the --with-glib-memory-slices-no-compat
00312  * configuration option is chosen.
00313  *
00314  * @b Usage
00315  *
00316  * For a class object my_obj of type MyClass, with a method void
00317  * MyClass::my_method(int, int, const char*), usage for a fully bound
00318  * callback or functor would be:
00319  *
00320  * @code 
00321  *   using namespace Cgu;
00322  *   int arg1 = 1, arg2 = 5;
00323  *   Callback::Callback* cb =
00324  *     Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n");
00325  *   cb->dispatch();
00326  *   delete cb;
00327  *
00328  *   Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")};
00329  *   f();
00330  * @endcode
00331  *
00332  * Or for a partially bound callback or functor:
00333  *
00334  * @code
00335  *   using namespace Cgu;
00336  *   int arg1 = 1, arg2 = 5;
00337  *   Callback::CallbackArg<int, const char*>* cb =
00338  *     Callback::make(my_obj, &MyClass::my_method, arg1);
00339  *   cb->dispatch(arg2, "Hello\n");
00340  *   delete cb;
00341  *
00342  *   Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)};
00343  *   f(arg2, "Hello\n");
00344  * @endcode
00345  *
00346  * The syntax for the construction of a callback object representing a
00347  * static member function with a signature void MyClass::my_func(int,
00348  * const char*), or for a normal function, is similar to the
00349  * non-static member function case, except that the call to
00350  * Callback::make would comprise:
00351  *
00352  * @code
00353  *   Callback::make(&MyClass::my_func, arg1, arg2, "Hello\n");
00354  * @endcode
00355  * (fully bound), or
00356  * @code
00357  *   Callback::make(&MyClass::my_func, arg1);
00358  * @endcode
00359  * (partially bound), and so on.
00360  *
00361  * To bind to reference arguments, the call to Callback::make() must
00362  * be explicitly typed.  For a class object my_obj of type MyClass,
00363  * with a method void MyClass::my_method(int&), usage for a fully
00364  * bound callback or functor would be:
00365  *
00366  * @code
00367  *   int arg = 1;
00368  *   Callback::Callback* cb =
00369  *     Callback::make<MyClass, int&>(my_obj, &MyClass::my_method, arg);
00370  * @endcode
00371  *
00372  * Note however the caveats above about binding to reference
00373  * arguments.
00374  *
00375  * No similar explicit typing is required by Callback::make_ref().
00376  * Thus for a class object my_obj of type MyClass, with a method void
00377  * MyClass::my_method(int, const Something&), usage for a fully bound
00378  * callback or functor would be:
00379  *
00380  * @code
00381  *   int arg1 = 1;
00382  *   Something arg2;
00383  *   Callback::Callback* cb =
00384  *     Callback::make_ref(my_obj, &MyClass::my_method, arg1, arg2);
00385  * @endcode
00386  *
00387  * Usage for constructing a callback object from a std::function
00388  * object is as follows, for a class object my_obj of type MyClass,
00389  * with a method void MyClass::my_method(int, int, int, double, const
00390  * char*), where a value is to be bound to the second argument:
00391  *
00392  * @code
00393  *   using namespace std::placeholders;  // for _1, _2, _3 and _4
00394  *   int arg = 1;
00395  *   Callback::CallbackArg<int, int, double, const char*>* cb =
00396  *     Callback::make(std::function<void(int, int, double, const char*)>{
00397  *       std::bind(std::mem_fn(&MyClass::my_method), &my_obj,
00398  *                 _1, arg, _2, _3, _4)
00399  *     });
00400  *   cb->dispatch(5, 3, 10.2, "Hello\n");
00401  *   delete cb;
00402  * @endcode
00403  *
00404  * In this example, if the bound argument were a reference (that is,
00405  * the signature of MyClass::my_method were (int, int&, int, double,
00406  * const char*) and it were safe to do so (see above), it could be
00407  * bound with std::ref(), as in:
00408  *
00409  * @code
00410  *   Callback::CallbackArg<int, int, double, const char*>* cb =
00411  *     Callback::make(std::function<void(int, int, double, const char*)>{
00412  *       std::bind(std::mem_fn(&MyClass::my_method), &my_obj,
00413  *                 _1, std::ref(arg), _2, _3, _4)
00414  *     });
00415  * @endcode
00416  *
00417  * Lambda expressions can also be passed to callback objects via
00418  * std::function, and arguments can be bound with the [=] capture
00419  * expression, as in:
00420  *
00421  * @code
00422  *   Callback::Callback* cb;
00423  *   {
00424  *     std::string s("Hello");
00425  *     cb = Callback::make(std::function<void()>{[=](){std::cout << s << std::endl;}});
00426  *   }
00427  *   cb->dispatch(); // 's' is now out of scope, but it has been copied by value to
00428  *                   // the lambda object and is now held by the callback object
00429  *   delete cb;
00430  * @endcode
00431  *
00432  * However, from version 2.0.9, Callback::lambda() provides an easier
00433  * way of dealing with lambda expressions.  The same code could be
00434  * implemented as:
00435  *
00436  * @code
00437  *   Callback::Callback* cb;
00438  *   {
00439  *     std::string s("Hello");
00440  *     cb = Callback::lambda<>([=](){std::cout << s << std::endl;});
00441  *   }
00442  *   cb->dispatch();
00443  *   delete cb;
00444  * @endcode
00445  *
00446  * With Callback::lambda(), the types of the unbound arguments must be
00447  * explicitly specified as they cannot be deduced.  Unbound arguments
00448  * can comprise reference arguments.  For example:
00449  * @code
00450  *   int res;
00451  *   auto cb = Callback::lambda<int, int, int&>([](int j, int k, int& r) {r = j * k;});
00452  *   cb->dispatch(2, 3, res);
00453  *   std::cout << res << std::endl;
00454  *   delete cb;
00455  * @endcode
00456  *
00457  * @b Overloaded @b functions
00458  *
00459  * Note that creating callbacks for overloaded functions can give rise
00460  * to an ambiguity when using Callback::make(), arising from the fact
00461  * that the callback object may have an unbound argument.  For
00462  * example:
00463  *
00464  * @code
00465  *   class MyClass {
00466  *     ...
00467  *     void add(int i);
00468  *     void add(int i, int j);
00469  *     void add(double d);
00470  *   };
00471  *   MyClass obj;
00472  *   using namespace Cgu;
00473  *   Callback::Callback* cb1 = Callback::make(obj, &MyClass::add, 1, 2); // ok
00474  *   Callback::Callback* cb2 = Callback::make(obj, &MyClass::add, 1.0);  // ok
00475  *   Callback::Callback* cb3 = Callback::make(obj, &MyClass::add, 1);    // ambiguous - compilation failure
00476  * @endcode
00477  *
00478  * The third call to Callback::make() is ambiguous, as it could be
00479  * creating a callback for either the function MyClass::add(int) with
00480  * no unbound argument (that is, creating a Callback::Callback
00481  * object), or the function MyClass::add(int, int) with an unbound int
00482  * argument (that is, creating a Callback::CallbackArg<int> object).
00483  * This situation could be disambiguated by specifically stating the
00484  * type of the function which is to be chosen, namely, to instantiate
00485  * the callback in the third call with:
00486  *
00487  * @code
00488  *   // either:
00489  *   Callback::Callback* cb3 =
00490  *     Callback::make(obj, static_cast<void (MyClass::*)(int)>(&MyClass::add), 1);
00491  *   // or:
00492  *   Callback::CallbackArg<int>* cb3 =
00493  *     Callback::make(obj, static_cast<void (MyClass::*)(int, int)>(&MyClass::add), 1);
00494  * @endcode
00495  *
00496  * Callback::make_ref() is less capable than Callback::make() at
00497  * deducing template types.  It cannot resolve overloaded functions by
00498  * examining the arguments passed to it.  For example, take a class
00499  * MyClass as follows:
00500  *
00501  * @code
00502  *   class MyClass {
00503  *     ...
00504  *     void add(int i, const double& d);
00505  *     void add(const int& j, const int& k);
00506  *   };
00507  * @endcode
00508  *
00509  * Callback::make_ref() would require explicit disambiguation like
00510  * this:
00511  *
00512  * @code
00513  *   Callback::Callback* cb1 =
00514  *     Callback::make_ref(obj, static_cast<void (MyClass::*)(int, const double&)>(&MyClass::add), 1, 2.2);
00515  *   Callback::Callback* cb2 =
00516  *     Callback::make_ref(obj, static_cast<void (MyClass::*)(const int&, const int&)>(&MyClass::add), 4, 5);
00517  * @endcode
00518  *
00519  * Note also that, for CallbackArg objects created from std::function
00520  * objects, the std::function constructors and the std::mem_fn() and
00521  * std::bind() functions normally do not allow any function
00522  * overloading without explicit disambiguation.
00523  *
00524  * @b Posting @b of @b callbacks
00525  *
00526  * This file also provides Callback::post() functions which will
00527  * execute a callback in a glib main loop and can be used (amongst
00528  * other things) to pass an event from a worker thread to the main
00529  * program thread.  In that respect, it provides an alternative to the
00530  * Notifier class.  It is passed a pointer to a Callback::CallbackArg
00531  * object created with a call to Callback::make.
00532  *
00533  * To provide for thread-safe automatic disconnection of the callback
00534  * if the object whose method it represents is destroyed before the
00535  * callback executes in the main loop, include a Releaser as a public
00536  * member of that object and pass the Releaser object as the second
00537  * argument of Callback::post().  Note that for this to be race free,
00538  * the lifetime of the remote object whose method is to be invoked
00539  * must be determined by the thread to whose main loop the callback
00540  * has been attached.  When the main loop begins invoking the
00541  * execution of the callback, the remote object must either wholly
00542  * exist (in which case the callback will be invoked) or have been
00543  * destroyed (in which case the callback will be ignored), and not be
00544  * in some transient half-state governed by another thread.
00545  *
00546  * Advantages as against Notifier:
00547  * 
00548  * 1. If there are a lot of different events requiring callbacks to be
00549  *    dispatched in the program from worker threads to the main
00550  *    thread, this avoids having separate Notifier objects for each
00551  *    event.
00552  *
00553  * 2. It is easier to pass arguments with varying values - they can be
00554  *    passed as arguments to the Callback::make functions and no
00555  *    special synchronisation is normally required (the call to
00556  *    g_source_attach() invokes locking of the main loop which will
00557  *    have the effect of ensuring memory visibility).  With a Notifier
00558  *    object it may be necessary to use an asynchronous queue to pass
00559  *    variable values (or to bind a reference to the data, thus
00560  *    normally requiring separate synchronisation).
00561  *
00562  * 3. Although the callback would normally be sent for execution by
00563  *    the main program loop, and that is the default, it can be sent
00564  *    for execution by any thread which has its own
00565  *    GMainContext/GMainLoop objects.  Thus callbacks can be passed
00566  *    for execution between worker threads, or from the main program
00567  *    thread to worker threads, as well as from worker threads to the
00568  *    main program thread.
00569  *
00570  * Disadvantages as against Notifier:
00571  *
00572  * 1. Less efficient, as a new callback object has to be created on
00573  *    freestore every time the callback is invoked, together with a
00574  *    new Emitter object if a Releaser is used to track the callback.
00575  * 
00576  * 2. Multiple callbacks relevant to a single event cannot be invoked
00577  *    from a single call for the event - each callback has to be
00578  *    separately dispatched.
00579  */
00580 
00581 /**
00582  * @namespace Cgu::Callback
00583  * @brief This namespace provides classes encapsulating callbacks.
00584  *
00585  * \#include <c++-gtk-utils/callback.h>
00586  *
00587  * These classes encapsulate callbacks (they are closures).  They
00588  * comprise a generic callback creation and execution interface.
00589  * There is a basic Callback::Callback type, which is an entire
00590  * closure or 'thunk', where all the arguments are bound in the
00591  * constructor and is completely opaque.  Callback::CallbackArg<T...>
00592  * is a class which takes unbound arguments of the template types when
00593  * the callback is dispatched, with any other arguments being bound at
00594  * construction time.  (The opaque Callback::Callback type is in fact
00595  * just a typedef for Callback::CallbackArg<>: the two types are
00596  * interchangeable.)
00597  *
00598  * The classes can represent static and non-static member functions
00599  * and plain functions.  In the case of a non-static member function,
00600  * the object whose member function the callback represents must
00601  * remain in existence until any invocations of the callback have
00602  * completed.  The function referred to must be one of void return
00603  * type.  A callback object can also be constructed from a
00604  * std::function object, provided that it is of void return type
00605  * (which would amongst other things enable, where necessary, the
00606  * binding of the referenced object of a non-static member function by
00607  * taking an internal copy of it using std::bind).
00608  *
00609  * They are particularly useful where a callback object may need to be
00610  * handed between threads.
00611  *
00612  * The classes can also be useful for general event passing when used
00613  * together with the Callback::post() functions, or as the data
00614  * argument of a call to g_signal_connect_data() in a case where a
00615  * better design arises when passing arguments known at connect time
00616  * by storing them in the callback object itself (say, where otherwise
00617  * you would pass a plain struct as the data argument).
00618  *
00619  * These classes are also used in the Emitter/EmitterArg classes in
00620  * emitter.h, which enable callbacks to be connected to an emitter and
00621  * provide for automatic disconnection where a class object whose
00622  * member a callback represents ceases to exist.
00623  *
00624  * @b The @b Callback::make() @b functions
00625  *
00626  * The templated helper Callback::make() functions make it trivial to
00627  * create a callback object of the correct type.  The ordinary
00628  * Callback::make() functions (that is, those not taking a
00629  * std::function object) provide for a maximum of five bound arguments
00630  * to pass to the relevant function or class method, and an unlimited
00631  * number of unbound arguments, but unbound arguments must be the last
00632  * (trailing) arguments of the relevant function or method to be
00633  * called if there is a bound argument.  Callback/CallbackArg classes
00634  * do not provide for a return value.  If a result is wanted, users
00635  * should pass an unbound argument by reference or pointer (or pointer
00636  * to pointer).
00637  *
00638  * Although as mentioned above only five bound arguments are provided
00639  * for by callbacks constructed by the ordinary Callback::make()
00640  * functions, as any of those arguments can be a struct, any number of
00641  * arguments can be passed as members of a struct or a std::tuple.  In
00642  * addition, a callback object can be constructed from a std::function
00643  * object, which can have any number of arguments bound to it, and in
00644  * any order (that is, unbound arguments may precede bound arguments).
00645  *
00646  * The Callback::make() functions not taking a std::function object do
00647  * a direct type mapping from the bound arguments of the function or
00648  * method represented by the callback object to the arguments stored
00649  * by the callback object.  Bound value arguments of the relevant
00650  * function or method to be called are therefore stored by value in
00651  * the callback object.  A bound argument can comprise a reference
00652  * argument (T& or const T&) if the template parameters of the
00653  * Callback::make() call are qualified by hand to avoid a type
00654  * mismatch: see under "Usage" below for further particulars, and if
00655  * the reference argument is non-const this allows the referenced
00656  * argument to be mutated.  However as this would result in the
00657  * lifetime of the argument not being controlled by the callback
00658  * object (it would not keep its own copy), it will often be unsafe to
00659  * do so.  (The documentation on Thread::JoinableHandle gives a usage
00660  * where where binding a reference argument would be safe.)
00661  *
00662  * From version 2.0.0-rc3, the library also provides
00663  * Callback::make_ref() functions, which force the callback object to
00664  * keep a copy of the value passed where a target function argument is
00665  * a const reference.  It is therefore safe with const reference
00666  * arguments.  No explicit type qualification is required by
00667  * Callback::make_ref().  In addition the Callback::make_ref()
00668  * functions provide for more efficient passing of class type bound
00669  * arguments (by l-value or r-value reference) than does
00670  * Callback::make(): see further below.
00671  *
00672  * @b The @b Callback::make_ref() @b functions
00673  *
00674  * In order to enable the widest variety of types to be accepted as
00675  * arguments (including reference arguments in those cases where it is
00676  * safe, and also string literals), as mentioned above when
00677  * constructing a callback object from other than a std::function
00678  * object, Callback::make() receives non-reference bound arguments by
00679  * value, and if unoptimised these may be copied up to two times, and
00680  * once more when the target function is dispatched.  Where a bound
00681  * argument is a pointer or a fundamental type (an integral or
00682  * floating-point type), optimization by copy elision will reduce the
00683  * number of times argument copying takes place when constructing a
00684  * callback object to once, but the standard does not permit that with
00685  * class types where the constructor or destructor have side effects
00686  * or it cannot be ascertained whether they have side effects.
00687  *
00688  * Therefore, to cater for cases where a target function takes a class
00689  * type argument by const reference or value, from version 2.0.0-rc3
00690  * the Callback::make_ref() functions are provided.  Unlike
00691  * Callback::make(), when constructing a callback for a target
00692  * function taking a const reference bound argument,
00693  * Callback::make_ref() will force the callback object to keep a copy
00694  * of the argument instead of a reference to that argument.  This
00695  * makes the use of const reference arguments safe (at the cost of the
00696  * storing of that copy).  It cannot be used with non-const
00697  * references.  In addition Callback::make_ref() automatically chooses
00698  * the most efficient means of passing class type arguments for
00699  * storage by the callback object, that is by l-value reference or
00700  * r-value reference, as appropriate.
00701  *
00702  * In the case of a value argument, at callback dispatch time one
00703  * additional copy will be made in the normal way when the target
00704  * function is called, but in the case of a const reference argument
00705  * no such additional copy will be made.  What all this means is that,
00706  * where bound arguments include a non-trivial class type, the most
00707  * efficient and exception safe strategy is usually:
00708  *
00709  * 1.  If that class type has a rvalue constructor, to have the target
00710  * function take that type by const reference argument, and pass a
00711  * newly constructed object of that type to Callback::make_ref() as a
00712  * temporary (so that it is passed by r-value reference and stored in
00713  * the callback object without any copying at all), or
00714  *
00715  * 2. To construct the object of the class type on free store and held
00716  * by Cgu::SharedPtr, Cgu::SharedLockPtr or std::shared_ptr, have the
00717  * target function take it by const Cgu::SharedPtr&, const
00718  * Cgu::SharedLockPtr& or const std::shared_ptr&, and construct the
00719  * callback object using Callback::make_ref().
00720  *
00721  * This flexibility of Callback::make_ref() has a downside: unlike
00722  * Callback::make(), Callback::make_ref() cannot resolve overloaded
00723  * functions by argument type.  Where a function has two or more
00724  * overloads taking the same number of arguments, explicit
00725  * disambiguation by the user is required (see further below under
00726  * Overloaded Functions).
00727  *
00728  * Summary: If a callback object's bound arguments are all simple
00729  * fundamental types such as pointers (including C strings), integers
00730  * or floating points, use Callback::make().  Where bound arguments
00731  * include class types, use Callback::make_ref().
00732  *
00733  * @b The @b Callback::make_val() @b functions
00734  *
00735  * The library also provides Callback::make_val() functions.  These
00736  * are provided to retain code compatibility with version 1.2 of the
00737  * library.  They were optimised for use where a target function takes
00738  * bound arguments of class type by value, but are now deprecated and
00739  * superseded by the automatic variable type mapping of
00740  * Callback::make_ref().  Callback::make_ref() should now be used
00741  * instead of Callback::make_val().
00742  *
00743  * @b Constructing @b callbacks @b from @b std::function @b objects
00744  *
00745  * The Callback::make() factory functions can also construct a
00746  * callback object from a std::function object, which would enable a
00747  * callback to take more than 5 bound arguments, or to have a bound
00748  * argument which is passed after (or mixed with) unbound arguments,
00749  * or to have its own copy of the referenced object of a non-static
00750  * member function bound to it.
00751  *
00752  * However, the genericity of the binding of arguments implemented in
00753  * std::function and std::bind comes at a cost.  Arguments bound to a
00754  * std::function object can be copied a significant number of times
00755  * (libstdc++ for example can copy class types four times when
00756  * constructing a std::function object and two more times when
00757  * executing the function, unless they have a r-value constructor, in
00758  * which case they are copied twice and once respectively with two and
00759  * one additional calls to the r-value constructor).  Non-trivial
00760  * class types should therefore only be passed as bound arguments to
00761  * std::function objects by pointer or smart pointer.
00762  *
00763  * Note that the overload of Callback::make() for std::function
00764  * objects has a version taking a r-value reference for the lossless
00765  * passing through of temporaries to the callback object, and a
00766  * version taking a const reference for std::function objects which
00767  * are l-values.  For std::function objects, Callback::make() and
00768  * Callback::make_ref() are all synonyms (the way arguments are dealt
00769  * with for std::function objects is determined by std::bind() and
00770  * std::ref()).
00771  *
00772  * @b The @b Callback::lambda() @b functions
00773  * 
00774  * Callback objects for C++11 lambda functions can be constructed
00775  * using Callback::make() by passing the lambda object via a temporary
00776  * std::function object (see under Usage below for an example).
00777  * However, from version 2.0.9 the Callback::lambda() factory function
00778  * is provided enabling callbacks for C++11 lambda functions to be
00779  * constructed more directly.  This is nice, as by using
00780  * Callback::lambda() a callback can, for example, be executed by a
00781  * glib main loop using Callback::post() with:
00782  * @code 
00783  *   using namespace Cgu;
00784  *   post(Callback::lambda<>([]() {std::cout << "Hello glib\n";})); // post() found by argument dependent lookup
00785  * @endcode
00786  * Further examples are given under Usage below.
00787  *
00788  * Using Callback::lambda() to construct a callback object from a
00789  * C++11 lambda function, rather than using Callback::make() with a
00790  * temporary std::function object, will also be more efficient, as
00791  * when executed it would normally avoid the additional virtual
00792  * function call that would arise with std::function.
00793  *
00794  * When using Callback::lambda(), the unbound argument types must be
00795  * specified explicitly (they cannot be deduced from the lambda
00796  * expression).
00797  *
00798  * Callback::lambda() can be used to construct a callback object from
00799  * any arbitrary callable object.  It could therefore be used to
00800  * construct callback objects from plain function pointers where no
00801  * arguments are to be bound, and from std::function objects.
00802  * However, that is rarely useful as employing Callback::make() with
00803  * function pointers and std::function objects provides the benefit of
00804  * automatic type deduction of the arguments.  One possible case where
00805  * Callback::lambda() might be useful with non-lambda callable objects
00806  * relates to another feature of Callback::lambda(), namely that the
00807  * callable object passed to it need not be of void return type.
00808  * However, if the callable object does return a value, that value is
00809  * discarded.  If a result is wanted, an unbound reference or pointer
00810  * argument should be passed when the callback is executed, to which
00811  * the result can be assigned.
00812  *
00813  * If using lambda expressions with gcc, gcc-4.5 or greater is needed.
00814  * The header file callback.h can be included without error with
00815  * gcc-4.4, but callable objects cannot be constructed using C++11
00816  * lambda syntax.
00817  *
00818  * @b Functors
00819  *
00820  * If a functor class of void return type is required (say for passing
00821  * to a c++ algorithm or container, or for automatic lifetime
00822  * management of the Callback object), the Callback::Functor and
00823  * Callback::FunctorArg wrapper classes can be used.  However, for
00824  * many c++ algorithms where anonymous functors created as temporaries
00825  * can be used, the std::ptr_fun(), std::mem_fn() and std::bind()
00826  * factory functions or a lambda function will be a more obvious
00827  * choice.  Callback::Functor and Callback::FunctorArg are to be
00828  * preferred to std::function where value arguments are to be bound
00829  * (see above), unless something other than a void return type is
00830  * required.
00831  *
00832  * Callback::SafeFunctor and Callback::SafeFunctorArg classes are the
00833  * same as Callback::Functor and Callback::FunctorArg classes, except
00834  * that objects of the safe version may be passed and copied between
00835  * threads and put in different containers in different threads (that
00836  * is, the reference count maintained with respect to the contained
00837  * callback object is thread-safe).  They use a SharedLockPtr object
00838  * to hold the referenced callback object.
00839  *
00840  * @b Memory @b allocation
00841  *
00842  * If the library is installed using the
00843  * --with-glib-memory-slices-compat or
00844  * --with-glib-memory-slices-no-compat configuration options, any
00845  * Callback::Functor, Callback::FunctorArg, Callback::SafeFunctor or
00846  * Callback::SafeFunctorArg objects constructed on free store (usually
00847  * they won't be) will be constructed in glib memory slices.  A
00848  * contained Callback::Callback or Callback::CallbackArg object, which
00849  * will always be constructed on free store, will be constructed in
00850  * glib memory slices if the --with-glib-memory-slices-no-compat
00851  * configuration option is chosen.
00852  *
00853  * @b Usage
00854  *
00855  * For a class object my_obj of type MyClass, with a method void
00856  * MyClass::my_method(int, int, const char*), usage for a fully bound
00857  * callback or functor would be:
00858  *
00859  * @code 
00860  *   using namespace Cgu;
00861  *   int arg1 = 1, arg2 = 5;
00862  *   Callback::Callback* cb =
00863  *     Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n");
00864  *   cb->dispatch();
00865  *   delete cb;
00866  *
00867  *   Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")};
00868  *   f();
00869  * @endcode
00870  *
00871  * Or for a partially bound callback or functor:
00872  *
00873  * @code
00874  *   using namespace Cgu;
00875  *   int arg1 = 1, arg2 = 5;
00876  *   Callback::CallbackArg<int, const char*>* cb =
00877  *     Callback::make(my_obj, &MyClass::my_method, arg1);
00878  *   cb->dispatch(arg2, "Hello\n");
00879  *   delete cb;
00880  *
00881  *   Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)};
00882  *   f(arg2, "Hello\n");
00883  * @endcode
00884  *
00885  * The syntax for the construction of a callback object representing a
00886  * static member function with a signature void MyClass::my_func(int,
00887  * const char*), or for a normal function, is similar to the
00888  * non-static member function case, except that the call to
00889  * Callback::make would comprise:
00890  *
00891  * @code
00892  *   Callback::make(&MyClass::my_func, arg1, arg2, "Hello\n");
00893  * @endcode
00894  * (fully bound), or
00895  * @code
00896  *   Callback::make(&MyClass::my_func, arg1);
00897  * @endcode
00898  * (partially bound), and so on.
00899  *
00900  * To bind to reference arguments, the call to Callback::make() must
00901  * be explicitly typed.  For a class object my_obj of type MyClass,
00902  * with a method void MyClass::my_method(int&), usage for a fully
00903  * bound callback or functor would be:
00904  *
00905  * @code
00906  *   int arg = 1;
00907  *   Callback::Callback* cb =
00908  *     Callback::make<MyClass, int&>(my_obj, &MyClass::my_method, arg);
00909  * @endcode
00910  *
00911  * Note however the caveats above about binding to reference
00912  * arguments.
00913  *
00914  * No similar explicit typing is required by Callback::make_ref().
00915  * Thus for a class object my_obj of type MyClass, with a method void
00916  * MyClass::my_method(int, const Something&), usage for a fully bound
00917  * callback or functor would be:
00918  *
00919  * @code
00920  *   int arg1 = 1;
00921  *   Something arg2;
00922  *   Callback::Callback* cb =
00923  *     Callback::make_ref(my_obj, &MyClass::my_method, arg1, arg2);
00924  * @endcode
00925  *
00926  * Usage for constructing a callback object from a std::function
00927  * object is as follows, for a class object my_obj of type MyClass,
00928  * with a method void MyClass::my_method(int, int, int, double, const
00929  * char*), where a value is to be bound to the second argument:
00930  *
00931  * @code
00932  *   using namespace std::placeholders;  // for _1, _2, _3 and _4
00933  *   int arg = 1;
00934  *   Callback::CallbackArg<int, int, double, const char*>* cb =
00935  *     Callback::make(std::function<void(int, int, double, const char*)>{
00936  *       std::bind(std::mem_fn(&MyClass::my_method), &my_obj,
00937  *                 _1, arg, _2, _3, _4)
00938  *     });
00939  *   cb->dispatch(5, 3, 10.2, "Hello\n");
00940  *   delete cb;
00941  * @endcode
00942  *
00943  * In this example, if the bound argument were a reference (that is,
00944  * the signature of MyClass::my_method were (int, int&, int, double,
00945  * const char*) and it were safe to do so (see above), it could be
00946  * bound with std::ref(), as in:
00947  *
00948  * @code
00949  *   Callback::CallbackArg<int, int, double, const char*>* cb =
00950  *     Callback::make(std::function<void(int, int, double, const char*)>{
00951  *       std::bind(std::mem_fn(&MyClass::my_method), &my_obj,
00952  *                 _1, std::ref(arg), _2, _3, _4)
00953  *     });
00954  * @endcode
00955  *
00956  * Lambda expressions can also be passed to callback objects via
00957  * std::function, and arguments can be bound with the [=] capture
00958  * expression, as in:
00959  *
00960  * @code
00961  *   Callback::Callback* cb;
00962  *   {
00963  *     std::string s("Hello");
00964  *     cb = Callback::make(std::function<void()>{[=](){std::cout << s << std::endl;}});
00965  *   }
00966  *   cb->dispatch(); // 's' is now out of scope, but it has been copied by value to
00967  *                   // the lambda object and is now held by the callback object
00968  *   delete cb;
00969  * @endcode
00970  *
00971  * However, from version 2.0.9, Callback::lambda() provides an easier
00972  * way of dealing with lambda expressions.  The same code could be
00973  * implemented as:
00974  *
00975  * @code
00976  *   Callback::Callback* cb;
00977  *   {
00978  *     std::string s("Hello");
00979  *     cb = Callback::lambda<>([=](){std::cout << s << std::endl;});
00980  *   }
00981  *   cb->dispatch();
00982  *   delete cb;
00983  * @endcode
00984  *
00985  * With Callback::lambda(), the types of the unbound arguments must be
00986  * explicitly specified as they cannot be deduced.  Unbound arguments
00987  * can comprise reference arguments.  For example:
00988  * @code
00989  *   int res;
00990  *   auto cb = Callback::lambda<int, int, int&>([](int j, int k, int& r) {r = j * k;});
00991  *   cb->dispatch(2, 3, res);
00992  *   std::cout << res << std::endl;
00993  *   delete cb;
00994  * @endcode
00995  *
00996  * @b Overloaded @b functions
00997  *
00998  * Note that creating callbacks for overloaded functions can give rise
00999  * to an ambiguity when using Callback::make(), arising from the fact
01000  * that the callback object may have an unbound argument.  For
01001  * example:
01002  *
01003  * @code
01004  *   class MyClass {
01005  *     ...
01006  *     void add(int i);
01007  *     void add(int i, int j);
01008  *     void add(double d);
01009  *   };
01010  *   MyClass obj;
01011  *   using namespace Cgu;
01012  *   Callback::Callback* cb1 = Callback::make(obj, &MyClass::add, 1, 2); // ok
01013  *   Callback::Callback* cb2 = Callback::make(obj, &MyClass::add, 1.0);  // ok
01014  *   Callback::Callback* cb3 = Callback::make(obj, &MyClass::add, 1);    // ambiguous - compilation failure
01015  * @endcode
01016  *
01017  * The third call to Callback::make() is ambiguous, as it could be
01018  * creating a callback for either the function MyClass::add(int) with
01019  * no unbound argument (that is, creating a Callback::Callback
01020  * object), or the function MyClass::add(int, int) with an unbound int
01021  * argument (that is, creating a Callback::CallbackArg<int> object).
01022  * This situation could be disambiguated by specifically stating the
01023  * type of the function which is to be chosen, namely, to instantiate
01024  * the callback in the third call with:
01025  *
01026  * @code
01027  *   // either:
01028  *   Callback::Callback* cb3 =
01029  *     Callback::make(obj, static_cast<void (MyClass::*)(int)>(&MyClass::add), 1);
01030  *   // or:
01031  *   Callback::CallbackArg<int>* cb3 =
01032  *     Callback::make(obj, static_cast<void (MyClass::*)(int, int)>(&MyClass::add), 1);
01033  * @endcode
01034  *
01035  * Callback::make_ref() is less capable than Callback::make() at
01036  * deducing template types.  It cannot resolve overloaded functions by
01037  * examining the arguments passed to it.  For example, take a class
01038  * MyClass as follows:
01039  *
01040  * @code
01041  *   class MyClass {
01042  *     ...
01043  *     void add(int i, const double& d);
01044  *     void add(const int& j, const int& k);
01045  *   };
01046  * @endcode
01047  *
01048  * Callback::make_ref() would require explicit disambiguation like
01049  * this:
01050  *
01051  * @code
01052  *   Callback::Callback* cb1 =
01053  *     Callback::make_ref(obj, static_cast<void (MyClass::*)(int, const double&)>(&MyClass::add), 1, 2.2);
01054  *   Callback::Callback* cb2 =
01055  *     Callback::make_ref(obj, static_cast<void (MyClass::*)(const int&, const int&)>(&MyClass::add), 4, 5);
01056  * @endcode
01057  *
01058  * Note also that, for CallbackArg objects created from std::function
01059  * objects, the std::function constructors and the std::mem_fn() and
01060  * std::bind() functions normally do not allow any function
01061  * overloading without explicit disambiguation.
01062  *
01063  * @b Posting @b of @b callbacks
01064  *
01065  * This file also provides Callback::post() functions which will
01066  * execute a callback in a glib main loop and can be used (amongst
01067  * other things) to pass an event from a worker thread to the main
01068  * program thread.  In that respect, it provides an alternative to the
01069  * Notifier class.  It is passed a pointer to a Callback::CallbackArg
01070  * object created with a call to Callback::make.
01071  *
01072  * To provide for thread-safe automatic disconnection of the callback
01073  * if the object whose method it represents is destroyed before the
01074  * callback executes in the main loop, include a Releaser as a public
01075  * member of that object and pass the Releaser object as the second
01076  * argument of Callback::post().  Note that for this to be race free,
01077  * the lifetime of the remote object whose method is to be invoked
01078  * must be determined by the thread to whose main loop the callback
01079  * has been attached.  When the main loop begins invoking the
01080  * execution of the callback, the remote object must either wholly
01081  * exist (in which case the callback will be invoked) or have been
01082  * destroyed (in which case the callback will be ignored), and not be
01083  * in some transient half-state governed by another thread.
01084  *
01085  * Advantages as against Notifier:
01086  * 
01087  * 1. If there are a lot of different events requiring callbacks to be
01088  *    dispatched in the program from worker threads to the main
01089  *    thread, this avoids having separate Notifier objects for each
01090  *    event.
01091  *
01092  * 2. It is easier to pass arguments with varying values - they can be
01093  *    passed as arguments to the Callback::make functions and no
01094  *    special synchronisation is normally required (the call to
01095  *    g_source_attach() invokes locking of the main loop which will
01096  *    have the effect of ensuring memory visibility).  With a Notifier
01097  *    object it may be necessary to use an asynchronous queue to pass
01098  *    variable values (or to bind a reference to the data, thus
01099  *    normally requiring separate synchronisation).
01100  *
01101  * 3. Although the callback would normally be sent for execution by
01102  *    the main program loop, and that is the default, it can be sent
01103  *    for execution by any thread which has its own
01104  *    GMainContext/GMainLoop objects.  Thus callbacks can be passed
01105  *    for execution between worker threads, or from the main program
01106  *    thread to worker threads, as well as from worker threads to the
01107  *    main program thread.
01108  *
01109  * Disadvantages as against Notifier:
01110  *
01111  * 1. Less efficient, as a new callback object has to be created on
01112  *    freestore every time the callback is invoked, together with a
01113  *    new Emitter object if a Releaser is used to track the callback.
01114  * 
01115  * 2. Multiple callbacks relevant to a single event cannot be invoked
01116  *    from a single call for the event - each callback has to be
01117  *    separately dispatched.
01118  */
01119 
01120 #include <functional> // for std::less, std::function and std::hash<T*>
01121 #include <utility>    // for std::move and std::forward
01122 #include <cstddef>    // for std::size_t
01123 
01124 #include <glib.h>
01125 
01126 #include <c++-gtk-utils/shared_ptr.h>
01127 #include <c++-gtk-utils/param.h>
01128 #include <c++-gtk-utils/cgu_config.h>
01129 
01130 namespace Cgu {
01131 
01132 namespace Callback {
01133 
01134 /*
01135    The CallbackArg class could be additionally templated to provide a
01136    return value, but that would affect the simplicity of the
01137    interface, and if a case were to arise where a result is needed, an
01138    alternative is for users to pass an argument by pointer (or pointer
01139    to pointer) rather than have a return value.
01140 */
01141 
01142 /* Declare the two basic interface types */
01143 
01144 template <class... FreeArgs> class CallbackArg;
01145 typedef CallbackArg<> Callback;
01146 
01147 /* now the class definitions */
01148 
01149 /**
01150  * @class CallbackArg callback.h c++-gtk-utils/callback.h
01151  * @brief The callback interface class
01152  * @sa Callback namespace
01153  * @sa FunctorArg SafeFunctorArg
01154  *
01155  * This provides the basic interface class that users will generally
01156  * see.  The template types are the types of the unbound arguments, if
01157  * any.  Callback::CallbackArg<> is typedef'ed to Callback::Callback.
01158  *
01159  * @b Usage
01160  *
01161  * For a class object my_obj of type MyClass, with a method void
01162  * MyClass::my_method(int, int, const char*), usage for a fully bound
01163  * callback would be:
01164  *
01165  * @code 
01166  *   using namespace Cgu;
01167  *   int arg1 = 1, arg2 = 5;
01168  *   Callback::Callback* cb =
01169  *     Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n");
01170  *   cb->dispatch();
01171  *   delete cb;
01172  * @endcode
01173  *
01174  * Or for a partially bound callback:
01175  *
01176  * @code
01177  *   using namespace Cgu;
01178  *   int arg1 = 1, arg2 = 5;
01179  *   Callback::CallbackArg<int, const char*>* cb =
01180  *     Callback::make(my_obj, &MyClass::my_method, arg1);
01181  *   cb->dispatch(arg2, "Hello\n");
01182  *   delete cb;
01183  * @endcode
01184  *
01185  * Callback/CallbackArg classes do not provide for a return value.  If
01186  * a result is wanted, users should pass an unbound argument by
01187  * reference or pointer (or pointer to pointer).
01188  *
01189  * For further background, including about the Callback::make(),
01190  * Callback::make_ref() and Callback::lambda() functions, and the use
01191  * of these classes with std::function objects, read this: Callback
01192  */
01193 
01194 template <class... FreeArgs>
01195 class CallbackArg {
01196 public:
01197 /* Because dispatch() is a virtual function, we cannot templatise it
01198  * with a view to preserving r-value forwarding of temporary objects
01199  * passed as a free argument.  But this would rarely be relevant
01200  * anyway - it would only be relevant if the target function were to
01201  * take an argument by r-value reference and a temporary were to be
01202  * passed to it.  In such a case virtual dispatch is at the cost of a
01203  * copy of the temporary.
01204  */
01205 /**
01206  * This will execute the referenced function or class method
01207  * encapsulated by this class.  It will only throw if the dispatched
01208  * function or class method throws, or if the copy constructor of the
01209  * free or a bound argument throws and it is not a reference argument.
01210  * It is thread safe if the referenced function or class method is
01211  * thread safe.
01212  * @param args The unbound arguments to be passed to the referenced
01213  * function or class method, if any.
01214  * @note We use dispatch() to execute the callback, because the
01215  * callback would normally be invoked through a base class pointer.
01216  * To invoke it through operator()(), use the FunctorArg wrapper
01217  * class.
01218  */
01219   virtual void dispatch(typename Cgu::Param<FreeArgs>::ParamType... args) const = 0;
01220 
01221 /**
01222  *  The constructor will not throw unless the copy constructor of an
01223  *  argument bound to the derived implementation class throws.
01224  */
01225   CallbackArg() {}
01226 
01227 /**
01228  *  The destructor will not throw unless the destructor of an argument
01229  *  bound to the derived implementation class throws.
01230  */
01231   virtual ~CallbackArg() {}
01232 
01233 /* these functions will be inherited by the derived callback classes */
01234 #ifdef CGU_USE_GLIB_MEMORY_SLICES_NO_COMPAT
01235   CGU_GLIB_MEMORY_SLICES_FUNCS
01236 #endif
01237 };
01238 
01239 /* The four basic functor types */
01240 
01241 template <class... FreeArgs> class FunctorArg;
01242 template <class... FreeArgs> class SafeFunctorArg;
01243 typedef FunctorArg<> Functor;
01244 typedef SafeFunctorArg<> SafeFunctor;
01245 
01246 /* Functor friend functions */
01247 
01248 // we can use built-in operator == when comparing pointers referencing
01249 // different objects of the same type
01250 /**
01251  * Two FunctorArg objects compare equal if the addresses of the
01252  * CallbackArg objects they contain are the same.  This comparison
01253  * operator does not throw.
01254  */
01255 template <class... T>
01256 bool operator==(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) {
01257   return (f1.cb_s.get() == f2.cb_s.get());
01258 }
01259 
01260 /**
01261  * Two FunctorArg objects compare unequal if the addresses of the
01262  * CallbackArg objects they contain are not the same.  This comparison
01263  * operator does not throw.
01264  */
01265 template <class... T>
01266 bool operator!=(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) {
01267   return !(f1 == f2);
01268 }
01269 
01270 // we must use std::less rather than the < built-in operator for
01271 // pointers to objects not within the same array or object: "For
01272 // templates greater, less, greater_equal, and less_equal, the
01273 // specializations for any pointer type yield a total order, even if
01274 // the built-in operators <, >, <=, >= do not." (para 20.3.3/8).
01275 /**
01276  * One FunctorArg object is less than another if the address of the
01277  * CallbackArg object contained by the first is regarded by std::less
01278  * as less than the address of the CallbackArg object contained by the
01279  * other.  This comparison operator does not throw.
01280  */
01281 template <class... T>
01282 bool operator<(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) {
01283   return std::less<const CallbackArg<T...>*>()(f1.cb_s.get(), f2.cb_s.get());
01284 }
01285 
01286 /**
01287  * Two SafeFunctorArg objects compare equal if the addresses of the
01288  * CallbackArg objects they contain are the same.  This comparison
01289  * operator does not throw.
01290  */
01291 template <class... T>
01292 bool operator==(const SafeFunctorArg<T...>& f1, const SafeFunctorArg<T...>& f2) {
01293   return (f1.cb_s.get() == f2.cb_s.get());
01294 }
01295 
01296 /**
01297  * Two SafeFunctorArg objects compare unequal if the addresses of the
01298  * CallbackArg objects they contain are not the same.  This comparison
01299  * operator does not throw.
01300  */
01301 template <class... T>
01302 bool operator!=(const SafeFunctorArg<T...>& f1, const SafeFunctorArg<T...>& f2) {
01303   return !(f1 == f2);
01304 }
01305 
01306 /**
01307  * One SafeFunctorArg object is less than another if the address of
01308  * the CallbackArg object contained by the first is regarded by
01309  * std::less as less than the address of the CallbackArg object
01310  * contained by the other.  This comparison operator does not throw.
01311  */
01312 template <class... T>
01313 bool operator<(const SafeFunctorArg<T...>& f1, const SafeFunctorArg<T...>& f2) {
01314   return std::less<const CallbackArg<T...>*>()(f1.cb_s.get(), f2.cb_s.get());
01315 }
01316 
01317 } // namespace Callback
01318 } // namespace Cgu
01319 
01320 // doxygen produces long filenames that tar can't handle:
01321 // we have generic documentation for std::hash specialisations
01322 // in doxygen.main.in
01323 #ifndef DOXYGEN_PARSING
01324 
01325 /* These structs allow FunctorArg and SafeFunctorArg objects to be
01326    keys in unordered associative containers */
01327 namespace std {
01328 template <class... T>
01329 struct hash<Cgu::Callback::FunctorArg<T...>> {
01330   typedef std::size_t result_type;
01331   typedef Cgu::Callback::FunctorArg<T...> argument_type;
01332   result_type operator()(const argument_type& f) const {
01333     // this is fine: std::hash structs do not normally contain data and
01334     // std::hash<T*> certainly won't, so we don't have overhead constructing
01335     // std::hash<T*> on the fly
01336     return std::hash<const Cgu::Callback::CallbackArg<T...>*>()(f.cb_s.get());
01337   }
01338 };
01339 template <class... T>
01340 struct hash<Cgu::Callback::SafeFunctorArg<T...>> {
01341   typedef std::size_t result_type;
01342   typedef Cgu::Callback::SafeFunctorArg<T...> argument_type;
01343   result_type operator()(const argument_type& f) const {
01344     // this is fine: std::hash structs do not normally contain data and
01345     // std::hash<T*> certainly won't, so we don't have overhead constructing
01346     // std::hash<T*> on the fly
01347     return std::hash<const Cgu::Callback::CallbackArg<T...>*>()(f.cb_s.get());
01348   }
01349 };
01350 } // namespace std
01351 
01352 #endif // DOXYGEN_PARSING
01353 
01354 namespace Cgu {
01355 namespace Callback {
01356 
01357 /* the functor classes */
01358 
01359 /**
01360  * @class FunctorArg callback.h c++-gtk-utils/callback.h
01361  * @brief Functor class holding a Callback::CallbackArg object.
01362  * @sa SafeFunctorArg
01363  * @sa Callback namespace
01364  *
01365  * This class wraps a CallbackArg object.  The callback object is kept
01366  * by SharedPtr so the functor can be copied and offers automatic
01367  * lifetime management of the wrapped callback object, as well as
01368  * providing an operator()() function.  Ownership is taken of the
01369  * CallbackArg object passed to the constructor taking a CallbackArg
01370  * pointer, so that constructor should be treated like a shared
01371  * pointer constructor - only pass a newly allocated object to it (or
01372  * copy construct it or assign to it from another existing FunctorArg
01373  * object).  The template types are the types of the unbound
01374  * arguments, if any.  Callback::FunctorArg<> is typedef'ed to
01375  * Callback::Functor.
01376  *
01377  * The constructor taking a Callback::CallbackArg pointer is not
01378  * marked explicit, so the results of Callback::make() can be passed
01379  * directly to a function taking a Callback::FunctorArg argument, and
01380  * implicit conversion will take place.
01381  *
01382  * @b Usage
01383  *
01384  * For a class object my_obj of type MyClass, with a method void
01385  * MyClass::my_method(int, int, const char*), usage for a fully bound
01386  * functor would be:
01387  *
01388  * @code 
01389  *   using namespace Cgu;
01390  *   int arg1 = 1, arg2 = 5;
01391  *   Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")};
01392  *   f();
01393  * @endcode
01394  *
01395  * Or for a partially bound functor:
01396  *
01397  * @code
01398  *   using namespace Cgu;
01399  *   int arg1 = 1, arg2 = 5;
01400  *   Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)};
01401  *   f(arg2, "Hello\n");
01402  * @endcode
01403  *
01404  * Callback/CallbackArg classes do not provide for a return value.  If
01405  * a result is wanted, users should pass an unbound argument by
01406  * reference or pointer (or pointer to pointer).
01407  *
01408  * For further background, including about the Callback::make() and
01409  * Callback::make_ref() functions, and the use of these classes with
01410  * std::function objects, read this: Callback
01411  */
01412 
01413 template <class... FreeArgs>
01414 class FunctorArg {
01415   SharedPtr<const CallbackArg<FreeArgs...>> cb_s;
01416 public:
01417 /* Because CallbackArg::dispatch() is a virtual function, it is
01418  * pointless templatising this function with a view to preserving
01419  * r-value forwarding of temporary objects passed as a free argument,
01420  * because the r-value typeness will be discarded in dispatch().  But
01421  * this would rarely be relevant anyway - it would only be relevant if
01422  * the target function were to take an argument by r-value reference
01423  * and a temporary were to be passed to it.  In such a case virtual
01424  * dispatch is at the cost of a copy of the temporary.
01425  */
01426 /**
01427  * This will execute the referenced function or class method
01428  * encapsulated by this class.  It will only throw if the executed
01429  * function or class method throws, or if the copy constructor of the
01430  * free or a bound argument throws and it is not a reference argument.
01431  * It is thread safe if the referenced function or class method is
01432  * thread safe.
01433  * @param args The unbound arguments to be passed to the referenced
01434  * function or class method, if any.
01435  */
01436   void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const {
01437     if (cb_s.get()) cb_s->dispatch(args...);
01438   }
01439 
01440 /** 
01441  * This function does not throw.
01442  * @param f The assignor.
01443  * @return The functor object after assignment.
01444  */ 
01445   FunctorArg& operator=(const FunctorArg& f) {cb_s = f.cb_s; return *this;}
01446 
01447 /** 
01448  * This function does not throw.
01449  * @param f The functor to be moved.
01450  * @return The functor object after the move operation.
01451  */ 
01452   FunctorArg& operator=(FunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;}
01453 
01454 /**
01455  * Two FunctorArg objects compare equal if the addresses of the
01456  * CallbackArg objects they contain are the same.  This comparison
01457  * operator does not throw.
01458  */
01459   friend bool operator== <>(const FunctorArg&, const FunctorArg&);
01460 
01461 /**
01462  * One FunctorArg object is less than another if the address of the
01463  * CallbackArg object contained by the first is regarded by std::less
01464  * as less than the address of the CallbackArg object contained by the
01465  * other.  This comparison operator does not throw.
01466  */
01467   friend bool operator< <>(const FunctorArg&, const FunctorArg&);
01468 
01469   friend struct std::hash<FunctorArg>;
01470 
01471 /**
01472  * Constructor of first FunctorArg holding the referenced callback.
01473  * As it is not marked explicit, it is also a type conversion
01474  * constructor.
01475  * @param cb The CallbackArg object which the functor is to manage.
01476  * @exception std::bad_alloc This might throw std::bad_alloc if
01477  * memory is exhausted and the system throws in that case.  Note that
01478  * if such an exception is thrown, then this constructor will clean
01479  * itself up and also delete the callback object passed to it.
01480  * @note std::bad_alloc will not be thrown if the library has been
01481  * installed using the --with-glib-memory-slices-no-compat
01482  * configuration option: instead glib will terminate the program if it
01483  * is unable to obtain memory from the operating system.
01484  */
01485   FunctorArg(const CallbackArg<FreeArgs...>* cb): cb_s(cb) {}
01486 
01487 /** 
01488  * The copy constructor does not throw.
01489  * @param f The assignor
01490  */ 
01491   FunctorArg(const FunctorArg& f): cb_s(f.cb_s) {}
01492 
01493 /** 
01494  * The move constructor does not throw.
01495  * @param f The functor to be moved.
01496  */ 
01497   FunctorArg(FunctorArg&& f): cb_s(std::move(f.cb_s)) {}
01498 
01499  /**
01500   * Default constructor, where a Callback::CallbackArg object is to be
01501   * assigned later (via the type conversion constructor and/or the
01502   * assignment operator).  This constructor does not throw.
01503   */
01504   FunctorArg() {}
01505 
01506 /* Only has effect if --with-glib-memory-slices-compat or
01507    --with-glib-memory-slices-no-compat option picked */
01508   CGU_GLIB_MEMORY_SLICES_FUNCS
01509 };
01510 
01511 /**
01512  * @class SafeFunctorArg callback.h c++-gtk-utils/callback.h
01513  * @brief Functor class holding a Callback::CallbackArg object, with
01514  * thread-safe reference count.
01515  * @sa FunctorArg
01516  * @sa Callback namespace
01517  *
01518  * This class is the same as Callback::FunctorArg except that it will
01519  * provide synchronisation of the reference count between threads.
01520  * Use it where a functor wrapper object is to be passed between
01521  * threads.  The FunctorArg documentation gives details on usage.
01522  *
01523  * Callback::SafeFunctorArg<> is typedef'ed to Callback::SafeFunctor.
01524  *
01525  * For further background, read this: Callback
01526  */
01527 
01528 template <class... FreeArgs>
01529 class SafeFunctorArg {
01530   SharedLockPtr<const CallbackArg<FreeArgs...>> cb_s;
01531 public:
01532 /**
01533  * This will execute the referenced function or class method
01534  * encapsulated by this class.  It will only throw if the executed
01535  * function or class method throws, or if the copy constructor of the
01536  * free or a bound argument throws and it is not a reference argument.
01537  * It is thread safe if the referenced function or class method is
01538  * thread safe.
01539  * @param args The unbound arguments to be passed to the referenced
01540  * function or class method, if any.
01541  */
01542   void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const {
01543     if (cb_s.get()) cb_s->dispatch(args...);
01544   }
01545 
01546 /** 
01547  * This function does not throw.
01548  * @param f The assignor.
01549  * @return The functor object after assignment.
01550  */ 
01551   SafeFunctorArg& operator=(const SafeFunctorArg& f) {cb_s = f.cb_s; return *this;}
01552 
01553 /** 
01554  * This function does not throw.
01555  * @param f The functor to be moved.
01556  * @return The functor object after the move operation.
01557  */ 
01558   SafeFunctorArg& operator=(SafeFunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;}
01559 
01560 /**
01561  * Two SafeFunctorArg objects compare equal if the addresses of the
01562  * CallbackArg objects they contain are the same.  This comparison
01563  * operator does not throw.
01564  */
01565   friend bool operator== <>(const SafeFunctorArg&, const SafeFunctorArg&);
01566 
01567 /**
01568  * One SafeFunctorArg object is less than another if the address of
01569  * the CallbackArg object contained by the first is regarded by
01570  * std::less as less than the address of the CallbackArg object
01571  * contained by the other.  This comparison operator does not throw.
01572  */
01573   friend bool operator< <>(const SafeFunctorArg&, const SafeFunctorArg&);
01574 
01575   friend struct std::hash<SafeFunctorArg>;
01576 
01577  /**
01578  * Constructor of first SafeFunctorArg holding the referenced
01579  * callback.  As it is not marked explicit, it is also a type
01580  * conversion constructor.
01581  * @param cb The CallbackArg object which the functor is to manage.
01582  * @exception std::bad_alloc This might throw std::bad_alloc if
01583  * memory is exhausted and the system throws in that case.  Note that
01584  * if such an exception is thrown, then this constructor will clean
01585  * itself up and also delete the callback object passed to it.
01586  * @note std::bad_alloc will not be thrown if the library has been
01587  * installed using the --with-glib-memory-slices-no-compat
01588  * configuration option: instead glib will terminate the program if it
01589  * is unable to obtain memory from the operating system.
01590  */
01591   SafeFunctorArg(const CallbackArg<FreeArgs...>* cb): cb_s(cb) {}
01592 
01593 /** 
01594  * The copy constructor does not throw.
01595  * @param f The assignor.
01596  */ 
01597   SafeFunctorArg(const SafeFunctorArg& f): cb_s(f.cb_s) {}
01598 
01599 /** 
01600  * The move constructor does not throw.
01601  * @param f The functor to be moved.
01602  */ 
01603   SafeFunctorArg(SafeFunctorArg&& f): cb_s(std::move(f.cb_s)) {}
01604 
01605  /**
01606   * Default constructor, where a Callback::CallbackArg object is to be
01607   * assigned later (via the type conversion constructor and/or the
01608   * assignment operator).  This constructor does not throw.
01609   * @note The reference count maintained with respect to the contained
01610   * callback object is thread-safe, so SafeFunctorArg objects may be
01611   * copied between threads by the implicit assignment operator and put
01612   * in different containers in different threads.  They use a
01613   * SharedLockPtr object to hold the referenced callback object.
01614   */
01615   SafeFunctorArg() {}
01616 
01617 /* Only has effect if --with-glib-memory-slices-compat or
01618    --with-glib-memory-slices-no-compat option picked */
01619   CGU_GLIB_MEMORY_SLICES_FUNCS
01620 };
01621 
01622 /* the callback implementation classes */
01623 
01624 template <class T, class... FreeArgs>
01625 class Callback0: public CallbackArg<FreeArgs...> {
01626 public:
01627   typedef void (T::* MemFunc)(FreeArgs...);
01628 private:
01629   T* obj;
01630   MemFunc func;
01631 public:
01632   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01633     (obj->*func)(free_args...);
01634   }
01635   Callback0(T& obj_, MemFunc func_): obj(&obj_), func(func_) {}
01636 };
01637 
01638 template <bool unref, class T, class BoundArg, class... FreeArgs>
01639 class Callback1: public CallbackArg<FreeArgs...> {
01640 public:
01641   typedef void (T::* MemFunc)(BoundArg, FreeArgs...);
01642 private:
01643   T* obj;
01644   MemFunc func;
01645   typename Cgu::RemoveRefCond<BoundArg, unref>::Type arg;
01646 public:
01647   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01648     (obj->*func)(arg, free_args...);
01649   }
01650   template <class Arg>
01651   Callback1(T& obj_, MemFunc func_,
01652             Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {}
01653 };
01654 
01655 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs>
01656 class Callback2: public CallbackArg<FreeArgs...> {
01657 public:
01658   typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...);
01659 private:
01660   T* obj;
01661   MemFunc func;
01662   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01663   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01664 public:
01665   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01666     (obj->*func)(arg1, arg2, free_args...);
01667   }
01668   template <class Arg1, class Arg2>
01669   Callback2(T& obj_, MemFunc func_,
01670             Arg1&& arg1_,
01671             Arg2&& arg2_): obj(&obj_), func(func_),
01672                            arg1(std::forward<Arg1>(arg1_)),
01673                            arg2(std::forward<Arg2>(arg2_)) {}
01674 };
01675 
01676 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
01677 class Callback3: public CallbackArg<FreeArgs...> {
01678 public:
01679   typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...);
01680 private:
01681   T* obj;
01682   MemFunc func;
01683   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01684   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01685   typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3;
01686 public:
01687   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01688     (obj->*func)(arg1, arg2, arg3, free_args...);
01689   }
01690   template <class Arg1, class Arg2, class Arg3>
01691   Callback3(T& obj_, MemFunc func_,
01692             Arg1&& arg1_,
01693             Arg2&& arg2_,
01694             Arg3&& arg3_):
01695               obj(&obj_), func(func_),
01696               arg1(std::forward<Arg1>(arg1_)),
01697               arg2(std::forward<Arg2>(arg2_)),
01698               arg3(std::forward<Arg3>(arg3_)) {}
01699 };
01700 
01701 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, 
01702           class BoundArg4, class... FreeArgs>
01703 class Callback4: public CallbackArg<FreeArgs...> {
01704 public:
01705   typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...);
01706 private:
01707   T* obj;
01708   MemFunc func;
01709   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01710   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01711   typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3;
01712   typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4;
01713 public:
01714   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01715     (obj->*func)(arg1, arg2, arg3, arg4, free_args...);
01716   }
01717   template <class Arg1, class Arg2, class Arg3, class Arg4>
01718   Callback4(T& obj_, MemFunc func_,
01719             Arg1&& arg1_,
01720             Arg2&& arg2_,
01721             Arg3&& arg3_,
01722             Arg4&& arg4_):
01723               obj(&obj_), func(func_),
01724               arg1(std::forward<Arg1>(arg1_)),
01725               arg2(std::forward<Arg2>(arg2_)),
01726               arg3(std::forward<Arg3>(arg3_)),
01727               arg4(std::forward<Arg4>(arg4_)) {}
01728 };
01729 
01730 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, 
01731           class BoundArg4, class BoundArg5, class... FreeArgs>
01732 class Callback5: public CallbackArg<FreeArgs...> {
01733 public:
01734   typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3,
01735                               BoundArg4, BoundArg5, FreeArgs...);
01736 private:
01737   T* obj;
01738   MemFunc func;
01739   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01740   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01741   typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3;
01742   typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4;
01743   typename Cgu::RemoveRefCond<BoundArg5, unref>::Type arg5;
01744 public:
01745   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01746     (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...);
01747   }
01748   template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
01749   Callback5(T& obj_, MemFunc func_,
01750             Arg1&& arg1_,
01751             Arg2&& arg2_,
01752             Arg3&& arg3_,
01753             Arg4&& arg4_,
01754             Arg5&& arg5_):
01755               obj(&obj_), func(func_),
01756               arg1(std::forward<Arg1>(arg1_)),
01757               arg2(std::forward<Arg2>(arg2_)),
01758               arg3(std::forward<Arg3>(arg3_)),
01759               arg4(std::forward<Arg4>(arg4_)),
01760               arg5(std::forward<Arg5>(arg5_)) {}
01761 };
01762 
01763 /* const versions, for binding to const methods */
01764 
01765 template <class T, class... FreeArgs>
01766 class Callback0_const: public CallbackArg<FreeArgs...> {
01767 public:
01768   typedef void (T::* MemFunc)(FreeArgs...) const;
01769 private:
01770   const T* obj;
01771   MemFunc func;
01772 public:
01773   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01774     (obj->*func)(free_args...);
01775   }
01776   Callback0_const(const T& obj_, MemFunc func_): obj(&obj_), func(func_) {}
01777 };
01778 
01779 template <bool unref, class T, class BoundArg, class... FreeArgs>
01780 class Callback1_const: public CallbackArg<FreeArgs...> {
01781 public:
01782   typedef void (T::* MemFunc)(BoundArg, FreeArgs...) const;
01783 private:
01784   const T* obj;
01785   MemFunc func;
01786   typename Cgu::RemoveRefCond<BoundArg, unref>::Type arg;
01787 public:
01788   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01789     (obj->*func)(arg, free_args...);
01790   }
01791   template <class Arg>
01792   Callback1_const(const T& obj_, MemFunc func_,
01793                   Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {}
01794 };
01795 
01796 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs>
01797 class Callback2_const: public CallbackArg<FreeArgs...> {
01798 public:
01799   typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...) const;
01800 private:
01801   const T* obj;
01802   MemFunc func;
01803   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01804   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01805 public:
01806   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01807     (obj->*func)(arg1, arg2, free_args...);
01808   }
01809   template <class Arg1, class Arg2>
01810   Callback2_const(const T& obj_, MemFunc func_,
01811                   Arg1&& arg1_,
01812                   Arg2&& arg2_): obj(&obj_), func(func_),
01813                                  arg1(std::forward<Arg1>(arg1_)),
01814                                  arg2(std::forward<Arg2>(arg2_)) {}
01815 };
01816 
01817 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
01818 class Callback3_const: public CallbackArg<FreeArgs...> {
01819 public:
01820   typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const;
01821 private:
01822   const T* obj;
01823   MemFunc func;
01824   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01825   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01826   typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3;
01827 public:
01828   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01829     (obj->*func)(arg1, arg2, arg3, free_args...);
01830   }
01831   template <class Arg1, class Arg2, class Arg3>
01832   Callback3_const(const T& obj_, MemFunc func_,
01833                   Arg1&& arg1_,
01834                   Arg2&& arg2_,
01835                   Arg3&& arg3_):
01836                     obj(&obj_), func(func_),
01837                     arg1(std::forward<Arg1>(arg1_)),
01838                     arg2(std::forward<Arg2>(arg2_)),
01839                     arg3(std::forward<Arg3>(arg3_)) {}
01840 };
01841 
01842 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, 
01843           class BoundArg4, class... FreeArgs>
01844 class Callback4_const: public CallbackArg<FreeArgs...> {
01845 public:
01846   typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const;
01847 private:
01848   const T* obj;
01849   MemFunc func;
01850   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01851   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01852   typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3;
01853   typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4;
01854 public:
01855   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01856     (obj->*func)(arg1, arg2, arg3, arg4, free_args...);
01857   }
01858   template <class Arg1, class Arg2, class Arg3, class Arg4>
01859   Callback4_const(const T& obj_, MemFunc func_,
01860                   Arg1&& arg1_,
01861                   Arg2&& arg2_,
01862                   Arg3&& arg3_,
01863                   Arg4&& arg4_):
01864                     obj(&obj_), func(func_),
01865                     arg1(std::forward<Arg1>(arg1_)),
01866                     arg2(std::forward<Arg2>(arg2_)),
01867                     arg3(std::forward<Arg3>(arg3_)),
01868                     arg4(std::forward<Arg4>(arg4_)) {}
01869 };
01870 
01871 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, 
01872           class BoundArg4, class BoundArg5, class... FreeArgs>
01873 class Callback5_const: public CallbackArg<FreeArgs...> {
01874 public:
01875   typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3,
01876                               BoundArg4, BoundArg5, FreeArgs...) const;
01877 private:
01878   const T* obj;
01879   MemFunc func;
01880   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01881   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01882   typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3;
01883   typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4;
01884   typename Cgu::RemoveRefCond<BoundArg5, unref>::Type arg5;
01885 public:
01886   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01887     (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...);
01888   }
01889   template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
01890   Callback5_const(const T& obj_, MemFunc func_,
01891                   Arg1&& arg1_,
01892                   Arg2&& arg2_,
01893                   Arg3&& arg3_,
01894                   Arg4&& arg4_,
01895                   Arg5&& arg5_):
01896                     obj(&obj_), func(func_),
01897                     arg1(std::forward<Arg1>(arg1_)),
01898                     arg2(std::forward<Arg2>(arg2_)),
01899                     arg3(std::forward<Arg3>(arg3_)),
01900                     arg4(std::forward<Arg4>(arg4_)),
01901                     arg5(std::forward<Arg5>(arg5_)) {}
01902 };
01903 
01904 /* for static class methods and non-class functions */
01905 
01906 template <class... FreeArgs>
01907 class Callback0_static: public CallbackArg<FreeArgs...> {
01908 public:
01909   typedef void (*Func)(FreeArgs...);
01910 private:
01911   Func func;
01912 public:
01913   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01914     func(free_args...);
01915   }
01916   Callback0_static(Func func_): func(func_) {}
01917 };
01918 
01919 template <bool unref, class BoundArg, class... FreeArgs>
01920 class Callback1_static: public CallbackArg<FreeArgs...> {
01921 public:
01922   typedef void (*Func)(BoundArg, FreeArgs...);
01923 private:
01924   Func func;
01925   typename Cgu::RemoveRefCond<BoundArg, unref>::Type arg;
01926 public:
01927   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01928     func(arg, free_args...);
01929   }
01930   template <class Arg>
01931   Callback1_static(Func func_, Arg&& arg_): func(func_), arg(std::forward<Arg>(arg_)) {}
01932 };
01933 
01934 template <bool unref, class BoundArg1, class BoundArg2, class... FreeArgs>
01935 class Callback2_static: public CallbackArg<FreeArgs...> {
01936 public:
01937   typedef void (*Func)(BoundArg1, BoundArg2, FreeArgs...);
01938 private:
01939   Func func;
01940   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01941   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01942 public:
01943   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01944     func(arg1, arg2, free_args...);
01945   }
01946   template <class Arg1, class Arg2>
01947   Callback2_static(Func func_, Arg1&& arg1_,
01948                    Arg2&& arg2_): func(func_),
01949                                   arg1(std::forward<Arg1>(arg1_)),
01950                                   arg2(std::forward<Arg2>(arg2_)) {}
01951 };
01952 
01953 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
01954 class Callback3_static: public CallbackArg<FreeArgs...> {
01955 public:
01956   typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...);
01957 private:
01958   Func func;
01959   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01960   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01961   typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3;
01962 public:
01963   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01964     func(arg1, arg2, arg3, free_args...);
01965   }
01966   template <class Arg1, class Arg2, class Arg3>
01967   Callback3_static(Func func_,
01968                    Arg1&& arg1_,
01969                    Arg2&& arg2_,
01970                    Arg3&& arg3_):
01971                      func(func_),
01972                      arg1(std::forward<Arg1>(arg1_)),
01973                      arg2(std::forward<Arg2>(arg2_)),
01974                      arg3(std::forward<Arg3>(arg3_)) {}
01975 };
01976 
01977 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3, 
01978           class BoundArg4, class... FreeArgs>
01979 class Callback4_static: public CallbackArg<FreeArgs...> {
01980 public:
01981   typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...);
01982 private:
01983   Func func;
01984   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
01985   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
01986   typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3;
01987   typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4;
01988 public:
01989   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
01990     func(arg1, arg2, arg3, arg4, free_args...);
01991   }
01992   template <class Arg1, class Arg2, class Arg3, class Arg4>
01993   Callback4_static(Func func_,
01994                    Arg1&& arg1_,
01995                    Arg2&& arg2_,
01996                    Arg3&& arg3_,
01997                    Arg4&& arg4_):
01998                      func(func_),
01999                      arg1(std::forward<Arg1>(arg1_)),
02000                      arg2(std::forward<Arg2>(arg2_)),
02001                      arg3(std::forward<Arg3>(arg3_)),
02002                      arg4(std::forward<Arg4>(arg4_)) {}
02003 };
02004 
02005 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3, 
02006           class BoundArg4, class BoundArg5, class... FreeArgs>
02007 class Callback5_static: public CallbackArg<FreeArgs...> {
02008 public:
02009   typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3,
02010                        BoundArg4, BoundArg5, FreeArgs...);
02011 private:
02012   Func func;
02013   typename Cgu::RemoveRefCond<BoundArg1, unref>::Type arg1;
02014   typename Cgu::RemoveRefCond<BoundArg2, unref>::Type arg2;
02015   typename Cgu::RemoveRefCond<BoundArg3, unref>::Type arg3;
02016   typename Cgu::RemoveRefCond<BoundArg4, unref>::Type arg4;
02017   typename Cgu::RemoveRefCond<BoundArg5, unref>::Type arg5;
02018 public:
02019   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
02020     func(arg1, arg2, arg3, arg4, arg5, free_args...);
02021   }
02022   template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
02023   Callback5_static(Func func_,
02024                    Arg1&& arg1_,
02025                    Arg2&& arg2_,
02026                    Arg3&& arg3_,
02027                    Arg4&& arg4_,
02028                    Arg5&& arg5_):
02029                      func(func_),
02030                      arg1(std::forward<Arg1>(arg1_)),
02031                      arg2(std::forward<Arg2>(arg2_)),
02032                      arg3(std::forward<Arg3>(arg3_)),
02033                      arg4(std::forward<Arg4>(arg4_)),
02034                      arg5(std::forward<Arg5>(arg5_)) {}
02035 };
02036 
02037 // TODO: Version 2.0.9 provides a Callback_lambda class for callable
02038 // objects which makes the specialized Callback_function class
02039 // redundant.  At an API break we can remove the Callback_function
02040 // class and modify the Callback::make() helper function overload for
02041 // std::function objects to construct a Callback_lambda object
02042 // instead.  Doing it now would not affect ABI compatibility as the
02043 // library produces these only by base pointer, but a user may have
02044 // instantiated them by hand in user code.
02045 template <class... FreeArgs>
02046 class Callback_function: public CallbackArg<FreeArgs...> {
02047   std::function<void(FreeArgs...)> f;
02048 public:
02049   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {f(free_args...);}
02050   Callback_function(const std::function<void(FreeArgs...)>& f_): f(f_) {}
02051   Callback_function(std::function<void(FreeArgs...)>&& f_): f(std::move(f_)) {}
02052 };
02053 
02054 // generic class for callable objects such as lambdas
02055 template <class Lambda, class... FreeArgs>
02056 class Callback_lambda: public CallbackArg<FreeArgs...> {
02057   Lambda l;
02058 public:
02059   void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {l(free_args...);}
02060   template <class L> Callback_lambda(L&& l_): l(std::forward<L>(l_)) {}
02061 };
02062 
02063 /* Convenience functions making callback objects on freestore.  These
02064  * can for example be passed as the first argument of the
02065  * Thread::start() method in thread.h. They are also used by the
02066  * Callback::post() function.
02067 */
02068 
02069 /**
02070  * A convenience function to make Callback::CallbackArg objects
02071  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02072  * is exhausted and the system throws in that case.  This exception
02073  * will not be thrown if the library has been installed using the
02074  * --with-glib-memory-slices-no-compat configuration option (instead
02075  * glib will terminate the program if it is unable to obtain memory
02076  * from the operating system).
02077  */
02078 template <class T, class... FreeArgs>
02079 CallbackArg<FreeArgs...>* make(T& t,
02080                                void (T::*func)(FreeArgs...)) {
02081   return new Callback0<T, FreeArgs...>{t, func};
02082 }
02083 
02084 /**
02085  * DEPRECATED.
02086  *
02087  * Since this function constructs a callback which does not take a
02088  * bound argument, it is a synonym for make() (the two are identical).
02089  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02090  * is exhausted and the system throws in that case.  This exception
02091  * will not be thrown if the library has been installed using the
02092  * --with-glib-memory-slices-no-compat configuration option (instead
02093  * glib will terminate the program if it is unable to obtain memory
02094  * from the operating system).
02095  */
02096 template <class T, class... FreeArgs>
02097 CallbackArg<FreeArgs...>* make_val(T& t,
02098                                    void (T::*func)(FreeArgs...)) {
02099   return new Callback0<T, FreeArgs...>{t, func};
02100 }
02101 
02102 /**
02103  * Since this function constructs a callback which does not take a
02104  * bound argument, it is a synonym for make() (the two are identical).
02105  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02106  * is exhausted and the system throws in that case.  This exception
02107  * will not be thrown if the library has been installed using the
02108  * --with-glib-memory-slices-no-compat configuration option (instead
02109  * glib will terminate the program if it is unable to obtain memory
02110  * from the operating system).
02111  *
02112  * Since 2.0.0-rc3
02113  */
02114 template <class T, class... FreeArgs>
02115 CallbackArg<FreeArgs...>* make_ref(T& t,
02116                                    void (T::*func)(FreeArgs...)) {
02117   return new Callback0<T, FreeArgs...>{t, func};
02118 }
02119 
02120 /**
02121  * A convenience function to make Callback::CallbackArg objects
02122  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02123  * is exhausted and the system throws in that case (this exception
02124  * will not be thrown if the library has been installed using the
02125  * --with-glib-memory-slices-no-compat configuration option: instead
02126  * glib will terminate the program if it is unable to obtain memory
02127  * from the operating system).  It will also throw if the copy
02128  * constructor of a bound argument throws and it is not a reference
02129  * argument.
02130  */
02131 template <class T, class BoundArg, class... FreeArgs>
02132 CallbackArg<FreeArgs...>* make(T& t,
02133                                void (T::*func)(BoundArg, FreeArgs...),
02134                                BoundArg arg) {
02135   return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg};
02136 }
02137 
02138 /**
02139  * DEPRECATED: use Callback::make_ref() instead.
02140  *
02141  * An alternative function to make Callback::CallbackArg objects,
02142  * which is for use where a target function receives an argument of
02143  * class type by value which is to be a bound argument, so the
02144  * compiler is not able to carry out copy elision when constructing
02145  * the callback object.
02146  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02147  * is exhausted and the system throws in that case (this exception
02148  * will not be thrown if the library has been installed using the
02149  * --with-glib-memory-slices-no-compat configuration option: instead
02150  * glib will terminate the program if it is unable to obtain memory
02151  * from the operating system).  It will also throw if the copy
02152  * constructor of a bound argument throws and it is not a reference
02153  * argument.
02154  */
02155 template <class T, class BoundArg, class... FreeArgs>
02156 CallbackArg<FreeArgs...>* make_val(T& t,
02157                                    void (T::*func)(BoundArg, FreeArgs...),
02158                                    const BoundArg& arg) {
02159   return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg};
02160 }
02161 
02162 /**
02163  * An alternative function to make Callback::CallbackArg objects,
02164  * which is for use where a target function either receives a class
02165  * type bound argument by value, or receives a bound argument by
02166  * reference to const in a case where the generated CallbackArg object
02167  * is to store a copy of that argument instead of just keeping a
02168  * reference.
02169  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02170  * is exhausted and the system throws in that case (this exception
02171  * will not be thrown if the library has been installed using the
02172  * --with-glib-memory-slices-no-compat configuration option: instead
02173  * glib will terminate the program if it is unable to obtain memory
02174  * from the operating system).  It will also throw if the copy or move
02175  * constructor of a bound argument throws and it is not a reference
02176  * argument.
02177  *
02178  * Since 2.0.0-rc3
02179  */
02180 template <class T, class BoundArg, class Arg, class... FreeArgs>
02181 CallbackArg<FreeArgs...>* make_ref(T& t,
02182                                    void (T::*func)(BoundArg, FreeArgs...),
02183                                    Arg&& arg) {
02184   return new Callback1<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)};
02185 }
02186 
02187 /**
02188  * A convenience function to make Callback::CallbackArg objects
02189  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02190  * is exhausted and the system throws in that case (this exception
02191  * will not be thrown if the library has been installed using the
02192  * --with-glib-memory-slices-no-compat configuration option: instead
02193  * glib will terminate the program if it is unable to obtain memory
02194  * from the operating system).  It will also throw if the copy
02195  * constructor of a bound argument throws and it is not a reference
02196  * argument.
02197  */
02198 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
02199 CallbackArg<FreeArgs...>* make(T& t,
02200                                void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
02201                                BoundArg1 arg1,
02202                                BoundArg2 arg2) {
02203   return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
02204 }
02205 
02206 /**
02207  * DEPRECATED: use Callback::make_ref() instead.
02208  *
02209  * An alternative function to make Callback::CallbackArg objects,
02210  * which is for use where a target function receives an argument of
02211  * class type by value which is to be a bound argument, so the
02212  * compiler is not able to carry out copy elision when constructing
02213  * the callback object.
02214  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02215  * is exhausted and the system throws in that case (this exception
02216  * will not be thrown if the library has been installed using the
02217  * --with-glib-memory-slices-no-compat configuration option: instead
02218  * glib will terminate the program if it is unable to obtain memory
02219  * from the operating system).  It will also throw if the copy
02220  * constructor of a bound argument throws and it is not a reference
02221  * argument.
02222  */
02223 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
02224 CallbackArg<FreeArgs...>* make_val(T& t,
02225                                    void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
02226                                    const BoundArg1& arg1,
02227                                    const BoundArg2& arg2) {
02228   return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
02229 }
02230 
02231 /**
02232  * An alternative function to make Callback::CallbackArg objects,
02233  * which is for use where a target function either receives a class
02234  * type bound argument by value, or receives a bound argument by
02235  * reference to const in a case where the generated CallbackArg object
02236  * is to store a copy of that argument instead of just keeping a
02237  * reference.
02238  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02239  * is exhausted and the system throws in that case (this exception
02240  * will not be thrown if the library has been installed using the
02241  * --with-glib-memory-slices-no-compat configuration option: instead
02242  * glib will terminate the program if it is unable to obtain memory
02243  * from the operating system).  It will also throw if the copy or move
02244  * constructor of a bound argument throws and it is not a reference
02245  * argument.
02246  *
02247  * Since 2.0.0-rc3
02248  */
02249 template <class T, class BoundArg1, class BoundArg2,
02250           class Arg1, class Arg2, class... FreeArgs>
02251 CallbackArg<FreeArgs...>* make_ref(T& t,
02252                                    void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
02253                                    Arg1&& arg1,
02254                                    Arg2&& arg2) {
02255   return new Callback2<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func,
02256                                                                    std::forward<Arg1>(arg1),
02257                                                                    std::forward<Arg2>(arg2)};
02258 }
02259 
02260 /**
02261  * A convenience function to make Callback::CallbackArg objects
02262  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02263  * is exhausted and the system throws in that case (this exception
02264  * will not be thrown if the library has been installed using the
02265  * --with-glib-memory-slices-no-compat configuration option: instead
02266  * glib will terminate the program if it is unable to obtain memory
02267  * from the operating system).  It will also throw if the copy
02268  * constructor of a bound argument throws and it is not a reference
02269  * argument.
02270  */
02271 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
02272 CallbackArg<FreeArgs...>* make(T& t,
02273                                void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
02274                                BoundArg1 arg1,
02275                                BoundArg2 arg2,
02276                                BoundArg3 arg3) {
02277   return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
02278 }
02279 
02280 /**
02281  * DEPRECATED: use Callback::make_ref() instead.
02282  *
02283  * An alternative function to make Callback::CallbackArg objects,
02284  * which is for use where a target function receives an argument of
02285  * class type by value which is to be a bound argument, so the
02286  * compiler is not able to carry out copy elision when constructing
02287  * the callback object.
02288  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02289  * is exhausted and the system throws in that case (this exception
02290  * will not be thrown if the library has been installed using the
02291  * --with-glib-memory-slices-no-compat configuration option: instead
02292  * glib will terminate the program if it is unable to obtain memory
02293  * from the operating system).  It will also throw if the copy
02294  * constructor of a bound argument throws and it is not a reference
02295  * argument.
02296  */
02297 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
02298 CallbackArg<FreeArgs...>* make_val(T& t,
02299                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
02300                                    const BoundArg1& arg1,
02301                                    const BoundArg2& arg2,
02302                                    const BoundArg3& arg3) {
02303   return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
02304 }
02305 
02306 /**
02307  * An alternative function to make Callback::CallbackArg objects,
02308  * which is for use where a target function either receives a class
02309  * type bound argument by value, or receives a bound argument by
02310  * reference to const in a case where the generated CallbackArg object
02311  * is to store a copy of that argument instead of just keeping a
02312  * reference.
02313  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02314  * is exhausted and the system throws in that case (this exception
02315  * will not be thrown if the library has been installed using the
02316  * --with-glib-memory-slices-no-compat configuration option: instead
02317  * glib will terminate the program if it is unable to obtain memory
02318  * from the operating system).  It will also throw if the copy or move
02319  * constructor of a bound argument throws and it is not a reference
02320  * argument.
02321  *
02322  * Since 2.0.0-rc3
02323  */
02324 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02325           class Arg1, class Arg2, class Arg3, class... FreeArgs>
02326 CallbackArg<FreeArgs...>* make_ref(T& t,
02327                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
02328                                    Arg1&& arg1,
02329                                    Arg2&& arg2,
02330                                    Arg3&& arg3) {
02331   return new Callback3<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func,
02332                                                                               std::forward<Arg1>(arg1),
02333                                                                               std::forward<Arg2>(arg2),
02334                                                                               std::forward<Arg3>(arg3)};
02335 }
02336 
02337 /**
02338  * A convenience function to make Callback::CallbackArg objects
02339  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02340  * is exhausted and the system throws in that case (this exception
02341  * will not be thrown if the library has been installed using the
02342  * --with-glib-memory-slices-no-compat configuration option: instead
02343  * glib will terminate the program if it is unable to obtain memory
02344  * from the operating system).  It will also throw if the copy
02345  * constructor of a bound argument throws and it is not a reference
02346  * argument.
02347  */
02348 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02349           class BoundArg4, class... FreeArgs>
02350 CallbackArg<FreeArgs...>* make(T& t,
02351                                void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02352                                                BoundArg4, FreeArgs...),
02353                                BoundArg1 arg1,
02354                                BoundArg2 arg2,
02355                                BoundArg3 arg3,
02356                                BoundArg4 arg4) {
02357   return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3,
02358                        BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
02359 }
02360 
02361 /**
02362  * DEPRECATED: use Callback::make_ref() instead.
02363  *
02364  * An alternative function to make Callback::CallbackArg objects,
02365  * which is for use where a target function receives an argument of
02366  * class type by value which is to be a bound argument, so the
02367  * compiler is not able to carry out copy elision when constructing
02368  * the callback object.
02369  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02370  * is exhausted and the system throws in that case (this exception
02371  * will not be thrown if the library has been installed using the
02372  * --with-glib-memory-slices-no-compat configuration option: instead
02373  * glib will terminate the program if it is unable to obtain memory
02374  * from the operating system).  It will also throw if the copy
02375  * constructor of a bound argument throws and it is not a reference
02376  * argument.
02377  */
02378 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02379           class BoundArg4, class... FreeArgs>
02380 CallbackArg<FreeArgs...>* make_val(T& t,
02381                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02382                                                    BoundArg4, FreeArgs...),
02383                                    const BoundArg1& arg1,
02384                                    const BoundArg2& arg2,
02385                                    const BoundArg3& arg3,
02386                                    const BoundArg4& arg4) {
02387   return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3,
02388                        BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
02389 }
02390 
02391 /**
02392  * An alternative function to make Callback::CallbackArg objects,
02393  * which is for use where a target function either receives a class
02394  * type bound argument by value, or receives a bound argument by
02395  * reference to const in a case where the generated CallbackArg object
02396  * is to store a copy of that argument instead of just keeping a
02397  * reference.
02398  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02399  * is exhausted and the system throws in that case (this exception
02400  * will not be thrown if the library has been installed using the
02401  * --with-glib-memory-slices-no-compat configuration option: instead
02402  * glib will terminate the program if it is unable to obtain memory
02403  * from the operating system).  It will also throw if the copy or move
02404  * constructor of a bound argument throws and it is not a reference
02405  * argument.
02406  *
02407  * Since 2.0.0-rc3
02408  */
02409 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
02410           class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
02411 CallbackArg<FreeArgs...>* make_ref(T& t,
02412                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02413                                                    BoundArg4, FreeArgs...),
02414                                    Arg1&& arg1,
02415                                    Arg2&& arg2,
02416                                    Arg3&& arg3,
02417                                    Arg4&& arg4) {
02418   return new Callback4<true, T, BoundArg1, BoundArg2, BoundArg3,
02419                        BoundArg4, FreeArgs...>{t, func,
02420                                                std::forward<Arg1>(arg1),
02421                                                std::forward<Arg2>(arg2),
02422                                                std::forward<Arg3>(arg3),
02423                                                std::forward<Arg4>(arg4)};
02424 }
02425 
02426 /**
02427  * A convenience function to make Callback::CallbackArg objects
02428  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02429  * is exhausted and the system throws in that case (this exception
02430  * will not be thrown if the library has been installed using the
02431  * --with-glib-memory-slices-no-compat configuration option: instead
02432  * glib will terminate the program if it is unable to obtain memory
02433  * from the operating system).  It will also throw if the copy
02434  * constructor of a bound argument throws and it is not a reference
02435  * argument.
02436  */
02437 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02438           class BoundArg4, class BoundArg5, class... FreeArgs>
02439 CallbackArg<FreeArgs...>* make(T& t,
02440                                void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02441                                                BoundArg4, BoundArg5, FreeArgs...),
02442                                BoundArg1 arg1,
02443                                BoundArg2 arg2,
02444                                BoundArg3 arg3,
02445                                BoundArg4 arg4,
02446                                BoundArg5 arg5) {
02447   return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3,
02448                        BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
02449 }
02450 
02451 /**
02452  * DEPRECATED: use Callback::make_ref() instead.
02453  *
02454  * An alternative function to make Callback::CallbackArg objects,
02455  * which is for use where a target function receives an argument of
02456  * class type by value which is to be a bound argument, so the
02457  * compiler is not able to carry out copy elision when constructing
02458  * the callback object.
02459  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02460  * is exhausted and the system throws in that case (this exception
02461  * will not be thrown if the library has been installed using the
02462  * --with-glib-memory-slices-no-compat configuration option: instead
02463  * glib will terminate the program if it is unable to obtain memory
02464  * from the operating system).  It will also throw if the copy
02465  * constructor of a bound argument throws and it is not a reference
02466  * argument.
02467  */
02468 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02469           class BoundArg4, class BoundArg5, class... FreeArgs>
02470 CallbackArg<FreeArgs...>* make_val(T& t,
02471                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02472                                                    BoundArg4, BoundArg5, FreeArgs...),
02473                                    const BoundArg1& arg1,
02474                                    const BoundArg2& arg2,
02475                                    const BoundArg3& arg3,
02476                                    const BoundArg4& arg4,
02477                                    const BoundArg5& arg5) {
02478   return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3,
02479                        BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
02480 }
02481 
02482 /**
02483  * An alternative function to make Callback::CallbackArg objects,
02484  * which is for use where a target function either receives a class
02485  * type bound argument by value, or receives a bound argument by
02486  * reference to const in a case where the generated CallbackArg object
02487  * is to store a copy of that argument instead of just keeping a
02488  * reference.
02489  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02490  * is exhausted and the system throws in that case (this exception
02491  * will not be thrown if the library has been installed using the
02492  * --with-glib-memory-slices-no-compat configuration option: instead
02493  * glib will terminate the program if it is unable to obtain memory
02494  * from the operating system).  It will also throw if the copy or move
02495  * constructor of a bound argument throws and it is not a reference
02496  * argument.
02497  *
02498  * Since 2.0.0-rc3
02499  */
02500 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
02501           class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
02502 CallbackArg<FreeArgs...>* make_ref(T& t,
02503                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02504                                                    BoundArg4, BoundArg5, FreeArgs...),
02505                                    Arg1&& arg1,
02506                                    Arg2&& arg2,
02507                                    Arg3&& arg3,
02508                                    Arg4&& arg4,
02509                                    Arg5&& arg5) {
02510   return new Callback5<true, T, BoundArg1, BoundArg2, BoundArg3,
02511                        BoundArg4, BoundArg5, FreeArgs...>{t, func,
02512                                                           std::forward<Arg1>(arg1),
02513                                                           std::forward<Arg2>(arg2),
02514                                                           std::forward<Arg3>(arg3),
02515                                                           std::forward<Arg4>(arg4),
02516                                                           std::forward<Arg5>(arg5)};
02517 }
02518 
02519 /* const versions, for binding to const methods */
02520 
02521 /**
02522  * A convenience function to make Callback::CallbackArg objects
02523  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02524  * is exhausted and the system throws in that case.  This exception
02525  * will not be thrown if the library has been installed using the
02526  * --with-glib-memory-slices-no-compat configuration option (instead
02527  * glib will terminate the program if it is unable to obtain memory
02528  * from the operating system).
02529  */
02530 template <class T, class... FreeArgs>
02531 CallbackArg<FreeArgs...>* make(const T& t,
02532                                void (T::*func)(FreeArgs...) const) {
02533   return new Callback0_const<T, FreeArgs...>{t, func};
02534 }
02535 
02536 /**
02537  * DEPRECATED.
02538  *
02539  * Since this function constructs a callback which does not take a
02540  * bound argument, it is a synonym for make() (the two are identical).
02541  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02542  * is exhausted and the system throws in that case.  This exception
02543  * will not be thrown if the library has been installed using the
02544  * --with-glib-memory-slices-no-compat configuration option (instead
02545  * glib will terminate the program if it is unable to obtain memory
02546  * from the operating system).
02547  */
02548 template <class T, class... FreeArgs>
02549 CallbackArg<FreeArgs...>* make_val(const T& t,
02550                                    void (T::*func)(FreeArgs...) const) {
02551   return new Callback0_const<T, FreeArgs...>{t, func};
02552 }
02553 
02554 /**
02555  * Since this function constructs a callback which does not take a
02556  * bound argument, it is a synonym for make() (the two are identical).
02557  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02558  * is exhausted and the system throws in that case.  This exception
02559  * will not be thrown if the library has been installed using the
02560  * --with-glib-memory-slices-no-compat configuration option (instead
02561  * glib will terminate the program if it is unable to obtain memory
02562  * from the operating system).
02563  *
02564  * Since 2.0.0-rc3
02565  */
02566 template <class T, class... FreeArgs>
02567 CallbackArg<FreeArgs...>* make_ref(const T& t,
02568                                    void (T::*func)(FreeArgs...) const) {
02569   return new Callback0_const<T, FreeArgs...>{t, func};
02570 }
02571 
02572 /**
02573  * A convenience function to make Callback::CallbackArg objects
02574  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02575  * is exhausted and the system throws in that case (this exception
02576  * will not be thrown if the library has been installed using the
02577  * --with-glib-memory-slices-no-compat configuration option: instead
02578  * glib will terminate the program if it is unable to obtain memory
02579  * from the operating system).  It will also throw if the copy
02580  * constructor of a bound argument throws and it is not a reference
02581  * argument.
02582  */
02583 template <class T, class BoundArg, class... FreeArgs>
02584 CallbackArg<FreeArgs...>* make(const T& t,
02585                                void (T::*func)(BoundArg, FreeArgs...) const,
02586                                BoundArg arg) {
02587   return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg};
02588 }
02589 
02590 /**
02591  * DEPRECATED: use Callback::make_ref() instead.
02592  *
02593  * An alternative function to make Callback::CallbackArg objects,
02594  * which is for use where a target function receives an argument of
02595  * class type by value which is to be a bound argument, so the
02596  * compiler is not able to carry out copy elision when constructing
02597  * the callback object.
02598  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02599  * is exhausted and the system throws in that case (this exception
02600  * will not be thrown if the library has been installed using the
02601  * --with-glib-memory-slices-no-compat configuration option: instead
02602  * glib will terminate the program if it is unable to obtain memory
02603  * from the operating system).  It will also throw if the copy
02604  * constructor of a bound argument throws and it is not a reference
02605  * argument.
02606  */
02607 template <class T, class BoundArg, class... FreeArgs>
02608 CallbackArg<FreeArgs...>* make_val(const T& t,
02609                                    void (T::*func)(BoundArg, FreeArgs...) const,
02610                                    const BoundArg& arg) {
02611   return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg};
02612 }
02613 
02614 /**
02615  * An alternative function to make Callback::CallbackArg objects,
02616  * which is for use where a target function either receives a class
02617  * type bound argument by value, or receives a bound argument by
02618  * reference to const in a case where the generated CallbackArg object
02619  * is to store a copy of that argument instead of just keeping a
02620  * reference.
02621  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02622  * is exhausted and the system throws in that case (this exception
02623  * will not be thrown if the library has been installed using the
02624  * --with-glib-memory-slices-no-compat configuration option: instead
02625  * glib will terminate the program if it is unable to obtain memory
02626  * from the operating system).  It will also throw if the copy or move
02627  * constructor of a bound argument throws and it is not a reference
02628  * argument.
02629  *
02630  * Since 2.0.0-rc3
02631  */
02632 template <class T, class BoundArg, class Arg, class... FreeArgs>
02633 CallbackArg<FreeArgs...>* make_ref(const T& t,
02634                                    void (T::*func)(BoundArg, FreeArgs...) const,
02635                                    Arg&& arg) {
02636   return new Callback1_const<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)};
02637 }
02638 
02639 /**
02640  * A convenience function to make Callback::CallbackArg objects
02641  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02642  * is exhausted and the system throws in that case (this exception
02643  * will not be thrown if the library has been installed using the
02644  * --with-glib-memory-slices-no-compat configuration option: instead
02645  * glib will terminate the program if it is unable to obtain memory
02646  * from the operating system).  It will also throw if the copy
02647  * constructor of a bound argument throws and it is not a reference
02648  * argument.
02649  */
02650 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
02651 CallbackArg<FreeArgs...>* make(const T& t,
02652                                void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
02653                                BoundArg1 arg1,
02654                                BoundArg2 arg2) {
02655   return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
02656 }
02657 
02658 /**
02659  * DEPRECATED: use Callback::make_ref() instead.
02660  *
02661  * An alternative function to make Callback::CallbackArg objects,
02662  * which is for use where a target function receives an argument of
02663  * class type by value which is to be a bound argument, so the
02664  * compiler is not able to carry out copy elision when constructing
02665  * the callback object.
02666  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02667  * is exhausted and the system throws in that case (this exception
02668  * will not be thrown if the library has been installed using the
02669  * --with-glib-memory-slices-no-compat configuration option: instead
02670  * glib will terminate the program if it is unable to obtain memory
02671  * from the operating system).  It will also throw if the copy
02672  * constructor of a bound argument throws and it is not a reference
02673  * argument.
02674  */
02675 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
02676 CallbackArg<FreeArgs...>* make_val(const T& t,
02677                                    void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
02678                                    const BoundArg1& arg1,
02679                                    const BoundArg2& arg2) {
02680   return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
02681 }
02682 
02683 /**
02684  * An alternative function to make Callback::CallbackArg objects,
02685  * which is for use where a target function either receives a class
02686  * type bound argument by value, or receives a bound argument by
02687  * reference to const in a case where the generated CallbackArg object
02688  * is to store a copy of that argument instead of just keeping a
02689  * reference.
02690  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02691  * is exhausted and the system throws in that case (this exception
02692  * will not be thrown if the library has been installed using the
02693  * --with-glib-memory-slices-no-compat configuration option: instead
02694  * glib will terminate the program if it is unable to obtain memory
02695  * from the operating system).  It will also throw if the copy or move
02696  * constructor of a bound argument throws and it is not a reference
02697  * argument.
02698  *
02699  * Since 2.0.0-rc3
02700  */
02701 template <class T, class BoundArg1, class BoundArg2,
02702           class Arg1, class Arg2, class... FreeArgs>
02703 CallbackArg<FreeArgs...>* make_ref(const T& t,
02704                                    void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
02705                                    Arg1&& arg1,
02706                                    Arg2&& arg2) {
02707   return new Callback2_const<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func,
02708                                                                          std::forward<Arg1>(arg1),
02709                                                                          std::forward<Arg2>(arg2)};
02710 }
02711 
02712 /**
02713  * A convenience function to make Callback::CallbackArg objects
02714  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02715  * is exhausted and the system throws in that case (this exception
02716  * will not be thrown if the library has been installed using the
02717  * --with-glib-memory-slices-no-compat configuration option: instead
02718  * glib will terminate the program if it is unable to obtain memory
02719  * from the operating system).  It will also throw if the copy
02720  * constructor of a bound argument throws and it is not a reference
02721  * argument.
02722  */
02723 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
02724 CallbackArg<FreeArgs...>* make(const T& t,
02725                                void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
02726                                BoundArg1 arg1,
02727                                BoundArg2 arg2,
02728                                BoundArg3 arg3) {
02729   return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
02730 }
02731 
02732 /**
02733  * DEPRECATED: use Callback::make_ref() instead.
02734  *
02735  * An alternative function to make Callback::CallbackArg objects,
02736  * which is for use where a target function receives an argument of
02737  * class type by value which is to be a bound argument, so the
02738  * compiler is not able to carry out copy elision when constructing
02739  * the callback object.
02740  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02741  * is exhausted and the system throws in that case (this exception
02742  * will not be thrown if the library has been installed using the
02743  * --with-glib-memory-slices-no-compat configuration option: instead
02744  * glib will terminate the program if it is unable to obtain memory
02745  * from the operating system).  It will also throw if the copy
02746  * constructor of a bound argument throws and it is not a reference
02747  * argument.
02748  */
02749 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
02750 CallbackArg<FreeArgs...>* make_val(const T& t,
02751                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
02752                                    const BoundArg1& arg1,
02753                                    const BoundArg2& arg2,
02754                                    const BoundArg3& arg3) {
02755   return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
02756 }
02757 
02758 /**
02759  * An alternative function to make Callback::CallbackArg objects,
02760  * which is for use where a target function either receives a class
02761  * type bound argument by value, or receives a bound argument by
02762  * reference to const in a case where the generated CallbackArg object
02763  * is to store a copy of that argument instead of just keeping a
02764  * reference.
02765  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02766  * is exhausted and the system throws in that case (this exception
02767  * will not be thrown if the library has been installed using the
02768  * --with-glib-memory-slices-no-compat configuration option: instead
02769  * glib will terminate the program if it is unable to obtain memory
02770  * from the operating system).  It will also throw if the copy or move
02771  * constructor of a bound argument throws and it is not a reference
02772  * argument.
02773  *
02774  * Since 2.0.0-rc3
02775  */
02776 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02777           class Arg1, class Arg2, class Arg3, class... FreeArgs>
02778 CallbackArg<FreeArgs...>* make_ref(const T& t,
02779                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
02780                                    Arg1&& arg1,
02781                                    Arg2&& arg2,
02782                                    Arg3&& arg3) {
02783   return new Callback3_const<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func,
02784                                                                                     std::forward<Arg1>(arg1),
02785                                                                                     std::forward<Arg2>(arg2),
02786                                                                                     std::forward<Arg3>(arg3)};
02787 }
02788 
02789 /**
02790  * A convenience function to make Callback::CallbackArg objects
02791  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02792  * is exhausted and the system throws in that case (this exception
02793  * will not be thrown if the library has been installed using the
02794  * --with-glib-memory-slices-no-compat configuration option: instead
02795  * glib will terminate the program if it is unable to obtain memory
02796  * from the operating system).  It will also throw if the copy
02797  * constructor of a bound argument throws and it is not a reference
02798  * argument.
02799  */
02800 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02801           class BoundArg4, class... FreeArgs>
02802 CallbackArg<FreeArgs...>* make(const T& t,
02803                                void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02804                                                BoundArg4, FreeArgs...) const,
02805                                BoundArg1 arg1,
02806                                BoundArg2 arg2,
02807                                BoundArg3 arg3,
02808                                BoundArg4 arg4) {
02809   return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3,
02810                              BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
02811 }
02812 
02813 /**
02814  * DEPRECATED: use Callback::make_ref() instead.
02815  *
02816  * An alternative function to make Callback::CallbackArg objects,
02817  * which is for use where a target function receives an argument of
02818  * class type by value which is to be a bound argument, so the
02819  * compiler is not able to carry out copy elision when constructing
02820  * the callback object.
02821  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02822  * is exhausted and the system throws in that case (this exception
02823  * will not be thrown if the library has been installed using the
02824  * --with-glib-memory-slices-no-compat configuration option: instead
02825  * glib will terminate the program if it is unable to obtain memory
02826  * from the operating system).  It will also throw if the copy
02827  * constructor of a bound argument throws and it is not a reference
02828  * argument.
02829  */
02830 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02831           class BoundArg4, class... FreeArgs>
02832 CallbackArg<FreeArgs...>* make_val(const T& t,
02833                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02834                                                    BoundArg4, FreeArgs...) const,
02835                                    const BoundArg1& arg1,
02836                                    const BoundArg2& arg2,
02837                                    const BoundArg3& arg3,
02838                                    const BoundArg4& arg4) {
02839   return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3,
02840                              BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
02841 }
02842 
02843 /**
02844  * An alternative function to make Callback::CallbackArg objects,
02845  * which is for use where a target function either receives a class
02846  * type bound argument by value, or receives a bound argument by
02847  * reference to const in a case where the generated CallbackArg object
02848  * is to store a copy of that argument instead of just keeping a
02849  * reference.
02850  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02851  * is exhausted and the system throws in that case (this exception
02852  * will not be thrown if the library has been installed using the
02853  * --with-glib-memory-slices-no-compat configuration option: instead
02854  * glib will terminate the program if it is unable to obtain memory
02855  * from the operating system).  It will also throw if the copy or move
02856  * constructor of a bound argument throws and it is not a reference
02857  * argument.
02858  *
02859  * Since 2.0.0-rc3
02860  */
02861 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
02862           class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
02863 CallbackArg<FreeArgs...>* make_ref(const T& t,
02864                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02865                                                    BoundArg4, FreeArgs...) const,
02866                                    Arg1&& arg1,
02867                                    Arg2&& arg2,
02868                                    Arg3&& arg3,
02869                                    Arg4&& arg4) {
02870   return new Callback4_const<true, T, BoundArg1, BoundArg2, BoundArg3,
02871                              BoundArg4, FreeArgs...>{t, func,
02872                                                      std::forward<Arg1>(arg1),
02873                                                      std::forward<Arg2>(arg2),
02874                                                      std::forward<Arg3>(arg3),
02875                                                      std::forward<Arg4>(arg4)};
02876 }
02877 
02878 /**
02879  * A convenience function to make Callback::CallbackArg objects
02880  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02881  * is exhausted and the system throws in that case (this exception
02882  * will not be thrown if the library has been installed using the
02883  * --with-glib-memory-slices-no-compat configuration option: instead
02884  * glib will terminate the program if it is unable to obtain memory
02885  * from the operating system).  It will also throw if the copy
02886  * constructor of a bound argument throws and it is not a reference
02887  * argument.
02888  */
02889 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02890           class BoundArg4, class BoundArg5, class... FreeArgs>
02891 CallbackArg<FreeArgs...>* make(const T& t,
02892                                void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02893                                                BoundArg4, BoundArg5, FreeArgs...) const,
02894                                BoundArg1 arg1,
02895                                BoundArg2 arg2,
02896                                BoundArg3 arg3,
02897                                BoundArg4 arg4,
02898                                BoundArg5 arg5) {
02899   return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3,
02900                              BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
02901 }
02902 
02903 /**
02904  * DEPRECATED: use Callback::make_ref() instead.
02905  *
02906  * An alternative function to make Callback::CallbackArg objects,
02907  * which is for use where a target function receives an argument of
02908  * class type by value which is to be a bound argument, so the
02909  * compiler is not able to carry out copy elision when constructing
02910  * the callback object.
02911  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02912  * is exhausted and the system throws in that case (this exception
02913  * will not be thrown if the library has been installed using the
02914  * --with-glib-memory-slices-no-compat configuration option: instead
02915  * glib will terminate the program if it is unable to obtain memory
02916  * from the operating system).  It will also throw if the copy
02917  * constructor of a bound argument throws and it is not a reference
02918  * argument.
02919  */
02920 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
02921           class BoundArg4, class BoundArg5, class... FreeArgs>
02922 CallbackArg<FreeArgs...>* make_val(const T& t,
02923                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02924                                                    BoundArg4, BoundArg5, FreeArgs...) const,
02925                                    const BoundArg1& arg1,
02926                                    const BoundArg2& arg2,
02927                                    const BoundArg3& arg3,
02928                                    const BoundArg4& arg4,
02929                                    const BoundArg5& arg5) {
02930   return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3,
02931                              BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
02932 }
02933 
02934 /**
02935  * An alternative function to make Callback::CallbackArg objects,
02936  * which is for use where a target function either receives a class
02937  * type bound argument by value, or receives a bound argument by
02938  * reference to const in a case where the generated CallbackArg object
02939  * is to store a copy of that argument instead of just keeping a
02940  * reference.
02941  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02942  * is exhausted and the system throws in that case (this exception
02943  * will not be thrown if the library has been installed using the
02944  * --with-glib-memory-slices-no-compat configuration option: instead
02945  * glib will terminate the program if it is unable to obtain memory
02946  * from the operating system).  It will also throw if the copy or move
02947  * constructor of a bound argument throws and it is not a reference
02948  * argument.
02949  *
02950  * Since 2.0.0-rc3
02951  */
02952 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
02953           class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
02954 CallbackArg<FreeArgs...>* make_ref(const T& t,
02955                                    void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
02956                                                    BoundArg4, BoundArg5, FreeArgs...) const,
02957                                    Arg1&& arg1,
02958                                    Arg2&& arg2,
02959                                    Arg3&& arg3,
02960                                    Arg4&& arg4,
02961                                    Arg5&& arg5) {
02962   return new Callback5_const<true, T, BoundArg1, BoundArg2, BoundArg3,
02963                              BoundArg4, BoundArg5, FreeArgs...>{t, func,
02964                                                                 std::forward<Arg1>(arg1),
02965                                                                 std::forward<Arg2>(arg2),
02966                                                                 std::forward<Arg3>(arg3),
02967                                                                 std::forward<Arg4>(arg4),
02968                                                                 std::forward<Arg5>(arg5)};
02969 }
02970 
02971 /* for static class methods and non-class functions */
02972 
02973 /**
02974  * A convenience function to make Callback::CallbackArg objects
02975  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02976  * is exhausted and the system throws in that case.  This exception
02977  * will not be thrown if the library has been installed using the
02978  * --with-glib-memory-slices-no-compat configuration option (instead
02979  * glib will terminate the program if it is unable to obtain memory
02980  * from the operating system).
02981  */
02982 template <class... FreeArgs>
02983 CallbackArg<FreeArgs...>* make(void (*func)(FreeArgs...)) {
02984   return new Callback0_static<FreeArgs...>{func};
02985 }
02986 
02987 /**
02988  * DEPRECATED.
02989  *
02990  * Since this function constructs a callback which does not take a
02991  * bound argument, it is a synonym for make() (the two are identical).
02992  * @exception std::bad_alloc It might throw std::bad_alloc if memory
02993  * is exhausted and the system throws in that case.  This exception
02994  * will not be thrown if the library has been installed using the
02995  * --with-glib-memory-slices-no-compat configuration option (instead
02996  * glib will terminate the program if it is unable to obtain memory
02997  * from the operating system).
02998  */
02999 template <class... FreeArgs>
03000 CallbackArg<FreeArgs...>* make_val(void (*func)(FreeArgs...)) {
03001   return new Callback0_static<FreeArgs...>{func};
03002 }
03003 
03004 /**
03005  * Since this function constructs a callback which does not take a
03006  * bound argument, it is a synonym for make() (the two are identical).
03007  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03008  * is exhausted and the system throws in that case.  This exception
03009  * will not be thrown if the library has been installed using the
03010  * --with-glib-memory-slices-no-compat configuration option (instead
03011  * glib will terminate the program if it is unable to obtain memory
03012  * from the operating system).
03013  *
03014  * Since 2.0.0-rc3
03015  */
03016 template <class... FreeArgs>
03017 CallbackArg<FreeArgs...>* make_ref(void (*func)(FreeArgs...)) {
03018   return new Callback0_static<FreeArgs...>{func};
03019 }
03020 
03021 /**
03022  * A convenience function to make Callback::CallbackArg objects
03023  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03024  * is exhausted and the system throws in that case (this exception
03025  * will not be thrown if the library has been installed using the
03026  * --with-glib-memory-slices-no-compat configuration option: instead
03027  * glib will terminate the program if it is unable to obtain memory
03028  * from the operating system).  It will also throw if the copy
03029  * constructor of a bound argument throws and it is not a reference
03030  * argument.
03031  */
03032 template <class BoundArg, class... FreeArgs>
03033 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg, FreeArgs...),
03034                                BoundArg arg) {
03035   return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg};
03036 }
03037 
03038 /**
03039  * DEPRECATED: use Callback::make_ref() instead.
03040  *
03041  * An alternative function to make Callback::CallbackArg objects,
03042  * which is for use where a target function receives an argument of
03043  * class type by value which is to be a bound argument, so the
03044  * compiler is not able to carry out copy elision when constructing
03045  * the callback object.
03046  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03047  * is exhausted and the system throws in that case (this exception
03048  * will not be thrown if the library has been installed using the
03049  * --with-glib-memory-slices-no-compat configuration option: instead
03050  * glib will terminate the program if it is unable to obtain memory
03051  * from the operating system).  It will also throw if the copy
03052  * constructor of a bound argument throws and it is not a reference
03053  * argument.
03054  */
03055 template <class BoundArg, class... FreeArgs>
03056 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg, FreeArgs...),
03057                                    const BoundArg& arg) {
03058   return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg};
03059 }
03060 
03061 /**
03062  * An alternative function to make Callback::CallbackArg objects,
03063  * which is for use where a target function either receives a class
03064  * type bound argument by value, or receives a bound argument by
03065  * reference to const in a case where the generated CallbackArg object
03066  * is to store a copy of that argument instead of just keeping a
03067  * reference.
03068  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03069  * is exhausted and the system throws in that case (this exception
03070  * will not be thrown if the library has been installed using the
03071  * --with-glib-memory-slices-no-compat configuration option: instead
03072  * glib will terminate the program if it is unable to obtain memory
03073  * from the operating system).  It will also throw if the copy or move
03074  * constructor of a bound argument throws and it is not a reference
03075  * argument.
03076  *
03077  * Since 2.0.0-rc3
03078  */
03079 template <class BoundArg, class Arg, class... FreeArgs>
03080 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg, FreeArgs...),
03081                                    Arg&& arg) {
03082   return new Callback1_static<true, BoundArg, FreeArgs...>{func, std::forward<Arg>(arg)};
03083 }
03084 
03085 /**
03086  * A convenience function to make Callback::CallbackArg objects
03087  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03088  * is exhausted and the system throws in that case (this exception
03089  * will not be thrown if the library has been installed using the
03090  * --with-glib-memory-slices-no-compat configuration option: instead
03091  * glib will terminate the program if it is unable to obtain memory
03092  * from the operating system).  It will also throw if the copy
03093  * constructor of a bound argument throws and it is not a reference
03094  * argument.
03095  */
03096 template <class BoundArg1, class BoundArg2, class... FreeArgs>
03097 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
03098                                BoundArg1 arg1,
03099                                BoundArg2 arg2) {
03100   return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2};
03101 }
03102 
03103 /**
03104  * DEPRECATED: use Callback::make_ref() instead.
03105  *
03106  * An alternative function to make Callback::CallbackArg objects,
03107  * which is for use where a target function receives an argument of
03108  * class type by value which is to be a bound argument, so the
03109  * compiler is not able to carry out copy elision when constructing
03110  * the callback object.
03111  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03112  * is exhausted and the system throws in that case (this exception
03113  * will not be thrown if the library has been installed using the
03114  * --with-glib-memory-slices-no-compat configuration option: instead
03115  * glib will terminate the program if it is unable to obtain memory
03116  * from the operating system).  It will also throw if the copy
03117  * constructor of a bound argument throws and it is not a reference
03118  * argument.
03119  */
03120 template <class BoundArg1, class BoundArg2, class... FreeArgs>
03121 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
03122                                    const BoundArg1& arg1,
03123                                    const BoundArg2& arg2) {
03124   return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2};
03125 }
03126 
03127 /**
03128  * An alternative function to make Callback::CallbackArg objects,
03129  * which is for use where a target function either receives a class
03130  * type bound argument by value, or receives a bound argument by
03131  * reference to const in a case where the generated CallbackArg object
03132  * is to store a copy of that argument instead of just keeping a
03133  * reference.
03134  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03135  * is exhausted and the system throws in that case (this exception
03136  * will not be thrown if the library has been installed using the
03137  * --with-glib-memory-slices-no-compat configuration option: instead
03138  * glib will terminate the program if it is unable to obtain memory
03139  * from the operating system).  It will also throw if the copy or move
03140  * constructor of a bound argument throws and it is not a reference
03141  * argument.
03142  *
03143  * Since 2.0.0-rc3
03144  */
03145 template <class BoundArg1, class BoundArg2, class Arg1, class Arg2, class... FreeArgs>
03146 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
03147                                    Arg1&& arg1,
03148                                    Arg2&& arg2) {
03149   return new Callback2_static<true, BoundArg1, BoundArg2, FreeArgs...>{func,
03150                                                                        std::forward<Arg1>(arg1),
03151                                                                        std::forward<Arg2>(arg2)};
03152 }
03153 
03154 /**
03155  * A convenience function to make Callback::CallbackArg objects
03156  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03157  * is exhausted and the system throws in that case (this exception
03158  * will not be thrown if the library has been installed using the
03159  * --with-glib-memory-slices-no-compat configuration option: instead
03160  * glib will terminate the program if it is unable to obtain memory
03161  * from the operating system).  It will also throw if the copy
03162  * constructor of a bound argument throws and it is not a reference
03163  * argument.
03164  */
03165 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
03166 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
03167                                BoundArg1 arg1,
03168                                BoundArg2 arg2,
03169                                BoundArg3 arg3) {
03170   return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3};
03171 }
03172 
03173 /**
03174  * DEPRECATED: use Callback::make_ref() instead.
03175  *
03176  * An alternative function to make Callback::CallbackArg objects,
03177  * which is for use where a target function receives an argument of
03178  * class type by value which is to be a bound argument, so the
03179  * compiler is not able to carry out copy elision when constructing
03180  * the callback object.
03181  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03182  * is exhausted and the system throws in that case (this exception
03183  * will not be thrown if the library has been installed using the
03184  * --with-glib-memory-slices-no-compat configuration option: instead
03185  * glib will terminate the program if it is unable to obtain memory
03186  * from the operating system).  It will also throw if the copy
03187  * constructor of a bound argument throws and it is not a reference
03188  * argument.
03189  */
03190 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
03191 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
03192                                    const BoundArg1& arg1,
03193                                    const BoundArg2& arg2,
03194                                    const BoundArg3& arg3) {
03195   return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3};
03196 }
03197 
03198 /**
03199  * An alternative function to make Callback::CallbackArg objects,
03200  * which is for use where a target function either receives a class
03201  * type bound argument by value, or receives a bound argument by
03202  * reference to const in a case where the generated CallbackArg object
03203  * is to store a copy of that argument instead of just keeping a
03204  * reference.
03205  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03206  * is exhausted and the system throws in that case (this exception
03207  * will not be thrown if the library has been installed using the
03208  * --with-glib-memory-slices-no-compat configuration option: instead
03209  * glib will terminate the program if it is unable to obtain memory
03210  * from the operating system).  It will also throw if the copy or move
03211  * constructor of a bound argument throws and it is not a reference
03212  * argument.
03213  *
03214  * Since 2.0.0-rc3
03215  */
03216 template <class BoundArg1, class BoundArg2, class BoundArg3,
03217           class Arg1, class Arg2, class Arg3, class... FreeArgs>
03218 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
03219                                    Arg1&& arg1,
03220                                    Arg2&& arg2,
03221                                    Arg3&& arg3) {
03222   return new Callback3_static<true, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func,
03223                                                                                   std::forward<Arg1>(arg1),
03224                                                                                   std::forward<Arg2>(arg2),
03225                                                                                   std::forward<Arg3>(arg3)};
03226 }
03227 
03228 /**
03229  * A convenience function to make Callback::CallbackArg objects
03230  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03231  * is exhausted and the system throws in that case (this exception
03232  * will not be thrown if the library has been installed using the
03233  * --with-glib-memory-slices-no-compat configuration option: instead
03234  * glib will terminate the program if it is unable to obtain memory
03235  * from the operating system).  It will also throw if the copy
03236  * constructor of a bound argument throws and it is not a reference
03237  * argument.
03238  */
03239 template <class BoundArg1, class BoundArg2, class BoundArg3,
03240           class BoundArg4, class... FreeArgs>
03241 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3,
03242                                             BoundArg4, FreeArgs...),
03243                                BoundArg1 arg1,
03244                                BoundArg2 arg2,
03245                                BoundArg3 arg3,
03246                                BoundArg4 arg4) {
03247   return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3,
03248                               BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4};
03249 }
03250 
03251 /**
03252  * DEPRECATED: use Callback::make_ref() instead.
03253  *
03254  * An alternative function to make Callback::CallbackArg objects,
03255  * which is for use where a target function receives an argument of
03256  * class type by value which is to be a bound argument, so the
03257  * compiler is not able to carry out copy elision when constructing
03258  * the callback object.
03259  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03260  * is exhausted and the system throws in that case (this exception
03261  * will not be thrown if the library has been installed using the
03262  * --with-glib-memory-slices-no-compat configuration option: instead
03263  * glib will terminate the program if it is unable to obtain memory
03264  * from the operating system).  It will also throw if the copy
03265  * constructor of a bound argument throws and it is not a reference
03266  * argument.
03267  */
03268 template <class BoundArg1, class BoundArg2, class BoundArg3,
03269           class BoundArg4, class... FreeArgs>
03270 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3,
03271                                                 BoundArg4, FreeArgs...),
03272                                    const BoundArg1& arg1,
03273                                    const BoundArg2& arg2,
03274                                    const BoundArg3& arg3,
03275                                    const BoundArg4& arg4) {
03276   return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3,
03277                               BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4};
03278 }
03279 
03280 /**
03281  * An alternative function to make Callback::CallbackArg objects,
03282  * which is for use where a target function either receives a class
03283  * type bound argument by value, or receives a bound argument by
03284  * reference to const in a case where the generated CallbackArg object
03285  * is to store a copy of that argument instead of just keeping a
03286  * reference.
03287  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03288  * is exhausted and the system throws in that case (this exception
03289  * will not be thrown if the library has been installed using the
03290  * --with-glib-memory-slices-no-compat configuration option: instead
03291  * glib will terminate the program if it is unable to obtain memory
03292  * from the operating system).  It will also throw if the copy or move
03293  * constructor of a bound argument throws and it is not a reference
03294  * argument.
03295  *
03296  * Since 2.0.0-rc3
03297  */
03298 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
03299           class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
03300 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3,
03301                                                 BoundArg4, FreeArgs...),
03302                                    Arg1&& arg1,
03303                                    Arg2&& arg2,
03304                                    Arg3&& arg3,
03305                                    Arg4&& arg4) {
03306   return new Callback4_static<true, BoundArg1, BoundArg2, BoundArg3,
03307                               BoundArg4, FreeArgs...>{func,
03308                                                       std::forward<Arg1>(arg1),
03309                                                       std::forward<Arg2>(arg2),
03310                                                       std::forward<Arg3>(arg3),
03311                                                       std::forward<Arg4>(arg4)};
03312 }
03313 
03314 /**
03315  * A convenience function to make Callback::CallbackArg objects
03316  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03317  * is exhausted and the system throws in that case (this exception
03318  * will not be thrown if the library has been installed using the
03319  * --with-glib-memory-slices-no-compat configuration option: instead
03320  * glib will terminate the program if it is unable to obtain memory
03321  * from the operating system).  It will also throw if the copy
03322  * constructor of a bound argument throws and it is not a reference
03323  * argument.
03324  */
03325 template <class BoundArg1, class BoundArg2, class BoundArg3,
03326           class BoundArg4, class BoundArg5, class... FreeArgs>
03327 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3,
03328                                             BoundArg4, BoundArg5, FreeArgs...),
03329                                BoundArg1 arg1,
03330                                BoundArg2 arg2,
03331                                BoundArg3 arg3,
03332                                BoundArg4 arg4,
03333                                BoundArg5 arg5) {
03334   return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3,
03335                               BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5};
03336 }
03337 
03338 /**
03339  * DEPRECATED: use Callback::make_ref() instead.
03340  *
03341  * An alternative function to make Callback::CallbackArg objects,
03342  * which is for use where a target function receives an argument of
03343  * class type by value which is to be a bound argument, so the
03344  * compiler is not able to carry out copy elision when constructing
03345  * the callback object.
03346  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03347  * is exhausted and the system throws in that case (this exception
03348  * will not be thrown if the library has been installed using the
03349  * --with-glib-memory-slices-no-compat configuration option: instead
03350  * glib will terminate the program if it is unable to obtain memory
03351  * from the operating system).  It will also throw if the copy
03352  * constructor of a bound argument throws and it is not a reference
03353  * argument.
03354  */
03355 template <class BoundArg1, class BoundArg2, class BoundArg3,
03356           class BoundArg4, class BoundArg5, class... FreeArgs>
03357 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3,
03358                                                 BoundArg4, BoundArg5, FreeArgs...),
03359                                    const BoundArg1& arg1,
03360                                    const BoundArg2& arg2,
03361                                    const BoundArg3& arg3,
03362                                    const BoundArg4& arg4,
03363                                    const BoundArg5& arg5) {
03364   return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3,
03365                               BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5};
03366 }
03367 
03368 /**
03369  * An alternative function to make Callback::CallbackArg objects,
03370  * which is for use where a target function either receives a class
03371  * type bound argument by value, or receives a bound argument by
03372  * reference to const in a case where the generated CallbackArg object
03373  * is to store a copy of that argument instead of just keeping a
03374  * reference.
03375  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03376  * is exhausted and the system throws in that case (this exception
03377  * will not be thrown if the library has been installed using the
03378  * --with-glib-memory-slices-no-compat configuration option: instead
03379  * glib will terminate the program if it is unable to obtain memory
03380  * from the operating system).  It will also throw if the copy or move
03381  * constructor of a bound argument throws and it is not a reference
03382  * argument.
03383  *
03384  * Since 2.0.0-rc3
03385  */
03386 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
03387           class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
03388 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3,
03389                                                 BoundArg4, BoundArg5, FreeArgs...),
03390                                    Arg1&& arg1,
03391                                    Arg2&& arg2,
03392                                    Arg3&& arg3,
03393                                    Arg4&& arg4,
03394                                    Arg5&& arg5) {
03395   return new Callback5_static<true, BoundArg1, BoundArg2, BoundArg3,
03396                               BoundArg4, BoundArg5, FreeArgs...>{func,
03397                                                                  std::forward<Arg1>(arg1),
03398                                                                  std::forward<Arg2>(arg2),
03399                                                                  std::forward<Arg3>(arg3),
03400                                                                  std::forward<Arg4>(arg4),
03401                                                                  std::forward<Arg5>(arg5)};
03402 }
03403 
03404 /* for std::function objects */
03405 
03406 /**
03407  * A convenience function to make Callback::CallbackArg objects from
03408  * std::function objects.
03409  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03410  * is exhausted and the system throws in that case (this exception
03411  * will not be thrown if the library has been installed using the
03412  * --with-glib-memory-slices-no-compat configuration option: instead
03413  * glib will terminate the program if it is unable to obtain memory
03414  * from the operating system).  It will also throw if the copy
03415  * constructor of a bound argument throws and it is not a reference
03416  * argument.
03417  */
03418 template <class... FreeArgs>
03419 CallbackArg<FreeArgs...>* make(const std::function<void(FreeArgs...)>& f) {
03420   return new Callback_function<FreeArgs...>{f};
03421 }
03422 
03423 /**
03424  * DEPRECATED.
03425  *
03426  * A convenience function to make Callback::Callback objects from
03427  * std::function objects.  Since this function takes no bound argument
03428  * (and bound arguments are bound into the std::function object), it
03429  * is a synonym for make() (the two are identical).
03430  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03431  * is exhausted and the system throws in that case (this exception
03432  * will not be thrown if the library has been installed using the
03433  * --with-glib-memory-slices-no-compat configuration option: instead
03434  * glib will terminate the program if it is unable to obtain memory
03435  * from the operating system).  It will also throw if the copy
03436  * constructor of a bound argument throws and it is not a reference
03437  * argument.
03438  */
03439 template <class... FreeArgs>
03440 CallbackArg<FreeArgs...>* make_val(const std::function<void(FreeArgs...)>& f) {
03441   return new Callback_function<FreeArgs...>{f};
03442 }
03443 
03444 /**
03445  * A convenience function to make Callback::Callback objects from
03446  * std::function objects.  Since this function takes no bound argument
03447  * (and bound arguments are bound into the std::function object), it
03448  * is a synonym for make() (the two are identical).
03449  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03450  * is exhausted and the system throws in that case (this exception
03451  * will not be thrown if the library has been installed using the
03452  * --with-glib-memory-slices-no-compat configuration option: instead
03453  * glib will terminate the program if it is unable to obtain memory
03454  * from the operating system).  It will also throw if the copy
03455  * constructor of a bound argument throws and it is not a reference
03456  * argument.
03457  */
03458 template <class... FreeArgs>
03459 CallbackArg<FreeArgs...>* make_ref(const std::function<void(FreeArgs...)>& f) {
03460   return new Callback_function<FreeArgs...>{f};
03461 }
03462 
03463 /**
03464  * A convenience function to make Callback::CallbackArg objects from
03465  * std::function objects.
03466  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03467  * is exhausted and the system throws in that case (this exception
03468  * will not be thrown if the library has been installed using the
03469  * --with-glib-memory-slices-no-compat configuration option: instead
03470  * glib will terminate the program if it is unable to obtain memory
03471  * from the operating system).  It will also throw if the copy
03472  * constructor of a bound argument throws and it is not a reference
03473  * argument.
03474  */
03475 template <class... FreeArgs>
03476 CallbackArg<FreeArgs...>* make(std::function<void(FreeArgs...)>&& f) {
03477   return new Callback_function<FreeArgs...>{std::move(f)};
03478 }
03479 
03480 /**
03481  * DEPRECATED.
03482  *
03483  * A convenience function to make Callback::Callback objects from
03484  * std::function objects.  Since this function takes no bound argument
03485  * (and bound arguments are bound into the std::function object), it
03486  * is a synonym for make() (the two are identical).
03487  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03488  * is exhausted and the system throws in that case (this exception
03489  * will not be thrown if the library has been installed using the
03490  * --with-glib-memory-slices-no-compat configuration option: instead
03491  * glib will terminate the program if it is unable to obtain memory
03492  * from the operating system).  It will also throw if the copy or move
03493  * constructor of a bound argument throws and it is not a reference
03494  * argument.
03495  */
03496 template <class... FreeArgs>
03497 CallbackArg<FreeArgs...>* make_val(std::function<void(FreeArgs...)>&& f) {
03498   return new Callback_function<FreeArgs...>{std::move(f)};
03499 }
03500 
03501 /**
03502  * A convenience function to make Callback::Callback objects from
03503  * std::function objects.  Since this function takes no bound argument
03504  * (and bound arguments are bound into the std::function object), it
03505  * is a synonym for make() (the two are identical).
03506  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03507  * is exhausted and the system throws in that case (this exception
03508  * will not be thrown if the library has been installed using the
03509  * --with-glib-memory-slices-no-compat configuration option: instead
03510  * glib will terminate the program if it is unable to obtain memory
03511  * from the operating system).  It will also throw if the copy or move
03512  * constructor of a bound argument throws and it is not a reference
03513  * argument.
03514  */
03515 template <class... FreeArgs>
03516 CallbackArg<FreeArgs...>* make_ref(std::function<void(FreeArgs...)>&& f) {
03517   return new Callback_function<FreeArgs...>{std::move(f)};
03518 }
03519 
03520 // This helper function to construct Callback_lambda objects could be
03521 // implemented as a further overload of Callback::make().  No best
03522 // match ambiguities would arise, because even when Callback::make()
03523 // is passed a function pointer without bound arguments, the overload
03524 // of Callback::make taking a function pointer (as opposed to a
03525 // generic callable object) would still comprise the best match.
03526 // However, to construct Callback_lambda objects, the unbound
03527 // arguments need to be specified by hand, which doesn't happen with
03528 // Callback::make() (it would only be necessary to specify an explicit
03529 // type where a mutable reference argument is to be bound to the
03530 // callback object).  It seems to me to be less confusing to the user
03531 // therefore to have a separate Callback::lambda() helper function.
03532 // However, if you disagree please let me know.
03533 
03534 // template parameter packs do not need to be placed last in the case
03535 // of function templates, as type deduction is available for the last
03536 // parameter: there is in fact no function parameter pack in
03537 // Callback::lambda() (function parameter packs must come last).
03538 /**
03539  * A convenience function to make Callback::CallbackArg objects from
03540  * C++11 lambda expressions, or from any other arbitrary callable
03541  * object.
03542  * @exception std::bad_alloc It might throw std::bad_alloc if memory
03543  * is exhausted and the system throws in that case.  It will also
03544  * throw if the copy or move constructor of an object captured by the
03545  * lambda expression throws.
03546  *
03547  * Since 2.0.9
03548  */
03549 template <class... FreeArgs, class Lambda>
03550 CallbackArg<FreeArgs...>* lambda(Lambda&& l) {
03551   return new Callback_lambda<Lambda, FreeArgs...>{std::forward<Lambda>(l)};
03552 }
03553 
03554 } // namespace Callback
03555 
03556 class Releaser;
03557 
03558 namespace Callback {
03559 
03560 /**
03561  * Posts a callback for execution by a glib main loop.  It is
03562  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
03563  * has been called.  glib >= 2.32 does not require g_thread_init() to
03564  * be called.  This function will not throw.
03565  * @param cb The callback object.  Ownership is taken of this object,
03566  * and it will be deleted when it has been finished with.
03567  * @param priority The priority to be given to the callback in the
03568  * main loop.  In ascending order of priorities, priorities are
03569  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
03570  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
03571  * G_PRIORITY_DEFAULT_IDLE.  This determines the order in which the
03572  * callback will appear in the event list in the main loop, not the
03573  * priority which the OS will adopt
03574  * @param context The glib main loop context in which the callback is
03575  * to be executed (the default of NULL will cause the callback to be
03576  * executed in the main program loop, and this is usually what is
03577  * wanted).
03578  * @note Cancellation of the receiving thread is blocked when the
03579  * callback executes.
03580  */
03581 void post(const Callback* cb, gint priority = G_PRIORITY_DEFAULT_IDLE,
03582           GMainContext* context = 0);
03583 
03584 /**
03585  * Posts a callback for execution by a glib main loop.  It is
03586  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
03587  * has been called.  glib >= 2.32 does not require g_thread_init() to
03588  * be called.  This function will not throw.
03589  * @param cb The callback object.  Ownership is taken of this object,
03590  * and it will be deleted when it has been finished with.
03591  * @param r A Releaser object for automatic disconnection of the
03592  * callback from the main loop.
03593  * @param priority The priority to be given to the callback in the
03594  * main loop.  In ascending order of priorities, priorities are
03595  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
03596  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
03597  * G_PRIORITY_DEFAULT_IDLE.  This determines the order in which the
03598  * callback will appear in the event list in the main loop, not the
03599  * priority which the OS will adopt.
03600  * @param context The glib main loop context in which the callback is
03601  * to be executed (the default of NULL will cause the callback to be
03602  * executed in the main program loop, and this is usually what is
03603  * wanted).
03604  * @exception std::bad_alloc This function might throw std::bad_alloc
03605  * if memory is exhausted and the system throws in that case.  If it
03606  * does so, the Callback object will be disposed of.
03607  * @exception Cgu::Thread::MutexError This method might throw
03608  * Cgu:Thread::MutexError if initialisation of the mutex in a
03609  * SafeEmitterArg object constructed by this method fails.  If it does
03610  * so, the Callback object will be disposed of.  (It is often not
03611  * worth checking for this exception, as it means either memory is
03612  * exhausted or pthread has run out of other resources to create new
03613  * mutexes.)
03614  * @note Cancellation of the receiving thread is blocked when the
03615  * callback executes.
03616  */
03617 void post(const Callback* cb, Releaser& r,
03618           gint priority = G_PRIORITY_DEFAULT_IDLE, GMainContext* context = 0);
03619 
03620 } // namespace Callback
03621 
03622 } // namespace Cgu
03623 
03624 #endif