c++-gtk-utils
callback.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 to 2013 Chris Vine
2 
3 The library comprised in this file or of which this file is part is
4 distributed by Chris Vine under the GNU Lesser General Public
5 License as follows:
6 
7  This library is free software; you can redistribute it and/or
8  modify it under the terms of the GNU Lesser General Public License
9  as published by the Free Software Foundation; either version 2.1 of
10  the License, or (at your option) any later version.
11 
12  This library is distributed in the hope that it will be useful, but
13  WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  Lesser General Public License, version 2.1, for more details.
16 
17  You should have received a copy of the GNU Lesser General Public
18  License, version 2.1, along with this library (see the file LGPL.TXT
19  which came with this source code package in the c++-gtk-utils
20  sub-directory); if not, write to the Free Software Foundation, Inc.,
21  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22 
23 However, it is not intended that the object code of a program whose
24 source code instantiates a template from this file or uses macros or
25 inline functions (of any length) should by reason only of that
26 instantiation or use be subject to the restrictions of use in the GNU
27 Lesser General Public License. With that in mind, the words "and
28 macros, inline functions and instantiations of templates (of any
29 length)" shall be treated as substituted for the words "and small
30 macros and small inline functions (ten lines or less in length)" in
31 the fourth paragraph of section 5 of that licence. This does not
32 affect any other reason why object code may be subject to the
33 restrictions in that licence (nor for the avoidance of doubt does it
34 affect the application of section 2 of that licence to modifications
35 of the source code in this file).
36 
37 */
38 
39 #ifndef CGU_CALLBACK_H
40 #define CGU_CALLBACK_H
41 
42 /**
43  * @file callback.h
44  * @brief This file provides classes encapsulating callbacks.
45  *
46  * \#include <c++-gtk-utils/callback.h>
47  *
48  * These classes encapsulate callbacks (they are closures). They
49  * comprise a generic callback creation and execution interface.
50  * There is a basic Callback::Callback type, which is an entire
51  * closure or 'thunk', where all the arguments are bound in the
52  * constructor and is completely opaque. Callback::CallbackArg<T...>
53  * is a class which takes unbound arguments of the template types when
54  * the callback is dispatched, with any other arguments being bound at
55  * construction time. (The opaque Callback::Callback type is in fact
56  * just a typedef for Callback::CallbackArg<>: the two types are
57  * interchangeable.)
58  *
59  * The classes can represent static and non-static member functions
60  * and plain functions. In the case of a non-static member function,
61  * the object whose member function the callback represents must
62  * remain in existence until any invocations of the callback have
63  * completed. The function referred to must be one of void return
64  * type. A callback object can also be constructed from any function
65  * object, provided that it is of void return type (which would
66  * amongst other things enable, where necessary, the binding of the
67  * referenced object of a non-static member function by taking an
68  * internal copy of it using std::bind or by lambda capture).
69  *
70  * They are particularly useful where a callback object may need to be
71  * handed between threads.
72  *
73  * The classes can also be useful for general event passing when used
74  * together with the Callback::post() functions, or as the data
75  * argument of a call to g_signal_connect_data() in a case where a
76  * better design arises when passing arguments known at connect time
77  * by storing them in the callback object itself, or as the
78  * continuation for GIO async operations.
79  *
80  * These classes are also used in the Emitter/EmitterArg classes in
81  * emitter.h, which enable callbacks to be connected to an emitter and
82  * provide for automatic disconnection where a class object whose
83  * member a callback represents ceases to exist.
84  *
85  * The Callback::make() functions
86  * ------------------------------
87  *
88  * The templated helper Callback::make() functions make it trivial to
89  * create a callback object of the correct type. The ordinary
90  * Callback::make() functions (that is, those not taking a
91  * std::function object) provide for a maximum of five bound arguments
92  * to pass to the relevant function or class method, and an unlimited
93  * number of unbound arguments, but unbound arguments must be the last
94  * (trailing) arguments of the relevant function or method to be
95  * called if there is a bound argument. Callback/CallbackArg classes
96  * do not provide for a return value. If a result is wanted, users
97  * should pass an unbound argument by reference or pointer (or pointer
98  * to pointer).
99  *
100  * Although as mentioned above only five bound arguments are provided
101  * for by callbacks constructed by the ordinary Callback::make()
102  * functions, as any of those arguments can be a struct, any number of
103  * arguments can be passed as members of a struct or a std::tuple. In
104  * addition, a callback object can be constructed using
105  * Callback::make() from a std::function object, which can have any
106  * number of arguments bound to it, and in any order (that is, unbound
107  * arguments may precede bound arguments).
108  *
109  * The Callback::make() functions not taking a std::function object do
110  * a direct type mapping from the bound arguments of the function or
111  * method represented by the callback object to the arguments stored
112  * by the callback object. Bound value arguments of the relevant
113  * function or method to be called are therefore stored by value in
114  * the callback object. A bound argument can comprise a reference
115  * argument (T& or const T&) if the template parameters of the
116  * Callback::make() call are qualified by hand to avoid a type
117  * mismatch: see under "Usage" below for further particulars, and if
118  * the reference argument is non-const this allows the referenced
119  * argument to be mutated. However as this would result in the
120  * lifetime of the argument not being controlled by the callback
121  * object (it would not keep its own copy), it will often be unsafe to
122  * do so. (The documentation on Thread::JoinableHandle gives a usage
123  * where where binding a reference argument would be safe.)
124  *
125  * From version 2.0.0-rc3, the library also provides
126  * Callback::make_ref() functions, which force the callback object to
127  * keep a copy of the value passed where a target function argument is
128  * a const reference. It is therefore safe with const reference
129  * arguments. No explicit type qualification is required by
130  * Callback::make_ref(). In addition the Callback::make_ref()
131  * functions provide for more efficient passing of class type bound
132  * arguments (by l-value or r-value reference) than does
133  * Callback::make(): see further below.
134  *
135  * The Callback::make_ref() functions
136  * ----------------------------------
137  *
138  * In order to enable the widest variety of types to be accepted as
139  * arguments (including reference arguments in those cases where it is
140  * safe, and also string literals), as mentioned above when
141  * constructing a callback object from other than a std::function
142  * object, Callback::make() receives non-reference bound arguments by
143  * value, and if unoptimised these may be copied up to two times, and
144  * once more when the target function is dispatched. Where a bound
145  * argument is a pointer or a fundamental type (an integral or
146  * floating-point type), optimization by copy elision will reduce the
147  * number of times argument copying takes place when constructing a
148  * callback object to once, but the standard does not permit that with
149  * class types where the constructor or destructor have side effects
150  * or it cannot be ascertained whether they have side effects.
151  *
152  * Therefore, to cater for cases where a target function takes a class
153  * type argument by const reference or value, from version 2.0.0-rc3
154  * the Callback::make_ref() functions are provided. Unlike
155  * Callback::make(), when constructing a callback for a target
156  * function taking a const reference bound argument,
157  * Callback::make_ref() will force the callback object to keep a copy
158  * of the argument instead of a reference to that argument. This
159  * makes the use of const reference arguments safe (at the cost of the
160  * storing of that copy). It cannot be used with non-const
161  * references. In addition Callback::make_ref() automatically chooses
162  * the most efficient means of passing class type arguments for
163  * storage by the callback object, that is by l-value reference or
164  * r-value reference, as appropriate.
165  *
166  * In the case of a value argument, at callback dispatch time one
167  * additional copy will be made in the normal way when the target
168  * function is called, but in the case of a const reference argument
169  * no such additional copy will be made. What all this means is that,
170  * where bound arguments include a non-trivial class type, the most
171  * efficient and exception safe strategy is usually:
172  *
173  * 1. If that class type has a rvalue constructor, to have the target
174  * function take that type by const reference argument, and pass a
175  * newly constructed object of that type to Callback::make_ref() as a
176  * temporary (so that it is passed by r-value reference and stored in
177  * the callback object without any copying at all), or
178  * 2. To construct the object of the class type on free store and held
179  * by Cgu::SharedPtr, Cgu::SharedLockPtr or std::shared_ptr, have the
180  * target function take it by const Cgu::SharedPtr&, const
181  * Cgu::SharedLockPtr& or const std::shared_ptr&, and construct the
182  * callback object using Callback::make_ref().
183  *
184  * This flexibility of Callback::make_ref() has a downside: unlike
185  * Callback::make(), Callback::make_ref() cannot resolve overloaded
186  * functions by argument type. Where a function has two or more
187  * overloads taking the same number of arguments, explicit
188  * disambiguation by the user is required (see further below under
189  * Overloaded Functions).
190  *
191  * Summary: If a callback object's bound arguments are all simple
192  * fundamental types such as pointers (including C strings), integers
193  * or floating points, use Callback::make(). Where bound arguments
194  * include class types, use Callback::make_ref().
195  *
196  * The Callback::make_val() functions
197  * ----------------------------------
198  *
199  * The library also provides Callback::make_val() functions. These
200  * are provided to retain code compatibility with version 1.2 of the
201  * library. They were optimised for use where a target function takes
202  * bound arguments of class type by value, but are now deprecated and
203  * superseded by the automatic variable type mapping of
204  * Callback::make_ref(). Callback::make_ref() should now be used
205  * instead of Callback::make_val().
206  *
207  * Constructing callbacks from std::function objects
208  * -------------------------------------------------
209  *
210  * The Callback::make() factory functions can also construct a
211  * callback object from a std::function object, which would enable a
212  * callback to take more than 5 bound arguments, or to have a bound
213  * argument which is passed after (or mixed with) unbound arguments,
214  * or to have its own copy of the referenced object of a non-static
215  * member function bound to it.
216  *
217  * However, the genericity of the binding of arguments implemented in
218  * std::function and std::bind comes at a cost. Arguments bound to a
219  * std::function object can be copied a significant number of times
220  * (libstdc++ for example can copy class types four times when
221  * constructing a std::function object and two more times when
222  * executing the function, unless they have a r-value constructor, in
223  * which case they are copied twice and once respectively with two and
224  * one additional calls to the r-value constructor). Non-trivial
225  * class types should therefore only be passed as bound arguments to
226  * std::function objects by pointer or smart pointer.
227  *
228  * Note that the overload of Callback::make() for std::function
229  * objects has a version taking a r-value reference for the lossless
230  * passing through of temporaries to the callback object, and a
231  * version taking a const reference for std::function objects which
232  * are l-values. For std::function objects, Callback::make() and
233  * Callback::make_ref() are all synonyms (the way arguments are dealt
234  * with for std::function objects is determined by std::bind() and
235  * std::ref()).
236  *
237  * From version 2.0.9, in many uses it is better to pass a function
238  * object (such as the return value of std::bind(), or one generated
239  * by a lambda expression) to Callback::lambda(), which takes any
240  * arbitrary callable object directly as a template parameter.
241  *
242  * The Callback::lambda() functions
243  * --------------------------------
244  *
245  * Callback objects for C++11 lambda expressions can be constructed
246  * using Callback::make() by passing the lambda object via a temporary
247  * std::function object (see under Usage below for an example).
248  * However, from version 2.0.9 the Callback::lambda() factory function
249  * is provided enabling callbacks for C++11 lambda expressions to be
250  * constructed more directly. This is nice, as by using
251  * Callback::lambda() a callback can, for example, be executed by a
252  * glib main loop using Callback::post() with:
253  * @code
254  * using namespace Cgu;
255  * post(Callback::lambda<>([]() {std::cout << "Hello glib\n";})); // post() found by argument dependent lookup
256  * @endcode
257  * Further examples are given under Usage below.
258  *
259  * Callback::lambda() can construct a callback object from any
260  * arbitrary function object, such as the return value of std::bind().
261  * Using Callback::lambda() to construct such a callback object,
262  * rather than using Callback::make() with a temporary std::function
263  * object, will also be more efficient, as when executed it would
264  * normally avoid the additional virtual function call that would
265  * arise with std::function.
266  *
267  * When using Callback::lambda(), the unbound argument types must be
268  * specified explicitly (they cannot be deduced from the lambda
269  * expression).
270  *
271  * From version 2.0.10, Callback::lambda() can be called for lambda
272  * expressions which are declared mutable capturing bound arguments by
273  * value (in version 2.0.9, the function could only be called for
274  * non-mutable lambda expressions). From version 2.0.16, it can be
275  * passed callable objects which are lvalues as well as rvalues (prior
276  * to version 2.0.16, it could only be passed callable objects which
277  * are rvalues).
278  *
279  * One other feature of Callback::lambda() is that the callable object
280  * passed to it need not be of void return type. However, if the
281  * callable object does return a value, that value is discarded. If a
282  * result is wanted, an unbound reference or pointer argument should
283  * be passed when the callback is executed, to which the result can be
284  * assigned.
285  *
286  * If using lambda expressions with gcc, gcc-4.5 or greater is needed.
287  * The header file callback.h can be included without error with
288  * gcc-4.4, but callable objects cannot be constructed using C++11
289  * lambda syntax.
290  *
291  * Functors
292  * --------
293  *
294  * If a functor class of void return type is required (say for passing
295  * to a c++ algorithm or container, or for automatic lifetime
296  * management of the Callback object), the Callback::Functor and
297  * Callback::FunctorArg wrapper classes can be used. However, for
298  * many c++ algorithms where anonymous functors created as temporaries
299  * can be used, the std::ptr_fun(), std::mem_fn() and std::bind()
300  * factory functions or a lambda expression will be a more obvious
301  * choice. Callback::Functor and Callback::FunctorArg are to be
302  * preferred to std::function where value arguments are to be bound
303  * (see above), unless something other than a void return type is
304  * required.
305  *
306  * Callback::SafeFunctor and Callback::SafeFunctorArg classes are the
307  * same as Callback::Functor and Callback::FunctorArg classes, except
308  * that objects of the safe version may be passed and copied between
309  * threads and put in different containers in different threads (that
310  * is, the reference count maintained with respect to the contained
311  * callback object is thread-safe). They use a SharedLockPtr object
312  * to hold the referenced callback object.
313  *
314  * Memory allocation
315  * -----------------
316  *
317  * If the library is installed using the
318  * \--with-glib-memory-slices-compat or
319  * \--with-glib-memory-slices-no-compat configuration options, any
320  * Callback::Functor, Callback::FunctorArg, Callback::SafeFunctor or
321  * Callback::SafeFunctorArg objects constructed on free store (usually
322  * they won't be) will be constructed in glib memory slices. A
323  * contained Callback::Callback or Callback::CallbackArg object, which
324  * will always be constructed on free store, will be constructed in
325  * glib memory slices if the \--with-glib-memory-slices-no-compat
326  * configuration option is chosen.
327  *
328  * Usage
329  * -----
330  *
331  * For a class object my_obj of type MyClass, with a method void
332  * MyClass::my_method(int, int, const char*), usage for a fully bound
333  * callback or functor would be:
334  *
335  * @code
336  * using namespace Cgu;
337  * int arg1 = 1, arg2 = 5;
338  * Callback::Callback* cb =
339  * Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n");
340  * cb->dispatch();
341  * delete cb;
342  *
343  * Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")};
344  * f();
345  * @endcode
346  *
347  * Or for a partially bound callback or functor:
348  *
349  * @code
350  * using namespace Cgu;
351  * int arg1 = 1, arg2 = 5;
352  * Callback::CallbackArg<int, const char*>* cb =
353  * Callback::make(my_obj, &MyClass::my_method, arg1);
354  * cb->dispatch(arg2, "Hello\n");
355  * delete cb;
356  *
357  * Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)};
358  * f(arg2, "Hello\n");
359  * @endcode
360  *
361  * The syntax for the construction of a callback object representing a
362  * static member function with a signature void MyClass::my_func(int,
363  * const char*), or for a normal function, is similar to the
364  * non-static member function case, except that the call to
365  * Callback::make would comprise:
366  *
367  * @code
368  * Callback::make(&MyClass::my_func, arg1, arg2, "Hello\n");
369  * @endcode
370  * (fully bound), or
371  * @code
372  * Callback::make(&MyClass::my_func, arg1);
373  * @endcode
374  * (partially bound), and so on.
375  *
376  * To bind to reference arguments, the call to Callback::make() must
377  * be explicitly typed. For a class object my_obj of type MyClass,
378  * with a method void MyClass::my_method(int&), usage for a fully
379  * bound callback or functor would be:
380  *
381  * @code
382  * int arg = 1;
383  * Callback::Callback* cb =
384  * Callback::make<MyClass, int&>(my_obj, &MyClass::my_method, arg);
385  * @endcode
386  *
387  * Note however the caveats above about binding to reference
388  * arguments.
389  *
390  * No similar explicit typing is required by Callback::make_ref().
391  * Thus for a class object my_obj of type MyClass, with a method void
392  * MyClass::my_method(int, const Something&), usage for a fully bound
393  * callback or functor would be:
394  *
395  * @code
396  * int arg1 = 1;
397  * Something arg2;
398  * Callback::Callback* cb =
399  * Callback::make_ref(my_obj, &MyClass::my_method, arg1, arg2);
400  * @endcode
401  *
402  * From version 2.0.9, Callback::lambda() provides an easy
403  * way of dealing with lambda expressions, for example:
404  *
405  * @code
406  * Callback::Callback* cb;
407  * {
408  * std::string s("Hello");
409  * cb = Callback::lambda<>([=](){std::cout << s << std::endl;});
410  * }
411  * cb->dispatch(); // 's' is now out of scope, but it has been captured by value
412  * // by the lambda object and is now held by the callback object
413  * delete cb;
414  * @endcode
415  *
416  * With Callback::lambda(), the types of the unbound arguments must be
417  * explicitly specified as they cannot be deduced. Unbound arguments
418  * can comprise reference arguments. For example:
419  *
420  * @code
421  * int res;
422  * auto cb = Callback::lambda<int, int, int&>([](int j, int k, int& r) {r = j * k;});
423  * cb->dispatch(2, 3, res);
424  * std::cout << res << std::endl;
425  * delete cb;
426  * @endcode
427  *
428  * Callback::lambda() can take any function object, such as one
429  * returned by std::bind(). So, constructing a callback object
430  * representing a class object my_obj of type MyClass, with a method
431  * void MyClass::my_method(int, int, int, double, const char*), where
432  * a value is to be bound to the second argument could comprise:
433  *
434  * @code
435  * using namespace std::placeholders; // for _1, _2, _3 and _4
436  * int arg = 1;
437  * auto cb = Callback::lambda<int, int, double, const char*>(
438  * std::bind(&MyClass::my_method, &my_obj,
439  * _1, arg, _2, _3, _4)
440  * );
441  * cb->dispatch(5, 3, 10.2, "Hello\n");
442  * delete cb;
443  * @endcode
444  *
445  * Using std::bind, if the bound argument were a reference (that is,
446  * the signature of MyClass::my_method were (int, int&, int, double,
447  * const char*) and it were safe to do so (see above), it could be
448  * bound with std::ref(), as in:
449  *
450  * @code
451  * using namespace std::placeholders; // for _1, _2, _3 and _4
452  * int arg;
453  * auto cb = Callback::lambda<int, int, double, const char*>(
454  * std::bind(&MyClass::my_method, &my_obj,
455  * _1, std::ref(arg), _2, _3, _4)
456  * );
457  * @endcode
458  *
459  * Prior version to 2.0.9, lambda expressions and the return value of
460  * std::bind() would have to be passed by using a temporary
461  * std::function object and Callback::make, as follows:
462  *
463  * @code
464  * Callback::Callback* cb;
465  * {
466  * std::string s("Hello");
467  * cb = Callback::make(std::function<void()>{[=](){std::cout << s << std::endl;}});
468  * }
469  * cb->dispatch();
470  * delete cb;
471  * @endcode
472  *
473  * Overloaded functions
474  * --------------------
475  *
476  * Note that creating callbacks for overloaded functions can give rise
477  * to an ambiguity when using Callback::make(), arising from the fact
478  * that the callback object may have an unbound argument. For
479  * example:
480  *
481  * @code
482  * class MyClass {
483  * ...
484  * void add(int i);
485  * void add(int i, int j);
486  * void add(double d);
487  * };
488  * MyClass obj;
489  * using namespace Cgu;
490  * Callback::Callback* cb1 = Callback::make(obj, &MyClass::add, 1, 2); // ok
491  * Callback::Callback* cb2 = Callback::make(obj, &MyClass::add, 1.0); // ok
492  * Callback::Callback* cb3 = Callback::make(obj, &MyClass::add, 1); // ambiguous - compilation failure
493  * @endcode
494  *
495  * The third call to Callback::make() is ambiguous, as it could be
496  * creating a callback for either the function MyClass::add(int) with
497  * no unbound argument (that is, creating a Callback::Callback
498  * object), or the function MyClass::add(int, int) with an unbound int
499  * argument (that is, creating a Callback::CallbackArg<int> object).
500  * This situation could be disambiguated by specifically stating the
501  * type of the function which is to be chosen, namely, to instantiate
502  * the callback in the third call with:
503  *
504  * @code
505  * // either:
506  * Callback::Callback* cb3 =
507  * Callback::make(obj, static_cast<void (MyClass::*)(int)>(&MyClass::add), 1);
508  * // or:
509  * Callback::CallbackArg<int>* cb3 =
510  * Callback::make(obj, static_cast<void (MyClass::*)(int, int)>(&MyClass::add), 1);
511  * @endcode
512  *
513  * Callback::make_ref() is less capable than Callback::make() at
514  * deducing template types. It cannot resolve overloaded functions by
515  * examining the arguments passed to it. For example, take a class
516  * MyClass as follows:
517  *
518  * @code
519  * class MyClass {
520  * ...
521  * void add(int i, const double& d);
522  * void add(const int& j, const int& k);
523  * };
524  * @endcode
525  *
526  * Callback::make_ref() would require explicit disambiguation like
527  * this:
528  *
529  * @code
530  * Callback::Callback* cb1 =
531  * Callback::make_ref(obj, static_cast<void (MyClass::*)(int, const double&)>(&MyClass::add), 1, 2.2);
532  * Callback::Callback* cb2 =
533  * Callback::make_ref(obj, static_cast<void (MyClass::*)(const int&, const int&)>(&MyClass::add), 4, 5);
534  * @endcode
535  *
536  * Note also that, for CallbackArg objects created from std::function
537  * objects, the std::function constructors and the std::mem_fn() and
538  * std::bind() functions normally do not allow any function
539  * overloading without explicit disambiguation.
540  *
541  * Posting of callbacks
542  * --------------------
543  *
544  * This file also provides Callback::post() functions which will
545  * execute a callback in a glib main loop and can be used (amongst
546  * other things) to pass an event from a worker thread to the main
547  * program thread. In that respect, it provides an alternative to the
548  * Notifier class. It is passed a pointer to a Callback::Callback
549  * object created with a call to Callback::make() or
550  * Callback::lambda().
551  *
552  * To provide for thread-safe automatic disconnection of the callback
553  * if the object whose method it represents is destroyed before the
554  * callback executes in the main loop, include a Releaser as a public
555  * member of that object and pass the Releaser object as the second
556  * argument of Callback::post(). Note that for this to be race free,
557  * the lifetime of the remote object whose method is to be invoked
558  * must be determined by the thread to whose main loop the callback
559  * has been attached. When the main loop begins invoking the
560  * execution of the callback, the remote object must either wholly
561  * exist (in which case the callback will be invoked) or have been
562  * destroyed (in which case the callback will be ignored), and not be
563  * in some transient half-state governed by another thread.
564  *
565  * Advantages as against Notifier:
566  *
567  * 1. If there are a lot of different events requiring callbacks to be
568  * dispatched in the program from worker threads to the main
569  * thread, this avoids having separate Notifier objects for each
570  * event.
571  * 2. It is easier to pass arguments with varying values - they can be
572  * passed as arguments to the Callback::make functions and no
573  * special synchronisation is normally required (the call to
574  * g_source_attach() invokes locking of the main loop which will
575  * have the effect of ensuring memory visibility). With a Notifier
576  * object it may be necessary to use an asynchronous queue to pass
577  * variable values (or to bind a reference to the data, thus
578  * normally requiring separate synchronisation).
579  * 3. Although the callback would normally be sent for execution by
580  * the main program loop, and that is the default, it can be sent
581  * for execution by any thread which has its own
582  * GMainContext/GMainLoop objects. Thus callbacks can be passed
583  * for execution between worker threads, or from the main program
584  * thread to worker threads, as well as from worker threads to the
585  * main program thread.
586  *
587  * Disadvantages as against Notifier:
588  *
589  * 1. Less efficient, as a new callback object has to be created on
590  * freestore every time the callback is invoked, together with a
591  * new Emitter object if a Releaser is used to track the callback.
592  * 2. Multiple callbacks relevant to a single event cannot be invoked
593  * from a single call for the event - each callback has to be
594  * separately dispatched.
595  */
596 
597 /**
598  * @namespace Cgu::Callback
599  * @brief This namespace provides classes encapsulating callbacks.
600  *
601  * \#include <c++-gtk-utils/callback.h>
602  *
603  * These classes encapsulate callbacks (they are closures). They
604  * comprise a generic callback creation and execution interface.
605  * There is a basic Callback::Callback type, which is an entire
606  * closure or 'thunk', where all the arguments are bound in the
607  * constructor and is completely opaque. Callback::CallbackArg<T...>
608  * is a class which takes unbound arguments of the template types when
609  * the callback is dispatched, with any other arguments being bound at
610  * construction time. (The opaque Callback::Callback type is in fact
611  * just a typedef for Callback::CallbackArg<>: the two types are
612  * interchangeable.)
613  *
614  * The classes can represent static and non-static member functions
615  * and plain functions. In the case of a non-static member function,
616  * the object whose member function the callback represents must
617  * remain in existence until any invocations of the callback have
618  * completed. The function referred to must be one of void return
619  * type. A callback object can also be constructed from any function
620  * object, provided that it is of void return type (which would
621  * amongst other things enable, where necessary, the binding of the
622  * referenced object of a non-static member function by taking an
623  * internal copy of it using std::bind or by lambda capture).
624  *
625  * They are particularly useful where a callback object may need to be
626  * handed between threads.
627  *
628  * The classes can also be useful for general event passing when used
629  * together with the Callback::post() functions, or as the data
630  * argument of a call to g_signal_connect_data() in a case where a
631  * better design arises when passing arguments known at connect time
632  * by storing them in the callback object itself, or as the
633  * continuation for GIO async operations.
634  *
635  * These classes are also used in the Emitter/EmitterArg classes in
636  * emitter.h, which enable callbacks to be connected to an emitter and
637  * provide for automatic disconnection where a class object whose
638  * member a callback represents ceases to exist.
639  *
640  * The Callback::make() functions
641  * ------------------------------
642  *
643  * The templated helper Callback::make() functions make it trivial to
644  * create a callback object of the correct type. The ordinary
645  * Callback::make() functions (that is, those not taking a
646  * std::function object) provide for a maximum of five bound arguments
647  * to pass to the relevant function or class method, and an unlimited
648  * number of unbound arguments, but unbound arguments must be the last
649  * (trailing) arguments of the relevant function or method to be
650  * called if there is a bound argument. Callback/CallbackArg classes
651  * do not provide for a return value. If a result is wanted, users
652  * should pass an unbound argument by reference or pointer (or pointer
653  * to pointer).
654  *
655  * Although as mentioned above only five bound arguments are provided
656  * for by callbacks constructed by the ordinary Callback::make()
657  * functions, as any of those arguments can be a struct, any number of
658  * arguments can be passed as members of a struct or a std::tuple. In
659  * addition, a callback object can be constructed using
660  * Callback::make() from a std::function object, which can have any
661  * number of arguments bound to it, and in any order (that is, unbound
662  * arguments may precede bound arguments).
663  *
664  * The Callback::make() functions not taking a std::function object do
665  * a direct type mapping from the bound arguments of the function or
666  * method represented by the callback object to the arguments stored
667  * by the callback object. Bound value arguments of the relevant
668  * function or method to be called are therefore stored by value in
669  * the callback object. A bound argument can comprise a reference
670  * argument (T& or const T&) if the template parameters of the
671  * Callback::make() call are qualified by hand to avoid a type
672  * mismatch: see under "Usage" below for further particulars, and if
673  * the reference argument is non-const this allows the referenced
674  * argument to be mutated. However as this would result in the
675  * lifetime of the argument not being controlled by the callback
676  * object (it would not keep its own copy), it will often be unsafe to
677  * do so. (The documentation on Thread::JoinableHandle gives a usage
678  * where where binding a reference argument would be safe.)
679  *
680  * From version 2.0.0-rc3, the library also provides
681  * Callback::make_ref() functions, which force the callback object to
682  * keep a copy of the value passed where a target function argument is
683  * a const reference. It is therefore safe with const reference
684  * arguments. No explicit type qualification is required by
685  * Callback::make_ref(). In addition the Callback::make_ref()
686  * functions provide for more efficient passing of class type bound
687  * arguments (by l-value or r-value reference) than does
688  * Callback::make(): see further below.
689  *
690  * The Callback::make_ref() functions
691  * ----------------------------------
692  *
693  * In order to enable the widest variety of types to be accepted as
694  * arguments (including reference arguments in those cases where it is
695  * safe, and also string literals), as mentioned above when
696  * constructing a callback object from other than a std::function
697  * object, Callback::make() receives non-reference bound arguments by
698  * value, and if unoptimised these may be copied up to two times, and
699  * once more when the target function is dispatched. Where a bound
700  * argument is a pointer or a fundamental type (an integral or
701  * floating-point type), optimization by copy elision will reduce the
702  * number of times argument copying takes place when constructing a
703  * callback object to once, but the standard does not permit that with
704  * class types where the constructor or destructor have side effects
705  * or it cannot be ascertained whether they have side effects.
706  *
707  * Therefore, to cater for cases where a target function takes a class
708  * type argument by const reference or value, from version 2.0.0-rc3
709  * the Callback::make_ref() functions are provided. Unlike
710  * Callback::make(), when constructing a callback for a target
711  * function taking a const reference bound argument,
712  * Callback::make_ref() will force the callback object to keep a copy
713  * of the argument instead of a reference to that argument. This
714  * makes the use of const reference arguments safe (at the cost of the
715  * storing of that copy). It cannot be used with non-const
716  * references. In addition Callback::make_ref() automatically chooses
717  * the most efficient means of passing class type arguments for
718  * storage by the callback object, that is by l-value reference or
719  * r-value reference, as appropriate.
720  *
721  * In the case of a value argument, at callback dispatch time one
722  * additional copy will be made in the normal way when the target
723  * function is called, but in the case of a const reference argument
724  * no such additional copy will be made. What all this means is that,
725  * where bound arguments include a non-trivial class type, the most
726  * efficient and exception safe strategy is usually:
727  *
728  * 1. If that class type has a rvalue constructor, to have the target
729  * function take that type by const reference argument, and pass a
730  * newly constructed object of that type to Callback::make_ref() as a
731  * temporary (so that it is passed by r-value reference and stored in
732  * the callback object without any copying at all), or
733  * 2. To construct the object of the class type on free store and held
734  * by Cgu::SharedPtr, Cgu::SharedLockPtr or std::shared_ptr, have the
735  * target function take it by const Cgu::SharedPtr&, const
736  * Cgu::SharedLockPtr& or const std::shared_ptr&, and construct the
737  * callback object using Callback::make_ref().
738  *
739  * This flexibility of Callback::make_ref() has a downside: unlike
740  * Callback::make(), Callback::make_ref() cannot resolve overloaded
741  * functions by argument type. Where a function has two or more
742  * overloads taking the same number of arguments, explicit
743  * disambiguation by the user is required (see further below under
744  * Overloaded Functions).
745  *
746  * Summary: If a callback object's bound arguments are all simple
747  * fundamental types such as pointers (including C strings), integers
748  * or floating points, use Callback::make(). Where bound arguments
749  * include class types, use Callback::make_ref().
750  *
751  * The Callback::make_val() functions
752  * ----------------------------------
753  *
754  * The library also provides Callback::make_val() functions. These
755  * are provided to retain code compatibility with version 1.2 of the
756  * library. They were optimised for use where a target function takes
757  * bound arguments of class type by value, but are now deprecated and
758  * superseded by the automatic variable type mapping of
759  * Callback::make_ref(). Callback::make_ref() should now be used
760  * instead of Callback::make_val().
761  *
762  * Constructing callbacks from std::function objects
763  * -------------------------------------------------
764  *
765  * The Callback::make() factory functions can also construct a
766  * callback object from a std::function object, which would enable a
767  * callback to take more than 5 bound arguments, or to have a bound
768  * argument which is passed after (or mixed with) unbound arguments,
769  * or to have its own copy of the referenced object of a non-static
770  * member function bound to it.
771  *
772  * However, the genericity of the binding of arguments implemented in
773  * std::function and std::bind comes at a cost. Arguments bound to a
774  * std::function object can be copied a significant number of times
775  * (libstdc++ for example can copy class types four times when
776  * constructing a std::function object and two more times when
777  * executing the function, unless they have a r-value constructor, in
778  * which case they are copied twice and once respectively with two and
779  * one additional calls to the r-value constructor). Non-trivial
780  * class types should therefore only be passed as bound arguments to
781  * std::function objects by pointer or smart pointer.
782  *
783  * Note that the overload of Callback::make() for std::function
784  * objects has a version taking a r-value reference for the lossless
785  * passing through of temporaries to the callback object, and a
786  * version taking a const reference for std::function objects which
787  * are l-values. For std::function objects, Callback::make() and
788  * Callback::make_ref() are all synonyms (the way arguments are dealt
789  * with for std::function objects is determined by std::bind() and
790  * std::ref()).
791  *
792  * From version 2.0.9, in many uses it is better to pass a function
793  * object (such as the return value of std::bind(), or one generated
794  * by a lambda expression) to Callback::lambda(), which takes any
795  * arbitrary callable object directly as a template parameter.
796  *
797  * The Callback::lambda() functions
798  * --------------------------------
799  *
800  * Callback objects for C++11 lambda expressions can be constructed
801  * using Callback::make() by passing the lambda object via a temporary
802  * std::function object (see under Usage below for an example).
803  * However, from version 2.0.9 the Callback::lambda() factory function
804  * is provided enabling callbacks for C++11 lambda expressions to be
805  * constructed more directly. This is nice, as by using
806  * Callback::lambda() a callback can, for example, be executed by a
807  * glib main loop using Callback::post() with:
808  * @code
809  * using namespace Cgu;
810  * post(Callback::lambda<>([]() {std::cout << "Hello glib\n";})); // post() found by argument dependent lookup
811  * @endcode
812  * Further examples are given under Usage below.
813  *
814  * Callback::lambda() can construct a callback object from any
815  * arbitrary function object, such as the return value of std::bind().
816  * Using Callback::lambda() to construct such a callback object,
817  * rather than using Callback::make() with a temporary std::function
818  * object, will also be more efficient, as when executed it would
819  * normally avoid the additional virtual function call that would
820  * arise with std::function.
821  *
822  * When using Callback::lambda(), the unbound argument types must be
823  * specified explicitly (they cannot be deduced from the lambda
824  * expression).
825  *
826  * From version 2.0.10, Callback::lambda() can be called for lambda
827  * expressions which are declared mutable capturing bound arguments by
828  * value (in version 2.0.9, the function could only be called for
829  * non-mutable lambda expressions). From version 2.0.16, it can be
830  * passed callable objects which are lvalues as well as rvalues (prior
831  * to version 2.0.16, it could only be passed callable objects which
832  * are rvalues).
833  *
834  * One other feature of Callback::lambda() is that the callable object
835  * passed to it need not be of void return type. However, if the
836  * callable object does return a value, that value is discarded. If a
837  * result is wanted, an unbound reference or pointer argument should
838  * be passed when the callback is executed, to which the result can be
839  * assigned.
840  *
841  * If using lambda expressions with gcc, gcc-4.5 or greater is needed.
842  * The header file callback.h can be included without error with
843  * gcc-4.4, but callable objects cannot be constructed using C++11
844  * lambda syntax.
845  *
846  * Functors
847  * --------
848  *
849  * If a functor class of void return type is required (say for passing
850  * to a c++ algorithm or container, or for automatic lifetime
851  * management of the Callback object), the Callback::Functor and
852  * Callback::FunctorArg wrapper classes can be used. However, for
853  * many c++ algorithms where anonymous functors created as temporaries
854  * can be used, the std::ptr_fun(), std::mem_fn() and std::bind()
855  * factory functions or a lambda expression will be a more obvious
856  * choice. Callback::Functor and Callback::FunctorArg are to be
857  * preferred to std::function where value arguments are to be bound
858  * (see above), unless something other than a void return type is
859  * required.
860  *
861  * Callback::SafeFunctor and Callback::SafeFunctorArg classes are the
862  * same as Callback::Functor and Callback::FunctorArg classes, except
863  * that objects of the safe version may be passed and copied between
864  * threads and put in different containers in different threads (that
865  * is, the reference count maintained with respect to the contained
866  * callback object is thread-safe). They use a SharedLockPtr object
867  * to hold the referenced callback object.
868  *
869  * Memory allocation
870  * -----------------
871  *
872  * If the library is installed using the
873  * \--with-glib-memory-slices-compat or
874  * \--with-glib-memory-slices-no-compat configuration options, any
875  * Callback::Functor, Callback::FunctorArg, Callback::SafeFunctor or
876  * Callback::SafeFunctorArg objects constructed on free store (usually
877  * they won't be) will be constructed in glib memory slices. A
878  * contained Callback::Callback or Callback::CallbackArg object, which
879  * will always be constructed on free store, will be constructed in
880  * glib memory slices if the \--with-glib-memory-slices-no-compat
881  * configuration option is chosen.
882  *
883  * Usage
884  * -----
885  *
886  * For a class object my_obj of type MyClass, with a method void
887  * MyClass::my_method(int, int, const char*), usage for a fully bound
888  * callback or functor would be:
889  *
890  * @code
891  * using namespace Cgu;
892  * int arg1 = 1, arg2 = 5;
893  * Callback::Callback* cb =
894  * Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n");
895  * cb->dispatch();
896  * delete cb;
897  *
898  * Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")};
899  * f();
900  * @endcode
901  *
902  * Or for a partially bound callback or functor:
903  *
904  * @code
905  * using namespace Cgu;
906  * int arg1 = 1, arg2 = 5;
907  * Callback::CallbackArg<int, const char*>* cb =
908  * Callback::make(my_obj, &MyClass::my_method, arg1);
909  * cb->dispatch(arg2, "Hello\n");
910  * delete cb;
911  *
912  * Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)};
913  * f(arg2, "Hello\n");
914  * @endcode
915  *
916  * The syntax for the construction of a callback object representing a
917  * static member function with a signature void MyClass::my_func(int,
918  * const char*), or for a normal function, is similar to the
919  * non-static member function case, except that the call to
920  * Callback::make would comprise:
921  *
922  * @code
923  * Callback::make(&MyClass::my_func, arg1, arg2, "Hello\n");
924  * @endcode
925  * (fully bound), or
926  * @code
927  * Callback::make(&MyClass::my_func, arg1);
928  * @endcode
929  * (partially bound), and so on.
930  *
931  * To bind to reference arguments, the call to Callback::make() must
932  * be explicitly typed. For a class object my_obj of type MyClass,
933  * with a method void MyClass::my_method(int&), usage for a fully
934  * bound callback or functor would be:
935  *
936  * @code
937  * int arg = 1;
938  * Callback::Callback* cb =
939  * Callback::make<MyClass, int&>(my_obj, &MyClass::my_method, arg);
940  * @endcode
941  *
942  * Note however the caveats above about binding to reference
943  * arguments.
944  *
945  * No similar explicit typing is required by Callback::make_ref().
946  * Thus for a class object my_obj of type MyClass, with a method void
947  * MyClass::my_method(int, const Something&), usage for a fully bound
948  * callback or functor would be:
949  *
950  * @code
951  * int arg1 = 1;
952  * Something arg2;
953  * Callback::Callback* cb =
954  * Callback::make_ref(my_obj, &MyClass::my_method, arg1, arg2);
955  * @endcode
956  *
957  * From version 2.0.9, Callback::lambda() provides an easy
958  * way of dealing with lambda expressions, for example:
959  *
960  * @code
961  * Callback::Callback* cb;
962  * {
963  * std::string s("Hello");
964  * cb = Callback::lambda<>([=](){std::cout << s << std::endl;});
965  * }
966  * cb->dispatch(); // 's' is now out of scope, but it has been captured by value
967  * // by the lambda object and is now held by the callback object
968  * delete cb;
969  * @endcode
970  *
971  * With Callback::lambda(), the types of the unbound arguments must be
972  * explicitly specified as they cannot be deduced. Unbound arguments
973  * can comprise reference arguments. For example:
974  *
975  * @code
976  * int res;
977  * auto cb = Callback::lambda<int, int, int&>([](int j, int k, int& r) {r = j * k;});
978  * cb->dispatch(2, 3, res);
979  * std::cout << res << std::endl;
980  * delete cb;
981  * @endcode
982  *
983  * Callback::lambda() can take any function object, such as one
984  * returned by std::bind(). So, constructing a callback object
985  * representing a class object my_obj of type MyClass, with a method
986  * void MyClass::my_method(int, int, int, double, const char*), where
987  * a value is to be bound to the second argument could comprise:
988  *
989  * @code
990  * using namespace std::placeholders; // for _1, _2, _3 and _4
991  * int arg = 1;
992  * auto cb = Callback::lambda<int, int, double, const char*>(
993  * std::bind(&MyClass::my_method, &my_obj,
994  * _1, arg, _2, _3, _4)
995  * );
996  * cb->dispatch(5, 3, 10.2, "Hello\n");
997  * delete cb;
998  * @endcode
999  *
1000  * Using std::bind, if the bound argument were a reference (that is,
1001  * the signature of MyClass::my_method were (int, int&, int, double,
1002  * const char*) and it were safe to do so (see above), it could be
1003  * bound with std::ref(), as in:
1004  *
1005  * @code
1006  * using namespace std::placeholders; // for _1, _2, _3 and _4
1007  * int arg;
1008  * auto cb = Callback::lambda<int, int, double, const char*>(
1009  * std::bind(&MyClass::my_method, &my_obj,
1010  * _1, std::ref(arg), _2, _3, _4)
1011  * );
1012  * @endcode
1013  *
1014  * Prior to version 2.0.9, lambda expressions and the return value of
1015  * std::bind() would have to be passed by using a temporary
1016  * std::function object and Callback::make, as follows:
1017  *
1018  * @code
1019  * Callback::Callback* cb;
1020  * {
1021  * std::string s("Hello");
1022  * cb = Callback::make(std::function<void()>{[=](){std::cout << s << std::endl;}});
1023  * }
1024  * cb->dispatch();
1025  * delete cb;
1026  * @endcode
1027  *
1028  * Overloaded functions
1029  * --------------------
1030  *
1031  * Note that creating callbacks for overloaded functions can give rise
1032  * to an ambiguity when using Callback::make(), arising from the fact
1033  * that the callback object may have an unbound argument. For
1034  * example:
1035  *
1036  * @code
1037  * class MyClass {
1038  * ...
1039  * void add(int i);
1040  * void add(int i, int j);
1041  * void add(double d);
1042  * };
1043  * MyClass obj;
1044  * using namespace Cgu;
1045  * Callback::Callback* cb1 = Callback::make(obj, &MyClass::add, 1, 2); // ok
1046  * Callback::Callback* cb2 = Callback::make(obj, &MyClass::add, 1.0); // ok
1047  * Callback::Callback* cb3 = Callback::make(obj, &MyClass::add, 1); // ambiguous - compilation failure
1048  * @endcode
1049  *
1050  * The third call to Callback::make() is ambiguous, as it could be
1051  * creating a callback for either the function MyClass::add(int) with
1052  * no unbound argument (that is, creating a Callback::Callback
1053  * object), or the function MyClass::add(int, int) with an unbound int
1054  * argument (that is, creating a Callback::CallbackArg<int> object).
1055  * This situation could be disambiguated by specifically stating the
1056  * type of the function which is to be chosen, namely, to instantiate
1057  * the callback in the third call with:
1058  *
1059  * @code
1060  * // either:
1061  * Callback::Callback* cb3 =
1062  * Callback::make(obj, static_cast<void (MyClass::*)(int)>(&MyClass::add), 1);
1063  * // or:
1064  * Callback::CallbackArg<int>* cb3 =
1065  * Callback::make(obj, static_cast<void (MyClass::*)(int, int)>(&MyClass::add), 1);
1066  * @endcode
1067  *
1068  * Callback::make_ref() is less capable than Callback::make() at
1069  * deducing template types. It cannot resolve overloaded functions by
1070  * examining the arguments passed to it. For example, take a class
1071  * MyClass as follows:
1072  *
1073  * @code
1074  * class MyClass {
1075  * ...
1076  * void add(int i, const double& d);
1077  * void add(const int& j, const int& k);
1078  * };
1079  * @endcode
1080  *
1081  * Callback::make_ref() would require explicit disambiguation like
1082  * this:
1083  *
1084  * @code
1085  * Callback::Callback* cb1 =
1086  * Callback::make_ref(obj, static_cast<void (MyClass::*)(int, const double&)>(&MyClass::add), 1, 2.2);
1087  * Callback::Callback* cb2 =
1088  * Callback::make_ref(obj, static_cast<void (MyClass::*)(const int&, const int&)>(&MyClass::add), 4, 5);
1089  * @endcode
1090  *
1091  * Note also that, for CallbackArg objects created from std::function
1092  * objects, the std::function constructors and the std::mem_fn() and
1093  * std::bind() functions normally do not allow any function
1094  * overloading without explicit disambiguation.
1095  *
1096  * Posting of callbacks
1097  * --------------------
1098  *
1099  * This file also provides Callback::post() functions which will
1100  * execute a callback in a glib main loop and can be used (amongst
1101  * other things) to pass an event from a worker thread to the main
1102  * program thread. In that respect, it provides an alternative to the
1103  * Notifier class. It is passed a pointer to a Callback::Callback
1104  * object created with a call to Callback::make() or
1105  * Callback::lambda().
1106  *
1107  * To provide for thread-safe automatic disconnection of the callback
1108  * if the object whose method it represents is destroyed before the
1109  * callback executes in the main loop, include a Releaser as a public
1110  * member of that object and pass the Releaser object as the second
1111  * argument of Callback::post(). Note that for this to be race free,
1112  * the lifetime of the remote object whose method is to be invoked
1113  * must be determined by the thread to whose main loop the callback
1114  * has been attached. When the main loop begins invoking the
1115  * execution of the callback, the remote object must either wholly
1116  * exist (in which case the callback will be invoked) or have been
1117  * destroyed (in which case the callback will be ignored), and not be
1118  * in some transient half-state governed by another thread.
1119  *
1120  * Advantages as against Notifier:
1121  *
1122  * 1. If there are a lot of different events requiring callbacks to be
1123  * dispatched in the program from worker threads to the main
1124  * thread, this avoids having separate Notifier objects for each
1125  * event.
1126  * 2. It is easier to pass arguments with varying values - they can be
1127  * passed as arguments to the Callback::make functions and no
1128  * special synchronisation is normally required (the call to
1129  * g_source_attach() invokes locking of the main loop which will
1130  * have the effect of ensuring memory visibility). With a Notifier
1131  * object it may be necessary to use an asynchronous queue to pass
1132  * variable values (or to bind a reference to the data, thus
1133  * normally requiring separate synchronisation).
1134  * 3. Although the callback would normally be sent for execution by
1135  * the main program loop, and that is the default, it can be sent
1136  * for execution by any thread which has its own
1137  * GMainContext/GMainLoop objects. Thus callbacks can be passed
1138  * for execution between worker threads, or from the main program
1139  * thread to worker threads, as well as from worker threads to the
1140  * main program thread.
1141  *
1142  * Disadvantages as against Notifier:
1143  *
1144  * 1. Less efficient, as a new callback object has to be created on
1145  * freestore every time the callback is invoked, together with a
1146  * new Emitter object if a Releaser is used to track the callback.
1147  * 2. Multiple callbacks relevant to a single event cannot be invoked
1148  * from a single call for the event - each callback has to be
1149  * separately dispatched.
1150  */
1151 
1152 #include <functional> // for std::less, std::function and std::hash<T*>
1153 #include <utility> // for std::move and std::forward
1154 #include <cstddef> // for std::size_t
1155 #include <type_traits> // for std::remove_reference and std::remove_const
1156 
1157 #include <glib.h>
1158 
1159 #include <c++-gtk-utils/shared_ptr.h>
1160 #include <c++-gtk-utils/param.h>
1161 #include <c++-gtk-utils/cgu_config.h>
1162 
1163 namespace Cgu {
1164 
1165 namespace Callback {
1166 
1167 /*
1168  The CallbackArg class could be additionally templated to provide a
1169  return value, but that would affect the simplicity of the
1170  interface, and if a case were to arise where a result is needed, an
1171  alternative is for users to pass an argument by reference or
1172  pointer (or pointer to pointer) rather than have a return value.
1173 */
1174 
1175 /* Declare the two basic interface types */
1176 
1177 template <class... FreeArgs> class CallbackArg;
1178 typedef CallbackArg<> Callback;
1179 
1180 /* now the class definitions */
1181 
1182 /**
1183  * @class CallbackArg callback.h c++-gtk-utils/callback.h
1184  * @brief The callback interface class
1185  * @sa Callback namespace
1186  * @sa FunctorArg SafeFunctorArg
1187  *
1188  * This provides the basic interface class that users will generally
1189  * see. The template types are the types of the unbound arguments, if
1190  * any. Callback::CallbackArg<> is typedef'ed to Callback::Callback.
1191  *
1192  * @b Usage
1193  *
1194  * For a class object my_obj of type MyClass, with a method void
1195  * MyClass::my_method(int, int, const char*), usage for a fully bound
1196  * callback would be:
1197  *
1198  * @code
1199  * using namespace Cgu;
1200  * int arg1 = 1, arg2 = 5;
1201  * Callback::Callback* cb =
1202  * Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n");
1203  * cb->dispatch();
1204  * delete cb;
1205  * @endcode
1206  *
1207  * Or for a partially bound callback:
1208  *
1209  * @code
1210  * using namespace Cgu;
1211  * int arg1 = 1, arg2 = 5;
1212  * Callback::CallbackArg<int, const char*>* cb =
1213  * Callback::make(my_obj, &MyClass::my_method, arg1);
1214  * cb->dispatch(arg2, "Hello\n");
1215  * delete cb;
1216  * @endcode
1217  *
1218  * Callback/CallbackArg classes do not provide for a return value. If
1219  * a result is wanted, users should pass an unbound argument by
1220  * reference or pointer (or pointer to pointer).
1221  *
1222  * For further background, including about the Callback::make(),
1223  * Callback::make_ref() and Callback::lambda() functions read this:
1224  * Callback
1225  */
1226 
1227 template <class... FreeArgs>
1228 class CallbackArg {
1229 public:
1230 /* Because dispatch() is a virtual function, we cannot templatise it
1231  * with a view to preserving r-value forwarding of temporary objects
1232  * passed as a free argument. But this would rarely be relevant
1233  * anyway - it would only be relevant if the target function were to
1234  * take an argument by r-value reference and a temporary were to be
1235  * passed to it. In such a case virtual dispatch is at the cost of a
1236  * copy of the temporary.
1237  */
1238 /**
1239  * This will execute the referenced function or class method
1240  * encapsulated by this class. It will only throw if the dispatched
1241  * function or class method throws, or if the copy constructor of a
1242  * free or bound argument throws and it is not a reference argument.
1243  * It is thread safe if the referenced function or class method is
1244  * thread safe.
1245  * @param args The unbound arguments to be passed to the referenced
1246  * function or class method, if any.
1247  * @note We use dispatch() to execute the callback, because the
1248  * callback would normally be invoked through a base class pointer.
1249  * To invoke it through operator()(), use the FunctorArg wrapper
1250  * class.
1251  */
1252  virtual void dispatch(typename Cgu::Param<FreeArgs>::ParamType... args) const = 0;
1253 
1254 /**
1255  * The constructor will not throw unless the copy constructor of an
1256  * argument bound to the derived implementation class throws.
1257  */
1259 
1260 /**
1261  * The destructor will not throw unless the destructor of an argument
1262  * bound to the derived implementation class throws.
1263  */
1264  virtual ~CallbackArg() {}
1265 
1266 /* these functions will be inherited by the derived callback classes */
1267 #ifdef CGU_USE_GLIB_MEMORY_SLICES_NO_COMPAT
1269 #endif
1270 };
1271 
1272 /* The four basic functor types */
1273 
1274 template <class... FreeArgs> class FunctorArg;
1275 template <class... FreeArgs> class SafeFunctorArg;
1276 typedef FunctorArg<> Functor;
1278 
1279 /* Functor friend functions */
1280 
1281 // we can use built-in operator == when comparing pointers referencing
1282 // different objects of the same type
1283 /**
1284  * Two FunctorArg objects compare equal if the addresses of the
1285  * CallbackArg objects they contain are the same. This comparison
1286  * operator does not throw.
1287  */
1288 template <class... T>
1289 bool operator==(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) {
1290  return (f1.cb_s.get() == f2.cb_s.get());
1291 }
1292 
1293 /**
1294  * Two FunctorArg objects compare unequal if the addresses of the
1295  * CallbackArg objects they contain are not the same. This comparison
1296  * operator does not throw.
1297  */
1298 template <class... T>
1299 bool operator!=(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) {
1300  return !(f1 == f2);
1301 }
1302 
1303 // we must use std::less rather than the < built-in operator for
1304 // pointers to objects not within the same array or object: "For
1305 // templates greater, less, greater_equal, and less_equal, the
1306 // specializations for any pointer type yield a total order, even if
1307 // the built-in operators <, >, <=, >= do not." (para 20.3.3/8).
1308 /**
1309  * One FunctorArg object is less than another if the address of the
1310  * CallbackArg object contained by the first is regarded by std::less
1311  * as less than the address of the CallbackArg object contained by the
1312  * other. This comparison operator does not throw.
1313  */
1314 template <class... T>
1315 bool operator<(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) {
1316  return std::less<const CallbackArg<T...>*>()(f1.cb_s.get(), f2.cb_s.get());
1317 }
1318 
1319 /**
1320  * Two SafeFunctorArg objects compare equal if the addresses of the
1321  * CallbackArg objects they contain are the same. This comparison
1322  * operator does not throw.
1323  */
1324 template <class... T>
1326  return (f1.cb_s.get() == f2.cb_s.get());
1327 }
1328 
1329 /**
1330  * Two SafeFunctorArg objects compare unequal if the addresses of the
1331  * CallbackArg objects they contain are not the same. This comparison
1332  * operator does not throw.
1333  */
1334 template <class... T>
1336  return !(f1 == f2);
1337 }
1338 
1339 /**
1340  * One SafeFunctorArg object is less than another if the address of
1341  * the CallbackArg object contained by the first is regarded by
1342  * std::less as less than the address of the CallbackArg object
1343  * contained by the other. This comparison operator does not throw.
1344  */
1345 template <class... T>
1347  return std::less<const CallbackArg<T...>*>()(f1.cb_s.get(), f2.cb_s.get());
1348 }
1349 
1350 } // namespace Callback
1351 } // namespace Cgu
1352 
1353 // doxygen produces long filenames that tar can't handle:
1354 // we have generic documentation for std::hash specialisations
1355 // in doxygen.main.in
1356 #ifndef DOXYGEN_PARSING
1357 
1358 /* These structs allow FunctorArg and SafeFunctorArg objects to be
1359  keys in unordered associative containers */
1360 namespace std {
1361 template <class... T>
1362 struct hash<Cgu::Callback::FunctorArg<T...>> {
1363  typedef std::size_t result_type;
1364  typedef Cgu::Callback::FunctorArg<T...> argument_type;
1365  result_type operator()(const argument_type& f) const {
1366  // this is fine: std::hash structs do not normally contain data and
1367  // std::hash<T*> certainly won't, so we don't have overhead constructing
1368  // std::hash<T*> on the fly
1369  return std::hash<const Cgu::Callback::CallbackArg<T...>*>()(f.cb_s.get());
1370  }
1371 };
1372 template <class... T>
1373 struct hash<Cgu::Callback::SafeFunctorArg<T...>> {
1374  typedef std::size_t result_type;
1375  typedef Cgu::Callback::SafeFunctorArg<T...> argument_type;
1376  result_type operator()(const argument_type& f) const {
1377  // this is fine: std::hash structs do not normally contain data and
1378  // std::hash<T*> certainly won't, so we don't have overhead constructing
1379  // std::hash<T*> on the fly
1380  return std::hash<const Cgu::Callback::CallbackArg<T...>*>()(f.cb_s.get());
1381  }
1382 };
1383 } // namespace std
1384 
1385 #endif // DOXYGEN_PARSING
1386 
1387 namespace Cgu {
1388 namespace Callback {
1389 
1390 /* the functor classes */
1391 
1392 /**
1393  * @class FunctorArg callback.h c++-gtk-utils/callback.h
1394  * @brief Functor class holding a Callback::CallbackArg object.
1395  * @sa SafeFunctorArg
1396  * @sa Callback namespace
1397  *
1398  * This class wraps a CallbackArg object. The callback object is kept
1399  * by SharedPtr so the functor can be copied and offers automatic
1400  * lifetime management of the wrapped callback object, as well as
1401  * providing an operator()() function. Ownership is taken of the
1402  * CallbackArg object passed to the constructor taking a CallbackArg
1403  * pointer, so that constructor should be treated like a shared
1404  * pointer constructor - only pass a newly allocated object to it (or
1405  * copy construct it or assign to it from another existing FunctorArg
1406  * object). The template types are the types of the unbound
1407  * arguments, if any. Callback::FunctorArg<> is typedef'ed to
1408  * Callback::Functor.
1409  *
1410  * The constructor taking a Callback::CallbackArg pointer is not
1411  * marked explicit, so the results of Callback::make() can be passed
1412  * directly to a function taking a Callback::FunctorArg argument, and
1413  * implicit conversion will take place.
1414  *
1415  * @b Usage
1416  *
1417  * For a class object my_obj of type MyClass, with a method void
1418  * MyClass::my_method(int, int, const char*), usage for a fully bound
1419  * functor would be:
1420  *
1421  * @code
1422  * using namespace Cgu;
1423  * int arg1 = 1, arg2 = 5;
1424  * Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")};
1425  * f();
1426  * @endcode
1427  *
1428  * Or for a partially bound functor:
1429  *
1430  * @code
1431  * using namespace Cgu;
1432  * int arg1 = 1, arg2 = 5;
1433  * Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)};
1434  * f(arg2, "Hello\n");
1435  * @endcode
1436  *
1437  * Callback/CallbackArg classes do not provide for a return value. If
1438  * a result is wanted, users should pass an unbound argument by
1439  * reference or pointer (or pointer to pointer).
1440  *
1441  * For further background, including about the Callback::make(),
1442  * Callback::make_ref() and Callback::lambda() functions, and the use
1443  * of these classes with std::function objects, read this: Callback
1444  */
1445 
1446 template <class... FreeArgs>
1447 class FunctorArg {
1448  SharedPtr<const CallbackArg<FreeArgs...>> cb_s;
1449 public:
1450 /* Because CallbackArg::dispatch() is a virtual function, it is
1451  * pointless templatising this function with a view to preserving
1452  * r-value forwarding of temporary objects passed as a free argument,
1453  * because the r-value typeness will be discarded in dispatch(). But
1454  * this would rarely be relevant anyway - it would only be relevant if
1455  * the target function were to take an argument by r-value reference
1456  * and a temporary were to be passed to it. In such a case virtual
1457  * dispatch is at the cost of a copy of the temporary.
1458  */
1459 /**
1460  * This will execute the function or class method referenced by the
1461  * callback encapsulated by this object, or do nothing if this object
1462  * has not been initialized with a callback. It will only throw if
1463  * the executed function or class method throws, or if the copy
1464  * constructor of a free or bound argument throws and it is not a
1465  * reference argument. It is thread safe if the referenced function
1466  * or class method is thread safe.
1467  * @param args The unbound arguments to be passed to the referenced
1468  * function or class method, if any.
1469  */
1470  void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const {
1471  if (cb_s.get()) cb_s->dispatch(args...);
1472  }
1473 
1474 /**
1475  * This function does not throw.
1476  * @param f The assignor.
1477  * @return The functor object after assignment.
1478  */
1479  FunctorArg& operator=(const FunctorArg& f) {cb_s = f.cb_s; return *this;}
1480 
1481 /**
1482  * This function does not throw.
1483  * @param f The functor to be moved.
1484  * @return The functor object after the move operation.
1485  */
1486  FunctorArg& operator=(FunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;}
1487 
1488 /**
1489  * Two FunctorArg objects compare equal if the addresses of the
1490  * CallbackArg objects they contain are the same. This comparison
1491  * operator does not throw.
1492  */
1493  friend bool operator== <>(const FunctorArg&, const FunctorArg&);
1494 
1495 /**
1496  * One FunctorArg object is less than another if the address of the
1497  * CallbackArg object contained by the first is regarded by std::less
1498  * as less than the address of the CallbackArg object contained by the
1499  * other. This comparison operator does not throw.
1500  */
1501  friend bool operator< <>(const FunctorArg&, const FunctorArg&);
1502 
1503  friend struct std::hash<FunctorArg>;
1504 
1505 /**
1506  * Constructor of first FunctorArg holding the referenced callback.
1507  * As it is not marked explicit, it is also a type conversion
1508  * constructor.
1509  * @param cb The CallbackArg object which the functor is to manage.
1510  * @exception std::bad_alloc This might throw std::bad_alloc if
1511  * memory is exhausted and the system throws in that case. Note that
1512  * if such an exception is thrown, then this constructor will clean
1513  * itself up and also delete the callback object passed to it.
1514  * @note std::bad_alloc will not be thrown if the library has been
1515  * installed using the \--with-glib-memory-slices-no-compat
1516  * configuration option: instead glib will terminate the program if it
1517  * is unable to obtain memory from the operating system.
1518  */
1519  FunctorArg(const CallbackArg<FreeArgs...>* cb): cb_s(cb) {}
1520 
1521 /**
1522  * The copy constructor does not throw.
1523  * @param f The assignor
1524  */
1525  FunctorArg(const FunctorArg& f): cb_s(f.cb_s) {}
1526 
1527 /**
1528  * The move constructor does not throw.
1529  * @param f The functor to be moved.
1530  */
1531  FunctorArg(FunctorArg&& f): cb_s(std::move(f.cb_s)) {}
1532 
1533  /**
1534  * Default constructor, where a Callback::CallbackArg object is to be
1535  * assigned later (via the type conversion constructor and/or the
1536  * assignment operator). This constructor does not throw.
1537  */
1539 
1540 /* Only has effect if --with-glib-memory-slices-compat or
1541  --with-glib-memory-slices-no-compat option picked */
1543 };
1544 
1545 /**
1546  * @class SafeFunctorArg callback.h c++-gtk-utils/callback.h
1547  * @brief Functor class holding a Callback::CallbackArg object, with
1548  * thread-safe reference count.
1549  * @sa FunctorArg
1550  * @sa Callback namespace
1551  *
1552  * This class is the same as Callback::FunctorArg except that it will
1553  * provide synchronisation of the reference count between threads.
1554  * Use it where a functor wrapper object is to be passed between
1555  * threads. The FunctorArg documentation gives details on usage.
1556  *
1557  * Callback::SafeFunctorArg<> is typedef'ed to Callback::SafeFunctor.
1558  *
1559  * For further background, read this: Callback
1560  */
1561 
1562 template <class... FreeArgs>
1563 class SafeFunctorArg {
1564  SharedLockPtr<const CallbackArg<FreeArgs...>> cb_s;
1565 public:
1566 /**
1567  * This will execute the function or class method referenced by the
1568  * callback encapsulated by this object, or do nothing if this object
1569  * has not been initialized with a callback. It will only throw if
1570  * the executed function or class method throws, or if the copy
1571  * constructor of a free or bound argument throws and it is not a
1572  * reference argument. It is thread safe if the referenced function
1573  * or class method is thread safe.
1574  * @param args The unbound arguments to be passed to the referenced
1575  * function or class method, if any.
1576  */
1577  void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const {
1578  if (cb_s.get()) cb_s->dispatch(args...);
1579  }
1580 
1581 /**
1582  * This function does not throw.
1583  * @param f The assignor.
1584  * @return The functor object after assignment.
1585  */
1586  SafeFunctorArg& operator=(const SafeFunctorArg& f) {cb_s = f.cb_s; return *this;}
1587 
1588 /**
1589  * This function does not throw.
1590  * @param f The functor to be moved.
1591  * @return The functor object after the move operation.
1592  */
1593  SafeFunctorArg& operator=(SafeFunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;}
1594 
1595 /**
1596  * Two SafeFunctorArg objects compare equal if the addresses of the
1597  * CallbackArg objects they contain are the same. This comparison
1598  * operator does not throw.
1599  */
1600  friend bool operator== <>(const SafeFunctorArg&, const SafeFunctorArg&);
1601 
1602 /**
1603  * One SafeFunctorArg object is less than another if the address of
1604  * the CallbackArg object contained by the first is regarded by
1605  * std::less as less than the address of the CallbackArg object
1606  * contained by the other. This comparison operator does not throw.
1607  */
1608  friend bool operator< <>(const SafeFunctorArg&, const SafeFunctorArg&);
1609 
1610  friend struct std::hash<SafeFunctorArg>;
1611 
1612  /**
1613  * Constructor of first SafeFunctorArg holding the referenced
1614  * callback. As it is not marked explicit, it is also a type
1615  * conversion constructor.
1616  * @param cb The CallbackArg object which the functor is to manage.
1617  * @exception std::bad_alloc This might throw std::bad_alloc if
1618  * memory is exhausted and the system throws in that case. Note that
1619  * if such an exception is thrown, then this constructor will clean
1620  * itself up and also delete the callback object passed to it.
1621  * @note std::bad_alloc will not be thrown if the library has been
1622  * installed using the \--with-glib-memory-slices-no-compat
1623  * configuration option: instead glib will terminate the program if it
1624  * is unable to obtain memory from the operating system.
1625  */
1627 
1628 /**
1629  * The copy constructor does not throw.
1630  * @param f The assignor.
1631  */
1632  SafeFunctorArg(const SafeFunctorArg& f): cb_s(f.cb_s) {}
1633 
1634 /**
1635  * The move constructor does not throw.
1636  * @param f The functor to be moved.
1637  */
1638  SafeFunctorArg(SafeFunctorArg&& f): cb_s(std::move(f.cb_s)) {}
1639 
1640  /**
1641  * Default constructor, where a Callback::CallbackArg object is to be
1642  * assigned later (via the type conversion constructor and/or the
1643  * assignment operator). This constructor does not throw.
1644  * @note The reference count maintained with respect to the contained
1645  * callback object is thread-safe, so SafeFunctorArg objects may be
1646  * copied between threads by the implicit assignment operator and put
1647  * in different containers in different threads. They use a
1648  * SharedLockPtr object to hold the referenced callback object.
1649  */
1651 
1652 /* Only has effect if --with-glib-memory-slices-compat or
1653  --with-glib-memory-slices-no-compat option picked */
1655 };
1656 
1657 /* the callback implementation classes */
1658 
1659 template <class T, class... FreeArgs>
1660 class Callback0: public CallbackArg<FreeArgs...> {
1661 public:
1662  typedef void (T::* MemFunc)(FreeArgs...);
1663 private:
1664  T* obj;
1665  MemFunc func;
1666 public:
1667  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1668  (obj->*func)(free_args...);
1669  }
1670  Callback0(T& obj_, MemFunc func_): obj(&obj_), func(func_) {}
1671 };
1672 
1673 template <bool unref, class T, class BoundArg, class... FreeArgs>
1674 class Callback1: public CallbackArg<FreeArgs...> {
1675 public:
1676  typedef void (T::* MemFunc)(BoundArg, FreeArgs...);
1677 private:
1678  T* obj;
1679  MemFunc func;
1681 public:
1682  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1683  (obj->*func)(arg, free_args...);
1684  }
1685  template <class Arg>
1686  Callback1(T& obj_, MemFunc func_,
1687  Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {}
1688 };
1689 
1690 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs>
1691 class Callback2: public CallbackArg<FreeArgs...> {
1692 public:
1693  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...);
1694 private:
1695  T* obj;
1696  MemFunc func;
1699 public:
1700  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1701  (obj->*func)(arg1, arg2, free_args...);
1702  }
1703  template <class Arg1, class Arg2>
1704  Callback2(T& obj_, MemFunc func_,
1705  Arg1&& arg1_,
1706  Arg2&& arg2_): obj(&obj_), func(func_),
1707  arg1(std::forward<Arg1>(arg1_)),
1708  arg2(std::forward<Arg2>(arg2_)) {}
1709 };
1710 
1711 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1712 class Callback3: public CallbackArg<FreeArgs...> {
1713 public:
1714  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...);
1715 private:
1716  T* obj;
1717  MemFunc func;
1721 public:
1722  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1723  (obj->*func)(arg1, arg2, arg3, free_args...);
1724  }
1725  template <class Arg1, class Arg2, class Arg3>
1726  Callback3(T& obj_, MemFunc func_,
1727  Arg1&& arg1_,
1728  Arg2&& arg2_,
1729  Arg3&& arg3_):
1730  obj(&obj_), func(func_),
1731  arg1(std::forward<Arg1>(arg1_)),
1732  arg2(std::forward<Arg2>(arg2_)),
1733  arg3(std::forward<Arg3>(arg3_)) {}
1734 };
1735 
1736 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1737  class BoundArg4, class... FreeArgs>
1738 class Callback4: public CallbackArg<FreeArgs...> {
1739 public:
1740  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...);
1741 private:
1742  T* obj;
1743  MemFunc func;
1748 public:
1749  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1750  (obj->*func)(arg1, arg2, arg3, arg4, free_args...);
1751  }
1752  template <class Arg1, class Arg2, class Arg3, class Arg4>
1753  Callback4(T& obj_, MemFunc func_,
1754  Arg1&& arg1_,
1755  Arg2&& arg2_,
1756  Arg3&& arg3_,
1757  Arg4&& arg4_):
1758  obj(&obj_), func(func_),
1759  arg1(std::forward<Arg1>(arg1_)),
1760  arg2(std::forward<Arg2>(arg2_)),
1761  arg3(std::forward<Arg3>(arg3_)),
1762  arg4(std::forward<Arg4>(arg4_)) {}
1763 };
1764 
1765 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1766  class BoundArg4, class BoundArg5, class... FreeArgs>
1767 class Callback5: public CallbackArg<FreeArgs...> {
1768 public:
1769  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3,
1770  BoundArg4, BoundArg5, FreeArgs...);
1771 private:
1772  T* obj;
1773  MemFunc func;
1779 public:
1780  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1781  (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...);
1782  }
1783  template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
1784  Callback5(T& obj_, MemFunc func_,
1785  Arg1&& arg1_,
1786  Arg2&& arg2_,
1787  Arg3&& arg3_,
1788  Arg4&& arg4_,
1789  Arg5&& arg5_):
1790  obj(&obj_), func(func_),
1791  arg1(std::forward<Arg1>(arg1_)),
1792  arg2(std::forward<Arg2>(arg2_)),
1793  arg3(std::forward<Arg3>(arg3_)),
1794  arg4(std::forward<Arg4>(arg4_)),
1795  arg5(std::forward<Arg5>(arg5_)) {}
1796 };
1797 
1798 /* const versions, for binding to const methods */
1799 
1800 template <class T, class... FreeArgs>
1801 class Callback0_const: public CallbackArg<FreeArgs...> {
1802 public:
1803  typedef void (T::* MemFunc)(FreeArgs...) const;
1804 private:
1805  const T* obj;
1806  MemFunc func;
1807 public:
1808  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1809  (obj->*func)(free_args...);
1810  }
1811  Callback0_const(const T& obj_, MemFunc func_): obj(&obj_), func(func_) {}
1812 };
1813 
1814 template <bool unref, class T, class BoundArg, class... FreeArgs>
1815 class Callback1_const: public CallbackArg<FreeArgs...> {
1816 public:
1817  typedef void (T::* MemFunc)(BoundArg, FreeArgs...) const;
1818 private:
1819  const T* obj;
1820  MemFunc func;
1822 public:
1823  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1824  (obj->*func)(arg, free_args...);
1825  }
1826  template <class Arg>
1827  Callback1_const(const T& obj_, MemFunc func_,
1828  Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {}
1829 };
1830 
1831 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs>
1832 class Callback2_const: public CallbackArg<FreeArgs...> {
1833 public:
1834  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...) const;
1835 private:
1836  const T* obj;
1837  MemFunc func;
1840 public:
1841  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1842  (obj->*func)(arg1, arg2, free_args...);
1843  }
1844  template <class Arg1, class Arg2>
1845  Callback2_const(const T& obj_, MemFunc func_,
1846  Arg1&& arg1_,
1847  Arg2&& arg2_): obj(&obj_), func(func_),
1848  arg1(std::forward<Arg1>(arg1_)),
1849  arg2(std::forward<Arg2>(arg2_)) {}
1850 };
1851 
1852 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1853 class Callback3_const: public CallbackArg<FreeArgs...> {
1854 public:
1855  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const;
1856 private:
1857  const T* obj;
1858  MemFunc func;
1862 public:
1863  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1864  (obj->*func)(arg1, arg2, arg3, free_args...);
1865  }
1866  template <class Arg1, class Arg2, class Arg3>
1867  Callback3_const(const T& obj_, MemFunc func_,
1868  Arg1&& arg1_,
1869  Arg2&& arg2_,
1870  Arg3&& arg3_):
1871  obj(&obj_), func(func_),
1872  arg1(std::forward<Arg1>(arg1_)),
1873  arg2(std::forward<Arg2>(arg2_)),
1874  arg3(std::forward<Arg3>(arg3_)) {}
1875 };
1876 
1877 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1878  class BoundArg4, class... FreeArgs>
1879 class Callback4_const: public CallbackArg<FreeArgs...> {
1880 public:
1881  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const;
1882 private:
1883  const T* obj;
1884  MemFunc func;
1889 public:
1890  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1891  (obj->*func)(arg1, arg2, arg3, arg4, free_args...);
1892  }
1893  template <class Arg1, class Arg2, class Arg3, class Arg4>
1894  Callback4_const(const T& obj_, MemFunc func_,
1895  Arg1&& arg1_,
1896  Arg2&& arg2_,
1897  Arg3&& arg3_,
1898  Arg4&& arg4_):
1899  obj(&obj_), func(func_),
1900  arg1(std::forward<Arg1>(arg1_)),
1901  arg2(std::forward<Arg2>(arg2_)),
1902  arg3(std::forward<Arg3>(arg3_)),
1903  arg4(std::forward<Arg4>(arg4_)) {}
1904 };
1905 
1906 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1907  class BoundArg4, class BoundArg5, class... FreeArgs>
1908 class Callback5_const: public CallbackArg<FreeArgs...> {
1909 public:
1910  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3,
1911  BoundArg4, BoundArg5, FreeArgs...) const;
1912 private:
1913  const T* obj;
1914  MemFunc func;
1920 public:
1921  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1922  (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...);
1923  }
1924  template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
1925  Callback5_const(const T& obj_, MemFunc func_,
1926  Arg1&& arg1_,
1927  Arg2&& arg2_,
1928  Arg3&& arg3_,
1929  Arg4&& arg4_,
1930  Arg5&& arg5_):
1931  obj(&obj_), func(func_),
1932  arg1(std::forward<Arg1>(arg1_)),
1933  arg2(std::forward<Arg2>(arg2_)),
1934  arg3(std::forward<Arg3>(arg3_)),
1935  arg4(std::forward<Arg4>(arg4_)),
1936  arg5(std::forward<Arg5>(arg5_)) {}
1937 };
1938 
1939 /* for static class methods and non-class functions */
1940 
1941 template <class... FreeArgs>
1942 class Callback0_static: public CallbackArg<FreeArgs...> {
1943 public:
1944  typedef void (*Func)(FreeArgs...);
1945 private:
1946  Func func;
1947 public:
1948  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1949  func(free_args...);
1950  }
1951  Callback0_static(Func func_): func(func_) {}
1952 };
1953 
1954 template <bool unref, class BoundArg, class... FreeArgs>
1955 class Callback1_static: public CallbackArg<FreeArgs...> {
1956 public:
1957  typedef void (*Func)(BoundArg, FreeArgs...);
1958 private:
1959  Func func;
1961 public:
1962  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1963  func(arg, free_args...);
1964  }
1965  template <class Arg>
1966  Callback1_static(Func func_, Arg&& arg_): func(func_), arg(std::forward<Arg>(arg_)) {}
1967 };
1968 
1969 template <bool unref, class BoundArg1, class BoundArg2, class... FreeArgs>
1970 class Callback2_static: public CallbackArg<FreeArgs...> {
1971 public:
1972  typedef void (*Func)(BoundArg1, BoundArg2, FreeArgs...);
1973 private:
1974  Func func;
1977 public:
1978  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1979  func(arg1, arg2, free_args...);
1980  }
1981  template <class Arg1, class Arg2>
1982  Callback2_static(Func func_, Arg1&& arg1_,
1983  Arg2&& arg2_): func(func_),
1984  arg1(std::forward<Arg1>(arg1_)),
1985  arg2(std::forward<Arg2>(arg2_)) {}
1986 };
1987 
1988 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1989 class Callback3_static: public CallbackArg<FreeArgs...> {
1990 public:
1991  typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...);
1992 private:
1993  Func func;
1997 public:
1998  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1999  func(arg1, arg2, arg3, free_args...);
2000  }
2001  template <class Arg1, class Arg2, class Arg3>
2003  Arg1&& arg1_,
2004  Arg2&& arg2_,
2005  Arg3&& arg3_):
2006  func(func_),
2007  arg1(std::forward<Arg1>(arg1_)),
2008  arg2(std::forward<Arg2>(arg2_)),
2009  arg3(std::forward<Arg3>(arg3_)) {}
2010 };
2011 
2012 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3,
2013  class BoundArg4, class... FreeArgs>
2014 class Callback4_static: public CallbackArg<FreeArgs...> {
2015 public:
2016  typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...);
2017 private:
2018  Func func;
2023 public:
2024  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
2025  func(arg1, arg2, arg3, arg4, free_args...);
2026  }
2027  template <class Arg1, class Arg2, class Arg3, class Arg4>
2029  Arg1&& arg1_,
2030  Arg2&& arg2_,
2031  Arg3&& arg3_,
2032  Arg4&& arg4_):
2033  func(func_),
2034  arg1(std::forward<Arg1>(arg1_)),
2035  arg2(std::forward<Arg2>(arg2_)),
2036  arg3(std::forward<Arg3>(arg3_)),
2037  arg4(std::forward<Arg4>(arg4_)) {}
2038 };
2039 
2040 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3,
2041  class BoundArg4, class BoundArg5, class... FreeArgs>
2042 class Callback5_static: public CallbackArg<FreeArgs...> {
2043 public:
2044  typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3,
2045  BoundArg4, BoundArg5, FreeArgs...);
2046 private:
2047  Func func;
2053 public:
2054  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
2055  func(arg1, arg2, arg3, arg4, arg5, free_args...);
2056  }
2057  template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
2059  Arg1&& arg1_,
2060  Arg2&& arg2_,
2061  Arg3&& arg3_,
2062  Arg4&& arg4_,
2063  Arg5&& arg5_):
2064  func(func_),
2065  arg1(std::forward<Arg1>(arg1_)),
2066  arg2(std::forward<Arg2>(arg2_)),
2067  arg3(std::forward<Arg3>(arg3_)),
2068  arg4(std::forward<Arg4>(arg4_)),
2069  arg5(std::forward<Arg5>(arg5_)) {}
2070 };
2071 
2072 // TODO: Version 2.0.9 provides a Callback_lambda class for callable
2073 // objects which makes the specialized Callback_function class
2074 // redundant. At an API break we can remove the Callback_function
2075 // class and modify the Callback::make() helper function overload for
2076 // std::function objects to construct a Callback_lambda object
2077 // instead. Doing it now would not affect ABI compatibility as the
2078 // library produces these only by base pointer, but a user may have
2079 // instantiated them by hand in user code.
2080 template <class... FreeArgs>
2081 class Callback_function: public CallbackArg<FreeArgs...> {
2082  std::function<void(FreeArgs...)> f;
2083 public:
2084  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {f(free_args...);}
2085  Callback_function(const std::function<void(FreeArgs...)>& f_): f(f_) {}
2086  Callback_function(std::function<void(FreeArgs...)>&& f_): f(std::move(f_)) {}
2087 };
2088 
2089 // generic class for callable objects such as lambdas
2090 template <class Lambda, class... FreeArgs>
2091 class Callback_lambda: public CallbackArg<FreeArgs...> {
2092  // making 'l' mutable means that Callback_lamdba objects can contain
2093  // mutable lambda expressions
2094  mutable Lambda l;
2095 public:
2096  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {l(free_args...);}
2097  template <class L> Callback_lambda(L&& l_): l(std::forward<L>(l_)) {}
2098 };
2099 
2100 /* Convenience functions making callback objects on freestore. These
2101  * can for example be passed as the first argument of the
2102  * Thread::start() method in thread.h. They are also used by the
2103  * Callback::post() function.
2104 */
2105 
2106 /**
2107  * A convenience function to make Callback::CallbackArg objects
2108  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2109  * is exhausted and the system throws in that case. This exception
2110  * will not be thrown if the library has been installed using the
2111  * \--with-glib-memory-slices-no-compat configuration option (instead
2112  * glib will terminate the program if it is unable to obtain memory
2113  * from the operating system).
2114  */
2115 template <class T, class... FreeArgs>
2116 CallbackArg<FreeArgs...>* make(T& t,
2117  void (T::*func)(FreeArgs...)) {
2118  return new Callback0<T, FreeArgs...>{t, func};
2119 }
2120 
2121 /**
2122  * DEPRECATED.
2123  *
2124  * Since this function constructs a callback which does not take a
2125  * bound argument, it is a synonym for make() (the two are identical).
2126  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2127  * is exhausted and the system throws in that case. This exception
2128  * will not be thrown if the library has been installed using the
2129  * \--with-glib-memory-slices-no-compat configuration option (instead
2130  * glib will terminate the program if it is unable to obtain memory
2131  * from the operating system).
2132  */
2133 template <class T, class... FreeArgs>
2134 CallbackArg<FreeArgs...>* make_val(T& t,
2135  void (T::*func)(FreeArgs...)) {
2136  return new Callback0<T, FreeArgs...>{t, func};
2137 }
2138 
2139 /**
2140  * Since this function constructs a callback which does not take a
2141  * bound argument, it is a synonym for make() (the two are identical).
2142  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2143  * is exhausted and the system throws in that case. This exception
2144  * will not be thrown if the library has been installed using the
2145  * \--with-glib-memory-slices-no-compat configuration option (instead
2146  * glib will terminate the program if it is unable to obtain memory
2147  * from the operating system).
2148  *
2149  * Since 2.0.0-rc3
2150  */
2151 template <class T, class... FreeArgs>
2152 CallbackArg<FreeArgs...>* make_ref(T& t,
2153  void (T::*func)(FreeArgs...)) {
2154  return new Callback0<T, FreeArgs...>{t, func};
2155 }
2156 
2157 /**
2158  * A convenience function to make Callback::CallbackArg objects
2159  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2160  * is exhausted and the system throws in that case (this exception
2161  * will not be thrown if the library has been installed using the
2162  * \--with-glib-memory-slices-no-compat configuration option: instead
2163  * glib will terminate the program if it is unable to obtain memory
2164  * from the operating system). It will also throw if the copy
2165  * constructor of a bound argument throws and it is not a reference
2166  * argument.
2167  */
2168 template <class T, class BoundArg, class... FreeArgs>
2169 CallbackArg<FreeArgs...>* make(T& t,
2170  void (T::*func)(BoundArg, FreeArgs...),
2171  BoundArg arg) {
2172  return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg};
2173 }
2174 
2175 /**
2176  * DEPRECATED: use Callback::make_ref() instead.
2177  *
2178  * An alternative function to make Callback::CallbackArg objects,
2179  * which is for use where a target function receives an argument of
2180  * class type by value which is to be a bound argument, so the
2181  * compiler is not able to carry out copy elision when constructing
2182  * the callback object.
2183  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2184  * is exhausted and the system throws in that case (this exception
2185  * will not be thrown if the library has been installed using the
2186  * \--with-glib-memory-slices-no-compat configuration option: instead
2187  * glib will terminate the program if it is unable to obtain memory
2188  * from the operating system). It will also throw if the copy
2189  * constructor of a bound argument throws and it is not a reference
2190  * argument.
2191  */
2192 template <class T, class BoundArg, class... FreeArgs>
2193 CallbackArg<FreeArgs...>* make_val(T& t,
2194  void (T::*func)(BoundArg, FreeArgs...),
2195  const BoundArg& arg) {
2196  return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg};
2197 }
2198 
2199 /**
2200  * An alternative function to make Callback::CallbackArg objects,
2201  * which is for use where a target function either receives a class
2202  * type bound argument by value, or receives a bound argument by
2203  * reference to const in a case where the generated CallbackArg object
2204  * is to store a copy of that argument instead of just keeping a
2205  * reference.
2206  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2207  * is exhausted and the system throws in that case (this exception
2208  * will not be thrown if the library has been installed using the
2209  * \--with-glib-memory-slices-no-compat configuration option: instead
2210  * glib will terminate the program if it is unable to obtain memory
2211  * from the operating system). It will also throw if the copy or move
2212  * constructor of a bound argument throws.
2213  *
2214  * Since 2.0.0-rc3
2215  */
2216 template <class T, class BoundArg, class Arg, class... FreeArgs>
2217 CallbackArg<FreeArgs...>* make_ref(T& t,
2218  void (T::*func)(BoundArg, FreeArgs...),
2219  Arg&& arg) {
2220  return new Callback1<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)};
2221 }
2222 
2223 /**
2224  * A convenience function to make Callback::CallbackArg objects
2225  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2226  * is exhausted and the system throws in that case (this exception
2227  * will not be thrown if the library has been installed using the
2228  * \--with-glib-memory-slices-no-compat configuration option: instead
2229  * glib will terminate the program if it is unable to obtain memory
2230  * from the operating system). It will also throw if the copy
2231  * constructor of a bound argument throws and it is not a reference
2232  * argument.
2233  */
2234 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2235 CallbackArg<FreeArgs...>* make(T& t,
2236  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
2237  BoundArg1 arg1,
2238  BoundArg2 arg2) {
2239  return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2240 }
2241 
2242 /**
2243  * DEPRECATED: use Callback::make_ref() instead.
2244  *
2245  * An alternative function to make Callback::CallbackArg objects,
2246  * which is for use where a target function receives an argument of
2247  * class type by value which is to be a bound argument, so the
2248  * compiler is not able to carry out copy elision when constructing
2249  * the callback object.
2250  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2251  * is exhausted and the system throws in that case (this exception
2252  * will not be thrown if the library has been installed using the
2253  * \--with-glib-memory-slices-no-compat configuration option: instead
2254  * glib will terminate the program if it is unable to obtain memory
2255  * from the operating system). It will also throw if the copy
2256  * constructor of a bound argument throws and it is not a reference
2257  * argument.
2258  */
2259 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2260 CallbackArg<FreeArgs...>* make_val(T& t,
2261  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
2262  const BoundArg1& arg1,
2263  const BoundArg2& arg2) {
2264  return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2265 }
2266 
2267 /**
2268  * An alternative function to make Callback::CallbackArg objects,
2269  * which is for use where a target function either receives a class
2270  * type bound argument by value, or receives a bound argument by
2271  * reference to const in a case where the generated CallbackArg object
2272  * is to store a copy of that argument instead of just keeping a
2273  * reference.
2274  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2275  * is exhausted and the system throws in that case (this exception
2276  * will not be thrown if the library has been installed using the
2277  * \--with-glib-memory-slices-no-compat configuration option: instead
2278  * glib will terminate the program if it is unable to obtain memory
2279  * from the operating system). It will also throw if the copy or move
2280  * constructor of a bound argument throws.
2281  *
2282  * Since 2.0.0-rc3
2283  */
2284 template <class T, class BoundArg1, class BoundArg2,
2285  class Arg1, class Arg2, class... FreeArgs>
2286 CallbackArg<FreeArgs...>* make_ref(T& t,
2287  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
2288  Arg1&& arg1,
2289  Arg2&& arg2) {
2290  return new Callback2<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func,
2291  std::forward<Arg1>(arg1),
2292  std::forward<Arg2>(arg2)};
2293 }
2294 
2295 /**
2296  * A convenience function to make Callback::CallbackArg objects
2297  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2298  * is exhausted and the system throws in that case (this exception
2299  * will not be thrown if the library has been installed using the
2300  * \--with-glib-memory-slices-no-compat configuration option: instead
2301  * glib will terminate the program if it is unable to obtain memory
2302  * from the operating system). It will also throw if the copy
2303  * constructor of a bound argument throws and it is not a reference
2304  * argument.
2305  */
2306 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2307 CallbackArg<FreeArgs...>* make(T& t,
2308  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2309  BoundArg1 arg1,
2310  BoundArg2 arg2,
2311  BoundArg3 arg3) {
2312  return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2313 }
2314 
2315 /**
2316  * DEPRECATED: use Callback::make_ref() instead.
2317  *
2318  * An alternative function to make Callback::CallbackArg objects,
2319  * which is for use where a target function receives an argument of
2320  * class type by value which is to be a bound argument, so the
2321  * compiler is not able to carry out copy elision when constructing
2322  * the callback object.
2323  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2324  * is exhausted and the system throws in that case (this exception
2325  * will not be thrown if the library has been installed using the
2326  * \--with-glib-memory-slices-no-compat configuration option: instead
2327  * glib will terminate the program if it is unable to obtain memory
2328  * from the operating system). It will also throw if the copy
2329  * constructor of a bound argument throws and it is not a reference
2330  * argument.
2331  */
2332 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2333 CallbackArg<FreeArgs...>* make_val(T& t,
2334  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2335  const BoundArg1& arg1,
2336  const BoundArg2& arg2,
2337  const BoundArg3& arg3) {
2338  return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2339 }
2340 
2341 /**
2342  * An alternative function to make Callback::CallbackArg objects,
2343  * which is for use where a target function either receives a class
2344  * type bound argument by value, or receives a bound argument by
2345  * reference to const in a case where the generated CallbackArg object
2346  * is to store a copy of that argument instead of just keeping a
2347  * reference.
2348  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2349  * is exhausted and the system throws in that case (this exception
2350  * will not be thrown if the library has been installed using the
2351  * \--with-glib-memory-slices-no-compat configuration option: instead
2352  * glib will terminate the program if it is unable to obtain memory
2353  * from the operating system). It will also throw if the copy or move
2354  * constructor of a bound argument throws.
2355  *
2356  * Since 2.0.0-rc3
2357  */
2358 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2359  class Arg1, class Arg2, class Arg3, class... FreeArgs>
2360 CallbackArg<FreeArgs...>* make_ref(T& t,
2361  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2362  Arg1&& arg1,
2363  Arg2&& arg2,
2364  Arg3&& arg3) {
2365  return new Callback3<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func,
2366  std::forward<Arg1>(arg1),
2367  std::forward<Arg2>(arg2),
2368  std::forward<Arg3>(arg3)};
2369 }
2370 
2371 /**
2372  * A convenience function to make Callback::CallbackArg objects
2373  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2374  * is exhausted and the system throws in that case (this exception
2375  * will not be thrown if the library has been installed using the
2376  * \--with-glib-memory-slices-no-compat configuration option: instead
2377  * glib will terminate the program if it is unable to obtain memory
2378  * from the operating system). It will also throw if the copy
2379  * constructor of a bound argument throws and it is not a reference
2380  * argument.
2381  */
2382 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2383  class BoundArg4, class... FreeArgs>
2384 CallbackArg<FreeArgs...>* make(T& t,
2385  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2386  BoundArg4, FreeArgs...),
2387  BoundArg1 arg1,
2388  BoundArg2 arg2,
2389  BoundArg3 arg3,
2390  BoundArg4 arg4) {
2391  return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3,
2392  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2393 }
2394 
2395 /**
2396  * DEPRECATED: use Callback::make_ref() instead.
2397  *
2398  * An alternative function to make Callback::CallbackArg objects,
2399  * which is for use where a target function receives an argument of
2400  * class type by value which is to be a bound argument, so the
2401  * compiler is not able to carry out copy elision when constructing
2402  * the callback object.
2403  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2404  * is exhausted and the system throws in that case (this exception
2405  * will not be thrown if the library has been installed using the
2406  * \--with-glib-memory-slices-no-compat configuration option: instead
2407  * glib will terminate the program if it is unable to obtain memory
2408  * from the operating system). It will also throw if the copy
2409  * constructor of a bound argument throws and it is not a reference
2410  * argument.
2411  */
2412 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2413  class BoundArg4, class... FreeArgs>
2414 CallbackArg<FreeArgs...>* make_val(T& t,
2415  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2416  BoundArg4, FreeArgs...),
2417  const BoundArg1& arg1,
2418  const BoundArg2& arg2,
2419  const BoundArg3& arg3,
2420  const BoundArg4& arg4) {
2421  return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3,
2422  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2423 }
2424 
2425 /**
2426  * An alternative function to make Callback::CallbackArg objects,
2427  * which is for use where a target function either receives a class
2428  * type bound argument by value, or receives a bound argument by
2429  * reference to const in a case where the generated CallbackArg object
2430  * is to store a copy of that argument instead of just keeping a
2431  * reference.
2432  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2433  * is exhausted and the system throws in that case (this exception
2434  * will not be thrown if the library has been installed using the
2435  * \--with-glib-memory-slices-no-compat configuration option: instead
2436  * glib will terminate the program if it is unable to obtain memory
2437  * from the operating system). It will also throw if the copy or move
2438  * constructor of a bound argument throws.
2439  *
2440  * Since 2.0.0-rc3
2441  */
2442 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
2443  class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
2444 CallbackArg<FreeArgs...>* make_ref(T& t,
2445  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2446  BoundArg4, FreeArgs...),
2447  Arg1&& arg1,
2448  Arg2&& arg2,
2449  Arg3&& arg3,
2450  Arg4&& arg4) {
2451  return new Callback4<true, T, BoundArg1, BoundArg2, BoundArg3,
2452  BoundArg4, FreeArgs...>{t, func,
2453  std::forward<Arg1>(arg1),
2454  std::forward<Arg2>(arg2),
2455  std::forward<Arg3>(arg3),
2456  std::forward<Arg4>(arg4)};
2457 }
2458 
2459 /**
2460  * A convenience function to make Callback::CallbackArg objects
2461  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2462  * is exhausted and the system throws in that case (this exception
2463  * will not be thrown if the library has been installed using the
2464  * \--with-glib-memory-slices-no-compat configuration option: instead
2465  * glib will terminate the program if it is unable to obtain memory
2466  * from the operating system). It will also throw if the copy
2467  * constructor of a bound argument throws and it is not a reference
2468  * argument.
2469  */
2470 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2471  class BoundArg4, class BoundArg5, class... FreeArgs>
2472 CallbackArg<FreeArgs...>* make(T& t,
2473  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2474  BoundArg4, BoundArg5, FreeArgs...),
2475  BoundArg1 arg1,
2476  BoundArg2 arg2,
2477  BoundArg3 arg3,
2478  BoundArg4 arg4,
2479  BoundArg5 arg5) {
2480  return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3,
2481  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2482 }
2483 
2484 /**
2485  * DEPRECATED: use Callback::make_ref() instead.
2486  *
2487  * An alternative function to make Callback::CallbackArg objects,
2488  * which is for use where a target function receives an argument of
2489  * class type by value which is to be a bound argument, so the
2490  * compiler is not able to carry out copy elision when constructing
2491  * the callback object.
2492  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2493  * is exhausted and the system throws in that case (this exception
2494  * will not be thrown if the library has been installed using the
2495  * \--with-glib-memory-slices-no-compat configuration option: instead
2496  * glib will terminate the program if it is unable to obtain memory
2497  * from the operating system). It will also throw if the copy
2498  * constructor of a bound argument throws and it is not a reference
2499  * argument.
2500  */
2501 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2502  class BoundArg4, class BoundArg5, class... FreeArgs>
2503 CallbackArg<FreeArgs...>* make_val(T& t,
2504  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2505  BoundArg4, BoundArg5, FreeArgs...),
2506  const BoundArg1& arg1,
2507  const BoundArg2& arg2,
2508  const BoundArg3& arg3,
2509  const BoundArg4& arg4,
2510  const BoundArg5& arg5) {
2511  return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3,
2512  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2513 }
2514 
2515 /**
2516  * An alternative function to make Callback::CallbackArg objects,
2517  * which is for use where a target function either receives a class
2518  * type bound argument by value, or receives a bound argument by
2519  * reference to const in a case where the generated CallbackArg object
2520  * is to store a copy of that argument instead of just keeping a
2521  * reference.
2522  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2523  * is exhausted and the system throws in that case (this exception
2524  * will not be thrown if the library has been installed using the
2525  * \--with-glib-memory-slices-no-compat configuration option: instead
2526  * glib will terminate the program if it is unable to obtain memory
2527  * from the operating system). It will also throw if the copy or move
2528  * constructor of a bound argument throws.
2529  *
2530  * Since 2.0.0-rc3
2531  */
2532 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
2533  class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
2534 CallbackArg<FreeArgs...>* make_ref(T& t,
2535  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2536  BoundArg4, BoundArg5, FreeArgs...),
2537  Arg1&& arg1,
2538  Arg2&& arg2,
2539  Arg3&& arg3,
2540  Arg4&& arg4,
2541  Arg5&& arg5) {
2542  return new Callback5<true, T, BoundArg1, BoundArg2, BoundArg3,
2543  BoundArg4, BoundArg5, FreeArgs...>{t, func,
2544  std::forward<Arg1>(arg1),
2545  std::forward<Arg2>(arg2),
2546  std::forward<Arg3>(arg3),
2547  std::forward<Arg4>(arg4),
2548  std::forward<Arg5>(arg5)};
2549 }
2550 
2551 /* const versions, for binding to const methods */
2552 
2553 /**
2554  * A convenience function to make Callback::CallbackArg objects
2555  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2556  * is exhausted and the system throws in that case. This exception
2557  * will not be thrown if the library has been installed using the
2558  * \--with-glib-memory-slices-no-compat configuration option (instead
2559  * glib will terminate the program if it is unable to obtain memory
2560  * from the operating system).
2561  */
2562 template <class T, class... FreeArgs>
2563 CallbackArg<FreeArgs...>* make(const T& t,
2564  void (T::*func)(FreeArgs...) const) {
2565  return new Callback0_const<T, FreeArgs...>{t, func};
2566 }
2567 
2568 /**
2569  * DEPRECATED.
2570  *
2571  * Since this function constructs a callback which does not take a
2572  * bound argument, it is a synonym for make() (the two are identical).
2573  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2574  * is exhausted and the system throws in that case. This exception
2575  * will not be thrown if the library has been installed using the
2576  * \--with-glib-memory-slices-no-compat configuration option (instead
2577  * glib will terminate the program if it is unable to obtain memory
2578  * from the operating system).
2579  */
2580 template <class T, class... FreeArgs>
2581 CallbackArg<FreeArgs...>* make_val(const T& t,
2582  void (T::*func)(FreeArgs...) const) {
2583  return new Callback0_const<T, FreeArgs...>{t, func};
2584 }
2585 
2586 /**
2587  * Since this function constructs a callback which does not take a
2588  * bound argument, it is a synonym for make() (the two are identical).
2589  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2590  * is exhausted and the system throws in that case. This exception
2591  * will not be thrown if the library has been installed using the
2592  * \--with-glib-memory-slices-no-compat configuration option (instead
2593  * glib will terminate the program if it is unable to obtain memory
2594  * from the operating system).
2595  *
2596  * Since 2.0.0-rc3
2597  */
2598 template <class T, class... FreeArgs>
2599 CallbackArg<FreeArgs...>* make_ref(const T& t,
2600  void (T::*func)(FreeArgs...) const) {
2601  return new Callback0_const<T, FreeArgs...>{t, func};
2602 }
2603 
2604 /**
2605  * A convenience function to make Callback::CallbackArg objects
2606  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2607  * is exhausted and the system throws in that case (this exception
2608  * will not be thrown if the library has been installed using the
2609  * \--with-glib-memory-slices-no-compat configuration option: instead
2610  * glib will terminate the program if it is unable to obtain memory
2611  * from the operating system). It will also throw if the copy
2612  * constructor of a bound argument throws and it is not a reference
2613  * argument.
2614  */
2615 template <class T, class BoundArg, class... FreeArgs>
2616 CallbackArg<FreeArgs...>* make(const T& t,
2617  void (T::*func)(BoundArg, FreeArgs...) const,
2618  BoundArg arg) {
2619  return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg};
2620 }
2621 
2622 /**
2623  * DEPRECATED: use Callback::make_ref() instead.
2624  *
2625  * An alternative function to make Callback::CallbackArg objects,
2626  * which is for use where a target function receives an argument of
2627  * class type by value which is to be a bound argument, so the
2628  * compiler is not able to carry out copy elision when constructing
2629  * the callback object.
2630  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2631  * is exhausted and the system throws in that case (this exception
2632  * will not be thrown if the library has been installed using the
2633  * \--with-glib-memory-slices-no-compat configuration option: instead
2634  * glib will terminate the program if it is unable to obtain memory
2635  * from the operating system). It will also throw if the copy
2636  * constructor of a bound argument throws and it is not a reference
2637  * argument.
2638  */
2639 template <class T, class BoundArg, class... FreeArgs>
2640 CallbackArg<FreeArgs...>* make_val(const T& t,
2641  void (T::*func)(BoundArg, FreeArgs...) const,
2642  const BoundArg& arg) {
2643  return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg};
2644 }
2645 
2646 /**
2647  * An alternative function to make Callback::CallbackArg objects,
2648  * which is for use where a target function either receives a class
2649  * type bound argument by value, or receives a bound argument by
2650  * reference to const in a case where the generated CallbackArg object
2651  * is to store a copy of that argument instead of just keeping a
2652  * reference.
2653  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2654  * is exhausted and the system throws in that case (this exception
2655  * will not be thrown if the library has been installed using the
2656  * \--with-glib-memory-slices-no-compat configuration option: instead
2657  * glib will terminate the program if it is unable to obtain memory
2658  * from the operating system). It will also throw if the copy or move
2659  * constructor of a bound argument throws.
2660  *
2661  * Since 2.0.0-rc3
2662  */
2663 template <class T, class BoundArg, class Arg, class... FreeArgs>
2664 CallbackArg<FreeArgs...>* make_ref(const T& t,
2665  void (T::*func)(BoundArg, FreeArgs...) const,
2666  Arg&& arg) {
2667  return new Callback1_const<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)};
2668 }
2669 
2670 /**
2671  * A convenience function to make Callback::CallbackArg objects
2672  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2673  * is exhausted and the system throws in that case (this exception
2674  * will not be thrown if the library has been installed using the
2675  * \--with-glib-memory-slices-no-compat configuration option: instead
2676  * glib will terminate the program if it is unable to obtain memory
2677  * from the operating system). It will also throw if the copy
2678  * constructor of a bound argument throws and it is not a reference
2679  * argument.
2680  */
2681 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2682 CallbackArg<FreeArgs...>* make(const T& t,
2683  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
2684  BoundArg1 arg1,
2685  BoundArg2 arg2) {
2686  return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2687 }
2688 
2689 /**
2690  * DEPRECATED: use Callback::make_ref() instead.
2691  *
2692  * An alternative function to make Callback::CallbackArg objects,
2693  * which is for use where a target function receives an argument of
2694  * class type by value which is to be a bound argument, so the
2695  * compiler is not able to carry out copy elision when constructing
2696  * the callback object.
2697  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2698  * is exhausted and the system throws in that case (this exception
2699  * will not be thrown if the library has been installed using the
2700  * \--with-glib-memory-slices-no-compat configuration option: instead
2701  * glib will terminate the program if it is unable to obtain memory
2702  * from the operating system). It will also throw if the copy
2703  * constructor of a bound argument throws and it is not a reference
2704  * argument.
2705  */
2706 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2707 CallbackArg<FreeArgs...>* make_val(const T& t,
2708  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
2709  const BoundArg1& arg1,
2710  const BoundArg2& arg2) {
2711  return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2712 }
2713 
2714 /**
2715  * An alternative function to make Callback::CallbackArg objects,
2716  * which is for use where a target function either receives a class
2717  * type bound argument by value, or receives a bound argument by
2718  * reference to const in a case where the generated CallbackArg object
2719  * is to store a copy of that argument instead of just keeping a
2720  * reference.
2721  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2722  * is exhausted and the system throws in that case (this exception
2723  * will not be thrown if the library has been installed using the
2724  * \--with-glib-memory-slices-no-compat configuration option: instead
2725  * glib will terminate the program if it is unable to obtain memory
2726  * from the operating system). It will also throw if the copy or move
2727  * constructor of a bound argument throws.
2728  *
2729  * Since 2.0.0-rc3
2730  */
2731 template <class T, class BoundArg1, class BoundArg2,
2732  class Arg1, class Arg2, class... FreeArgs>
2733 CallbackArg<FreeArgs...>* make_ref(const T& t,
2734  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
2735  Arg1&& arg1,
2736  Arg2&& arg2) {
2737  return new Callback2_const<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func,
2738  std::forward<Arg1>(arg1),
2739  std::forward<Arg2>(arg2)};
2740 }
2741 
2742 /**
2743  * A convenience function to make Callback::CallbackArg objects
2744  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2745  * is exhausted and the system throws in that case (this exception
2746  * will not be thrown if the library has been installed using the
2747  * \--with-glib-memory-slices-no-compat configuration option: instead
2748  * glib will terminate the program if it is unable to obtain memory
2749  * from the operating system). It will also throw if the copy
2750  * constructor of a bound argument throws and it is not a reference
2751  * argument.
2752  */
2753 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2754 CallbackArg<FreeArgs...>* make(const T& t,
2755  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
2756  BoundArg1 arg1,
2757  BoundArg2 arg2,
2758  BoundArg3 arg3) {
2759  return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2760 }
2761 
2762 /**
2763  * DEPRECATED: use Callback::make_ref() instead.
2764  *
2765  * An alternative function to make Callback::CallbackArg objects,
2766  * which is for use where a target function receives an argument of
2767  * class type by value which is to be a bound argument, so the
2768  * compiler is not able to carry out copy elision when constructing
2769  * the callback object.
2770  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2771  * is exhausted and the system throws in that case (this exception
2772  * will not be thrown if the library has been installed using the
2773  * \--with-glib-memory-slices-no-compat configuration option: instead
2774  * glib will terminate the program if it is unable to obtain memory
2775  * from the operating system). It will also throw if the copy
2776  * constructor of a bound argument throws and it is not a reference
2777  * argument.
2778  */
2779 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2780 CallbackArg<FreeArgs...>* make_val(const T& t,
2781  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
2782  const BoundArg1& arg1,
2783  const BoundArg2& arg2,
2784  const BoundArg3& arg3) {
2785  return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2786 }
2787 
2788 /**
2789  * An alternative function to make Callback::CallbackArg objects,
2790  * which is for use where a target function either receives a class
2791  * type bound argument by value, or receives a bound argument by
2792  * reference to const in a case where the generated CallbackArg object
2793  * is to store a copy of that argument instead of just keeping a
2794  * reference.
2795  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2796  * is exhausted and the system throws in that case (this exception
2797  * will not be thrown if the library has been installed using the
2798  * \--with-glib-memory-slices-no-compat configuration option: instead
2799  * glib will terminate the program if it is unable to obtain memory
2800  * from the operating system). It will also throw if the copy or move
2801  * constructor of a bound argument throws.
2802  *
2803  * Since 2.0.0-rc3
2804  */
2805 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2806  class Arg1, class Arg2, class Arg3, class... FreeArgs>
2807 CallbackArg<FreeArgs...>* make_ref(const T& t,
2808  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
2809  Arg1&& arg1,
2810  Arg2&& arg2,
2811  Arg3&& arg3) {
2812  return new Callback3_const<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func,
2813  std::forward<Arg1>(arg1),
2814  std::forward<Arg2>(arg2),
2815  std::forward<Arg3>(arg3)};
2816 }
2817 
2818 /**
2819  * A convenience function to make Callback::CallbackArg objects
2820  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2821  * is exhausted and the system throws in that case (this exception
2822  * will not be thrown if the library has been installed using the
2823  * \--with-glib-memory-slices-no-compat configuration option: instead
2824  * glib will terminate the program if it is unable to obtain memory
2825  * from the operating system). It will also throw if the copy
2826  * constructor of a bound argument throws and it is not a reference
2827  * argument.
2828  */
2829 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2830  class BoundArg4, class... FreeArgs>
2831 CallbackArg<FreeArgs...>* make(const T& t,
2832  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2833  BoundArg4, FreeArgs...) const,
2834  BoundArg1 arg1,
2835  BoundArg2 arg2,
2836  BoundArg3 arg3,
2837  BoundArg4 arg4) {
2838  return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2839  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2840 }
2841 
2842 /**
2843  * DEPRECATED: use Callback::make_ref() instead.
2844  *
2845  * An alternative function to make Callback::CallbackArg objects,
2846  * which is for use where a target function receives an argument of
2847  * class type by value which is to be a bound argument, so the
2848  * compiler is not able to carry out copy elision when constructing
2849  * the callback object.
2850  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2851  * is exhausted and the system throws in that case (this exception
2852  * will not be thrown if the library has been installed using the
2853  * \--with-glib-memory-slices-no-compat configuration option: instead
2854  * glib will terminate the program if it is unable to obtain memory
2855  * from the operating system). It will also throw if the copy
2856  * constructor of a bound argument throws and it is not a reference
2857  * argument.
2858  */
2859 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2860  class BoundArg4, class... FreeArgs>
2861 CallbackArg<FreeArgs...>* make_val(const T& t,
2862  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2863  BoundArg4, FreeArgs...) const,
2864  const BoundArg1& arg1,
2865  const BoundArg2& arg2,
2866  const BoundArg3& arg3,
2867  const BoundArg4& arg4) {
2868  return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2869  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2870 }
2871 
2872 /**
2873  * An alternative function to make Callback::CallbackArg objects,
2874  * which is for use where a target function either receives a class
2875  * type bound argument by value, or receives a bound argument by
2876  * reference to const in a case where the generated CallbackArg object
2877  * is to store a copy of that argument instead of just keeping a
2878  * reference.
2879  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2880  * is exhausted and the system throws in that case (this exception
2881  * will not be thrown if the library has been installed using the
2882  * \--with-glib-memory-slices-no-compat configuration option: instead
2883  * glib will terminate the program if it is unable to obtain memory
2884  * from the operating system). It will also throw if the copy or move
2885  * constructor of a bound argument throws.
2886  *
2887  * Since 2.0.0-rc3
2888  */
2889 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
2890  class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
2891 CallbackArg<FreeArgs...>* make_ref(const T& t,
2892  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2893  BoundArg4, FreeArgs...) const,
2894  Arg1&& arg1,
2895  Arg2&& arg2,
2896  Arg3&& arg3,
2897  Arg4&& arg4) {
2898  return new Callback4_const<true, T, BoundArg1, BoundArg2, BoundArg3,
2899  BoundArg4, FreeArgs...>{t, func,
2900  std::forward<Arg1>(arg1),
2901  std::forward<Arg2>(arg2),
2902  std::forward<Arg3>(arg3),
2903  std::forward<Arg4>(arg4)};
2904 }
2905 
2906 /**
2907  * A convenience function to make Callback::CallbackArg objects
2908  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2909  * is exhausted and the system throws in that case (this exception
2910  * will not be thrown if the library has been installed using the
2911  * \--with-glib-memory-slices-no-compat configuration option: instead
2912  * glib will terminate the program if it is unable to obtain memory
2913  * from the operating system). It will also throw if the copy
2914  * constructor of a bound argument throws and it is not a reference
2915  * argument.
2916  */
2917 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2918  class BoundArg4, class BoundArg5, class... FreeArgs>
2919 CallbackArg<FreeArgs...>* make(const T& t,
2920  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2921  BoundArg4, BoundArg5, FreeArgs...) const,
2922  BoundArg1 arg1,
2923  BoundArg2 arg2,
2924  BoundArg3 arg3,
2925  BoundArg4 arg4,
2926  BoundArg5 arg5) {
2927  return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2928  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2929 }
2930 
2931 /**
2932  * DEPRECATED: use Callback::make_ref() instead.
2933  *
2934  * An alternative function to make Callback::CallbackArg objects,
2935  * which is for use where a target function receives an argument of
2936  * class type by value which is to be a bound argument, so the
2937  * compiler is not able to carry out copy elision when constructing
2938  * the callback object.
2939  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2940  * is exhausted and the system throws in that case (this exception
2941  * will not be thrown if the library has been installed using the
2942  * \--with-glib-memory-slices-no-compat configuration option: instead
2943  * glib will terminate the program if it is unable to obtain memory
2944  * from the operating system). It will also throw if the copy
2945  * constructor of a bound argument throws and it is not a reference
2946  * argument.
2947  */
2948 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2949  class BoundArg4, class BoundArg5, class... FreeArgs>
2950 CallbackArg<FreeArgs...>* make_val(const T& t,
2951  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2952  BoundArg4, BoundArg5, FreeArgs...) const,
2953  const BoundArg1& arg1,
2954  const BoundArg2& arg2,
2955  const BoundArg3& arg3,
2956  const BoundArg4& arg4,
2957  const BoundArg5& arg5) {
2958  return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2959  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2960 }
2961 
2962 /**
2963  * An alternative function to make Callback::CallbackArg objects,
2964  * which is for use where a target function either receives a class
2965  * type bound argument by value, or receives a bound argument by
2966  * reference to const in a case where the generated CallbackArg object
2967  * is to store a copy of that argument instead of just keeping a
2968  * reference.
2969  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2970  * is exhausted and the system throws in that case (this exception
2971  * will not be thrown if the library has been installed using the
2972  * \--with-glib-memory-slices-no-compat configuration option: instead
2973  * glib will terminate the program if it is unable to obtain memory
2974  * from the operating system). It will also throw if the copy or move
2975  * constructor of a bound argument throws.
2976  *
2977  * Since 2.0.0-rc3
2978  */
2979 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
2980  class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
2981 CallbackArg<FreeArgs...>* make_ref(const T& t,
2982  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2983  BoundArg4, BoundArg5, FreeArgs...) const,
2984  Arg1&& arg1,
2985  Arg2&& arg2,
2986  Arg3&& arg3,
2987  Arg4&& arg4,
2988  Arg5&& arg5) {
2989  return new Callback5_const<true, T, BoundArg1, BoundArg2, BoundArg3,
2990  BoundArg4, BoundArg5, FreeArgs...>{t, func,
2991  std::forward<Arg1>(arg1),
2992  std::forward<Arg2>(arg2),
2993  std::forward<Arg3>(arg3),
2994  std::forward<Arg4>(arg4),
2995  std::forward<Arg5>(arg5)};
2996 }
2997 
2998 /* for static class methods and non-class functions */
2999 
3000 /**
3001  * A convenience function to make Callback::CallbackArg objects
3002  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3003  * is exhausted and the system throws in that case. This exception
3004  * will not be thrown if the library has been installed using the
3005  * \--with-glib-memory-slices-no-compat configuration option (instead
3006  * glib will terminate the program if it is unable to obtain memory
3007  * from the operating system).
3008  */
3009 template <class... FreeArgs>
3010 CallbackArg<FreeArgs...>* make(void (*func)(FreeArgs...)) {
3011  return new Callback0_static<FreeArgs...>{func};
3012 }
3013 
3014 /**
3015  * DEPRECATED.
3016  *
3017  * Since this function constructs a callback which does not take a
3018  * bound argument, it is a synonym for make() (the two are identical).
3019  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3020  * is exhausted and the system throws in that case. This exception
3021  * will not be thrown if the library has been installed using the
3022  * \--with-glib-memory-slices-no-compat configuration option (instead
3023  * glib will terminate the program if it is unable to obtain memory
3024  * from the operating system).
3025  */
3026 template <class... FreeArgs>
3027 CallbackArg<FreeArgs...>* make_val(void (*func)(FreeArgs...)) {
3028  return new Callback0_static<FreeArgs...>{func};
3029 }
3030 
3031 /**
3032  * Since this function constructs a callback which does not take a
3033  * bound argument, it is a synonym for make() (the two are identical).
3034  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3035  * is exhausted and the system throws in that case. This exception
3036  * will not be thrown if the library has been installed using the
3037  * \--with-glib-memory-slices-no-compat configuration option (instead
3038  * glib will terminate the program if it is unable to obtain memory
3039  * from the operating system).
3040  *
3041  * Since 2.0.0-rc3
3042  */
3043 template <class... FreeArgs>
3044 CallbackArg<FreeArgs...>* make_ref(void (*func)(FreeArgs...)) {
3045  return new Callback0_static<FreeArgs...>{func};
3046 }
3047 
3048 /**
3049  * A convenience function to make Callback::CallbackArg objects
3050  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3051  * is exhausted and the system throws in that case (this exception
3052  * will not be thrown if the library has been installed using the
3053  * \--with-glib-memory-slices-no-compat configuration option: instead
3054  * glib will terminate the program if it is unable to obtain memory
3055  * from the operating system). It will also throw if the copy
3056  * constructor of a bound argument throws and it is not a reference
3057  * argument.
3058  */
3059 template <class BoundArg, class... FreeArgs>
3060 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg, FreeArgs...),
3061  BoundArg arg) {
3062  return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg};
3063 }
3064 
3065 /**
3066  * DEPRECATED: use Callback::make_ref() instead.
3067  *
3068  * An alternative function to make Callback::CallbackArg objects,
3069  * which is for use where a target function receives an argument of
3070  * class type by value which is to be a bound argument, so the
3071  * compiler is not able to carry out copy elision when constructing
3072  * the callback object.
3073  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3074  * is exhausted and the system throws in that case (this exception
3075  * will not be thrown if the library has been installed using the
3076  * \--with-glib-memory-slices-no-compat configuration option: instead
3077  * glib will terminate the program if it is unable to obtain memory
3078  * from the operating system). It will also throw if the copy
3079  * constructor of a bound argument throws and it is not a reference
3080  * argument.
3081  */
3082 template <class BoundArg, class... FreeArgs>
3083 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg, FreeArgs...),
3084  const BoundArg& arg) {
3085  return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg};
3086 }
3087 
3088 /**
3089  * An alternative function to make Callback::CallbackArg objects,
3090  * which is for use where a target function either receives a class
3091  * type bound argument by value, or receives a bound argument by
3092  * reference to const in a case where the generated CallbackArg object
3093  * is to store a copy of that argument instead of just keeping a
3094  * reference.
3095  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3096  * is exhausted and the system throws in that case (this exception
3097  * will not be thrown if the library has been installed using the
3098  * \--with-glib-memory-slices-no-compat configuration option: instead
3099  * glib will terminate the program if it is unable to obtain memory
3100  * from the operating system). It will also throw if the copy or move
3101  * constructor of a bound argument throws.
3102  *
3103  * Since 2.0.0-rc3
3104  */
3105 template <class BoundArg, class Arg, class... FreeArgs>
3106 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg, FreeArgs...),
3107  Arg&& arg) {
3108  return new Callback1_static<true, BoundArg, FreeArgs...>{func, std::forward<Arg>(arg)};
3109 }
3110 
3111 /**
3112  * A convenience function to make Callback::CallbackArg objects
3113  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3114  * is exhausted and the system throws in that case (this exception
3115  * will not be thrown if the library has been installed using the
3116  * \--with-glib-memory-slices-no-compat configuration option: instead
3117  * glib will terminate the program if it is unable to obtain memory
3118  * from the operating system). It will also throw if the copy
3119  * constructor of a bound argument throws and it is not a reference
3120  * argument.
3121  */
3122 template <class BoundArg1, class BoundArg2, class... FreeArgs>
3123 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
3124  BoundArg1 arg1,
3125  BoundArg2 arg2) {
3126  return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2};
3127 }
3128 
3129 /**
3130  * DEPRECATED: use Callback::make_ref() instead.
3131  *
3132  * An alternative function to make Callback::CallbackArg objects,
3133  * which is for use where a target function receives an argument of
3134  * class type by value which is to be a bound argument, so the
3135  * compiler is not able to carry out copy elision when constructing
3136  * the callback object.
3137  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3138  * is exhausted and the system throws in that case (this exception
3139  * will not be thrown if the library has been installed using the
3140  * \--with-glib-memory-slices-no-compat configuration option: instead
3141  * glib will terminate the program if it is unable to obtain memory
3142  * from the operating system). It will also throw if the copy
3143  * constructor of a bound argument throws and it is not a reference
3144  * argument.
3145  */
3146 template <class BoundArg1, class BoundArg2, class... FreeArgs>
3147 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
3148  const BoundArg1& arg1,
3149  const BoundArg2& arg2) {
3150  return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2};
3151 }
3152 
3153 /**
3154  * An alternative function to make Callback::CallbackArg objects,
3155  * which is for use where a target function either receives a class
3156  * type bound argument by value, or receives a bound argument by
3157  * reference to const in a case where the generated CallbackArg object
3158  * is to store a copy of that argument instead of just keeping a
3159  * reference.
3160  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3161  * is exhausted and the system throws in that case (this exception
3162  * will not be thrown if the library has been installed using the
3163  * \--with-glib-memory-slices-no-compat configuration option: instead
3164  * glib will terminate the program if it is unable to obtain memory
3165  * from the operating system). It will also throw if the copy or move
3166  * constructor of a bound argument throws.
3167  *
3168  * Since 2.0.0-rc3
3169  */
3170 template <class BoundArg1, class BoundArg2, class Arg1, class Arg2, class... FreeArgs>
3171 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
3172  Arg1&& arg1,
3173  Arg2&& arg2) {
3174  return new Callback2_static<true, BoundArg1, BoundArg2, FreeArgs...>{func,
3175  std::forward<Arg1>(arg1),
3176  std::forward<Arg2>(arg2)};
3177 }
3178 
3179 /**
3180  * A convenience function to make Callback::CallbackArg objects
3181  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3182  * is exhausted and the system throws in that case (this exception
3183  * will not be thrown if the library has been installed using the
3184  * \--with-glib-memory-slices-no-compat configuration option: instead
3185  * glib will terminate the program if it is unable to obtain memory
3186  * from the operating system). It will also throw if the copy
3187  * constructor of a bound argument throws and it is not a reference
3188  * argument.
3189  */
3190 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
3191 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
3192  BoundArg1 arg1,
3193  BoundArg2 arg2,
3194  BoundArg3 arg3) {
3195  return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3};
3196 }
3197 
3198 /**
3199  * DEPRECATED: use Callback::make_ref() instead.
3200  *
3201  * An alternative function to make Callback::CallbackArg objects,
3202  * which is for use where a target function receives an argument of
3203  * class type by value which is to be a bound argument, so the
3204  * compiler is not able to carry out copy elision when constructing
3205  * the callback object.
3206  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3207  * is exhausted and the system throws in that case (this exception
3208  * will not be thrown if the library has been installed using the
3209  * \--with-glib-memory-slices-no-compat configuration option: instead
3210  * glib will terminate the program if it is unable to obtain memory
3211  * from the operating system). It will also throw if the copy
3212  * constructor of a bound argument throws and it is not a reference
3213  * argument.
3214  */
3215 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
3216 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
3217  const BoundArg1& arg1,
3218  const BoundArg2& arg2,
3219  const BoundArg3& arg3) {
3220  return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3};
3221 }
3222 
3223 /**
3224  * An alternative function to make Callback::CallbackArg objects,
3225  * which is for use where a target function either receives a class
3226  * type bound argument by value, or receives a bound argument by
3227  * reference to const in a case where the generated CallbackArg object
3228  * is to store a copy of that argument instead of just keeping a
3229  * reference.
3230  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3231  * is exhausted and the system throws in that case (this exception
3232  * will not be thrown if the library has been installed using the
3233  * \--with-glib-memory-slices-no-compat configuration option: instead
3234  * glib will terminate the program if it is unable to obtain memory
3235  * from the operating system). It will also throw if the copy or move
3236  * constructor of a bound argument throws.
3237  *
3238  * Since 2.0.0-rc3
3239  */
3240 template <class BoundArg1, class BoundArg2, class BoundArg3,
3241  class Arg1, class Arg2, class Arg3, class... FreeArgs>
3242 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
3243  Arg1&& arg1,
3244  Arg2&& arg2,
3245  Arg3&& arg3) {
3246  return new Callback3_static<true, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func,
3247  std::forward<Arg1>(arg1),
3248  std::forward<Arg2>(arg2),
3249  std::forward<Arg3>(arg3)};
3250 }
3251 
3252 /**
3253  * A convenience function to make Callback::CallbackArg objects
3254  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3255  * is exhausted and the system throws in that case (this exception
3256  * will not be thrown if the library has been installed using the
3257  * \--with-glib-memory-slices-no-compat configuration option: instead
3258  * glib will terminate the program if it is unable to obtain memory
3259  * from the operating system). It will also throw if the copy
3260  * constructor of a bound argument throws and it is not a reference
3261  * argument.
3262  */
3263 template <class BoundArg1, class BoundArg2, class BoundArg3,
3264  class BoundArg4, class... FreeArgs>
3265 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3266  BoundArg4, FreeArgs...),
3267  BoundArg1 arg1,
3268  BoundArg2 arg2,
3269  BoundArg3 arg3,
3270  BoundArg4 arg4) {
3271  return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3,
3272  BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4};
3273 }
3274 
3275 /**
3276  * DEPRECATED: use Callback::make_ref() instead.
3277  *
3278  * An alternative function to make Callback::CallbackArg objects,
3279  * which is for use where a target function receives an argument of
3280  * class type by value which is to be a bound argument, so the
3281  * compiler is not able to carry out copy elision when constructing
3282  * the callback object.
3283  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3284  * is exhausted and the system throws in that case (this exception
3285  * will not be thrown if the library has been installed using the
3286  * \--with-glib-memory-slices-no-compat configuration option: instead
3287  * glib will terminate the program if it is unable to obtain memory
3288  * from the operating system). It will also throw if the copy
3289  * constructor of a bound argument throws and it is not a reference
3290  * argument.
3291  */
3292 template <class BoundArg1, class BoundArg2, class BoundArg3,
3293  class BoundArg4, class... FreeArgs>
3294 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3295  BoundArg4, FreeArgs...),
3296  const BoundArg1& arg1,
3297  const BoundArg2& arg2,
3298  const BoundArg3& arg3,
3299  const BoundArg4& arg4) {
3300  return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3,
3301  BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4};
3302 }
3303 
3304 /**
3305  * An alternative function to make Callback::CallbackArg objects,
3306  * which is for use where a target function either receives a class
3307  * type bound argument by value, or receives a bound argument by
3308  * reference to const in a case where the generated CallbackArg object
3309  * is to store a copy of that argument instead of just keeping a
3310  * reference.
3311  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3312  * is exhausted and the system throws in that case (this exception
3313  * will not be thrown if the library has been installed using the
3314  * \--with-glib-memory-slices-no-compat configuration option: instead
3315  * glib will terminate the program if it is unable to obtain memory
3316  * from the operating system). It will also throw if the copy or move
3317  * constructor of a bound argument throws.
3318  *
3319  * Since 2.0.0-rc3
3320  */
3321 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
3322  class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
3323 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3324  BoundArg4, FreeArgs...),
3325  Arg1&& arg1,
3326  Arg2&& arg2,
3327  Arg3&& arg3,
3328  Arg4&& arg4) {
3329  return new Callback4_static<true, BoundArg1, BoundArg2, BoundArg3,
3330  BoundArg4, FreeArgs...>{func,
3331  std::forward<Arg1>(arg1),
3332  std::forward<Arg2>(arg2),
3333  std::forward<Arg3>(arg3),
3334  std::forward<Arg4>(arg4)};
3335 }
3336 
3337 /**
3338  * A convenience function to make Callback::CallbackArg objects
3339  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3340  * is exhausted and the system throws in that case (this exception
3341  * will not be thrown if the library has been installed using the
3342  * \--with-glib-memory-slices-no-compat configuration option: instead
3343  * glib will terminate the program if it is unable to obtain memory
3344  * from the operating system). It will also throw if the copy
3345  * constructor of a bound argument throws and it is not a reference
3346  * argument.
3347  */
3348 template <class BoundArg1, class BoundArg2, class BoundArg3,
3349  class BoundArg4, class BoundArg5, class... FreeArgs>
3350 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3351  BoundArg4, BoundArg5, FreeArgs...),
3352  BoundArg1 arg1,
3353  BoundArg2 arg2,
3354  BoundArg3 arg3,
3355  BoundArg4 arg4,
3356  BoundArg5 arg5) {
3357  return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3,
3358  BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5};
3359 }
3360 
3361 /**
3362  * DEPRECATED: use Callback::make_ref() instead.
3363  *
3364  * An alternative function to make Callback::CallbackArg objects,
3365  * which is for use where a target function receives an argument of
3366  * class type by value which is to be a bound argument, so the
3367  * compiler is not able to carry out copy elision when constructing
3368  * the callback object.
3369  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3370  * is exhausted and the system throws in that case (this exception
3371  * will not be thrown if the library has been installed using the
3372  * \--with-glib-memory-slices-no-compat configuration option: instead
3373  * glib will terminate the program if it is unable to obtain memory
3374  * from the operating system). It will also throw if the copy
3375  * constructor of a bound argument throws and it is not a reference
3376  * argument.
3377  */
3378 template <class BoundArg1, class BoundArg2, class BoundArg3,
3379  class BoundArg4, class BoundArg5, class... FreeArgs>
3380 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3381  BoundArg4, BoundArg5, FreeArgs...),
3382  const BoundArg1& arg1,
3383  const BoundArg2& arg2,
3384  const BoundArg3& arg3,
3385  const BoundArg4& arg4,
3386  const BoundArg5& arg5) {
3387  return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3,
3388  BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5};
3389 }
3390 
3391 /**
3392  * An alternative function to make Callback::CallbackArg objects,
3393  * which is for use where a target function either receives a class
3394  * type bound argument by value, or receives a bound argument by
3395  * reference to const in a case where the generated CallbackArg object
3396  * is to store a copy of that argument instead of just keeping a
3397  * reference.
3398  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3399  * is exhausted and the system throws in that case (this exception
3400  * will not be thrown if the library has been installed using the
3401  * \--with-glib-memory-slices-no-compat configuration option: instead
3402  * glib will terminate the program if it is unable to obtain memory
3403  * from the operating system). It will also throw if the copy or move
3404  * constructor of a bound argument throws.
3405  *
3406  * Since 2.0.0-rc3
3407  */
3408 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
3409  class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
3410 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3411  BoundArg4, BoundArg5, FreeArgs...),
3412  Arg1&& arg1,
3413  Arg2&& arg2,
3414  Arg3&& arg3,
3415  Arg4&& arg4,
3416  Arg5&& arg5) {
3417  return new Callback5_static<true, BoundArg1, BoundArg2, BoundArg3,
3418  BoundArg4, BoundArg5, FreeArgs...>{func,
3419  std::forward<Arg1>(arg1),
3420  std::forward<Arg2>(arg2),
3421  std::forward<Arg3>(arg3),
3422  std::forward<Arg4>(arg4),
3423  std::forward<Arg5>(arg5)};
3424 }
3425 
3426 /* for std::function objects */
3427 
3428 /**
3429  * A convenience function to make Callback::CallbackArg objects from
3430  * std::function objects.
3431  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3432  * is exhausted and the system throws in that case (this exception
3433  * will not be thrown if the library has been installed using the
3434  * \--with-glib-memory-slices-no-compat configuration option: instead
3435  * glib will terminate the program if it is unable to obtain memory
3436  * from the operating system). It will also throw if the copy
3437  * constructor of a bound argument throws and it is not a reference
3438  * argument.
3439  */
3440 template <class... FreeArgs>
3441 CallbackArg<FreeArgs...>* make(const std::function<void(FreeArgs...)>& f) {
3442  return new Callback_function<FreeArgs...>{f};
3443 }
3444 
3445 /**
3446  * DEPRECATED.
3447  *
3448  * A convenience function to make Callback::Callback objects from
3449  * std::function objects. Since this function takes no bound argument
3450  * (and bound arguments are bound into the std::function object), it
3451  * is a synonym for make() (the two are identical).
3452  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3453  * is exhausted and the system throws in that case (this exception
3454  * will not be thrown if the library has been installed using the
3455  * \--with-glib-memory-slices-no-compat configuration option: instead
3456  * glib will terminate the program if it is unable to obtain memory
3457  * from the operating system). It will also throw if the copy
3458  * constructor of a bound argument throws and it is not a reference
3459  * argument.
3460  */
3461 template <class... FreeArgs>
3462 CallbackArg<FreeArgs...>* make_val(const std::function<void(FreeArgs...)>& f) {
3463  return new Callback_function<FreeArgs...>{f};
3464 }
3465 
3466 /**
3467  * A convenience function to make Callback::Callback objects from
3468  * std::function objects. Since this function takes no bound argument
3469  * (and bound arguments are bound into the std::function object), it
3470  * is a synonym for make() (the two are identical).
3471  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3472  * is exhausted and the system throws in that case (this exception
3473  * will not be thrown if the library has been installed using the
3474  * \--with-glib-memory-slices-no-compat configuration option: instead
3475  * glib will terminate the program if it is unable to obtain memory
3476  * from the operating system). It will also throw if the copy
3477  * constructor of a bound argument throws and it is not a reference
3478  * argument.
3479  */
3480 template <class... FreeArgs>
3481 CallbackArg<FreeArgs...>* make_ref(const std::function<void(FreeArgs...)>& f) {
3482  return new Callback_function<FreeArgs...>{f};
3483 }
3484 
3485 /**
3486  * A convenience function to make Callback::CallbackArg objects from
3487  * std::function objects.
3488  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3489  * is exhausted and the system throws in that case (this exception
3490  * will not be thrown if the library has been installed using the
3491  * \--with-glib-memory-slices-no-compat configuration option: instead
3492  * glib will terminate the program if it is unable to obtain memory
3493  * from the operating system). It will also throw if the copy
3494  * constructor of a bound argument throws and it is not a reference
3495  * argument.
3496  */
3497 template <class... FreeArgs>
3498 CallbackArg<FreeArgs...>* make(std::function<void(FreeArgs...)>&& f) {
3499  return new Callback_function<FreeArgs...>{std::move(f)};
3500 }
3501 
3502 /**
3503  * DEPRECATED.
3504  *
3505  * A convenience function to make Callback::Callback objects from
3506  * std::function objects. Since this function takes no bound argument
3507  * (and bound arguments are bound into the std::function object), it
3508  * is a synonym for make() (the two are identical).
3509  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3510  * is exhausted and the system throws in that case (this exception
3511  * will not be thrown if the library has been installed using the
3512  * \--with-glib-memory-slices-no-compat configuration option: instead
3513  * glib will terminate the program if it is unable to obtain memory
3514  * from the operating system). It will also throw if the copy or move
3515  * constructor of a bound argument throws and it is not a reference
3516  * argument.
3517  */
3518 template <class... FreeArgs>
3519 CallbackArg<FreeArgs...>* make_val(std::function<void(FreeArgs...)>&& f) {
3520  return new Callback_function<FreeArgs...>{std::move(f)};
3521 }
3522 
3523 /**
3524  * A convenience function to make Callback::Callback objects from
3525  * std::function objects. Since this function takes no bound argument
3526  * (and bound arguments are bound into the std::function object), it
3527  * is a synonym for make() (the two are identical).
3528  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3529  * is exhausted and the system throws in that case (this exception
3530  * will not be thrown if the library has been installed using the
3531  * \--with-glib-memory-slices-no-compat configuration option: instead
3532  * glib will terminate the program if it is unable to obtain memory
3533  * from the operating system). It will also throw if the copy or move
3534  * constructor of a bound argument throws and it is not a reference
3535  * argument.
3536  */
3537 template <class... FreeArgs>
3538 CallbackArg<FreeArgs...>* make_ref(std::function<void(FreeArgs...)>&& f) {
3539  return new Callback_function<FreeArgs...>{std::move(f)};
3540 }
3541 
3542 // This helper function to construct Callback_lambda objects could be
3543 // implemented as a further overload of Callback::make(). No best
3544 // match ambiguities would arise, because even when Callback::make()
3545 // is passed a function pointer without bound arguments, the overload
3546 // of Callback::make taking a function pointer (as opposed to a
3547 // generic callable object) would still comprise the best match.
3548 // However, to construct Callback_lambda objects, the unbound
3549 // arguments need to be specified by hand, which doesn't happen with
3550 // Callback::make() (it would only be necessary to specify an explicit
3551 // type where a mutable reference argument is to be bound to the
3552 // callback object). It seems to me to be less confusing to the user
3553 // therefore to have a separate Callback::lambda() helper function.
3554 // However, if you disagree please let me know.
3555 
3556 // template parameter packs do not need to be placed last in the case
3557 // of function templates, as type deduction is available for the last
3558 // parameter: there is in fact no function parameter pack in
3559 // Callback::lambda() (function parameter packs must come last).
3560 /**
3561  * A convenience function to make Callback::CallbackArg objects from
3562  * C++11 lambda expressions, or from any other arbitrary callable
3563  * object. The types of the unbound arguments (if any) must be
3564  * explicitly specified as template parameters, as they cannot be
3565  * deduced. From version 2.0.10, this function can be called for
3566  * lambda expressions which are declared mutable (in version 2.0.9,
3567  * this function could only be called for non-mutable lambda
3568  * expressions). From version 2.0.16, this function can be passed
3569  * callable objects which are lvalues as well as rvalues (prior to
3570  * version 2.0.16, it could only be passed callable objects which are
3571  * rvalues).
3572  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3573  * is exhausted and the system throws in that case (this exception
3574  * will not be thrown if the library has been installed using the
3575  * \--with-glib-memory-slices-no-compat configuration option: instead
3576  * glib will terminate the program if it is unable to obtain memory
3577  * from the operating system). It will also throw if the copy or move
3578  * constructor of an object captured by the lambda expression throws.
3579  *
3580  * Since 2.0.9
3581  */
3582 template <class... FreeArgs, class Lambda>
3583 CallbackArg<FreeArgs...>* lambda(Lambda&& l) {
3584  typedef typename std::remove_const<typename std::remove_reference<Lambda>::type>::type LType;
3585  return new Callback_lambda<LType, FreeArgs...>{std::forward<Lambda>(l)};
3586 }
3587 
3588 } // namespace Callback
3589 
3590 class Releaser;
3591 
3592 namespace Callback {
3593 
3594 /**
3595  * Posts a callback for execution by a glib main loop. It is
3596  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
3597  * has been called. glib >= 2.32 does not require g_thread_init() to
3598  * be called. This function will not throw.
3599  * @param cb The callback object. Ownership is taken of this object,
3600  * and it will be deleted when it has been finished with.
3601  * @param priority The priority to be given to the callback in the
3602  * main loop. In ascending order of priorities, priorities are
3603  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
3604  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
3605  * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the
3606  * callback will appear in the event list in the main loop, not the
3607  * priority which the OS will adopt
3608  * @param context The glib main loop context in which the callback is
3609  * to be executed (the default of NULL will cause the callback to be
3610  * executed in the main program loop, and this is usually what is
3611  * wanted).
3612  * @note Cancellation of the receiving thread is blocked when the
3613  * callback executes.
3614  */
3615 void post(const Callback* cb, gint priority = G_PRIORITY_DEFAULT_IDLE,
3616  GMainContext* context = 0);
3617 
3618 /**
3619  * Posts a callback for execution by a glib main loop. It is
3620  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
3621  * has been called. glib >= 2.32 does not require g_thread_init() to
3622  * be called. This function will not throw.
3623  * @param cb The callback object. Ownership is taken of this object,
3624  * and it will be deleted when it has been finished with.
3625  * @param r A Releaser object for automatic disconnection of the
3626  * callback from the main loop.
3627  * @param priority The priority to be given to the callback in the
3628  * main loop. In ascending order of priorities, priorities are
3629  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
3630  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
3631  * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the
3632  * callback will appear in the event list in the main loop, not the
3633  * priority which the OS will adopt.
3634  * @param context The glib main loop context in which the callback is
3635  * to be executed (the default of NULL will cause the callback to be
3636  * executed in the main program loop, and this is usually what is
3637  * wanted).
3638  * @exception std::bad_alloc This function might throw std::bad_alloc
3639  * if memory is exhausted and the system throws in that case. If it
3640  * does so, the Callback object will be disposed of.
3641  * @exception Cgu::Thread::MutexError This method might throw
3642  * Cgu:Thread::MutexError if initialisation of the mutex in a
3643  * SafeEmitterArg object constructed by this method fails. If it does
3644  * so, the Callback object will be disposed of. (It is often not
3645  * worth checking for this exception, as it means either memory is
3646  * exhausted or pthread has run out of other resources to create new
3647  * mutexes.)
3648  * @note 1. Cancellation of the receiving thread is blocked when the
3649  * callback executes.
3650  * @note 2. By virtue of the Releaser object, it is in theory possible
3651  * (if memory is exhausted and the system throws in that case) that an
3652  * internal SafeEmitterArg object will throw std::bad_alloc when
3653  * emitting/executing the callback in the glib main loop, with the
3654  * result that the relevant callback will not execute (instead the
3655  * exception will be consumed and a g_critical() warning will be
3656  * issued). This is rarely of any relevance because glib will abort
3657  * the program if it is itself unable to obtain memory from the
3658  * operating system. However, where it is relevant, design the
3659  * program so that it is not necessary to provide a releaser object.
3660  */
3661 void post(const Callback* cb, Releaser& r,
3662  gint priority = G_PRIORITY_DEFAULT_IDLE, GMainContext* context = 0);
3663 
3664 } // namespace Callback
3665 
3666 } // namespace Cgu
3667 
3668 #endif