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