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