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