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