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