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, or as the
78  * continuation for GIO async operations.
79  *
80  * These classes are also used in the Emitter/EmitterArg classes in
81  * emitter.h, which enable callbacks to be connected to an emitter and
82  * provide for automatic disconnection where a class object whose
83  * member a callback represents ceases to exist.
84  *
85  * @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, or as the
624  * continuation for GIO async operations.
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 read this:
1205  * Callback
1206  */
1207 
1208 template <class... FreeArgs>
1209 class CallbackArg {
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 a
1223  * free or 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 function or class method referenced by the
1442  * callback encapsulated by this object, or do nothing if this object
1443  * has not been initialized with a callback. It will only throw if
1444  * the executed function or class method throws, or if the copy
1445  * constructor of a free or bound argument throws and it is not a
1446  * reference argument. It is thread safe if the referenced function
1447  * or class method is thread safe.
1448  * @param args The unbound arguments to be passed to the referenced
1449  * function or class method, if any.
1450  */
1451  void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const {
1452  if (cb_s.get()) cb_s->dispatch(args...);
1453  }
1454 
1455 /**
1456  * This function does not throw.
1457  * @param f The assignor.
1458  * @return The functor object after assignment.
1459  */
1460  FunctorArg& operator=(const FunctorArg& f) {cb_s = f.cb_s; return *this;}
1461 
1462 /**
1463  * This function does not throw.
1464  * @param f The functor to be moved.
1465  * @return The functor object after the move operation.
1466  */
1467  FunctorArg& operator=(FunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;}
1468 
1469 /**
1470  * Two FunctorArg objects compare equal if the addresses of the
1471  * CallbackArg objects they contain are the same. This comparison
1472  * operator does not throw.
1473  */
1474  friend bool operator== <>(const FunctorArg&, const FunctorArg&);
1475 
1476 /**
1477  * One FunctorArg object is less than another if the address of the
1478  * CallbackArg object contained by the first is regarded by std::less
1479  * as less than the address of the CallbackArg object contained by the
1480  * other. This comparison operator does not throw.
1481  */
1482  friend bool operator< <>(const FunctorArg&, const FunctorArg&);
1483 
1484  friend struct std::hash<FunctorArg>;
1485 
1486 /**
1487  * Constructor of first FunctorArg holding the referenced callback.
1488  * As it is not marked explicit, it is also a type conversion
1489  * constructor.
1490  * @param cb The CallbackArg object which the functor is to manage.
1491  * @exception std::bad_alloc This might throw std::bad_alloc if
1492  * memory is exhausted and the system throws in that case. Note that
1493  * if such an exception is thrown, then this constructor will clean
1494  * itself up and also delete the callback object passed to it.
1495  * @note std::bad_alloc will not be thrown if the library has been
1496  * installed using the --with-glib-memory-slices-no-compat
1497  * configuration option: instead glib will terminate the program if it
1498  * is unable to obtain memory from the operating system.
1499  */
1500  FunctorArg(const CallbackArg<FreeArgs...>* cb): cb_s(cb) {}
1501 
1502 /**
1503  * The copy constructor does not throw.
1504  * @param f The assignor
1505  */
1506  FunctorArg(const FunctorArg& f): cb_s(f.cb_s) {}
1507 
1508 /**
1509  * The move constructor does not throw.
1510  * @param f The functor to be moved.
1511  */
1512  FunctorArg(FunctorArg&& f): cb_s(std::move(f.cb_s)) {}
1513 
1514  /**
1515  * Default constructor, where a Callback::CallbackArg object is to be
1516  * assigned later (via the type conversion constructor and/or the
1517  * assignment operator). This constructor does not throw.
1518  */
1520 
1521 /* Only has effect if --with-glib-memory-slices-compat or
1522  --with-glib-memory-slices-no-compat option picked */
1524 };
1525 
1526 /**
1527  * @class SafeFunctorArg callback.h c++-gtk-utils/callback.h
1528  * @brief Functor class holding a Callback::CallbackArg object, with
1529  * thread-safe reference count.
1530  * @sa FunctorArg
1531  * @sa Callback namespace
1532  *
1533  * This class is the same as Callback::FunctorArg except that it will
1534  * provide synchronisation of the reference count between threads.
1535  * Use it where a functor wrapper object is to be passed between
1536  * threads. The FunctorArg documentation gives details on usage.
1537  *
1538  * Callback::SafeFunctorArg<> is typedef'ed to Callback::SafeFunctor.
1539  *
1540  * For further background, read this: Callback
1541  */
1542 
1543 template <class... FreeArgs>
1544 class SafeFunctorArg {
1545  SharedLockPtr<const CallbackArg<FreeArgs...>> cb_s;
1546 public:
1547 /**
1548  * This will execute the function or class method referenced by the
1549  * callback encapsulated by this object, or do nothing if this object
1550  * has not been initialized with a callback. It will only throw if
1551  * the executed function or class method throws, or if the copy
1552  * constructor of a free or bound argument throws and it is not a
1553  * reference argument. It is thread safe if the referenced function
1554  * or class method is thread safe.
1555  * @param args The unbound arguments to be passed to the referenced
1556  * function or class method, if any.
1557  */
1558  void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const {
1559  if (cb_s.get()) cb_s->dispatch(args...);
1560  }
1561 
1562 /**
1563  * This function does not throw.
1564  * @param f The assignor.
1565  * @return The functor object after assignment.
1566  */
1567  SafeFunctorArg& operator=(const SafeFunctorArg& f) {cb_s = f.cb_s; return *this;}
1568 
1569 /**
1570  * This function does not throw.
1571  * @param f The functor to be moved.
1572  * @return The functor object after the move operation.
1573  */
1574  SafeFunctorArg& operator=(SafeFunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;}
1575 
1576 /**
1577  * Two SafeFunctorArg objects compare equal if the addresses of the
1578  * CallbackArg objects they contain are the same. This comparison
1579  * operator does not throw.
1580  */
1581  friend bool operator== <>(const SafeFunctorArg&, const SafeFunctorArg&);
1582 
1583 /**
1584  * One SafeFunctorArg object is less than another if the address of
1585  * the CallbackArg object contained by the first is regarded by
1586  * std::less as less than the address of the CallbackArg object
1587  * contained by the other. This comparison operator does not throw.
1588  */
1589  friend bool operator< <>(const SafeFunctorArg&, const SafeFunctorArg&);
1590 
1591  friend struct std::hash<SafeFunctorArg>;
1592 
1593  /**
1594  * Constructor of first SafeFunctorArg holding the referenced
1595  * callback. As it is not marked explicit, it is also a type
1596  * conversion constructor.
1597  * @param cb The CallbackArg object which the functor is to manage.
1598  * @exception std::bad_alloc This might throw std::bad_alloc if
1599  * memory is exhausted and the system throws in that case. Note that
1600  * if such an exception is thrown, then this constructor will clean
1601  * itself up and also delete the callback object passed to it.
1602  * @note std::bad_alloc will not be thrown if the library has been
1603  * installed using the --with-glib-memory-slices-no-compat
1604  * configuration option: instead glib will terminate the program if it
1605  * is unable to obtain memory from the operating system.
1606  */
1608 
1609 /**
1610  * The copy constructor does not throw.
1611  * @param f The assignor.
1612  */
1613  SafeFunctorArg(const SafeFunctorArg& f): cb_s(f.cb_s) {}
1614 
1615 /**
1616  * The move constructor does not throw.
1617  * @param f The functor to be moved.
1618  */
1619  SafeFunctorArg(SafeFunctorArg&& f): cb_s(std::move(f.cb_s)) {}
1620 
1621  /**
1622  * Default constructor, where a Callback::CallbackArg object is to be
1623  * assigned later (via the type conversion constructor and/or the
1624  * assignment operator). This constructor does not throw.
1625  * @note The reference count maintained with respect to the contained
1626  * callback object is thread-safe, so SafeFunctorArg objects may be
1627  * copied between threads by the implicit assignment operator and put
1628  * in different containers in different threads. They use a
1629  * SharedLockPtr object to hold the referenced callback object.
1630  */
1632 
1633 /* Only has effect if --with-glib-memory-slices-compat or
1634  --with-glib-memory-slices-no-compat option picked */
1636 };
1637 
1638 /* the callback implementation classes */
1639 
1640 template <class T, class... FreeArgs>
1641 class Callback0: public CallbackArg<FreeArgs...> {
1642 public:
1643  typedef void (T::* MemFunc)(FreeArgs...);
1644 private:
1645  T* obj;
1646  MemFunc func;
1647 public:
1648  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1649  (obj->*func)(free_args...);
1650  }
1651  Callback0(T& obj_, MemFunc func_): obj(&obj_), func(func_) {}
1652 };
1653 
1654 template <bool unref, class T, class BoundArg, class... FreeArgs>
1655 class Callback1: public CallbackArg<FreeArgs...> {
1656 public:
1657  typedef void (T::* MemFunc)(BoundArg, FreeArgs...);
1658 private:
1659  T* obj;
1660  MemFunc func;
1662 public:
1663  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1664  (obj->*func)(arg, free_args...);
1665  }
1666  template <class Arg>
1667  Callback1(T& obj_, MemFunc func_,
1668  Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {}
1669 };
1670 
1671 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs>
1672 class Callback2: public CallbackArg<FreeArgs...> {
1673 public:
1674  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...);
1675 private:
1676  T* obj;
1677  MemFunc func;
1680 public:
1681  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1682  (obj->*func)(arg1, arg2, free_args...);
1683  }
1684  template <class Arg1, class Arg2>
1685  Callback2(T& obj_, MemFunc func_,
1686  Arg1&& arg1_,
1687  Arg2&& arg2_): obj(&obj_), func(func_),
1688  arg1(std::forward<Arg1>(arg1_)),
1689  arg2(std::forward<Arg2>(arg2_)) {}
1690 };
1691 
1692 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1693 class Callback3: public CallbackArg<FreeArgs...> {
1694 public:
1695  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...);
1696 private:
1697  T* obj;
1698  MemFunc func;
1702 public:
1703  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1704  (obj->*func)(arg1, arg2, arg3, free_args...);
1705  }
1706  template <class Arg1, class Arg2, class Arg3>
1707  Callback3(T& obj_, MemFunc func_,
1708  Arg1&& arg1_,
1709  Arg2&& arg2_,
1710  Arg3&& arg3_):
1711  obj(&obj_), func(func_),
1712  arg1(std::forward<Arg1>(arg1_)),
1713  arg2(std::forward<Arg2>(arg2_)),
1714  arg3(std::forward<Arg3>(arg3_)) {}
1715 };
1716 
1717 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1718  class BoundArg4, class... FreeArgs>
1719 class Callback4: public CallbackArg<FreeArgs...> {
1720 public:
1721  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...);
1722 private:
1723  T* obj;
1724  MemFunc func;
1729 public:
1730  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1731  (obj->*func)(arg1, arg2, arg3, arg4, free_args...);
1732  }
1733  template <class Arg1, class Arg2, class Arg3, class Arg4>
1734  Callback4(T& obj_, MemFunc func_,
1735  Arg1&& arg1_,
1736  Arg2&& arg2_,
1737  Arg3&& arg3_,
1738  Arg4&& arg4_):
1739  obj(&obj_), func(func_),
1740  arg1(std::forward<Arg1>(arg1_)),
1741  arg2(std::forward<Arg2>(arg2_)),
1742  arg3(std::forward<Arg3>(arg3_)),
1743  arg4(std::forward<Arg4>(arg4_)) {}
1744 };
1745 
1746 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1747  class BoundArg4, class BoundArg5, class... FreeArgs>
1748 class Callback5: public CallbackArg<FreeArgs...> {
1749 public:
1750  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3,
1751  BoundArg4, BoundArg5, FreeArgs...);
1752 private:
1753  T* obj;
1754  MemFunc func;
1760 public:
1761  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1762  (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...);
1763  }
1764  template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
1765  Callback5(T& obj_, MemFunc func_,
1766  Arg1&& arg1_,
1767  Arg2&& arg2_,
1768  Arg3&& arg3_,
1769  Arg4&& arg4_,
1770  Arg5&& arg5_):
1771  obj(&obj_), func(func_),
1772  arg1(std::forward<Arg1>(arg1_)),
1773  arg2(std::forward<Arg2>(arg2_)),
1774  arg3(std::forward<Arg3>(arg3_)),
1775  arg4(std::forward<Arg4>(arg4_)),
1776  arg5(std::forward<Arg5>(arg5_)) {}
1777 };
1778 
1779 /* const versions, for binding to const methods */
1780 
1781 template <class T, class... FreeArgs>
1782 class Callback0_const: public CallbackArg<FreeArgs...> {
1783 public:
1784  typedef void (T::* MemFunc)(FreeArgs...) const;
1785 private:
1786  const T* obj;
1787  MemFunc func;
1788 public:
1789  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1790  (obj->*func)(free_args...);
1791  }
1792  Callback0_const(const T& obj_, MemFunc func_): obj(&obj_), func(func_) {}
1793 };
1794 
1795 template <bool unref, class T, class BoundArg, class... FreeArgs>
1796 class Callback1_const: public CallbackArg<FreeArgs...> {
1797 public:
1798  typedef void (T::* MemFunc)(BoundArg, FreeArgs...) const;
1799 private:
1800  const T* obj;
1801  MemFunc func;
1803 public:
1804  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1805  (obj->*func)(arg, free_args...);
1806  }
1807  template <class Arg>
1808  Callback1_const(const T& obj_, MemFunc func_,
1809  Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {}
1810 };
1811 
1812 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs>
1813 class Callback2_const: public CallbackArg<FreeArgs...> {
1814 public:
1815  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...) const;
1816 private:
1817  const T* obj;
1818  MemFunc func;
1821 public:
1822  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1823  (obj->*func)(arg1, arg2, free_args...);
1824  }
1825  template <class Arg1, class Arg2>
1826  Callback2_const(const T& obj_, MemFunc func_,
1827  Arg1&& arg1_,
1828  Arg2&& arg2_): obj(&obj_), func(func_),
1829  arg1(std::forward<Arg1>(arg1_)),
1830  arg2(std::forward<Arg2>(arg2_)) {}
1831 };
1832 
1833 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1834 class Callback3_const: public CallbackArg<FreeArgs...> {
1835 public:
1836  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const;
1837 private:
1838  const T* obj;
1839  MemFunc func;
1843 public:
1844  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1845  (obj->*func)(arg1, arg2, arg3, free_args...);
1846  }
1847  template <class Arg1, class Arg2, class Arg3>
1848  Callback3_const(const T& obj_, MemFunc func_,
1849  Arg1&& arg1_,
1850  Arg2&& arg2_,
1851  Arg3&& arg3_):
1852  obj(&obj_), func(func_),
1853  arg1(std::forward<Arg1>(arg1_)),
1854  arg2(std::forward<Arg2>(arg2_)),
1855  arg3(std::forward<Arg3>(arg3_)) {}
1856 };
1857 
1858 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1859  class BoundArg4, class... FreeArgs>
1860 class Callback4_const: public CallbackArg<FreeArgs...> {
1861 public:
1862  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const;
1863 private:
1864  const T* obj;
1865  MemFunc func;
1870 public:
1871  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1872  (obj->*func)(arg1, arg2, arg3, arg4, free_args...);
1873  }
1874  template <class Arg1, class Arg2, class Arg3, class Arg4>
1875  Callback4_const(const T& obj_, MemFunc func_,
1876  Arg1&& arg1_,
1877  Arg2&& arg2_,
1878  Arg3&& arg3_,
1879  Arg4&& arg4_):
1880  obj(&obj_), func(func_),
1881  arg1(std::forward<Arg1>(arg1_)),
1882  arg2(std::forward<Arg2>(arg2_)),
1883  arg3(std::forward<Arg3>(arg3_)),
1884  arg4(std::forward<Arg4>(arg4_)) {}
1885 };
1886 
1887 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1888  class BoundArg4, class BoundArg5, class... FreeArgs>
1889 class Callback5_const: public CallbackArg<FreeArgs...> {
1890 public:
1891  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3,
1892  BoundArg4, BoundArg5, FreeArgs...) const;
1893 private:
1894  const T* obj;
1895  MemFunc func;
1901 public:
1902  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1903  (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...);
1904  }
1905  template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
1906  Callback5_const(const T& obj_, MemFunc func_,
1907  Arg1&& arg1_,
1908  Arg2&& arg2_,
1909  Arg3&& arg3_,
1910  Arg4&& arg4_,
1911  Arg5&& arg5_):
1912  obj(&obj_), func(func_),
1913  arg1(std::forward<Arg1>(arg1_)),
1914  arg2(std::forward<Arg2>(arg2_)),
1915  arg3(std::forward<Arg3>(arg3_)),
1916  arg4(std::forward<Arg4>(arg4_)),
1917  arg5(std::forward<Arg5>(arg5_)) {}
1918 };
1919 
1920 /* for static class methods and non-class functions */
1921 
1922 template <class... FreeArgs>
1923 class Callback0_static: public CallbackArg<FreeArgs...> {
1924 public:
1925  typedef void (*Func)(FreeArgs...);
1926 private:
1927  Func func;
1928 public:
1929  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1930  func(free_args...);
1931  }
1932  Callback0_static(Func func_): func(func_) {}
1933 };
1934 
1935 template <bool unref, class BoundArg, class... FreeArgs>
1936 class Callback1_static: public CallbackArg<FreeArgs...> {
1937 public:
1938  typedef void (*Func)(BoundArg, FreeArgs...);
1939 private:
1940  Func func;
1942 public:
1943  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1944  func(arg, free_args...);
1945  }
1946  template <class Arg>
1947  Callback1_static(Func func_, Arg&& arg_): func(func_), arg(std::forward<Arg>(arg_)) {}
1948 };
1949 
1950 template <bool unref, class BoundArg1, class BoundArg2, class... FreeArgs>
1951 class Callback2_static: public CallbackArg<FreeArgs...> {
1952 public:
1953  typedef void (*Func)(BoundArg1, BoundArg2, FreeArgs...);
1954 private:
1955  Func func;
1958 public:
1959  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1960  func(arg1, arg2, free_args...);
1961  }
1962  template <class Arg1, class Arg2>
1963  Callback2_static(Func func_, Arg1&& arg1_,
1964  Arg2&& arg2_): func(func_),
1965  arg1(std::forward<Arg1>(arg1_)),
1966  arg2(std::forward<Arg2>(arg2_)) {}
1967 };
1968 
1969 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1970 class Callback3_static: public CallbackArg<FreeArgs...> {
1971 public:
1972  typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...);
1973 private:
1974  Func func;
1978 public:
1979  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1980  func(arg1, arg2, arg3, free_args...);
1981  }
1982  template <class Arg1, class Arg2, class Arg3>
1984  Arg1&& arg1_,
1985  Arg2&& arg2_,
1986  Arg3&& arg3_):
1987  func(func_),
1988  arg1(std::forward<Arg1>(arg1_)),
1989  arg2(std::forward<Arg2>(arg2_)),
1990  arg3(std::forward<Arg3>(arg3_)) {}
1991 };
1992 
1993 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3,
1994  class BoundArg4, class... FreeArgs>
1995 class Callback4_static: public CallbackArg<FreeArgs...> {
1996 public:
1997  typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...);
1998 private:
1999  Func func;
2004 public:
2005  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
2006  func(arg1, arg2, arg3, arg4, free_args...);
2007  }
2008  template <class Arg1, class Arg2, class Arg3, class Arg4>
2010  Arg1&& arg1_,
2011  Arg2&& arg2_,
2012  Arg3&& arg3_,
2013  Arg4&& arg4_):
2014  func(func_),
2015  arg1(std::forward<Arg1>(arg1_)),
2016  arg2(std::forward<Arg2>(arg2_)),
2017  arg3(std::forward<Arg3>(arg3_)),
2018  arg4(std::forward<Arg4>(arg4_)) {}
2019 };
2020 
2021 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3,
2022  class BoundArg4, class BoundArg5, class... FreeArgs>
2023 class Callback5_static: public CallbackArg<FreeArgs...> {
2024 public:
2025  typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3,
2026  BoundArg4, BoundArg5, FreeArgs...);
2027 private:
2028  Func func;
2034 public:
2035  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
2036  func(arg1, arg2, arg3, arg4, arg5, free_args...);
2037  }
2038  template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
2040  Arg1&& arg1_,
2041  Arg2&& arg2_,
2042  Arg3&& arg3_,
2043  Arg4&& arg4_,
2044  Arg5&& arg5_):
2045  func(func_),
2046  arg1(std::forward<Arg1>(arg1_)),
2047  arg2(std::forward<Arg2>(arg2_)),
2048  arg3(std::forward<Arg3>(arg3_)),
2049  arg4(std::forward<Arg4>(arg4_)),
2050  arg5(std::forward<Arg5>(arg5_)) {}
2051 };
2052 
2053 // TODO: Version 2.0.9 provides a Callback_lambda class for callable
2054 // objects which makes the specialized Callback_function class
2055 // redundant. At an API break we can remove the Callback_function
2056 // class and modify the Callback::make() helper function overload for
2057 // std::function objects to construct a Callback_lambda object
2058 // instead. Doing it now would not affect ABI compatibility as the
2059 // library produces these only by base pointer, but a user may have
2060 // instantiated them by hand in user code.
2061 template <class... FreeArgs>
2062 class Callback_function: public CallbackArg<FreeArgs...> {
2063  std::function<void(FreeArgs...)> f;
2064 public:
2065  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {f(free_args...);}
2066  Callback_function(const std::function<void(FreeArgs...)>& f_): f(f_) {}
2067  Callback_function(std::function<void(FreeArgs...)>&& f_): f(std::move(f_)) {}
2068 };
2069 
2070 // generic class for callable objects such as lambdas
2071 template <class Lambda, class... FreeArgs>
2072 class Callback_lambda: public CallbackArg<FreeArgs...> {
2073  // making 'l' mutable means that Callback_lamdba objects can contain
2074  // mutable lambda expressions
2075  mutable Lambda l;
2076 public:
2077  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {l(free_args...);}
2078  template <class L> Callback_lambda(L&& l_): l(std::forward<L>(l_)) {}
2079 };
2080 
2081 /* Convenience functions making callback objects on freestore. These
2082  * can for example be passed as the first argument of the
2083  * Thread::start() method in thread.h. They are also used by the
2084  * Callback::post() function.
2085 */
2086 
2087 /**
2088  * A convenience function to make Callback::CallbackArg objects
2089  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2090  * is exhausted and the system throws in that case. This exception
2091  * will not be thrown if the library has been installed using the
2092  * --with-glib-memory-slices-no-compat configuration option (instead
2093  * glib will terminate the program if it is unable to obtain memory
2094  * from the operating system).
2095  */
2096 template <class T, class... FreeArgs>
2097 CallbackArg<FreeArgs...>* make(T& t,
2098  void (T::*func)(FreeArgs...)) {
2099  return new Callback0<T, FreeArgs...>{t, func};
2100 }
2101 
2102 /**
2103  * DEPRECATED.
2104  *
2105  * Since this function constructs a callback which does not take a
2106  * bound argument, it is a synonym for make() (the two are identical).
2107  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2108  * is exhausted and the system throws in that case. This exception
2109  * will not be thrown if the library has been installed using the
2110  * --with-glib-memory-slices-no-compat configuration option (instead
2111  * glib will terminate the program if it is unable to obtain memory
2112  * from the operating system).
2113  */
2114 template <class T, class... FreeArgs>
2115 CallbackArg<FreeArgs...>* make_val(T& t,
2116  void (T::*func)(FreeArgs...)) {
2117  return new Callback0<T, FreeArgs...>{t, func};
2118 }
2119 
2120 /**
2121  * Since this function constructs a callback which does not take a
2122  * bound argument, it is a synonym for make() (the two are identical).
2123  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2124  * is exhausted and the system throws in that case. This exception
2125  * will not be thrown if the library has been installed using the
2126  * --with-glib-memory-slices-no-compat configuration option (instead
2127  * glib will terminate the program if it is unable to obtain memory
2128  * from the operating system).
2129  *
2130  * Since 2.0.0-rc3
2131  */
2132 template <class T, class... FreeArgs>
2133 CallbackArg<FreeArgs...>* make_ref(T& t,
2134  void (T::*func)(FreeArgs...)) {
2135  return new Callback0<T, FreeArgs...>{t, func};
2136 }
2137 
2138 /**
2139  * A convenience function to make Callback::CallbackArg objects
2140  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2141  * is exhausted and the system throws in that case (this exception
2142  * will not be thrown if the library has been installed using the
2143  * --with-glib-memory-slices-no-compat configuration option: instead
2144  * glib will terminate the program if it is unable to obtain memory
2145  * from the operating system). It will also throw if the copy
2146  * constructor of a bound argument throws and it is not a reference
2147  * argument.
2148  */
2149 template <class T, class BoundArg, class... FreeArgs>
2150 CallbackArg<FreeArgs...>* make(T& t,
2151  void (T::*func)(BoundArg, FreeArgs...),
2152  BoundArg arg) {
2153  return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg};
2154 }
2155 
2156 /**
2157  * DEPRECATED: use Callback::make_ref() instead.
2158  *
2159  * An alternative function to make Callback::CallbackArg objects,
2160  * which is for use where a target function receives an argument of
2161  * class type by value which is to be a bound argument, so the
2162  * compiler is not able to carry out copy elision when constructing
2163  * the callback object.
2164  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2165  * is exhausted and the system throws in that case (this exception
2166  * will not be thrown if the library has been installed using the
2167  * --with-glib-memory-slices-no-compat configuration option: instead
2168  * glib will terminate the program if it is unable to obtain memory
2169  * from the operating system). It will also throw if the copy
2170  * constructor of a bound argument throws and it is not a reference
2171  * argument.
2172  */
2173 template <class T, class BoundArg, class... FreeArgs>
2174 CallbackArg<FreeArgs...>* make_val(T& t,
2175  void (T::*func)(BoundArg, FreeArgs...),
2176  const BoundArg& arg) {
2177  return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg};
2178 }
2179 
2180 /**
2181  * An alternative function to make Callback::CallbackArg objects,
2182  * which is for use where a target function either receives a class
2183  * type bound argument by value, or receives a bound argument by
2184  * reference to const in a case where the generated CallbackArg object
2185  * is to store a copy of that argument instead of just keeping a
2186  * reference.
2187  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2188  * is exhausted and the system throws in that case (this exception
2189  * will not be thrown if the library has been installed using the
2190  * --with-glib-memory-slices-no-compat configuration option: instead
2191  * glib will terminate the program if it is unable to obtain memory
2192  * from the operating system). It will also throw if the copy or move
2193  * constructor of a bound argument throws and it is not a reference
2194  * argument.
2195  *
2196  * Since 2.0.0-rc3
2197  */
2198 template <class T, class BoundArg, class Arg, class... FreeArgs>
2199 CallbackArg<FreeArgs...>* make_ref(T& t,
2200  void (T::*func)(BoundArg, FreeArgs...),
2201  Arg&& arg) {
2202  return new Callback1<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)};
2203 }
2204 
2205 /**
2206  * A convenience function to make Callback::CallbackArg objects
2207  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2208  * is exhausted and the system throws in that case (this exception
2209  * will not be thrown if the library has been installed using the
2210  * --with-glib-memory-slices-no-compat configuration option: instead
2211  * glib will terminate the program if it is unable to obtain memory
2212  * from the operating system). It will also throw if the copy
2213  * constructor of a bound argument throws and it is not a reference
2214  * argument.
2215  */
2216 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2217 CallbackArg<FreeArgs...>* make(T& t,
2218  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
2219  BoundArg1 arg1,
2220  BoundArg2 arg2) {
2221  return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2222 }
2223 
2224 /**
2225  * DEPRECATED: use Callback::make_ref() instead.
2226  *
2227  * An alternative function to make Callback::CallbackArg objects,
2228  * which is for use where a target function receives an argument of
2229  * class type by value which is to be a bound argument, so the
2230  * compiler is not able to carry out copy elision when constructing
2231  * the callback object.
2232  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2233  * is exhausted and the system throws in that case (this exception
2234  * will not be thrown if the library has been installed using the
2235  * --with-glib-memory-slices-no-compat configuration option: instead
2236  * glib will terminate the program if it is unable to obtain memory
2237  * from the operating system). It will also throw if the copy
2238  * constructor of a bound argument throws and it is not a reference
2239  * argument.
2240  */
2241 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2242 CallbackArg<FreeArgs...>* make_val(T& t,
2243  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
2244  const BoundArg1& arg1,
2245  const BoundArg2& arg2) {
2246  return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2247 }
2248 
2249 /**
2250  * An alternative function to make Callback::CallbackArg objects,
2251  * which is for use where a target function either receives a class
2252  * type bound argument by value, or receives a bound argument by
2253  * reference to const in a case where the generated CallbackArg object
2254  * is to store a copy of that argument instead of just keeping a
2255  * reference.
2256  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2257  * is exhausted and the system throws in that case (this exception
2258  * will not be thrown if the library has been installed using the
2259  * --with-glib-memory-slices-no-compat configuration option: instead
2260  * glib will terminate the program if it is unable to obtain memory
2261  * from the operating system). It will also throw if the copy or move
2262  * constructor of a bound argument throws and it is not a reference
2263  * argument.
2264  *
2265  * Since 2.0.0-rc3
2266  */
2267 template <class T, class BoundArg1, class BoundArg2,
2268  class Arg1, class Arg2, class... FreeArgs>
2269 CallbackArg<FreeArgs...>* make_ref(T& t,
2270  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
2271  Arg1&& arg1,
2272  Arg2&& arg2) {
2273  return new Callback2<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func,
2274  std::forward<Arg1>(arg1),
2275  std::forward<Arg2>(arg2)};
2276 }
2277 
2278 /**
2279  * A convenience function to make Callback::CallbackArg objects
2280  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2281  * is exhausted and the system throws in that case (this exception
2282  * will not be thrown if the library has been installed using the
2283  * --with-glib-memory-slices-no-compat configuration option: instead
2284  * glib will terminate the program if it is unable to obtain memory
2285  * from the operating system). It will also throw if the copy
2286  * constructor of a bound argument throws and it is not a reference
2287  * argument.
2288  */
2289 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2290 CallbackArg<FreeArgs...>* make(T& t,
2291  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2292  BoundArg1 arg1,
2293  BoundArg2 arg2,
2294  BoundArg3 arg3) {
2295  return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2296 }
2297 
2298 /**
2299  * DEPRECATED: use Callback::make_ref() instead.
2300  *
2301  * An alternative function to make Callback::CallbackArg objects,
2302  * which is for use where a target function receives an argument of
2303  * class type by value which is to be a bound argument, so the
2304  * compiler is not able to carry out copy elision when constructing
2305  * the callback object.
2306  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2307  * is exhausted and the system throws in that case (this exception
2308  * will not be thrown if the library has been installed using the
2309  * --with-glib-memory-slices-no-compat configuration option: instead
2310  * glib will terminate the program if it is unable to obtain memory
2311  * from the operating system). It will also throw if the copy
2312  * constructor of a bound argument throws and it is not a reference
2313  * argument.
2314  */
2315 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2316 CallbackArg<FreeArgs...>* make_val(T& t,
2317  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2318  const BoundArg1& arg1,
2319  const BoundArg2& arg2,
2320  const BoundArg3& arg3) {
2321  return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2322 }
2323 
2324 /**
2325  * An alternative function to make Callback::CallbackArg objects,
2326  * which is for use where a target function either receives a class
2327  * type bound argument by value, or receives a bound argument by
2328  * reference to const in a case where the generated CallbackArg object
2329  * is to store a copy of that argument instead of just keeping a
2330  * reference.
2331  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2332  * is exhausted and the system throws in that case (this exception
2333  * will not be thrown if the library has been installed using the
2334  * --with-glib-memory-slices-no-compat configuration option: instead
2335  * glib will terminate the program if it is unable to obtain memory
2336  * from the operating system). It will also throw if the copy or move
2337  * constructor of a bound argument throws and it is not a reference
2338  * argument.
2339  *
2340  * Since 2.0.0-rc3
2341  */
2342 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2343  class Arg1, class Arg2, class Arg3, class... FreeArgs>
2344 CallbackArg<FreeArgs...>* make_ref(T& t,
2345  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2346  Arg1&& arg1,
2347  Arg2&& arg2,
2348  Arg3&& arg3) {
2349  return new Callback3<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func,
2350  std::forward<Arg1>(arg1),
2351  std::forward<Arg2>(arg2),
2352  std::forward<Arg3>(arg3)};
2353 }
2354 
2355 /**
2356  * A convenience function to make Callback::CallbackArg objects
2357  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2358  * is exhausted and the system throws in that case (this exception
2359  * will not be thrown if the library has been installed using the
2360  * --with-glib-memory-slices-no-compat configuration option: instead
2361  * glib will terminate the program if it is unable to obtain memory
2362  * from the operating system). It will also throw if the copy
2363  * constructor of a bound argument throws and it is not a reference
2364  * argument.
2365  */
2366 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2367  class BoundArg4, class... FreeArgs>
2368 CallbackArg<FreeArgs...>* make(T& t,
2369  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2370  BoundArg4, FreeArgs...),
2371  BoundArg1 arg1,
2372  BoundArg2 arg2,
2373  BoundArg3 arg3,
2374  BoundArg4 arg4) {
2375  return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3,
2376  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2377 }
2378 
2379 /**
2380  * DEPRECATED: use Callback::make_ref() instead.
2381  *
2382  * An alternative function to make Callback::CallbackArg objects,
2383  * which is for use where a target function receives an argument of
2384  * class type by value which is to be a bound argument, so the
2385  * compiler is not able to carry out copy elision when constructing
2386  * the callback object.
2387  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2388  * is exhausted and the system throws in that case (this exception
2389  * will not be thrown if the library has been installed using the
2390  * --with-glib-memory-slices-no-compat configuration option: instead
2391  * glib will terminate the program if it is unable to obtain memory
2392  * from the operating system). It will also throw if the copy
2393  * constructor of a bound argument throws and it is not a reference
2394  * argument.
2395  */
2396 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2397  class BoundArg4, class... FreeArgs>
2398 CallbackArg<FreeArgs...>* make_val(T& t,
2399  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2400  BoundArg4, FreeArgs...),
2401  const BoundArg1& arg1,
2402  const BoundArg2& arg2,
2403  const BoundArg3& arg3,
2404  const BoundArg4& arg4) {
2405  return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3,
2406  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2407 }
2408 
2409 /**
2410  * An alternative function to make Callback::CallbackArg objects,
2411  * which is for use where a target function either receives a class
2412  * type bound argument by value, or receives a bound argument by
2413  * reference to const in a case where the generated CallbackArg object
2414  * is to store a copy of that argument instead of just keeping a
2415  * reference.
2416  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2417  * is exhausted and the system throws in that case (this exception
2418  * will not be thrown if the library has been installed using the
2419  * --with-glib-memory-slices-no-compat configuration option: instead
2420  * glib will terminate the program if it is unable to obtain memory
2421  * from the operating system). It will also throw if the copy or move
2422  * constructor of a bound argument throws and it is not a reference
2423  * argument.
2424  *
2425  * Since 2.0.0-rc3
2426  */
2427 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
2428  class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
2429 CallbackArg<FreeArgs...>* make_ref(T& t,
2430  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2431  BoundArg4, FreeArgs...),
2432  Arg1&& arg1,
2433  Arg2&& arg2,
2434  Arg3&& arg3,
2435  Arg4&& arg4) {
2436  return new Callback4<true, T, BoundArg1, BoundArg2, BoundArg3,
2437  BoundArg4, FreeArgs...>{t, func,
2438  std::forward<Arg1>(arg1),
2439  std::forward<Arg2>(arg2),
2440  std::forward<Arg3>(arg3),
2441  std::forward<Arg4>(arg4)};
2442 }
2443 
2444 /**
2445  * A convenience function to make Callback::CallbackArg objects
2446  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2447  * is exhausted and the system throws in that case (this exception
2448  * will not be thrown if the library has been installed using the
2449  * --with-glib-memory-slices-no-compat configuration option: instead
2450  * glib will terminate the program if it is unable to obtain memory
2451  * from the operating system). It will also throw if the copy
2452  * constructor of a bound argument throws and it is not a reference
2453  * argument.
2454  */
2455 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2456  class BoundArg4, class BoundArg5, class... FreeArgs>
2457 CallbackArg<FreeArgs...>* make(T& t,
2458  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2459  BoundArg4, BoundArg5, FreeArgs...),
2460  BoundArg1 arg1,
2461  BoundArg2 arg2,
2462  BoundArg3 arg3,
2463  BoundArg4 arg4,
2464  BoundArg5 arg5) {
2465  return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3,
2466  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2467 }
2468 
2469 /**
2470  * DEPRECATED: use Callback::make_ref() instead.
2471  *
2472  * An alternative function to make Callback::CallbackArg objects,
2473  * which is for use where a target function receives an argument of
2474  * class type by value which is to be a bound argument, so the
2475  * compiler is not able to carry out copy elision when constructing
2476  * the callback object.
2477  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2478  * is exhausted and the system throws in that case (this exception
2479  * will not be thrown if the library has been installed using the
2480  * --with-glib-memory-slices-no-compat configuration option: instead
2481  * glib will terminate the program if it is unable to obtain memory
2482  * from the operating system). It will also throw if the copy
2483  * constructor of a bound argument throws and it is not a reference
2484  * argument.
2485  */
2486 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2487  class BoundArg4, class BoundArg5, class... FreeArgs>
2488 CallbackArg<FreeArgs...>* make_val(T& t,
2489  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2490  BoundArg4, BoundArg5, FreeArgs...),
2491  const BoundArg1& arg1,
2492  const BoundArg2& arg2,
2493  const BoundArg3& arg3,
2494  const BoundArg4& arg4,
2495  const BoundArg5& arg5) {
2496  return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3,
2497  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2498 }
2499 
2500 /**
2501  * An alternative function to make Callback::CallbackArg objects,
2502  * which is for use where a target function either receives a class
2503  * type bound argument by value, or receives a bound argument by
2504  * reference to const in a case where the generated CallbackArg object
2505  * is to store a copy of that argument instead of just keeping a
2506  * reference.
2507  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2508  * is exhausted and the system throws in that case (this exception
2509  * will not be thrown if the library has been installed using the
2510  * --with-glib-memory-slices-no-compat configuration option: instead
2511  * glib will terminate the program if it is unable to obtain memory
2512  * from the operating system). It will also throw if the copy or move
2513  * constructor of a bound argument throws and it is not a reference
2514  * argument.
2515  *
2516  * Since 2.0.0-rc3
2517  */
2518 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
2519  class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
2520 CallbackArg<FreeArgs...>* make_ref(T& t,
2521  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2522  BoundArg4, BoundArg5, FreeArgs...),
2523  Arg1&& arg1,
2524  Arg2&& arg2,
2525  Arg3&& arg3,
2526  Arg4&& arg4,
2527  Arg5&& arg5) {
2528  return new Callback5<true, T, BoundArg1, BoundArg2, BoundArg3,
2529  BoundArg4, BoundArg5, FreeArgs...>{t, func,
2530  std::forward<Arg1>(arg1),
2531  std::forward<Arg2>(arg2),
2532  std::forward<Arg3>(arg3),
2533  std::forward<Arg4>(arg4),
2534  std::forward<Arg5>(arg5)};
2535 }
2536 
2537 /* const versions, for binding to const methods */
2538 
2539 /**
2540  * A convenience function to make Callback::CallbackArg objects
2541  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2542  * is exhausted and the system throws in that case. This exception
2543  * will not be thrown if the library has been installed using the
2544  * --with-glib-memory-slices-no-compat configuration option (instead
2545  * glib will terminate the program if it is unable to obtain memory
2546  * from the operating system).
2547  */
2548 template <class T, class... FreeArgs>
2549 CallbackArg<FreeArgs...>* make(const T& t,
2550  void (T::*func)(FreeArgs...) const) {
2551  return new Callback0_const<T, FreeArgs...>{t, func};
2552 }
2553 
2554 /**
2555  * DEPRECATED.
2556  *
2557  * Since this function constructs a callback which does not take a
2558  * bound argument, it is a synonym for make() (the two are identical).
2559  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2560  * is exhausted and the system throws in that case. This exception
2561  * will not be thrown if the library has been installed using the
2562  * --with-glib-memory-slices-no-compat configuration option (instead
2563  * glib will terminate the program if it is unable to obtain memory
2564  * from the operating system).
2565  */
2566 template <class T, class... FreeArgs>
2567 CallbackArg<FreeArgs...>* make_val(const T& t,
2568  void (T::*func)(FreeArgs...) const) {
2569  return new Callback0_const<T, FreeArgs...>{t, func};
2570 }
2571 
2572 /**
2573  * Since this function constructs a callback which does not take a
2574  * bound argument, it is a synonym for make() (the two are identical).
2575  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2576  * is exhausted and the system throws in that case. This exception
2577  * will not be thrown if the library has been installed using the
2578  * --with-glib-memory-slices-no-compat configuration option (instead
2579  * glib will terminate the program if it is unable to obtain memory
2580  * from the operating system).
2581  *
2582  * Since 2.0.0-rc3
2583  */
2584 template <class T, class... FreeArgs>
2585 CallbackArg<FreeArgs...>* make_ref(const T& t,
2586  void (T::*func)(FreeArgs...) const) {
2587  return new Callback0_const<T, FreeArgs...>{t, func};
2588 }
2589 
2590 /**
2591  * A convenience function to make Callback::CallbackArg objects
2592  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2593  * is exhausted and the system throws in that case (this exception
2594  * will not be thrown if the library has been installed using the
2595  * --with-glib-memory-slices-no-compat configuration option: instead
2596  * glib will terminate the program if it is unable to obtain memory
2597  * from the operating system). It will also throw if the copy
2598  * constructor of a bound argument throws and it is not a reference
2599  * argument.
2600  */
2601 template <class T, class BoundArg, class... FreeArgs>
2602 CallbackArg<FreeArgs...>* make(const T& t,
2603  void (T::*func)(BoundArg, FreeArgs...) const,
2604  BoundArg arg) {
2605  return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg};
2606 }
2607 
2608 /**
2609  * DEPRECATED: use Callback::make_ref() instead.
2610  *
2611  * An alternative function to make Callback::CallbackArg objects,
2612  * which is for use where a target function receives an argument of
2613  * class type by value which is to be a bound argument, so the
2614  * compiler is not able to carry out copy elision when constructing
2615  * the callback object.
2616  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2617  * is exhausted and the system throws in that case (this exception
2618  * will not be thrown if the library has been installed using the
2619  * --with-glib-memory-slices-no-compat configuration option: instead
2620  * glib will terminate the program if it is unable to obtain memory
2621  * from the operating system). It will also throw if the copy
2622  * constructor of a bound argument throws and it is not a reference
2623  * argument.
2624  */
2625 template <class T, class BoundArg, class... FreeArgs>
2626 CallbackArg<FreeArgs...>* make_val(const T& t,
2627  void (T::*func)(BoundArg, FreeArgs...) const,
2628  const BoundArg& arg) {
2629  return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg};
2630 }
2631 
2632 /**
2633  * An alternative function to make Callback::CallbackArg objects,
2634  * which is for use where a target function either receives a class
2635  * type bound argument by value, or receives a bound argument by
2636  * reference to const in a case where the generated CallbackArg object
2637  * is to store a copy of that argument instead of just keeping a
2638  * reference.
2639  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2640  * is exhausted and the system throws in that case (this exception
2641  * will not be thrown if the library has been installed using the
2642  * --with-glib-memory-slices-no-compat configuration option: instead
2643  * glib will terminate the program if it is unable to obtain memory
2644  * from the operating system). It will also throw if the copy or move
2645  * constructor of a bound argument throws and it is not a reference
2646  * argument.
2647  *
2648  * Since 2.0.0-rc3
2649  */
2650 template <class T, class BoundArg, class Arg, class... FreeArgs>
2651 CallbackArg<FreeArgs...>* make_ref(const T& t,
2652  void (T::*func)(BoundArg, FreeArgs...) const,
2653  Arg&& arg) {
2654  return new Callback1_const<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)};
2655 }
2656 
2657 /**
2658  * A convenience function to make Callback::CallbackArg objects
2659  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2660  * is exhausted and the system throws in that case (this exception
2661  * will not be thrown if the library has been installed using the
2662  * --with-glib-memory-slices-no-compat configuration option: instead
2663  * glib will terminate the program if it is unable to obtain memory
2664  * from the operating system). It will also throw if the copy
2665  * constructor of a bound argument throws and it is not a reference
2666  * argument.
2667  */
2668 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2669 CallbackArg<FreeArgs...>* make(const T& t,
2670  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
2671  BoundArg1 arg1,
2672  BoundArg2 arg2) {
2673  return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2674 }
2675 
2676 /**
2677  * DEPRECATED: use Callback::make_ref() instead.
2678  *
2679  * An alternative function to make Callback::CallbackArg objects,
2680  * which is for use where a target function receives an argument of
2681  * class type by value which is to be a bound argument, so the
2682  * compiler is not able to carry out copy elision when constructing
2683  * the callback object.
2684  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2685  * is exhausted and the system throws in that case (this exception
2686  * will not be thrown if the library has been installed using the
2687  * --with-glib-memory-slices-no-compat configuration option: instead
2688  * glib will terminate the program if it is unable to obtain memory
2689  * from the operating system). It will also throw if the copy
2690  * constructor of a bound argument throws and it is not a reference
2691  * argument.
2692  */
2693 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2694 CallbackArg<FreeArgs...>* make_val(const T& t,
2695  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
2696  const BoundArg1& arg1,
2697  const BoundArg2& arg2) {
2698  return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2699 }
2700 
2701 /**
2702  * An alternative function to make Callback::CallbackArg objects,
2703  * which is for use where a target function either receives a class
2704  * type bound argument by value, or receives a bound argument by
2705  * reference to const in a case where the generated CallbackArg object
2706  * is to store a copy of that argument instead of just keeping a
2707  * reference.
2708  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2709  * is exhausted and the system throws in that case (this exception
2710  * will not be thrown if the library has been installed using the
2711  * --with-glib-memory-slices-no-compat configuration option: instead
2712  * glib will terminate the program if it is unable to obtain memory
2713  * from the operating system). It will also throw if the copy or move
2714  * constructor of a bound argument throws and it is not a reference
2715  * argument.
2716  *
2717  * Since 2.0.0-rc3
2718  */
2719 template <class T, class BoundArg1, class BoundArg2,
2720  class Arg1, class Arg2, class... FreeArgs>
2721 CallbackArg<FreeArgs...>* make_ref(const T& t,
2722  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
2723  Arg1&& arg1,
2724  Arg2&& arg2) {
2725  return new Callback2_const<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func,
2726  std::forward<Arg1>(arg1),
2727  std::forward<Arg2>(arg2)};
2728 }
2729 
2730 /**
2731  * A convenience function to make Callback::CallbackArg objects
2732  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2733  * is exhausted and the system throws in that case (this exception
2734  * will not be thrown if the library has been installed using the
2735  * --with-glib-memory-slices-no-compat configuration option: instead
2736  * glib will terminate the program if it is unable to obtain memory
2737  * from the operating system). It will also throw if the copy
2738  * constructor of a bound argument throws and it is not a reference
2739  * argument.
2740  */
2741 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2742 CallbackArg<FreeArgs...>* make(const T& t,
2743  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
2744  BoundArg1 arg1,
2745  BoundArg2 arg2,
2746  BoundArg3 arg3) {
2747  return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2748 }
2749 
2750 /**
2751  * DEPRECATED: use Callback::make_ref() instead.
2752  *
2753  * An alternative function to make Callback::CallbackArg objects,
2754  * which is for use where a target function receives an argument of
2755  * class type by value which is to be a bound argument, so the
2756  * compiler is not able to carry out copy elision when constructing
2757  * the callback object.
2758  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2759  * is exhausted and the system throws in that case (this exception
2760  * will not be thrown if the library has been installed using the
2761  * --with-glib-memory-slices-no-compat configuration option: instead
2762  * glib will terminate the program if it is unable to obtain memory
2763  * from the operating system). It will also throw if the copy
2764  * constructor of a bound argument throws and it is not a reference
2765  * argument.
2766  */
2767 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2768 CallbackArg<FreeArgs...>* make_val(const T& t,
2769  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
2770  const BoundArg1& arg1,
2771  const BoundArg2& arg2,
2772  const BoundArg3& arg3) {
2773  return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2774 }
2775 
2776 /**
2777  * An alternative function to make Callback::CallbackArg objects,
2778  * which is for use where a target function either receives a class
2779  * type bound argument by value, or receives a bound argument by
2780  * reference to const in a case where the generated CallbackArg object
2781  * is to store a copy of that argument instead of just keeping a
2782  * reference.
2783  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2784  * is exhausted and the system throws in that case (this exception
2785  * will not be thrown if the library has been installed using the
2786  * --with-glib-memory-slices-no-compat configuration option: instead
2787  * glib will terminate the program if it is unable to obtain memory
2788  * from the operating system). It will also throw if the copy or move
2789  * constructor of a bound argument throws and it is not a reference
2790  * argument.
2791  *
2792  * Since 2.0.0-rc3
2793  */
2794 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2795  class Arg1, class Arg2, class Arg3, class... FreeArgs>
2796 CallbackArg<FreeArgs...>* make_ref(const T& t,
2797  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
2798  Arg1&& arg1,
2799  Arg2&& arg2,
2800  Arg3&& arg3) {
2801  return new Callback3_const<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func,
2802  std::forward<Arg1>(arg1),
2803  std::forward<Arg2>(arg2),
2804  std::forward<Arg3>(arg3)};
2805 }
2806 
2807 /**
2808  * A convenience function to make Callback::CallbackArg objects
2809  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2810  * is exhausted and the system throws in that case (this exception
2811  * will not be thrown if the library has been installed using the
2812  * --with-glib-memory-slices-no-compat configuration option: instead
2813  * glib will terminate the program if it is unable to obtain memory
2814  * from the operating system). It will also throw if the copy
2815  * constructor of a bound argument throws and it is not a reference
2816  * argument.
2817  */
2818 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2819  class BoundArg4, class... FreeArgs>
2820 CallbackArg<FreeArgs...>* make(const T& t,
2821  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2822  BoundArg4, FreeArgs...) const,
2823  BoundArg1 arg1,
2824  BoundArg2 arg2,
2825  BoundArg3 arg3,
2826  BoundArg4 arg4) {
2827  return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2828  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2829 }
2830 
2831 /**
2832  * DEPRECATED: use Callback::make_ref() instead.
2833  *
2834  * An alternative function to make Callback::CallbackArg objects,
2835  * which is for use where a target function receives an argument of
2836  * class type by value which is to be a bound argument, so the
2837  * compiler is not able to carry out copy elision when constructing
2838  * the callback object.
2839  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2840  * is exhausted and the system throws in that case (this exception
2841  * will not be thrown if the library has been installed using the
2842  * --with-glib-memory-slices-no-compat configuration option: instead
2843  * glib will terminate the program if it is unable to obtain memory
2844  * from the operating system). It will also throw if the copy
2845  * constructor of a bound argument throws and it is not a reference
2846  * argument.
2847  */
2848 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2849  class BoundArg4, class... FreeArgs>
2850 CallbackArg<FreeArgs...>* make_val(const T& t,
2851  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2852  BoundArg4, FreeArgs...) const,
2853  const BoundArg1& arg1,
2854  const BoundArg2& arg2,
2855  const BoundArg3& arg3,
2856  const BoundArg4& arg4) {
2857  return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2858  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2859 }
2860 
2861 /**
2862  * An alternative function to make Callback::CallbackArg objects,
2863  * which is for use where a target function either receives a class
2864  * type bound argument by value, or receives a bound argument by
2865  * reference to const in a case where the generated CallbackArg object
2866  * is to store a copy of that argument instead of just keeping a
2867  * reference.
2868  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2869  * is exhausted and the system throws in that case (this exception
2870  * will not be thrown if the library has been installed using the
2871  * --with-glib-memory-slices-no-compat configuration option: instead
2872  * glib will terminate the program if it is unable to obtain memory
2873  * from the operating system). It will also throw if the copy or move
2874  * constructor of a bound argument throws and it is not a reference
2875  * argument.
2876  *
2877  * Since 2.0.0-rc3
2878  */
2879 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
2880  class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
2881 CallbackArg<FreeArgs...>* make_ref(const T& t,
2882  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2883  BoundArg4, FreeArgs...) const,
2884  Arg1&& arg1,
2885  Arg2&& arg2,
2886  Arg3&& arg3,
2887  Arg4&& arg4) {
2888  return new Callback4_const<true, T, BoundArg1, BoundArg2, BoundArg3,
2889  BoundArg4, FreeArgs...>{t, func,
2890  std::forward<Arg1>(arg1),
2891  std::forward<Arg2>(arg2),
2892  std::forward<Arg3>(arg3),
2893  std::forward<Arg4>(arg4)};
2894 }
2895 
2896 /**
2897  * A convenience function to make Callback::CallbackArg objects
2898  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2899  * is exhausted and the system throws in that case (this exception
2900  * will not be thrown if the library has been installed using the
2901  * --with-glib-memory-slices-no-compat configuration option: instead
2902  * glib will terminate the program if it is unable to obtain memory
2903  * from the operating system). It will also throw if the copy
2904  * constructor of a bound argument throws and it is not a reference
2905  * argument.
2906  */
2907 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2908  class BoundArg4, class BoundArg5, class... FreeArgs>
2909 CallbackArg<FreeArgs...>* make(const T& t,
2910  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2911  BoundArg4, BoundArg5, FreeArgs...) const,
2912  BoundArg1 arg1,
2913  BoundArg2 arg2,
2914  BoundArg3 arg3,
2915  BoundArg4 arg4,
2916  BoundArg5 arg5) {
2917  return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2918  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2919 }
2920 
2921 /**
2922  * DEPRECATED: use Callback::make_ref() instead.
2923  *
2924  * An alternative function to make Callback::CallbackArg objects,
2925  * which is for use where a target function receives an argument of
2926  * class type by value which is to be a bound argument, so the
2927  * compiler is not able to carry out copy elision when constructing
2928  * the callback object.
2929  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2930  * is exhausted and the system throws in that case (this exception
2931  * will not be thrown if the library has been installed using the
2932  * --with-glib-memory-slices-no-compat configuration option: instead
2933  * glib will terminate the program if it is unable to obtain memory
2934  * from the operating system). It will also throw if the copy
2935  * constructor of a bound argument throws and it is not a reference
2936  * argument.
2937  */
2938 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2939  class BoundArg4, class BoundArg5, class... FreeArgs>
2940 CallbackArg<FreeArgs...>* make_val(const T& t,
2941  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2942  BoundArg4, BoundArg5, FreeArgs...) const,
2943  const BoundArg1& arg1,
2944  const BoundArg2& arg2,
2945  const BoundArg3& arg3,
2946  const BoundArg4& arg4,
2947  const BoundArg5& arg5) {
2948  return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2949  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2950 }
2951 
2952 /**
2953  * An alternative function to make Callback::CallbackArg objects,
2954  * which is for use where a target function either receives a class
2955  * type bound argument by value, or receives a bound argument by
2956  * reference to const in a case where the generated CallbackArg object
2957  * is to store a copy of that argument instead of just keeping a
2958  * reference.
2959  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2960  * is exhausted and the system throws in that case (this exception
2961  * will not be thrown if the library has been installed using the
2962  * --with-glib-memory-slices-no-compat configuration option: instead
2963  * glib will terminate the program if it is unable to obtain memory
2964  * from the operating system). It will also throw if the copy or move
2965  * constructor of a bound argument throws and it is not a reference
2966  * argument.
2967  *
2968  * Since 2.0.0-rc3
2969  */
2970 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
2971  class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
2972 CallbackArg<FreeArgs...>* make_ref(const T& t,
2973  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2974  BoundArg4, BoundArg5, FreeArgs...) const,
2975  Arg1&& arg1,
2976  Arg2&& arg2,
2977  Arg3&& arg3,
2978  Arg4&& arg4,
2979  Arg5&& arg5) {
2980  return new Callback5_const<true, T, BoundArg1, BoundArg2, BoundArg3,
2981  BoundArg4, BoundArg5, FreeArgs...>{t, func,
2982  std::forward<Arg1>(arg1),
2983  std::forward<Arg2>(arg2),
2984  std::forward<Arg3>(arg3),
2985  std::forward<Arg4>(arg4),
2986  std::forward<Arg5>(arg5)};
2987 }
2988 
2989 /* for static class methods and non-class functions */
2990 
2991 /**
2992  * A convenience function to make Callback::CallbackArg objects
2993  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2994  * is exhausted and the system throws in that case. This exception
2995  * will not be thrown if the library has been installed using the
2996  * --with-glib-memory-slices-no-compat configuration option (instead
2997  * glib will terminate the program if it is unable to obtain memory
2998  * from the operating system).
2999  */
3000 template <class... FreeArgs>
3001 CallbackArg<FreeArgs...>* make(void (*func)(FreeArgs...)) {
3002  return new Callback0_static<FreeArgs...>{func};
3003 }
3004 
3005 /**
3006  * DEPRECATED.
3007  *
3008  * Since this function constructs a callback which does not take a
3009  * bound argument, it is a synonym for make() (the two are identical).
3010  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3011  * is exhausted and the system throws in that case. This exception
3012  * will not be thrown if the library has been installed using the
3013  * --with-glib-memory-slices-no-compat configuration option (instead
3014  * glib will terminate the program if it is unable to obtain memory
3015  * from the operating system).
3016  */
3017 template <class... FreeArgs>
3018 CallbackArg<FreeArgs...>* make_val(void (*func)(FreeArgs...)) {
3019  return new Callback0_static<FreeArgs...>{func};
3020 }
3021 
3022 /**
3023  * Since this function constructs a callback which does not take a
3024  * bound argument, it is a synonym for make() (the two are identical).
3025  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3026  * is exhausted and the system throws in that case. This exception
3027  * will not be thrown if the library has been installed using the
3028  * --with-glib-memory-slices-no-compat configuration option (instead
3029  * glib will terminate the program if it is unable to obtain memory
3030  * from the operating system).
3031  *
3032  * Since 2.0.0-rc3
3033  */
3034 template <class... FreeArgs>
3035 CallbackArg<FreeArgs...>* make_ref(void (*func)(FreeArgs...)) {
3036  return new Callback0_static<FreeArgs...>{func};
3037 }
3038 
3039 /**
3040  * A convenience function to make Callback::CallbackArg objects
3041  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3042  * is exhausted and the system throws in that case (this exception
3043  * will not be thrown if the library has been installed using the
3044  * --with-glib-memory-slices-no-compat configuration option: instead
3045  * glib will terminate the program if it is unable to obtain memory
3046  * from the operating system). It will also throw if the copy
3047  * constructor of a bound argument throws and it is not a reference
3048  * argument.
3049  */
3050 template <class BoundArg, class... FreeArgs>
3051 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg, FreeArgs...),
3052  BoundArg arg) {
3053  return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg};
3054 }
3055 
3056 /**
3057  * DEPRECATED: use Callback::make_ref() instead.
3058  *
3059  * An alternative function to make Callback::CallbackArg objects,
3060  * which is for use where a target function receives an argument of
3061  * class type by value which is to be a bound argument, so the
3062  * compiler is not able to carry out copy elision when constructing
3063  * the callback object.
3064  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3065  * is exhausted and the system throws in that case (this exception
3066  * will not be thrown if the library has been installed using the
3067  * --with-glib-memory-slices-no-compat configuration option: instead
3068  * glib will terminate the program if it is unable to obtain memory
3069  * from the operating system). It will also throw if the copy
3070  * constructor of a bound argument throws and it is not a reference
3071  * argument.
3072  */
3073 template <class BoundArg, class... FreeArgs>
3074 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg, FreeArgs...),
3075  const BoundArg& arg) {
3076  return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg};
3077 }
3078 
3079 /**
3080  * An alternative function to make Callback::CallbackArg objects,
3081  * which is for use where a target function either receives a class
3082  * type bound argument by value, or receives a bound argument by
3083  * reference to const in a case where the generated CallbackArg object
3084  * is to store a copy of that argument instead of just keeping a
3085  * reference.
3086  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3087  * is exhausted and the system throws in that case (this exception
3088  * will not be thrown if the library has been installed using the
3089  * --with-glib-memory-slices-no-compat configuration option: instead
3090  * glib will terminate the program if it is unable to obtain memory
3091  * from the operating system). It will also throw if the copy or move
3092  * constructor of a bound argument throws and it is not a reference
3093  * argument.
3094  *
3095  * Since 2.0.0-rc3
3096  */
3097 template <class BoundArg, class Arg, class... FreeArgs>
3098 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg, FreeArgs...),
3099  Arg&& arg) {
3100  return new Callback1_static<true, BoundArg, FreeArgs...>{func, std::forward<Arg>(arg)};
3101 }
3102 
3103 /**
3104  * A convenience function to make Callback::CallbackArg objects
3105  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3106  * is exhausted and the system throws in that case (this exception
3107  * will not be thrown if the library has been installed using the
3108  * --with-glib-memory-slices-no-compat configuration option: instead
3109  * glib will terminate the program if it is unable to obtain memory
3110  * from the operating system). It will also throw if the copy
3111  * constructor of a bound argument throws and it is not a reference
3112  * argument.
3113  */
3114 template <class BoundArg1, class BoundArg2, class... FreeArgs>
3115 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
3116  BoundArg1 arg1,
3117  BoundArg2 arg2) {
3118  return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2};
3119 }
3120 
3121 /**
3122  * DEPRECATED: use Callback::make_ref() instead.
3123  *
3124  * An alternative function to make Callback::CallbackArg objects,
3125  * which is for use where a target function receives an argument of
3126  * class type by value which is to be a bound argument, so the
3127  * compiler is not able to carry out copy elision when constructing
3128  * the callback object.
3129  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3130  * is exhausted and the system throws in that case (this exception
3131  * will not be thrown if the library has been installed using the
3132  * --with-glib-memory-slices-no-compat configuration option: instead
3133  * glib will terminate the program if it is unable to obtain memory
3134  * from the operating system). It will also throw if the copy
3135  * constructor of a bound argument throws and it is not a reference
3136  * argument.
3137  */
3138 template <class BoundArg1, class BoundArg2, class... FreeArgs>
3139 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
3140  const BoundArg1& arg1,
3141  const BoundArg2& arg2) {
3142  return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2};
3143 }
3144 
3145 /**
3146  * An alternative function to make Callback::CallbackArg objects,
3147  * which is for use where a target function either receives a class
3148  * type bound argument by value, or receives a bound argument by
3149  * reference to const in a case where the generated CallbackArg object
3150  * is to store a copy of that argument instead of just keeping a
3151  * reference.
3152  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3153  * is exhausted and the system throws in that case (this exception
3154  * will not be thrown if the library has been installed using the
3155  * --with-glib-memory-slices-no-compat configuration option: instead
3156  * glib will terminate the program if it is unable to obtain memory
3157  * from the operating system). It will also throw if the copy or move
3158  * constructor of a bound argument throws and it is not a reference
3159  * argument.
3160  *
3161  * Since 2.0.0-rc3
3162  */
3163 template <class BoundArg1, class BoundArg2, class Arg1, class Arg2, class... FreeArgs>
3164 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
3165  Arg1&& arg1,
3166  Arg2&& arg2) {
3167  return new Callback2_static<true, BoundArg1, BoundArg2, FreeArgs...>{func,
3168  std::forward<Arg1>(arg1),
3169  std::forward<Arg2>(arg2)};
3170 }
3171 
3172 /**
3173  * A convenience function to make Callback::CallbackArg objects
3174  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3175  * is exhausted and the system throws in that case (this exception
3176  * will not be thrown if the library has been installed using the
3177  * --with-glib-memory-slices-no-compat configuration option: instead
3178  * glib will terminate the program if it is unable to obtain memory
3179  * from the operating system). It will also throw if the copy
3180  * constructor of a bound argument throws and it is not a reference
3181  * argument.
3182  */
3183 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
3184 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
3185  BoundArg1 arg1,
3186  BoundArg2 arg2,
3187  BoundArg3 arg3) {
3188  return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3};
3189 }
3190 
3191 /**
3192  * DEPRECATED: use Callback::make_ref() instead.
3193  *
3194  * An alternative function to make Callback::CallbackArg objects,
3195  * which is for use where a target function receives an argument of
3196  * class type by value which is to be a bound argument, so the
3197  * compiler is not able to carry out copy elision when constructing
3198  * the callback object.
3199  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3200  * is exhausted and the system throws in that case (this exception
3201  * will not be thrown if the library has been installed using the
3202  * --with-glib-memory-slices-no-compat configuration option: instead
3203  * glib will terminate the program if it is unable to obtain memory
3204  * from the operating system). It will also throw if the copy
3205  * constructor of a bound argument throws and it is not a reference
3206  * argument.
3207  */
3208 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
3209 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
3210  const BoundArg1& arg1,
3211  const BoundArg2& arg2,
3212  const BoundArg3& arg3) {
3213  return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3};
3214 }
3215 
3216 /**
3217  * An alternative function to make Callback::CallbackArg objects,
3218  * which is for use where a target function either receives a class
3219  * type bound argument by value, or receives a bound argument by
3220  * reference to const in a case where the generated CallbackArg object
3221  * is to store a copy of that argument instead of just keeping a
3222  * reference.
3223  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3224  * is exhausted and the system throws in that case (this exception
3225  * will not be thrown if the library has been installed using the
3226  * --with-glib-memory-slices-no-compat configuration option: instead
3227  * glib will terminate the program if it is unable to obtain memory
3228  * from the operating system). It will also throw if the copy or move
3229  * constructor of a bound argument throws and it is not a reference
3230  * argument.
3231  *
3232  * Since 2.0.0-rc3
3233  */
3234 template <class BoundArg1, class BoundArg2, class BoundArg3,
3235  class Arg1, class Arg2, class Arg3, class... FreeArgs>
3236 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
3237  Arg1&& arg1,
3238  Arg2&& arg2,
3239  Arg3&& arg3) {
3240  return new Callback3_static<true, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func,
3241  std::forward<Arg1>(arg1),
3242  std::forward<Arg2>(arg2),
3243  std::forward<Arg3>(arg3)};
3244 }
3245 
3246 /**
3247  * A convenience function to make Callback::CallbackArg objects
3248  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3249  * is exhausted and the system throws in that case (this exception
3250  * will not be thrown if the library has been installed using the
3251  * --with-glib-memory-slices-no-compat configuration option: instead
3252  * glib will terminate the program if it is unable to obtain memory
3253  * from the operating system). It will also throw if the copy
3254  * constructor of a bound argument throws and it is not a reference
3255  * argument.
3256  */
3257 template <class BoundArg1, class BoundArg2, class BoundArg3,
3258  class BoundArg4, class... FreeArgs>
3259 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3260  BoundArg4, FreeArgs...),
3261  BoundArg1 arg1,
3262  BoundArg2 arg2,
3263  BoundArg3 arg3,
3264  BoundArg4 arg4) {
3265  return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3,
3266  BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4};
3267 }
3268 
3269 /**
3270  * DEPRECATED: use Callback::make_ref() instead.
3271  *
3272  * An alternative function to make Callback::CallbackArg objects,
3273  * which is for use where a target function receives an argument of
3274  * class type by value which is to be a bound argument, so the
3275  * compiler is not able to carry out copy elision when constructing
3276  * the callback object.
3277  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3278  * is exhausted and the system throws in that case (this exception
3279  * will not be thrown if the library has been installed using the
3280  * --with-glib-memory-slices-no-compat configuration option: instead
3281  * glib will terminate the program if it is unable to obtain memory
3282  * from the operating system). It will also throw if the copy
3283  * constructor of a bound argument throws and it is not a reference
3284  * argument.
3285  */
3286 template <class BoundArg1, class BoundArg2, class BoundArg3,
3287  class BoundArg4, class... FreeArgs>
3288 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3289  BoundArg4, FreeArgs...),
3290  const BoundArg1& arg1,
3291  const BoundArg2& arg2,
3292  const BoundArg3& arg3,
3293  const BoundArg4& arg4) {
3294  return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3,
3295  BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4};
3296 }
3297 
3298 /**
3299  * An alternative function to make Callback::CallbackArg objects,
3300  * which is for use where a target function either receives a class
3301  * type bound argument by value, or receives a bound argument by
3302  * reference to const in a case where the generated CallbackArg object
3303  * is to store a copy of that argument instead of just keeping a
3304  * reference.
3305  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3306  * is exhausted and the system throws in that case (this exception
3307  * will not be thrown if the library has been installed using the
3308  * --with-glib-memory-slices-no-compat configuration option: instead
3309  * glib will terminate the program if it is unable to obtain memory
3310  * from the operating system). It will also throw if the copy or move
3311  * constructor of a bound argument throws and it is not a reference
3312  * argument.
3313  *
3314  * Since 2.0.0-rc3
3315  */
3316 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
3317  class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
3318 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3319  BoundArg4, FreeArgs...),
3320  Arg1&& arg1,
3321  Arg2&& arg2,
3322  Arg3&& arg3,
3323  Arg4&& arg4) {
3324  return new Callback4_static<true, BoundArg1, BoundArg2, BoundArg3,
3325  BoundArg4, FreeArgs...>{func,
3326  std::forward<Arg1>(arg1),
3327  std::forward<Arg2>(arg2),
3328  std::forward<Arg3>(arg3),
3329  std::forward<Arg4>(arg4)};
3330 }
3331 
3332 /**
3333  * A convenience function to make Callback::CallbackArg objects
3334  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3335  * is exhausted and the system throws in that case (this exception
3336  * will not be thrown if the library has been installed using the
3337  * --with-glib-memory-slices-no-compat configuration option: instead
3338  * glib will terminate the program if it is unable to obtain memory
3339  * from the operating system). It will also throw if the copy
3340  * constructor of a bound argument throws and it is not a reference
3341  * argument.
3342  */
3343 template <class BoundArg1, class BoundArg2, class BoundArg3,
3344  class BoundArg4, class BoundArg5, class... FreeArgs>
3345 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3346  BoundArg4, BoundArg5, FreeArgs...),
3347  BoundArg1 arg1,
3348  BoundArg2 arg2,
3349  BoundArg3 arg3,
3350  BoundArg4 arg4,
3351  BoundArg5 arg5) {
3352  return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3,
3353  BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5};
3354 }
3355 
3356 /**
3357  * DEPRECATED: use Callback::make_ref() instead.
3358  *
3359  * An alternative function to make Callback::CallbackArg objects,
3360  * which is for use where a target function receives an argument of
3361  * class type by value which is to be a bound argument, so the
3362  * compiler is not able to carry out copy elision when constructing
3363  * the callback object.
3364  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3365  * is exhausted and the system throws in that case (this exception
3366  * will not be thrown if the library has been installed using the
3367  * --with-glib-memory-slices-no-compat configuration option: instead
3368  * glib will terminate the program if it is unable to obtain memory
3369  * from the operating system). It will also throw if the copy
3370  * constructor of a bound argument throws and it is not a reference
3371  * argument.
3372  */
3373 template <class BoundArg1, class BoundArg2, class BoundArg3,
3374  class BoundArg4, class BoundArg5, class... FreeArgs>
3375 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3376  BoundArg4, BoundArg5, FreeArgs...),
3377  const BoundArg1& arg1,
3378  const BoundArg2& arg2,
3379  const BoundArg3& arg3,
3380  const BoundArg4& arg4,
3381  const BoundArg5& arg5) {
3382  return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3,
3383  BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5};
3384 }
3385 
3386 /**
3387  * An alternative function to make Callback::CallbackArg objects,
3388  * which is for use where a target function either receives a class
3389  * type bound argument by value, or receives a bound argument by
3390  * reference to const in a case where the generated CallbackArg object
3391  * is to store a copy of that argument instead of just keeping a
3392  * reference.
3393  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3394  * is exhausted and the system throws in that case (this exception
3395  * will not be thrown if the library has been installed using the
3396  * --with-glib-memory-slices-no-compat configuration option: instead
3397  * glib will terminate the program if it is unable to obtain memory
3398  * from the operating system). It will also throw if the copy or move
3399  * constructor of a bound argument throws and it is not a reference
3400  * argument.
3401  *
3402  * Since 2.0.0-rc3
3403  */
3404 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
3405  class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
3406 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3,
3407  BoundArg4, BoundArg5, FreeArgs...),
3408  Arg1&& arg1,
3409  Arg2&& arg2,
3410  Arg3&& arg3,
3411  Arg4&& arg4,
3412  Arg5&& arg5) {
3413  return new Callback5_static<true, BoundArg1, BoundArg2, BoundArg3,
3414  BoundArg4, BoundArg5, FreeArgs...>{func,
3415  std::forward<Arg1>(arg1),
3416  std::forward<Arg2>(arg2),
3417  std::forward<Arg3>(arg3),
3418  std::forward<Arg4>(arg4),
3419  std::forward<Arg5>(arg5)};
3420 }
3421 
3422 /* for std::function objects */
3423 
3424 /**
3425  * A convenience function to make Callback::CallbackArg objects from
3426  * std::function objects.
3427  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3428  * is exhausted and the system throws in that case (this exception
3429  * will not be thrown if the library has been installed using the
3430  * --with-glib-memory-slices-no-compat configuration option: instead
3431  * glib will terminate the program if it is unable to obtain memory
3432  * from the operating system). It will also throw if the copy
3433  * constructor of a bound argument throws and it is not a reference
3434  * argument.
3435  */
3436 template <class... FreeArgs>
3437 CallbackArg<FreeArgs...>* make(const std::function<void(FreeArgs...)>& f) {
3438  return new Callback_function<FreeArgs...>{f};
3439 }
3440 
3441 /**
3442  * DEPRECATED.
3443  *
3444  * A convenience function to make Callback::Callback objects from
3445  * std::function objects. Since this function takes no bound argument
3446  * (and bound arguments are bound into the std::function object), it
3447  * is a synonym for make() (the two are identical).
3448  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3449  * is exhausted and the system throws in that case (this exception
3450  * will not be thrown if the library has been installed using the
3451  * --with-glib-memory-slices-no-compat configuration option: instead
3452  * glib will terminate the program if it is unable to obtain memory
3453  * from the operating system). It will also throw if the copy
3454  * constructor of a bound argument throws and it is not a reference
3455  * argument.
3456  */
3457 template <class... FreeArgs>
3458 CallbackArg<FreeArgs...>* make_val(const std::function<void(FreeArgs...)>& f) {
3459  return new Callback_function<FreeArgs...>{f};
3460 }
3461 
3462 /**
3463  * A convenience function to make Callback::Callback objects from
3464  * std::function objects. Since this function takes no bound argument
3465  * (and bound arguments are bound into the std::function object), it
3466  * is a synonym for make() (the two are identical).
3467  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3468  * is exhausted and the system throws in that case (this exception
3469  * will not be thrown if the library has been installed using the
3470  * --with-glib-memory-slices-no-compat configuration option: instead
3471  * glib will terminate the program if it is unable to obtain memory
3472  * from the operating system). It will also throw if the copy
3473  * constructor of a bound argument throws and it is not a reference
3474  * argument.
3475  */
3476 template <class... FreeArgs>
3477 CallbackArg<FreeArgs...>* make_ref(const std::function<void(FreeArgs...)>& f) {
3478  return new Callback_function<FreeArgs...>{f};
3479 }
3480 
3481 /**
3482  * A convenience function to make Callback::CallbackArg objects from
3483  * std::function objects.
3484  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3485  * is exhausted and the system throws in that case (this exception
3486  * will not be thrown if the library has been installed using the
3487  * --with-glib-memory-slices-no-compat configuration option: instead
3488  * glib will terminate the program if it is unable to obtain memory
3489  * from the operating system). It will also throw if the copy
3490  * constructor of a bound argument throws and it is not a reference
3491  * argument.
3492  */
3493 template <class... FreeArgs>
3494 CallbackArg<FreeArgs...>* make(std::function<void(FreeArgs...)>&& f) {
3495  return new Callback_function<FreeArgs...>{std::move(f)};
3496 }
3497 
3498 /**
3499  * DEPRECATED.
3500  *
3501  * A convenience function to make Callback::Callback objects from
3502  * std::function objects. Since this function takes no bound argument
3503  * (and bound arguments are bound into the std::function object), it
3504  * is a synonym for make() (the two are identical).
3505  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3506  * is exhausted and the system throws in that case (this exception
3507  * will not be thrown if the library has been installed using the
3508  * --with-glib-memory-slices-no-compat configuration option: instead
3509  * glib will terminate the program if it is unable to obtain memory
3510  * from the operating system). It will also throw if the copy or move
3511  * constructor of a bound argument throws and it is not a reference
3512  * argument.
3513  */
3514 template <class... FreeArgs>
3515 CallbackArg<FreeArgs...>* make_val(std::function<void(FreeArgs...)>&& f) {
3516  return new Callback_function<FreeArgs...>{std::move(f)};
3517 }
3518 
3519 /**
3520  * A convenience function to make Callback::Callback objects from
3521  * std::function objects. Since this function takes no bound argument
3522  * (and bound arguments are bound into the std::function object), it
3523  * is a synonym for make() (the two are identical).
3524  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3525  * is exhausted and the system throws in that case (this exception
3526  * will not be thrown if the library has been installed using the
3527  * --with-glib-memory-slices-no-compat configuration option: instead
3528  * glib will terminate the program if it is unable to obtain memory
3529  * from the operating system). It will also throw if the copy or move
3530  * constructor of a bound argument throws and it is not a reference
3531  * argument.
3532  */
3533 template <class... FreeArgs>
3534 CallbackArg<FreeArgs...>* make_ref(std::function<void(FreeArgs...)>&& f) {
3535  return new Callback_function<FreeArgs...>{std::move(f)};
3536 }
3537 
3538 // This helper function to construct Callback_lambda objects could be
3539 // implemented as a further overload of Callback::make(). No best
3540 // match ambiguities would arise, because even when Callback::make()
3541 // is passed a function pointer without bound arguments, the overload
3542 // of Callback::make taking a function pointer (as opposed to a
3543 // generic callable object) would still comprise the best match.
3544 // However, to construct Callback_lambda objects, the unbound
3545 // arguments need to be specified by hand, which doesn't happen with
3546 // Callback::make() (it would only be necessary to specify an explicit
3547 // type where a mutable reference argument is to be bound to the
3548 // callback object). It seems to me to be less confusing to the user
3549 // therefore to have a separate Callback::lambda() helper function.
3550 // However, if you disagree please let me know.
3551 
3552 // template parameter packs do not need to be placed last in the case
3553 // of function templates, as type deduction is available for the last
3554 // parameter: there is in fact no function parameter pack in
3555 // Callback::lambda() (function parameter packs must come last).
3556 /**
3557  * A convenience function to make Callback::CallbackArg objects from
3558  * C++11 lambda expressions, or from any other arbitrary callable
3559  * object. The types of the unbound arguments (if any) must be
3560  * explicitly specified as template parameters, as they cannot be
3561  * deduced. From version 2.0.10, this function can be called for
3562  * lambda expressions which are declared mutable (in version 2.0.9,
3563  * this function could only be called for non-mutable lambda
3564  * expressions).
3565  * @exception std::bad_alloc It might throw std::bad_alloc if memory
3566  * is exhausted and the system throws in that case (this exception
3567  * will not be thrown if the library has been installed using the
3568  * --with-glib-memory-slices-no-compat configuration option: instead
3569  * glib will terminate the program if it is unable to obtain memory
3570  * from the operating system). It will also throw if the copy or move
3571  * constructor of an object captured by the lambda expression throws.
3572  *
3573  * Since 2.0.9
3574  */
3575 template <class... FreeArgs, class Lambda>
3576 CallbackArg<FreeArgs...>* lambda(Lambda&& l) {
3577  return new Callback_lambda<Lambda, FreeArgs...>{std::forward<Lambda>(l)};
3578 }
3579 
3580 } // namespace Callback
3581 
3582 class Releaser;
3583 
3584 namespace Callback {
3585 
3586 /**
3587  * Posts a callback for execution by a glib main loop. It is
3588  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
3589  * has been called. glib >= 2.32 does not require g_thread_init() to
3590  * be called. This function will not throw.
3591  * @param cb The callback object. Ownership is taken of this object,
3592  * and it will be deleted when it has been finished with.
3593  * @param priority The priority to be given to the callback in the
3594  * main loop. In ascending order of priorities, priorities are
3595  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
3596  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
3597  * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the
3598  * callback will appear in the event list in the main loop, not the
3599  * priority which the OS will adopt
3600  * @param context The glib main loop context in which the callback is
3601  * to be executed (the default of NULL will cause the callback to be
3602  * executed in the main program loop, and this is usually what is
3603  * wanted).
3604  * @note Cancellation of the receiving thread is blocked when the
3605  * callback executes.
3606  */
3607 void post(const Callback* cb, gint priority = G_PRIORITY_DEFAULT_IDLE,
3608  GMainContext* context = 0);
3609 
3610 /**
3611  * Posts a callback for execution by a glib main loop. It is
3612  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
3613  * has been called. glib >= 2.32 does not require g_thread_init() to
3614  * be called. This function will not throw.
3615  * @param cb The callback object. Ownership is taken of this object,
3616  * and it will be deleted when it has been finished with.
3617  * @param r A Releaser object for automatic disconnection of the
3618  * callback from the main loop.
3619  * @param priority The priority to be given to the callback in the
3620  * main loop. In ascending order of priorities, priorities are
3621  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
3622  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
3623  * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the
3624  * callback will appear in the event list in the main loop, not the
3625  * priority which the OS will adopt.
3626  * @param context The glib main loop context in which the callback is
3627  * to be executed (the default of NULL will cause the callback to be
3628  * executed in the main program loop, and this is usually what is
3629  * wanted).
3630  * @exception std::bad_alloc This function might throw std::bad_alloc
3631  * if memory is exhausted and the system throws in that case. If it
3632  * does so, the Callback object will be disposed of.
3633  * @exception Cgu::Thread::MutexError This method might throw
3634  * Cgu:Thread::MutexError if initialisation of the mutex in a
3635  * SafeEmitterArg object constructed by this method fails. If it does
3636  * so, the Callback object will be disposed of. (It is often not
3637  * worth checking for this exception, as it means either memory is
3638  * exhausted or pthread has run out of other resources to create new
3639  * mutexes.)
3640  * @note 1. Cancellation of the receiving thread is blocked when the
3641  * callback executes.
3642  * @note 2. By virtue of the Releaser object, it is in theory possible
3643  * (if memory is exhausted and the system throws in that case) that an
3644  * internal SafeEmitterArg object will throw std::bad_alloc when
3645  * emitting/executing the callback in the glib main loop, with the
3646  * result that the relevant callback will not execute (instead the
3647  * exception will be consumed and a g_critical() warning will be
3648  * issued). This is rarely of any relevance because glib will abort
3649  * the program if it is itself unable to obtain memory from the
3650  * operating system. However, where it is relevant, design the
3651  * program so that it is not necessary to provide a releaser object.
3652  */
3653 void post(const Callback* cb, Releaser& r,
3654  gint priority = G_PRIORITY_DEFAULT_IDLE, GMainContext* context = 0);
3655 
3656 } // namespace Callback
3657 
3658 } // namespace Cgu
3659 
3660 #endif