c++-gtk-utils
callback.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 to 2013 Chris Vine
2 
3 The library comprised in this file or of which this file is part is
4 distributed by Chris Vine under the GNU Lesser General Public
5 License as follows:
6 
7  This library is free software; you can redistribute it and/or
8  modify it under the terms of the GNU Lesser General Public License
9  as published by the Free Software Foundation; either version 2.1 of
10  the License, or (at your option) any later version.
11 
12  This library is distributed in the hope that it will be useful, but
13  WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  Lesser General Public License, version 2.1, for more details.
16 
17  You should have received a copy of the GNU Lesser General Public
18  License, version 2.1, along with this library (see the file LGPL.TXT
19  which came with this source code package in the c++-gtk-utils
20  sub-directory); if not, write to the Free Software Foundation, Inc.,
21  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22 
23 However, it is not intended that the object code of a program whose
24 source code instantiates a template from this file or uses macros or
25 inline functions (of any length) should by reason only of that
26 instantiation or use be subject to the restrictions of use in the GNU
27 Lesser General Public License. With that in mind, the words "and
28 macros, inline functions and instantiations of templates (of any
29 length)" shall be treated as substituted for the words "and small
30 macros and small inline functions (ten lines or less in length)" in
31 the fourth paragraph of section 5 of that licence. This does not
32 affect any other reason why object code may be subject to the
33 restrictions in that licence (nor for the avoidance of doubt does it
34 affect the application of section 2 of that licence to modifications
35 of the source code in this file).
36 
37 */
38 
39 #ifndef CGU_CALLBACK_H
40 #define CGU_CALLBACK_H
41 
42 /**
43  * @file callback.h
44  * @brief This file provides classes for type erasure.
45  *
46  * \#include <c++-gtk-utils/callback.h>
47  *
48  * These classes provide type erasure on callable objects. They
49  * comprise a generic callback creation and execution interface for
50  * closures. There is a basic Callback::Callback type, which is an
51  * entire closure or 'thunk', where all values are bound into the
52  * object, and is completely opaque. Callback::CallbackArg<T...> is a
53  * class which takes unbound arguments of the template types when the
54  * object is dispatched. (The opaque Callback::Callback type is a
55  * typedef for Callback::CallbackArg<>: the two types are
56  * interchangeable.)
57  *
58  * The classes are normally constructed using the Callback::lambda()
59  * factory function, which takes any callable object such as a lambda
60  * expression or the return value of std::bind and returns a pointer
61  * to a Callback or CallbackArg object. When using
62  * Callback::lambda(), the unbound arguments (if any) must be passed
63  * as explicit template parameters.
64  *
65  * Callback/CallbackArg objects can also be constructed using the
66  * Callback::make() and Callback::make_ref() factory functions, which
67  * can be useful where invoking standalone functions or object
68  * methods.
69  *
70  * The Callback::make() and Callback::make_ref() functions
71  * -------------------------------------------------------
72  *
73  * The Callback::make() and Callback::make_ref() functions construct a
74  * Callback/CallbackArg object from a function pointer (or an object
75  * reference and member function pointer) together with bound
76  * arguments. They provide for a maximum of five bound arguments, and
77  * the unbound arguments (if any) must be the last (trailing)
78  * arguments of the relevant function or method to be called.
79  *
80  * Callback::make() does a direct type mapping from the bound
81  * arguments of the function or method represented by the callback
82  * object to the arguments stored by it and is for use when all bound
83  * arguments are simple fundamental types such as pointers (including
84  * C strings), integers or floating points.
85  *
86  * Callback::make_ref() is for use where bound arguments include class
87  * types or one or more of the types of the bound arguments include a
88  * const reference. It will accomplish perfect forwarding (by lvalue
89  * reference or rvalue reference) when constructing the callback and
90  * will also ensure that a copy of any object to be passed by const
91  * reference (as well as any taken by value) is kept in order to avoid
92  * dangling references. Note however that where a member function is
93  * called, the object of which the target function is a member must
94  * still be in existence when the Callback/CallbackArg object is
95  * dispatched and, unlike Callback::make(), Callback::make_ref()
96  * cannot be used with overloaded functions except with explicit
97  * disambiguation.
98  *
99  * Callback::make() can also construct a Callback/CallbackArg object
100  * from a std::function object.
101  *
102  * Callback::FunctorArg and Callback::SafeFunctorArg classes
103  * ---------------------------------------------------------
104  *
105  * Functor/FunctorArg objects hold a Callback/CallbackArg object by
106  * SharedPtr to enable them to be shared by reference counting, and
107  * SafeFunctor/SafeFunctorArg objects hold them by SharedLockPtr,
108  * which have a thread safe reference count so that they may be shared
109  * between different threads. These classes also have an operator()()
110  * method so as to be callable with function syntax.
111  *
112  * Memory allocation
113  * -----------------
114  *
115  * If the library is installed using the
116  * \--with-glib-memory-slices-no-compat configuration option, any
117  * Callback/CallbackArg object will be constructed in glib memory
118  * slices rather than in the generic C++ free store.
119  *
120  * Usage
121  * -----
122  *
123  * Using Callback::lambda():
124  *
125  * @code
126  * using namespace Cgu;
127  *
128  * // here cb1 is of type Callback::Callback*
129  * auto cb1 = Callback::lambda<>([] () {std::cout << "Hello world\n";});
130  * cb1->dispatch();
131  * delete cb1;
132  *
133  * // the same using Callback::Functor
134  * Callback::Functor f1{Callback::lambda<>([] () {std::cout << "Hello world\n";})};
135  * f1();
136  *
137  * // here cb2 is of type Callback::CallbackArg<int, int&>*
138  * auto cb2 = Callback::lambda<int, int&>([] (int i, int& j) {j = 10 * i;});
139  * int res;
140  * cb2->dispatch(2, res);
141  * std::cout << "10 times 2 is " << res << '\n';
142  * delete cb2;
143  *
144  * // the same using Callback::FunctorArg
145  * Callback::FunctorArg<int, int&> f2{Callback::lambda<int, int&>([] (int i, int& j) {j = 10 * i;})};
146  * f2(2, res);
147  * std::cout << "10 times 2 is " << res << '\n';
148  * @endcode
149  *
150  * Using Callback::make(), with a class object my_obj of type MyClass,
151  * with a method void MyClass::my_method(int, int, const char*):
152  *
153  * @code
154  * using namespace Cgu;
155  *
156  * int arg1 = 1, arg2 = 5;
157  * // here cb1 is of type Callback::Callback*
158  * auto cb1 = Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n");
159  * cb1->dispatch();
160  * delete cb1;
161  *
162  * // the same using Callback::Functor
163  * Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")};
164  * f();
165  *
166  * int arg1 = 1, arg2 = 5;
167  * // cb2 is of type Callback::CallbackArg<int, const char*>*
168  * auto cb = Callback::make(my_obj, &MyClass::my_method, arg1);
169  * cb->dispatch(arg2, "Hello\n");
170  * delete cb;
171  *
172  * // the same using Callback::FunctorArg
173  * Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)};
174  * f(arg2, "Hello\n");
175  * @endcode
176  *
177  * Using Callback::make_ref(), with a class object my_obj of type
178  * MyClass, with a method void MyClass::my_method(int, const
179  * Something&):
180  *
181  * @code
182  * int arg1 = 1;
183  * Something arg2;
184  * // here cb is of type Callback::Callback*
185  * auto cb = Callback::make_ref(my_obj, &MyClass::my_method, arg1, arg2);
186  * @endcode
187  *
188  * Posting of callbacks
189  * --------------------
190  *
191  * This file also provides Callback::post() functions which will
192  * execute a callback in a glib main loop and can be used (amongst
193  * other things) to pass an event from a worker thread to the main
194  * program thread. In that respect, it provides an alternative to the
195  * Notifier class. It is passed either a pointer to a
196  * Callback::Callback object created with a call to Callback::lambda()
197  * (or Callback::make(), Callback::make_ref()), or it can be passed a
198  * callable object and the implementation will call Callback::lambda()
199  * for you.
200  *
201  * To provide for thread-safe automatic disconnection of the callback
202  * if the object whose method it represents or calls into is destroyed
203  * before the callback executes in the main loop, include a Releaser
204  * as a public member of that object and pass the Releaser object as
205  * the second argument of Callback::post(). Note that for this to be
206  * race free, the lifetime of the remote object whose method is to be
207  * invoked must be determined by the thread to whose main loop the
208  * callback has been attached. When the main loop begins invoking the
209  * execution of the callback, the remote object must either wholly
210  * exist (in which case the callback will be invoked) or have been
211  * destroyed (in which case the callback will be ignored), and not be
212  * in some transient half-state governed by another thread.
213  *
214  * Advantages as against Notifier:
215  *
216  * 1. If there are a lot of different events requiring callbacks to be
217  * dispatched in the program from worker threads to the main
218  * thread, this avoids having separate Notifier objects for each
219  * event.
220  * 2. It is easier to pass arguments with varying values - they can be
221  * passed as arguments to the Callback::make functions and no
222  * special synchronisation is normally required (the call to
223  * g_source_attach() invokes locking of the main loop which will
224  * have the effect of ensuring memory visibility). With a Notifier
225  * object it may be necessary to use an asynchronous queue to pass
226  * variable values (or to bind a reference to the data, thus
227  * normally requiring separate synchronisation).
228  * 3. Although the callback would normally be sent for execution by
229  * the main program loop, and that is the default, it can be sent
230  * for execution by any thread which has its own
231  * GMainContext/GMainLoop objects. Thus callbacks can be passed
232  * for execution between worker threads, or from the main program
233  * thread to worker threads, as well as from worker threads to the
234  * main program thread.
235  *
236  * Disadvantages as against Notifier:
237  *
238  * 1. Less efficient, as a new callback object has to be created on
239  * freestore every time the callback is invoked, together with a
240  * new Emitter object if a Releaser is used to track the callback.
241  * 2. Multiple callbacks relevant to a single event cannot be invoked
242  * from a single call for the event - each callback has to be
243  * separately dispatched.
244  */
245 
246 /**
247  * @namespace Cgu::Callback
248  * @brief This namespace provides classes for type erasure.
249  *
250  * \#include <c++-gtk-utils/callback.h>
251  *
252  * These classes provide type erasure on callable objects. They
253  * comprise a generic callback creation and execution interface for
254  * closures. There is a basic Callback::Callback type, which is an
255  * entire closure or 'thunk', where all values are bound into the
256  * object, and is completely opaque. Callback::CallbackArg<T...> is a
257  * class which takes unbound arguments of the template types when the
258  * object is dispatched. (The opaque Callback::Callback type is a
259  * typedef for Callback::CallbackArg<>: the two types are
260  * interchangeable.)
261  *
262  * The classes are normally constructed using the Callback::lambda()
263  * factory function, which takes any callable object such as a lambda
264  * expression or the return value of std::bind and returns a pointer
265  * to a Callback or CallbackArg object. When using
266  * Callback::lambda(), the unbound arguments (if any) must be passed
267  * as explicit template parameters.
268  *
269  * Callback/CallbackArg objects can also be constructed using the
270  * Callback::make() and Callback::make_ref() factory functions, which
271  * can be useful where invoking standalone functions or object
272  * methods.
273  *
274  * The Callback::make() and Callback::make_ref() functions
275  * -------------------------------------------------------
276  *
277  * The Callback::make() and Callback::make_ref() functions construct a
278  * Callback/CallbackArg object from a function pointer (or an object
279  * reference and member function pointer) together with bound
280  * arguments. They provide for a maximum of five bound arguments, and
281  * the unbound arguments (if any) must be the last (trailing)
282  * arguments of the relevant function or method to be called.
283  *
284  * Callback::make() does a direct type mapping from the bound
285  * arguments of the function or method represented by the callback
286  * object to the arguments stored by it and is for use when all bound
287  * arguments are simple fundamental types such as pointers (including
288  * C strings), integers or floating points.
289  *
290  * Callback::make_ref() is for use where bound arguments include class
291  * types or one or more of the types of the bound arguments include a
292  * const reference. It will accomplish perfect forwarding (by lvalue
293  * reference or rvalue reference) when constructing the callback and
294  * will also ensure that a copy of any object to be passed by const
295  * reference (as well as any taken by value) is kept in order to avoid
296  * dangling references. Note however that where a member function is
297  * called, the object of which the target function is a member must
298  * still be in existence when the Callback/CallbackArg object is
299  * dispatched and, unlike Callback::make(), Callback::make_ref()
300  * cannot be used with overloaded functions except with explicit
301  * disambiguation.
302  *
303  * Callback::make() can also construct a Callback/CallbackArg object
304  * from a std::function object.
305  *
306  * Callback::FunctorArg and Callback::SafeFunctorArg classes
307  * ---------------------------------------------------------
308  *
309  * Functor/FunctorArg objects hold a Callback/CallbackArg object by
310  * SharedPtr to enable them to be shared by reference counting, and
311  * SafeFunctor/SafeFunctorArg objects hold them by SharedLockPtr,
312  * which have a thread safe reference count so that they may be shared
313  * between different threads. These classes also have an operator()()
314  * method so as to be callable with function syntax.
315  *
316  * Memory allocation
317  * -----------------
318  *
319  * If the library is installed using the
320  * \--with-glib-memory-slices-no-compat configuration option, any
321  * Callback/CallbackArg object will be constructed in glib memory
322  * slices rather than in the generic C++ free store.
323  *
324  * Usage
325  * -----
326  *
327  * Using Callback::lambda():
328  *
329  * @code
330  * using namespace Cgu;
331  *
332  * // here cb1 is of type Callback::Callback*
333  * auto cb1 = Callback::lambda<>([] () {std::cout << "Hello world\n";});
334  * cb1->dispatch();
335  * delete cb1;
336  *
337  * // the same using Callback::Functor
338  * Callback::Functor f1{Callback::lambda<>([] () {std::cout << "Hello world\n";})};
339  * f1();
340  *
341  * // here cb2 is of type Callback::CallbackArg<int, int&>*
342  * auto cb2 = Callback::lambda<int, int&>([] (int i, int& j) {j = 10 * i;});
343  * int res;
344  * cb2->dispatch(2, res);
345  * std::cout << "10 times 2 is " << res << '\n';
346  * delete cb2;
347  *
348  * // the same using Callback::FunctorArg
349  * Callback::FunctorArg<int, int&> f2{Callback::lambda<int, int&>([] (int i, int& j) {j = 10 * i;})};
350  * f2(2, res);
351  * std::cout << "10 times 2 is " << res << '\n';
352  * @endcode
353  *
354  * Using Callback::make(), with a class object my_obj of type MyClass,
355  * with a method void MyClass::my_method(int, int, const char*):
356  *
357  * @code
358  * using namespace Cgu;
359  *
360  * int arg1 = 1, arg2 = 5;
361  * // here cb1 is of type Callback::Callback*
362  * auto cb1 = Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n");
363  * cb1->dispatch();
364  * delete cb1;
365  *
366  * // the same using Callback::Functor
367  * Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")};
368  * f();
369  *
370  * int arg1 = 1, arg2 = 5;
371  * // cb2 is of type Callback::CallbackArg<int, const char*>*
372  * auto cb = Callback::make(my_obj, &MyClass::my_method, arg1);
373  * cb->dispatch(arg2, "Hello\n");
374  * delete cb;
375  *
376  * // the same using Callback::FunctorArg
377  * Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)};
378  * f(arg2, "Hello\n");
379  * @endcode
380  *
381  * Using Callback::make_ref(), with a class object my_obj of type
382  * MyClass, with a method void MyClass::my_method(int, const
383  * Something&):
384  *
385  * @code
386  * int arg1 = 1;
387  * Something arg2;
388  * // here cb is of type Callback::Callback*
389  * auto cb = Callback::make_ref(my_obj, &MyClass::my_method, arg1, arg2);
390  * @endcode
391  *
392  * Posting of callbacks
393  * --------------------
394  *
395  * This namespace also provides Callback::post() functions which will
396  * execute a callback in a glib main loop and can be used (amongst
397  * other things) to pass an event from a worker thread to the main
398  * program thread. In that respect, it provides an alternative to the
399  * Notifier class. It is passed either a pointer to a
400  * Callback::Callback object created with a call to Callback::lambda()
401  * (or Callback::make(), Callback::make_ref()), or it can be passed a
402  * callable object and the implementation will call Callback::lambda()
403  * for you.
404  *
405  * To provide for thread-safe automatic disconnection of the callback
406  * if the object whose method it represents or calls into is destroyed
407  * before the callback executes in the main loop, include a Releaser
408  * as a public member of that object and pass the Releaser object as
409  * the second argument of Callback::post(). Note that for this to be
410  * race free, the lifetime of the remote object whose method is to be
411  * invoked must be determined by the thread to whose main loop the
412  * callback has been attached. When the main loop begins invoking the
413  * execution of the callback, the remote object must either wholly
414  * exist (in which case the callback will be invoked) or have been
415  * destroyed (in which case the callback will be ignored), and not be
416  * in some transient half-state governed by another thread.
417  *
418  * Advantages as against Notifier:
419  *
420  * 1. If there are a lot of different events requiring callbacks to be
421  * dispatched in the program from worker threads to the main
422  * thread, this avoids having separate Notifier objects for each
423  * event.
424  * 2. It is easier to pass arguments with varying values - they can be
425  * passed as arguments to the Callback::make functions and no
426  * special synchronisation is normally required (the call to
427  * g_source_attach() invokes locking of the main loop which will
428  * have the effect of ensuring memory visibility). With a Notifier
429  * object it may be necessary to use an asynchronous queue to pass
430  * variable values (or to bind a reference to the data, thus
431  * normally requiring separate synchronisation).
432  * 3. Although the callback would normally be sent for execution by
433  * the main program loop, and that is the default, it can be sent
434  * for execution by any thread which has its own
435  * GMainContext/GMainLoop objects. Thus callbacks can be passed
436  * for execution between worker threads, or from the main program
437  * thread to worker threads, as well as from worker threads to the
438  * main program thread.
439  *
440  * Disadvantages as against Notifier:
441  *
442  * 1. Less efficient, as a new callback object has to be created on
443  * freestore every time the callback is invoked, together with a
444  * new Emitter object if a Releaser is used to track the callback.
445  * 2. Multiple callbacks relevant to a single event cannot be invoked
446  * from a single call for the event - each callback has to be
447  * separately dispatched.
448  */
449 
450 #include <functional> // for std::less, std::function and std::hash<T*>
451 #include <utility> // for std::move and std::forward
452 #include <cstddef> // for std::size_t
453 #include <type_traits> // for std::remove_reference, std::remove_const and std::enable_if
454 
455 #include <glib.h>
456 
458 #include <c++-gtk-utils/param.h>
460 
461 namespace Cgu {
462 
463 namespace Callback {
464 
465 /*
466  The CallbackArg class could be additionally templated to provide a
467  return value, but that would affect the simplicity of the
468  interface, and if a case were to arise where a result is needed, an
469  alternative is for users to pass an argument by reference or
470  pointer (or pointer to pointer) rather than have a return value.
471 */
472 
473 /* Declare the two basic interface types */
474 
475 template <class... FreeArgs> class CallbackArg;
476 typedef CallbackArg<> Callback;
477 
478 /* now the class definitions */
479 
480 /**
481  * @class CallbackArg callback.h c++-gtk-utils/callback.h
482  * @brief The callback interface class
483  * @sa Callback namespace
484  * @sa FunctorArg SafeFunctorArg
485  *
486  * This class provides type erasure for callable objects. The
487  * CallbackArg type is constructed on free store and can wrap any
488  * callable object, such as a lambda expression or the return value of
489  * std::bind.
490  *
491  * The class is particularly relevant where a callable object with
492  * bound values needs to be handed safely between threads, or in other
493  * cases where a callback object has to be passed by pointer (which
494  * will happen at some stage with glib or pthreads). They are
495  * therefore useful for general event passing when used together with
496  * the Callback::post() functions or as the continuation for GIO async
497  * operations, and are more efficient than constructing std::function
498  * objects on free store and passing them by pointer (they avoid one
499  * level of indirection and only require one rather than two
500  * allocations).
501  *
502  * The classes are also used in the Emitter/EmitterArg and
503  * SafeEmitter/SafeEmitterArg classes in emitter.h, which enable
504  * callable objects to be connected to an emitter and provide for
505  * automatic disconnection where a class object whose member a
506  * callback represents or calls into ceases to exist. They are also
507  * used internally to implement the Thread::Future and
508  * Thread::TaskManager classes.
509  *
510  * The template types are the types of the unbound arguments, if any.
511  * Callback::CallbackArg<> is typedef'ed to Callback::Callback. The
512  * main method of constructing a Callback/CallbackArg object is with
513  * the Callback::lambda() factory function. When using
514  * Callback::lambda(), the unbound arguments (if any) must be passed
515  * as explicit template parameters.
516  *
517  * Callback/CallbackArg classes do not provide for a return value. If
518  * a result is wanted, users should pass an unbound argument by
519  * reference or pointer (or pointer to pointer).
520  *
521  * The 2.2 series of the library generally dispenses with the need to
522  * create objects explicitly using Callback::lambda() when calling
523  * into the library itself: all the library interfaces which take a
524  * Callback/CallbackArg object also now provide an overload which
525  * takes any callable object as a template type, and the
526  * implementation calls Callback::lambda() internally for you.
527  *
528  * @b Usage
529  *
530  * These are examples:
531  *
532  * @code
533  * using namespace Cgu;
534  *
535  * // here cb1 is of type Callback::Callback*
536  * auto cb1 = Callback::lambda<>([] () {std::cout << "Hello world\n";});
537  * cb1->dispatch();
538  * delete cb1;
539  *
540  * // here cb2 is of type Callback::CallbackArg<int, int&>*
541  * auto cb2 = Callback::lambda<int, int&>([] (int i, int& j) {j = 10 * i;});
542  * int res;
543  * cb2->dispatch(2, res);
544  * std::cout << "10 times 2 is " << res << '\n';
545  * delete cb2;
546  * @endcode
547  *
548  * For further background, including about the Callback::make(),
549  * Callback::make_ref() functions, read this: Callback
550  */
551 
552 template <class... FreeArgs>
553 class CallbackArg {
554 public:
555 /* Because dispatch() is a virtual function, we cannot templatise it
556  * with a view to preserving r-value forwarding of temporary objects
557  * passed as a free argument. But this would rarely be relevant
558  * anyway - it would only be relevant if the target function were to
559  * take an argument by r-value reference and a temporary were to be
560  * passed to it. In such a case virtual dispatch is at the cost of a
561  * copy of the temporary.
562  */
563 /**
564  * This will execute the referenced function, callable object or class
565  * method encapsulated by this class. It will only throw if the
566  * dispatched function, callable object or class method throws, or if
567  * the copy constructor of a free or bound argument throws and it is
568  * not a reference argument. It is thread safe if the referenced
569  * function or class method is thread safe.
570  * @param args The unbound arguments to be passed to the referenced
571  * function, callable object or class method, if any.
572  * @note We use dispatch() to execute the callback, because the
573  * callback would normally be invoked through a base class pointer.
574  * To invoke it through operator()(), use the FunctorArg or
575  * SafeFunctorArg wrapper class.
576  */
577  virtual void dispatch(typename Cgu::Param<FreeArgs>::ParamType... args) const = 0;
578 
579 /**
580  * The constructor will not throw unless the copy constructor of an
581  * argument bound to the derived implementation class throws.
582  */
584 
585 /**
586  * The destructor will not throw unless the destructor of an argument
587  * bound to the derived implementation class throws.
588  */
589  virtual ~CallbackArg() {}
590 
591 /* these functions will be inherited by the derived callback classes */
592 #ifdef CGU_USE_GLIB_MEMORY_SLICES_NO_COMPAT
594 #endif
595 };
596 
597 /* The four basic functor types */
598 
599 template <class... FreeArgs> class FunctorArg;
600 template <class... FreeArgs> class SafeFunctorArg;
601 typedef FunctorArg<> Functor;
603 
604 /* Functor friend functions */
605 
606 // we can use built-in operator == when comparing pointers referencing
607 // different objects of the same type
608 /**
609  * Two FunctorArg objects compare equal if the addresses of the
610  * CallbackArg objects they contain are the same. This comparison
611  * operator does not throw.
612  */
613 template <class... T>
614 bool operator==(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) {
615  return (f1.cb_s.get() == f2.cb_s.get());
616 }
617 
618 /**
619  * Two FunctorArg objects compare unequal if the addresses of the
620  * CallbackArg objects they contain are not the same. This comparison
621  * operator does not throw.
622  */
623 template <class... T>
624 bool operator!=(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) {
625  return !(f1 == f2);
626 }
627 
628 // we must use std::less rather than the < built-in operator for
629 // pointers to objects not within the same array or object: "For
630 // templates greater, less, greater_equal, and less_equal, the
631 // specializations for any pointer type yield a total order, even if
632 // the built-in operators <, >, <=, >= do not." (para 20.3.3/8).
633 /**
634  * One FunctorArg object is less than another if the address of the
635  * CallbackArg object contained by the first is regarded by std::less
636  * as less than the address of the CallbackArg object contained by the
637  * other. This comparison operator does not throw.
638  */
639 template <class... T>
640 bool operator<(const FunctorArg<T...>& f1, const FunctorArg<T...>& f2) {
641  return std::less<const CallbackArg<T...>*>()(f1.cb_s.get(), f2.cb_s.get());
642 }
643 
644 /**
645  * Two SafeFunctorArg objects compare equal if the addresses of the
646  * CallbackArg objects they contain are the same. This comparison
647  * operator does not throw.
648  */
649 template <class... T>
651  return (f1.cb_s.get() == f2.cb_s.get());
652 }
653 
654 /**
655  * Two SafeFunctorArg objects compare unequal if the addresses of the
656  * CallbackArg objects they contain are not the same. This comparison
657  * operator does not throw.
658  */
659 template <class... T>
661  return !(f1 == f2);
662 }
663 
664 /**
665  * One SafeFunctorArg object is less than another if the address of
666  * the CallbackArg object contained by the first is regarded by
667  * std::less as less than the address of the CallbackArg object
668  * contained by the other. This comparison operator does not throw.
669  */
670 template <class... T>
672  return std::less<const CallbackArg<T...>*>()(f1.cb_s.get(), f2.cb_s.get());
673 }
674 
675 } // namespace Callback
676 } // namespace Cgu
677 
678 // doxygen produces long filenames that tar can't handle:
679 // we have generic documentation for std::hash specialisations
680 // in doxygen.main.in
681 #ifndef DOXYGEN_PARSING
682 
683 /* These structs allow FunctorArg and SafeFunctorArg objects to be
684  keys in unordered associative containers */
685 namespace std {
686 template <class... T>
687 struct hash<Cgu::Callback::FunctorArg<T...>> {
688  typedef std::size_t result_type;
689  typedef Cgu::Callback::FunctorArg<T...> argument_type;
690  result_type operator()(const argument_type& f) const {
691  // this is fine: std::hash structs do not normally contain data and
692  // std::hash<T*> certainly won't, so we don't have overhead constructing
693  // std::hash<T*> on the fly
694  return std::hash<const Cgu::Callback::CallbackArg<T...>*>()(f.cb_s.get());
695  }
696 };
697 template <class... T>
698 struct hash<Cgu::Callback::SafeFunctorArg<T...>> {
699  typedef std::size_t result_type;
700  typedef Cgu::Callback::SafeFunctorArg<T...> argument_type;
701  result_type operator()(const argument_type& f) const {
702  // this is fine: std::hash structs do not normally contain data and
703  // std::hash<T*> certainly won't, so we don't have overhead constructing
704  // std::hash<T*> on the fly
705  return std::hash<const Cgu::Callback::CallbackArg<T...>*>()(f.cb_s.get());
706  }
707 };
708 } // namespace std
709 
710 #endif // DOXYGEN_PARSING
711 
712 namespace Cgu {
713 namespace Callback {
714 
715 /* the functor classes */
716 
717 /**
718  * @class FunctorArg callback.h c++-gtk-utils/callback.h
719  * @brief Functor class holding a Callback::CallbackArg object.
720  * @sa SafeFunctorArg
721  * @sa Callback namespace
722  *
723  * This class wraps a CallbackArg object. The callback object is kept
724  * by SharedPtr so the functor can be copied and offers automatic
725  * lifetime management of the wrapped callback object, as well as
726  * providing an operator()() function. Ownership is taken of the
727  * CallbackArg object passed to the constructor taking a CallbackArg
728  * pointer, so that constructor should be treated like a shared
729  * pointer constructor - only pass a newly allocated object to it (or
730  * copy construct it or assign to it from another existing FunctorArg
731  * object). The template types are the types of the unbound
732  * arguments, if any. Callback::FunctorArg<> is typedef'ed to
733  * Callback::Functor.
734  *
735  * The constructor taking a Callback::CallbackArg pointer is not
736  * marked explicit, so the results of Callback::lambda(),
737  * Callback::make() or Callback::make_ref() can be passed directly to
738  * a function taking a Callback::FunctorArg argument, and implicit
739  * conversion will take place.
740  *
741  * Functor/FunctorArg classes do not provide for a return value. If
742  * a result is wanted, users should pass an unbound argument by
743  * reference or pointer (or pointer to pointer).
744  *
745  * @b Usage
746  *
747  * These are examples:
748  *
749  * @code
750  * using namespace Cgu;
751  *
752  * Callback::Functor f1{Callback::lambda<>([] () {std::cout << "Hello world\n";})};
753  * f1();
754  *
755  * int res;
756  * Callback::FunctorArg<int, int&> f2{Callback::lambda<int, int&>([] (int i, int& j) {j = 10 * i;})};
757  * f2(2, res);
758  * std::cout << "10 times 2 is " << res << '\n';
759  * @endcode
760  *
761  * For further background, including about the Callback::make(),
762  * Callback::make_ref() functions, read this: Callback
763  */
764 
765 template <class... FreeArgs>
766 class FunctorArg {
767  SharedPtr<const CallbackArg<FreeArgs...>> cb_s;
768 public:
769 /* Because CallbackArg::dispatch() is a virtual function, it is
770  * pointless templatising this function with a view to preserving
771  * r-value forwarding of temporary objects passed as a free argument,
772  * because the r-value typeness will be discarded in dispatch(). But
773  * this would rarely be relevant anyway - it would only be relevant if
774  * the target function were to take an argument by r-value reference
775  * and a temporary were to be passed to it. In such a case virtual
776  * dispatch is at the cost of a copy of the temporary.
777  */
778 /**
779  * This will execute the function, callable object or class method
780  * represented by the callback encapsulated by this object, or do
781  * nothing if this object has not been initialized with a callback.
782  * It will only throw if the executed function, callable object or
783  * class method throws, or if the copy constructor of a free or bound
784  * argument throws and it is not a reference argument. It is thread
785  * safe if the referenced function or class method is thread safe.
786  * @param args The unbound arguments to be passed to the referenced
787  * function, callable object or class method, if any.
788  */
789  void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const {
790  if (cb_s.get()) cb_s->dispatch(args...);
791  }
792 
793 /**
794  * This function does not throw.
795  * @param f The assignor.
796  * @return The functor object after assignment.
797  */
798  FunctorArg& operator=(const FunctorArg& f) {cb_s = f.cb_s; return *this;}
799 
800 /**
801  * This function does not throw.
802  * @param f The functor to be moved.
803  * @return The functor object after the move operation.
804  */
805  FunctorArg& operator=(FunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;}
806 
807 /**
808  * Two FunctorArg objects compare equal if the addresses of the
809  * CallbackArg objects they contain are the same. This comparison
810  * operator does not throw.
811  */
812  friend bool operator== <>(const FunctorArg&, const FunctorArg&);
813 
814 /**
815  * One FunctorArg object is less than another if the address of the
816  * CallbackArg object contained by the first is regarded by std::less
817  * as less than the address of the CallbackArg object contained by the
818  * other. This comparison operator does not throw.
819  */
820  friend bool operator< <>(const FunctorArg&, const FunctorArg&);
821 
822  friend struct std::hash<FunctorArg>;
823 
824 /**
825  * Constructor of first FunctorArg holding the referenced callback.
826  * As it is not marked explicit, it is also a type conversion
827  * constructor.
828  * @param cb The CallbackArg object which the functor is to manage.
829  * @exception std::bad_alloc This might throw std::bad_alloc if
830  * memory is exhausted and the system throws in that case. Note that
831  * if such an exception is thrown, then this constructor will clean
832  * itself up and also delete the callback object passed to it.
833  * @note std::bad_alloc will not be thrown if the library has been
834  * installed using the \--with-glib-memory-slices-no-compat
835  * configuration option: instead glib will terminate the program if it
836  * is unable to obtain memory from the operating system.
837  */
838  FunctorArg(const CallbackArg<FreeArgs...>* cb): cb_s(cb) {}
839 
840 /**
841  * The copy constructor does not throw.
842  * @param f The assignor
843  */
844  FunctorArg(const FunctorArg& f): cb_s(f.cb_s) {}
845 
846 /**
847  * The move constructor does not throw.
848  * @param f The functor to be moved.
849  */
850  FunctorArg(FunctorArg&& f): cb_s(std::move(f.cb_s)) {}
851 
852  /**
853  * Default constructor, where a Callback::CallbackArg object is to be
854  * assigned later (via the type conversion constructor and/or the
855  * assignment operator). This constructor does not throw.
856  */
858 
859 /* Only has effect if --with-glib-memory-slices-compat or
860  --with-glib-memory-slices-no-compat option picked */
862 };
863 
864 /**
865  * @class SafeFunctorArg callback.h c++-gtk-utils/callback.h
866  * @brief Functor class holding a Callback::CallbackArg object, with
867  * thread-safe reference count.
868  * @sa FunctorArg
869  * @sa Callback namespace
870  *
871  * This class is the same as Callback::FunctorArg except that it will
872  * provide synchronisation of the reference count between threads.
873  * Use it where a functor wrapper object is to be passed between
874  * threads. The FunctorArg documentation gives details on usage.
875  *
876  * Callback::SafeFunctorArg<> is typedef'ed to Callback::SafeFunctor.
877  *
878  * For further background, read this: Callback
879  */
880 
881 template <class... FreeArgs>
882 class SafeFunctorArg {
883  SharedLockPtr<const CallbackArg<FreeArgs...>> cb_s;
884 public:
885 /**
886  * This will execute the function, callable object or class method
887  * represented by the callback encapsulated by this object, or do
888  * nothing if this object has not been initialized with a callback.
889  * It will only throw if the executed function, callable object or
890  * class method throws, or if the copy constructor of a free or bound
891  * argument throws and it is not a reference argument. It is thread
892  * safe if the referenced function or class method is thread safe.
893  * @param args The unbound arguments to be passed to the referenced
894  * function, callable object or class method, if any.
895  */
896  void operator()(typename Cgu::Param<FreeArgs>::ParamType... args) const {
897  if (cb_s.get()) cb_s->dispatch(args...);
898  }
899 
900 /**
901  * This function does not throw.
902  * @param f The assignor.
903  * @return The functor object after assignment.
904  */
905  SafeFunctorArg& operator=(const SafeFunctorArg& f) {cb_s = f.cb_s; return *this;}
906 
907 /**
908  * This function does not throw.
909  * @param f The functor to be moved.
910  * @return The functor object after the move operation.
911  */
912  SafeFunctorArg& operator=(SafeFunctorArg&& f) {cb_s = std::move(f.cb_s); return *this;}
913 
914 /**
915  * Two SafeFunctorArg objects compare equal if the addresses of the
916  * CallbackArg objects they contain are the same. This comparison
917  * operator does not throw.
918  */
919  friend bool operator== <>(const SafeFunctorArg&, const SafeFunctorArg&);
920 
921 /**
922  * One SafeFunctorArg object is less than another if the address of
923  * the CallbackArg object contained by the first is regarded by
924  * std::less as less than the address of the CallbackArg object
925  * contained by the other. This comparison operator does not throw.
926  */
927  friend bool operator< <>(const SafeFunctorArg&, const SafeFunctorArg&);
928 
929  friend struct std::hash<SafeFunctorArg>;
930 
931  /**
932  * Constructor of first SafeFunctorArg holding the referenced
933  * callback. As it is not marked explicit, it is also a type
934  * conversion constructor.
935  * @param cb The CallbackArg object which the functor is to manage.
936  * @exception std::bad_alloc This might throw std::bad_alloc if
937  * memory is exhausted and the system throws in that case. Note that
938  * if such an exception is thrown, then this constructor will clean
939  * itself up and also delete the callback object passed to it.
940  * @note std::bad_alloc will not be thrown if the library has been
941  * installed using the \--with-glib-memory-slices-no-compat
942  * configuration option: instead glib will terminate the program if it
943  * is unable to obtain memory from the operating system.
944  */
945  SafeFunctorArg(const CallbackArg<FreeArgs...>* cb): cb_s(cb) {}
946 
947 /**
948  * The copy constructor does not throw.
949  * @param f The assignor.
950  */
951  SafeFunctorArg(const SafeFunctorArg& f): cb_s(f.cb_s) {}
952 
953 /**
954  * The move constructor does not throw.
955  * @param f The functor to be moved.
956  */
957  SafeFunctorArg(SafeFunctorArg&& f): cb_s(std::move(f.cb_s)) {}
958 
959  /**
960  * Default constructor, where a Callback::CallbackArg object is to be
961  * assigned later (via the type conversion constructor and/or the
962  * assignment operator). This constructor does not throw.
963  * @note The reference count maintained with respect to the contained
964  * callback object is thread-safe, so SafeFunctorArg objects may be
965  * copied between threads by the implicit assignment operator and put
966  * in different containers in different threads. They use a
967  * SharedLockPtr object to hold the referenced callback object.
968  */
970 
971 /* Only has effect if --with-glib-memory-slices-compat or
972  --with-glib-memory-slices-no-compat option picked */
974 };
975 
976 /* the callback implementation classes */
977 
978 template <class T, class... FreeArgs>
979 class Callback0: public CallbackArg<FreeArgs...> {
980 public:
981  typedef void (T::* MemFunc)(FreeArgs...);
982 private:
983  T* obj;
984  MemFunc func;
985 public:
986  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
987  (obj->*func)(free_args...);
988  }
989  Callback0(T& obj_, MemFunc func_): obj(&obj_), func(func_) {}
990 };
991 
992 template <bool unref, class T, class BoundArg, class... FreeArgs>
993 class Callback1: public CallbackArg<FreeArgs...> {
994 public:
995  typedef void (T::* MemFunc)(BoundArg, FreeArgs...);
996 private:
997  T* obj;
998  MemFunc func;
1000 public:
1001  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1002  (obj->*func)(arg, free_args...);
1003  }
1004  template <class Arg>
1005  Callback1(T& obj_, MemFunc func_,
1006  Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {}
1007 };
1008 
1009 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs>
1010 class Callback2: public CallbackArg<FreeArgs...> {
1011 public:
1012  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...);
1013 private:
1014  T* obj;
1015  MemFunc func;
1018 public:
1019  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1020  (obj->*func)(arg1, arg2, free_args...);
1021  }
1022  template <class Arg1, class Arg2>
1023  Callback2(T& obj_, MemFunc func_,
1024  Arg1&& arg1_,
1025  Arg2&& arg2_): obj(&obj_), func(func_),
1026  arg1(std::forward<Arg1>(arg1_)),
1027  arg2(std::forward<Arg2>(arg2_)) {}
1028 };
1029 
1030 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1031 class Callback3: public CallbackArg<FreeArgs...> {
1032 public:
1033  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...);
1034 private:
1035  T* obj;
1036  MemFunc func;
1040 public:
1041  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1042  (obj->*func)(arg1, arg2, arg3, free_args...);
1043  }
1044  template <class Arg1, class Arg2, class Arg3>
1045  Callback3(T& obj_, MemFunc func_,
1046  Arg1&& arg1_,
1047  Arg2&& arg2_,
1048  Arg3&& arg3_):
1049  obj(&obj_), func(func_),
1050  arg1(std::forward<Arg1>(arg1_)),
1051  arg2(std::forward<Arg2>(arg2_)),
1052  arg3(std::forward<Arg3>(arg3_)) {}
1053 };
1054 
1055 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1056  class BoundArg4, class... FreeArgs>
1057 class Callback4: public CallbackArg<FreeArgs...> {
1058 public:
1059  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...);
1060 private:
1061  T* obj;
1062  MemFunc func;
1067 public:
1068  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1069  (obj->*func)(arg1, arg2, arg3, arg4, free_args...);
1070  }
1071  template <class Arg1, class Arg2, class Arg3, class Arg4>
1072  Callback4(T& obj_, MemFunc func_,
1073  Arg1&& arg1_,
1074  Arg2&& arg2_,
1075  Arg3&& arg3_,
1076  Arg4&& arg4_):
1077  obj(&obj_), func(func_),
1078  arg1(std::forward<Arg1>(arg1_)),
1079  arg2(std::forward<Arg2>(arg2_)),
1080  arg3(std::forward<Arg3>(arg3_)),
1081  arg4(std::forward<Arg4>(arg4_)) {}
1082 };
1083 
1084 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1085  class BoundArg4, class BoundArg5, class... FreeArgs>
1086 class Callback5: public CallbackArg<FreeArgs...> {
1087 public:
1088  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3,
1089  BoundArg4, BoundArg5, FreeArgs...);
1090 private:
1091  T* obj;
1092  MemFunc func;
1098 public:
1099  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1100  (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...);
1101  }
1102  template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
1103  Callback5(T& obj_, MemFunc func_,
1104  Arg1&& arg1_,
1105  Arg2&& arg2_,
1106  Arg3&& arg3_,
1107  Arg4&& arg4_,
1108  Arg5&& arg5_):
1109  obj(&obj_), func(func_),
1110  arg1(std::forward<Arg1>(arg1_)),
1111  arg2(std::forward<Arg2>(arg2_)),
1112  arg3(std::forward<Arg3>(arg3_)),
1113  arg4(std::forward<Arg4>(arg4_)),
1114  arg5(std::forward<Arg5>(arg5_)) {}
1115 };
1116 
1117 /* const versions, for binding to const methods */
1118 
1119 template <class T, class... FreeArgs>
1120 class Callback0_const: public CallbackArg<FreeArgs...> {
1121 public:
1122  typedef void (T::* MemFunc)(FreeArgs...) const;
1123 private:
1124  const T* obj;
1125  MemFunc func;
1126 public:
1127  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1128  (obj->*func)(free_args...);
1129  }
1130  Callback0_const(const T& obj_, MemFunc func_): obj(&obj_), func(func_) {}
1131 };
1132 
1133 template <bool unref, class T, class BoundArg, class... FreeArgs>
1134 class Callback1_const: public CallbackArg<FreeArgs...> {
1135 public:
1136  typedef void (T::* MemFunc)(BoundArg, FreeArgs...) const;
1137 private:
1138  const T* obj;
1139  MemFunc func;
1141 public:
1142  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1143  (obj->*func)(arg, free_args...);
1144  }
1145  template <class Arg>
1146  Callback1_const(const T& obj_, MemFunc func_,
1147  Arg&& arg_): obj(&obj_), func(func_), arg(std::forward<Arg>(arg_)) {}
1148 };
1149 
1150 template <bool unref, class T, class BoundArg1, class BoundArg2, class... FreeArgs>
1151 class Callback2_const: public CallbackArg<FreeArgs...> {
1152 public:
1153  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, FreeArgs...) const;
1154 private:
1155  const T* obj;
1156  MemFunc func;
1159 public:
1160  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1161  (obj->*func)(arg1, arg2, free_args...);
1162  }
1163  template <class Arg1, class Arg2>
1164  Callback2_const(const T& obj_, MemFunc func_,
1165  Arg1&& arg1_,
1166  Arg2&& arg2_): obj(&obj_), func(func_),
1167  arg1(std::forward<Arg1>(arg1_)),
1168  arg2(std::forward<Arg2>(arg2_)) {}
1169 };
1170 
1171 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1172 class Callback3_const: public CallbackArg<FreeArgs...> {
1173 public:
1174  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const;
1175 private:
1176  const T* obj;
1177  MemFunc func;
1181 public:
1182  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1183  (obj->*func)(arg1, arg2, arg3, free_args...);
1184  }
1185  template <class Arg1, class Arg2, class Arg3>
1186  Callback3_const(const T& obj_, MemFunc func_,
1187  Arg1&& arg1_,
1188  Arg2&& arg2_,
1189  Arg3&& arg3_):
1190  obj(&obj_), func(func_),
1191  arg1(std::forward<Arg1>(arg1_)),
1192  arg2(std::forward<Arg2>(arg2_)),
1193  arg3(std::forward<Arg3>(arg3_)) {}
1194 };
1195 
1196 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1197  class BoundArg4, class... FreeArgs>
1198 class Callback4_const: public CallbackArg<FreeArgs...> {
1199 public:
1200  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const;
1201 private:
1202  const T* obj;
1203  MemFunc func;
1208 public:
1209  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1210  (obj->*func)(arg1, arg2, arg3, arg4, free_args...);
1211  }
1212  template <class Arg1, class Arg2, class Arg3, class Arg4>
1213  Callback4_const(const T& obj_, MemFunc func_,
1214  Arg1&& arg1_,
1215  Arg2&& arg2_,
1216  Arg3&& arg3_,
1217  Arg4&& arg4_):
1218  obj(&obj_), func(func_),
1219  arg1(std::forward<Arg1>(arg1_)),
1220  arg2(std::forward<Arg2>(arg2_)),
1221  arg3(std::forward<Arg3>(arg3_)),
1222  arg4(std::forward<Arg4>(arg4_)) {}
1223 };
1224 
1225 template <bool unref, class T, class BoundArg1, class BoundArg2, class BoundArg3,
1226  class BoundArg4, class BoundArg5, class... FreeArgs>
1227 class Callback5_const: public CallbackArg<FreeArgs...> {
1228 public:
1229  typedef void (T::* MemFunc)(BoundArg1, BoundArg2, BoundArg3,
1230  BoundArg4, BoundArg5, FreeArgs...) const;
1231 private:
1232  const T* obj;
1233  MemFunc func;
1239 public:
1240  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1241  (obj->*func)(arg1, arg2, arg3, arg4, arg5, free_args...);
1242  }
1243  template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
1244  Callback5_const(const T& obj_, MemFunc func_,
1245  Arg1&& arg1_,
1246  Arg2&& arg2_,
1247  Arg3&& arg3_,
1248  Arg4&& arg4_,
1249  Arg5&& arg5_):
1250  obj(&obj_), func(func_),
1251  arg1(std::forward<Arg1>(arg1_)),
1252  arg2(std::forward<Arg2>(arg2_)),
1253  arg3(std::forward<Arg3>(arg3_)),
1254  arg4(std::forward<Arg4>(arg4_)),
1255  arg5(std::forward<Arg5>(arg5_)) {}
1256 };
1257 
1258 /* for static class methods and non-class functions */
1259 
1260 template <class... FreeArgs>
1261 class Callback0_static: public CallbackArg<FreeArgs...> {
1262 public:
1263  typedef void (*Func)(FreeArgs...);
1264 private:
1265  Func func;
1266 public:
1267  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1268  func(free_args...);
1269  }
1270  Callback0_static(Func func_): func(func_) {}
1271 };
1272 
1273 template <bool unref, class BoundArg, class... FreeArgs>
1274 class Callback1_static: public CallbackArg<FreeArgs...> {
1275 public:
1276  typedef void (*Func)(BoundArg, FreeArgs...);
1277 private:
1278  Func func;
1280 public:
1281  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1282  func(arg, free_args...);
1283  }
1284  template <class Arg>
1285  Callback1_static(Func func_, Arg&& arg_): func(func_), arg(std::forward<Arg>(arg_)) {}
1286 };
1287 
1288 template <bool unref, class BoundArg1, class BoundArg2, class... FreeArgs>
1289 class Callback2_static: public CallbackArg<FreeArgs...> {
1290 public:
1291  typedef void (*Func)(BoundArg1, BoundArg2, FreeArgs...);
1292 private:
1293  Func func;
1296 public:
1297  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1298  func(arg1, arg2, free_args...);
1299  }
1300  template <class Arg1, class Arg2>
1301  Callback2_static(Func func_, Arg1&& arg1_,
1302  Arg2&& arg2_): func(func_),
1303  arg1(std::forward<Arg1>(arg1_)),
1304  arg2(std::forward<Arg2>(arg2_)) {}
1305 };
1306 
1307 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1308 class Callback3_static: public CallbackArg<FreeArgs...> {
1309 public:
1310  typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...);
1311 private:
1312  Func func;
1316 public:
1317  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1318  func(arg1, arg2, arg3, free_args...);
1319  }
1320  template <class Arg1, class Arg2, class Arg3>
1322  Arg1&& arg1_,
1323  Arg2&& arg2_,
1324  Arg3&& arg3_):
1325  func(func_),
1326  arg1(std::forward<Arg1>(arg1_)),
1327  arg2(std::forward<Arg2>(arg2_)),
1328  arg3(std::forward<Arg3>(arg3_)) {}
1329 };
1330 
1331 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3,
1332  class BoundArg4, class... FreeArgs>
1333 class Callback4_static: public CallbackArg<FreeArgs...> {
1334 public:
1335  typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...);
1336 private:
1337  Func func;
1342 public:
1343  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1344  func(arg1, arg2, arg3, arg4, free_args...);
1345  }
1346  template <class Arg1, class Arg2, class Arg3, class Arg4>
1348  Arg1&& arg1_,
1349  Arg2&& arg2_,
1350  Arg3&& arg3_,
1351  Arg4&& arg4_):
1352  func(func_),
1353  arg1(std::forward<Arg1>(arg1_)),
1354  arg2(std::forward<Arg2>(arg2_)),
1355  arg3(std::forward<Arg3>(arg3_)),
1356  arg4(std::forward<Arg4>(arg4_)) {}
1357 };
1358 
1359 template <bool unref, class BoundArg1, class BoundArg2, class BoundArg3,
1360  class BoundArg4, class BoundArg5, class... FreeArgs>
1361 class Callback5_static: public CallbackArg<FreeArgs...> {
1362 public:
1363  typedef void (*Func)(BoundArg1, BoundArg2, BoundArg3,
1364  BoundArg4, BoundArg5, FreeArgs...);
1365 private:
1366  Func func;
1372 public:
1373  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {
1374  func(arg1, arg2, arg3, arg4, arg5, free_args...);
1375  }
1376  template <class Arg1, class Arg2, class Arg3, class Arg4, class Arg5>
1378  Arg1&& arg1_,
1379  Arg2&& arg2_,
1380  Arg3&& arg3_,
1381  Arg4&& arg4_,
1382  Arg5&& arg5_):
1383  func(func_),
1384  arg1(std::forward<Arg1>(arg1_)),
1385  arg2(std::forward<Arg2>(arg2_)),
1386  arg3(std::forward<Arg3>(arg3_)),
1387  arg4(std::forward<Arg4>(arg4_)),
1388  arg5(std::forward<Arg5>(arg5_)) {}
1389 };
1390 
1391 // generic class for callable objects such as lambdas
1392 template <class Lambda, class... FreeArgs>
1393 class Callback_lambda: public CallbackArg<FreeArgs...> {
1394  // making 'l' mutable means that Callback_lamdba objects can contain
1395  // mutable lambda expressions
1396  mutable Lambda l;
1397 public:
1398  void dispatch(typename Cgu::Param<FreeArgs>::ParamType... free_args) const {l(free_args...);}
1399  template <class L> Callback_lambda(L&& l_): l(std::forward<L>(l_)) {}
1400 };
1401 
1402 /* Convenience functions making callback objects on freestore. These
1403  * can for example be passed as the first argument of the
1404  * Thread::start() method in thread.h. They are also used by the
1405  * Callback::post() function.
1406 */
1407 
1408 /**
1409  * A convenience function to make Callback::CallbackArg objects
1410  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1411  * is exhausted and the system throws in that case. This exception
1412  * will not be thrown if the library has been installed using the
1413  * \--with-glib-memory-slices-no-compat configuration option (instead
1414  * glib will terminate the program if it is unable to obtain memory
1415  * from the operating system).
1416  */
1417 template <class T, class... FreeArgs>
1418 CallbackArg<FreeArgs...>* make(T& t,
1419  void (T::*func)(FreeArgs...)) {
1420  return new Callback0<T, FreeArgs...>{t, func};
1421 }
1422 
1423 /**
1424  * Since this function constructs a callback which does not take a
1425  * bound argument, it is a synonym for make() (the two are identical).
1426  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1427  * is exhausted and the system throws in that case. This exception
1428  * will not be thrown if the library has been installed using the
1429  * \--with-glib-memory-slices-no-compat configuration option (instead
1430  * glib will terminate the program if it is unable to obtain memory
1431  * from the operating system).
1432  *
1433  * Since 2.0.0-rc3
1434  */
1435 template <class T, class... FreeArgs>
1436 CallbackArg<FreeArgs...>* make_ref(T& t,
1437  void (T::*func)(FreeArgs...)) {
1438  return new Callback0<T, FreeArgs...>{t, func};
1439 }
1440 
1441 /**
1442  * A convenience function to make Callback::CallbackArg objects
1443  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1444  * is exhausted and the system throws in that case (this exception
1445  * will not be thrown if the library has been installed using the
1446  * \--with-glib-memory-slices-no-compat configuration option: instead
1447  * glib will terminate the program if it is unable to obtain memory
1448  * from the operating system). It will also throw if the copy
1449  * constructor of a bound argument throws and it is not a reference
1450  * argument.
1451  */
1452 template <class T, class BoundArg, class... FreeArgs>
1453 CallbackArg<FreeArgs...>* make(T& t,
1454  void (T::*func)(BoundArg, FreeArgs...),
1455  BoundArg arg) {
1456  return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg};
1457 }
1458 
1459 /**
1460  * An alternative function to make Callback::CallbackArg objects,
1461  * which is for use where a target function either receives a class
1462  * type bound argument by value, or receives a bound argument by
1463  * reference to const in a case where the generated CallbackArg object
1464  * is to store a copy of that argument instead of just keeping a
1465  * reference.
1466  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1467  * is exhausted and the system throws in that case (this exception
1468  * will not be thrown if the library has been installed using the
1469  * \--with-glib-memory-slices-no-compat configuration option: instead
1470  * glib will terminate the program if it is unable to obtain memory
1471  * from the operating system). It will also throw if the copy or move
1472  * constructor of a bound argument throws.
1473  *
1474  * Since 2.0.0-rc3
1475  */
1476 template <class T, class BoundArg, class Arg, class... FreeArgs>
1477 CallbackArg<FreeArgs...>* make_ref(T& t,
1478  void (T::*func)(BoundArg, FreeArgs...),
1479  Arg&& arg) {
1480  return new Callback1<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)};
1481 }
1482 
1483 /**
1484  * A convenience function to make Callback::CallbackArg objects
1485  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1486  * is exhausted and the system throws in that case (this exception
1487  * will not be thrown if the library has been installed using the
1488  * \--with-glib-memory-slices-no-compat configuration option: instead
1489  * glib will terminate the program if it is unable to obtain memory
1490  * from the operating system). It will also throw if the copy
1491  * constructor of a bound argument throws and it is not a reference
1492  * argument.
1493  */
1494 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
1495 CallbackArg<FreeArgs...>* make(T& t,
1496  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
1497  BoundArg1 arg1,
1498  BoundArg2 arg2) {
1499  return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
1500 }
1501 
1502 /**
1503  * An alternative function to make Callback::CallbackArg objects,
1504  * which is for use where a target function either receives a class
1505  * type bound argument by value, or receives a bound argument by
1506  * reference to const in a case where the generated CallbackArg object
1507  * is to store a copy of that argument instead of just keeping a
1508  * reference.
1509  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1510  * is exhausted and the system throws in that case (this exception
1511  * will not be thrown if the library has been installed using the
1512  * \--with-glib-memory-slices-no-compat configuration option: instead
1513  * glib will terminate the program if it is unable to obtain memory
1514  * from the operating system). It will also throw if the copy or move
1515  * constructor of a bound argument throws.
1516  *
1517  * Since 2.0.0-rc3
1518  */
1519 template <class T, class BoundArg1, class BoundArg2,
1520  class Arg1, class Arg2, class... FreeArgs>
1521 CallbackArg<FreeArgs...>* make_ref(T& t,
1522  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
1523  Arg1&& arg1,
1524  Arg2&& arg2) {
1525  return new Callback2<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func,
1526  std::forward<Arg1>(arg1),
1527  std::forward<Arg2>(arg2)};
1528 }
1529 
1530 /**
1531  * A convenience function to make Callback::CallbackArg objects
1532  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1533  * is exhausted and the system throws in that case (this exception
1534  * will not be thrown if the library has been installed using the
1535  * \--with-glib-memory-slices-no-compat configuration option: instead
1536  * glib will terminate the program if it is unable to obtain memory
1537  * from the operating system). It will also throw if the copy
1538  * constructor of a bound argument throws and it is not a reference
1539  * argument.
1540  */
1541 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1542 CallbackArg<FreeArgs...>* make(T& t,
1543  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
1544  BoundArg1 arg1,
1545  BoundArg2 arg2,
1546  BoundArg3 arg3) {
1547  return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
1548 }
1549 
1550 /**
1551  * An alternative function to make Callback::CallbackArg objects,
1552  * which is for use where a target function either receives a class
1553  * type bound argument by value, or receives a bound argument by
1554  * reference to const in a case where the generated CallbackArg object
1555  * is to store a copy of that argument instead of just keeping a
1556  * reference.
1557  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1558  * is exhausted and the system throws in that case (this exception
1559  * will not be thrown if the library has been installed using the
1560  * \--with-glib-memory-slices-no-compat configuration option: instead
1561  * glib will terminate the program if it is unable to obtain memory
1562  * from the operating system). It will also throw if the copy or move
1563  * constructor of a bound argument throws.
1564  *
1565  * Since 2.0.0-rc3
1566  */
1567 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
1568  class Arg1, class Arg2, class Arg3, class... FreeArgs>
1569 CallbackArg<FreeArgs...>* make_ref(T& t,
1570  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
1571  Arg1&& arg1,
1572  Arg2&& arg2,
1573  Arg3&& arg3) {
1574  return new Callback3<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func,
1575  std::forward<Arg1>(arg1),
1576  std::forward<Arg2>(arg2),
1577  std::forward<Arg3>(arg3)};
1578 }
1579 
1580 /**
1581  * A convenience function to make Callback::CallbackArg objects
1582  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1583  * is exhausted and the system throws in that case (this exception
1584  * will not be thrown if the library has been installed using the
1585  * \--with-glib-memory-slices-no-compat configuration option: instead
1586  * glib will terminate the program if it is unable to obtain memory
1587  * from the operating system). It will also throw if the copy
1588  * constructor of a bound argument throws and it is not a reference
1589  * argument.
1590  */
1591 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
1592  class BoundArg4, class... FreeArgs>
1593 CallbackArg<FreeArgs...>* make(T& t,
1594  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
1595  BoundArg4, FreeArgs...),
1596  BoundArg1 arg1,
1597  BoundArg2 arg2,
1598  BoundArg3 arg3,
1599  BoundArg4 arg4) {
1600  return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3,
1601  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
1602 }
1603 
1604 /**
1605  * An alternative function to make Callback::CallbackArg objects,
1606  * which is for use where a target function either receives a class
1607  * type bound argument by value, or receives a bound argument by
1608  * reference to const in a case where the generated CallbackArg object
1609  * is to store a copy of that argument instead of just keeping a
1610  * reference.
1611  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1612  * is exhausted and the system throws in that case (this exception
1613  * will not be thrown if the library has been installed using the
1614  * \--with-glib-memory-slices-no-compat configuration option: instead
1615  * glib will terminate the program if it is unable to obtain memory
1616  * from the operating system). It will also throw if the copy or move
1617  * constructor of a bound argument throws.
1618  *
1619  * Since 2.0.0-rc3
1620  */
1621 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
1622  class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
1623 CallbackArg<FreeArgs...>* make_ref(T& t,
1624  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
1625  BoundArg4, FreeArgs...),
1626  Arg1&& arg1,
1627  Arg2&& arg2,
1628  Arg3&& arg3,
1629  Arg4&& arg4) {
1630  return new Callback4<true, T, BoundArg1, BoundArg2, BoundArg3,
1631  BoundArg4, FreeArgs...>{t, func,
1632  std::forward<Arg1>(arg1),
1633  std::forward<Arg2>(arg2),
1634  std::forward<Arg3>(arg3),
1635  std::forward<Arg4>(arg4)};
1636 }
1637 
1638 /**
1639  * A convenience function to make Callback::CallbackArg objects
1640  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1641  * is exhausted and the system throws in that case (this exception
1642  * will not be thrown if the library has been installed using the
1643  * \--with-glib-memory-slices-no-compat configuration option: instead
1644  * glib will terminate the program if it is unable to obtain memory
1645  * from the operating system). It will also throw if the copy
1646  * constructor of a bound argument throws and it is not a reference
1647  * argument.
1648  */
1649 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
1650  class BoundArg4, class BoundArg5, class... FreeArgs>
1651 CallbackArg<FreeArgs...>* make(T& t,
1652  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
1653  BoundArg4, BoundArg5, FreeArgs...),
1654  BoundArg1 arg1,
1655  BoundArg2 arg2,
1656  BoundArg3 arg3,
1657  BoundArg4 arg4,
1658  BoundArg5 arg5) {
1659  return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3,
1660  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
1661 }
1662 
1663 /**
1664  * An alternative function to make Callback::CallbackArg objects,
1665  * which is for use where a target function either receives a class
1666  * type bound argument by value, or receives a bound argument by
1667  * reference to const in a case where the generated CallbackArg object
1668  * is to store a copy of that argument instead of just keeping a
1669  * reference.
1670  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1671  * is exhausted and the system throws in that case (this exception
1672  * will not be thrown if the library has been installed using the
1673  * \--with-glib-memory-slices-no-compat configuration option: instead
1674  * glib will terminate the program if it is unable to obtain memory
1675  * from the operating system). It will also throw if the copy or move
1676  * constructor of a bound argument throws.
1677  *
1678  * Since 2.0.0-rc3
1679  */
1680 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
1681  class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
1682 CallbackArg<FreeArgs...>* make_ref(T& t,
1683  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
1684  BoundArg4, BoundArg5, FreeArgs...),
1685  Arg1&& arg1,
1686  Arg2&& arg2,
1687  Arg3&& arg3,
1688  Arg4&& arg4,
1689  Arg5&& arg5) {
1690  return new Callback5<true, T, BoundArg1, BoundArg2, BoundArg3,
1691  BoundArg4, BoundArg5, FreeArgs...>{t, func,
1692  std::forward<Arg1>(arg1),
1693  std::forward<Arg2>(arg2),
1694  std::forward<Arg3>(arg3),
1695  std::forward<Arg4>(arg4),
1696  std::forward<Arg5>(arg5)};
1697 }
1698 
1699 /* const versions, for binding to const methods */
1700 
1701 /**
1702  * A convenience function to make Callback::CallbackArg objects
1703  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1704  * is exhausted and the system throws in that case. This exception
1705  * will not be thrown if the library has been installed using the
1706  * \--with-glib-memory-slices-no-compat configuration option (instead
1707  * glib will terminate the program if it is unable to obtain memory
1708  * from the operating system).
1709  */
1710 template <class T, class... FreeArgs>
1711 CallbackArg<FreeArgs...>* make(const T& t,
1712  void (T::*func)(FreeArgs...) const) {
1713  return new Callback0_const<T, FreeArgs...>{t, func};
1714 }
1715 
1716 /**
1717  * Since this function constructs a callback which does not take a
1718  * bound argument, it is a synonym for make() (the two are identical).
1719  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1720  * is exhausted and the system throws in that case. This exception
1721  * will not be thrown if the library has been installed using the
1722  * \--with-glib-memory-slices-no-compat configuration option (instead
1723  * glib will terminate the program if it is unable to obtain memory
1724  * from the operating system).
1725  *
1726  * Since 2.0.0-rc3
1727  */
1728 template <class T, class... FreeArgs>
1729 CallbackArg<FreeArgs...>* make_ref(const T& t,
1730  void (T::*func)(FreeArgs...) const) {
1731  return new Callback0_const<T, FreeArgs...>{t, func};
1732 }
1733 
1734 /**
1735  * A convenience function to make Callback::CallbackArg objects
1736  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1737  * is exhausted and the system throws in that case (this exception
1738  * will not be thrown if the library has been installed using the
1739  * \--with-glib-memory-slices-no-compat configuration option: instead
1740  * glib will terminate the program if it is unable to obtain memory
1741  * from the operating system). It will also throw if the copy
1742  * constructor of a bound argument throws and it is not a reference
1743  * argument.
1744  */
1745 template <class T, class BoundArg, class... FreeArgs>
1746 CallbackArg<FreeArgs...>* make(const T& t,
1747  void (T::*func)(BoundArg, FreeArgs...) const,
1748  BoundArg arg) {
1749  return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg};
1750 }
1751 
1752 /**
1753  * An alternative function to make Callback::CallbackArg objects,
1754  * which is for use where a target function either receives a class
1755  * type bound argument by value, or receives a bound argument by
1756  * reference to const in a case where the generated CallbackArg object
1757  * is to store a copy of that argument instead of just keeping a
1758  * reference.
1759  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1760  * is exhausted and the system throws in that case (this exception
1761  * will not be thrown if the library has been installed using the
1762  * \--with-glib-memory-slices-no-compat configuration option: instead
1763  * glib will terminate the program if it is unable to obtain memory
1764  * from the operating system). It will also throw if the copy or move
1765  * constructor of a bound argument throws.
1766  *
1767  * Since 2.0.0-rc3
1768  */
1769 template <class T, class BoundArg, class Arg, class... FreeArgs>
1770 CallbackArg<FreeArgs...>* make_ref(const T& t,
1771  void (T::*func)(BoundArg, FreeArgs...) const,
1772  Arg&& arg) {
1773  return new Callback1_const<true, T, BoundArg, FreeArgs...>{t, func, std::forward<Arg>(arg)};
1774 }
1775 
1776 /**
1777  * A convenience function to make Callback::CallbackArg objects
1778  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1779  * is exhausted and the system throws in that case (this exception
1780  * will not be thrown if the library has been installed using the
1781  * \--with-glib-memory-slices-no-compat configuration option: instead
1782  * glib will terminate the program if it is unable to obtain memory
1783  * from the operating system). It will also throw if the copy
1784  * constructor of a bound argument throws and it is not a reference
1785  * argument.
1786  */
1787 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
1788 CallbackArg<FreeArgs...>* make(const T& t,
1789  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
1790  BoundArg1 arg1,
1791  BoundArg2 arg2) {
1792  return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
1793 }
1794 
1795 /**
1796  * An alternative function to make Callback::CallbackArg objects,
1797  * which is for use where a target function either receives a class
1798  * type bound argument by value, or receives a bound argument by
1799  * reference to const in a case where the generated CallbackArg object
1800  * is to store a copy of that argument instead of just keeping a
1801  * reference.
1802  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1803  * is exhausted and the system throws in that case (this exception
1804  * will not be thrown if the library has been installed using the
1805  * \--with-glib-memory-slices-no-compat configuration option: instead
1806  * glib will terminate the program if it is unable to obtain memory
1807  * from the operating system). It will also throw if the copy or move
1808  * constructor of a bound argument throws.
1809  *
1810  * Since 2.0.0-rc3
1811  */
1812 template <class T, class BoundArg1, class BoundArg2,
1813  class Arg1, class Arg2, class... FreeArgs>
1814 CallbackArg<FreeArgs...>* make_ref(const T& t,
1815  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
1816  Arg1&& arg1,
1817  Arg2&& arg2) {
1818  return new Callback2_const<true, T, BoundArg1, BoundArg2, FreeArgs...>{t, func,
1819  std::forward<Arg1>(arg1),
1820  std::forward<Arg2>(arg2)};
1821 }
1822 
1823 /**
1824  * A convenience function to make Callback::CallbackArg objects
1825  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1826  * is exhausted and the system throws in that case (this exception
1827  * will not be thrown if the library has been installed using the
1828  * \--with-glib-memory-slices-no-compat configuration option: instead
1829  * glib will terminate the program if it is unable to obtain memory
1830  * from the operating system). It will also throw if the copy
1831  * constructor of a bound argument throws and it is not a reference
1832  * argument.
1833  */
1834 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
1835 CallbackArg<FreeArgs...>* make(const T& t,
1836  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
1837  BoundArg1 arg1,
1838  BoundArg2 arg2,
1839  BoundArg3 arg3) {
1840  return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
1841 }
1842 
1843 /**
1844  * An alternative function to make Callback::CallbackArg objects,
1845  * which is for use where a target function either receives a class
1846  * type bound argument by value, or receives a bound argument by
1847  * reference to const in a case where the generated CallbackArg object
1848  * is to store a copy of that argument instead of just keeping a
1849  * reference.
1850  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1851  * is exhausted and the system throws in that case (this exception
1852  * will not be thrown if the library has been installed using the
1853  * \--with-glib-memory-slices-no-compat configuration option: instead
1854  * glib will terminate the program if it is unable to obtain memory
1855  * from the operating system). It will also throw if the copy or move
1856  * constructor of a bound argument throws.
1857  *
1858  * Since 2.0.0-rc3
1859  */
1860 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
1861  class Arg1, class Arg2, class Arg3, class... FreeArgs>
1862 CallbackArg<FreeArgs...>* make_ref(const T& t,
1863  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
1864  Arg1&& arg1,
1865  Arg2&& arg2,
1866  Arg3&& arg3) {
1867  return new Callback3_const<true, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func,
1868  std::forward<Arg1>(arg1),
1869  std::forward<Arg2>(arg2),
1870  std::forward<Arg3>(arg3)};
1871 }
1872 
1873 /**
1874  * A convenience function to make Callback::CallbackArg objects
1875  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1876  * is exhausted and the system throws in that case (this exception
1877  * will not be thrown if the library has been installed using the
1878  * \--with-glib-memory-slices-no-compat configuration option: instead
1879  * glib will terminate the program if it is unable to obtain memory
1880  * from the operating system). It will also throw if the copy
1881  * constructor of a bound argument throws and it is not a reference
1882  * argument.
1883  */
1884 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
1885  class BoundArg4, class... FreeArgs>
1886 CallbackArg<FreeArgs...>* make(const T& t,
1887  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
1888  BoundArg4, FreeArgs...) const,
1889  BoundArg1 arg1,
1890  BoundArg2 arg2,
1891  BoundArg3 arg3,
1892  BoundArg4 arg4) {
1893  return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3,
1894  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
1895 }
1896 
1897 /**
1898  * An alternative function to make Callback::CallbackArg objects,
1899  * which is for use where a target function either receives a class
1900  * type bound argument by value, or receives a bound argument by
1901  * reference to const in a case where the generated CallbackArg object
1902  * is to store a copy of that argument instead of just keeping a
1903  * reference.
1904  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1905  * is exhausted and the system throws in that case (this exception
1906  * will not be thrown if the library has been installed using the
1907  * \--with-glib-memory-slices-no-compat configuration option: instead
1908  * glib will terminate the program if it is unable to obtain memory
1909  * from the operating system). It will also throw if the copy or move
1910  * constructor of a bound argument throws.
1911  *
1912  * Since 2.0.0-rc3
1913  */
1914 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
1915  class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
1916 CallbackArg<FreeArgs...>* make_ref(const T& t,
1917  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
1918  BoundArg4, FreeArgs...) const,
1919  Arg1&& arg1,
1920  Arg2&& arg2,
1921  Arg3&& arg3,
1922  Arg4&& arg4) {
1923  return new Callback4_const<true, T, BoundArg1, BoundArg2, BoundArg3,
1924  BoundArg4, FreeArgs...>{t, func,
1925  std::forward<Arg1>(arg1),
1926  std::forward<Arg2>(arg2),
1927  std::forward<Arg3>(arg3),
1928  std::forward<Arg4>(arg4)};
1929 }
1930 
1931 /**
1932  * A convenience function to make Callback::CallbackArg objects
1933  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1934  * is exhausted and the system throws in that case (this exception
1935  * will not be thrown if the library has been installed using the
1936  * \--with-glib-memory-slices-no-compat configuration option: instead
1937  * glib will terminate the program if it is unable to obtain memory
1938  * from the operating system). It will also throw if the copy
1939  * constructor of a bound argument throws and it is not a reference
1940  * argument.
1941  */
1942 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
1943  class BoundArg4, class BoundArg5, class... FreeArgs>
1944 CallbackArg<FreeArgs...>* make(const T& t,
1945  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
1946  BoundArg4, BoundArg5, FreeArgs...) const,
1947  BoundArg1 arg1,
1948  BoundArg2 arg2,
1949  BoundArg3 arg3,
1950  BoundArg4 arg4,
1951  BoundArg5 arg5) {
1952  return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3,
1953  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
1954 }
1955 
1956 /**
1957  * An alternative function to make Callback::CallbackArg objects,
1958  * which is for use where a target function either receives a class
1959  * type bound argument by value, or receives a bound argument by
1960  * reference to const in a case where the generated CallbackArg object
1961  * is to store a copy of that argument instead of just keeping a
1962  * reference.
1963  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1964  * is exhausted and the system throws in that case (this exception
1965  * will not be thrown if the library has been installed using the
1966  * \--with-glib-memory-slices-no-compat configuration option: instead
1967  * glib will terminate the program if it is unable to obtain memory
1968  * from the operating system). It will also throw if the copy or move
1969  * constructor of a bound argument throws.
1970  *
1971  * Since 2.0.0-rc3
1972  */
1973 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
1974  class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
1975 CallbackArg<FreeArgs...>* make_ref(const T& t,
1976  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
1977  BoundArg4, BoundArg5, FreeArgs...) const,
1978  Arg1&& arg1,
1979  Arg2&& arg2,
1980  Arg3&& arg3,
1981  Arg4&& arg4,
1982  Arg5&& arg5) {
1983  return new Callback5_const<true, T, BoundArg1, BoundArg2, BoundArg3,
1984  BoundArg4, BoundArg5, FreeArgs...>{t, func,
1985  std::forward<Arg1>(arg1),
1986  std::forward<Arg2>(arg2),
1987  std::forward<Arg3>(arg3),
1988  std::forward<Arg4>(arg4),
1989  std::forward<Arg5>(arg5)};
1990 }
1991 
1992 /* for static class methods and non-class functions */
1993 
1994 /**
1995  * A convenience function to make Callback::CallbackArg objects
1996  * @exception std::bad_alloc It might throw std::bad_alloc if memory
1997  * is exhausted and the system throws in that case. This exception
1998  * will not be thrown if the library has been installed using the
1999  * \--with-glib-memory-slices-no-compat configuration option (instead
2000  * glib will terminate the program if it is unable to obtain memory
2001  * from the operating system).
2002  */
2003 template <class... FreeArgs>
2004 CallbackArg<FreeArgs...>* make(void (*func)(FreeArgs...)) {
2005  return new Callback0_static<FreeArgs...>{func};
2006 }
2007 
2008 /**
2009  * Since this function constructs a callback which does not take a
2010  * bound argument, it is a synonym for make() (the two are identical).
2011  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2012  * is exhausted and the system throws in that case. This exception
2013  * will not be thrown if the library has been installed using the
2014  * \--with-glib-memory-slices-no-compat configuration option (instead
2015  * glib will terminate the program if it is unable to obtain memory
2016  * from the operating system).
2017  *
2018  * Since 2.0.0-rc3
2019  */
2020 template <class... FreeArgs>
2021 CallbackArg<FreeArgs...>* make_ref(void (*func)(FreeArgs...)) {
2022  return new Callback0_static<FreeArgs...>{func};
2023 }
2024 
2025 /**
2026  * A convenience function to make Callback::CallbackArg objects
2027  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2028  * is exhausted and the system throws in that case (this exception
2029  * will not be thrown if the library has been installed using the
2030  * \--with-glib-memory-slices-no-compat configuration option: instead
2031  * glib will terminate the program if it is unable to obtain memory
2032  * from the operating system). It will also throw if the copy
2033  * constructor of a bound argument throws and it is not a reference
2034  * argument.
2035  */
2036 template <class BoundArg, class... FreeArgs>
2037 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg, FreeArgs...),
2038  BoundArg arg) {
2039  return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg};
2040 }
2041 
2042 /**
2043  * An alternative function to make Callback::CallbackArg objects,
2044  * which is for use where a target function either receives a class
2045  * type bound argument by value, or receives a bound argument by
2046  * reference to const in a case where the generated CallbackArg object
2047  * is to store a copy of that argument instead of just keeping a
2048  * reference.
2049  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2050  * is exhausted and the system throws in that case (this exception
2051  * will not be thrown if the library has been installed using the
2052  * \--with-glib-memory-slices-no-compat configuration option: instead
2053  * glib will terminate the program if it is unable to obtain memory
2054  * from the operating system). It will also throw if the copy or move
2055  * constructor of a bound argument throws.
2056  *
2057  * Since 2.0.0-rc3
2058  */
2059 template <class BoundArg, class Arg, class... FreeArgs>
2060 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg, FreeArgs...),
2061  Arg&& arg) {
2062  return new Callback1_static<true, BoundArg, FreeArgs...>{func, std::forward<Arg>(arg)};
2063 }
2064 
2065 /**
2066  * A convenience function to make Callback::CallbackArg objects
2067  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2068  * is exhausted and the system throws in that case (this exception
2069  * will not be thrown if the library has been installed using the
2070  * \--with-glib-memory-slices-no-compat configuration option: instead
2071  * glib will terminate the program if it is unable to obtain memory
2072  * from the operating system). It will also throw if the copy
2073  * constructor of a bound argument throws and it is not a reference
2074  * argument.
2075  */
2076 template <class BoundArg1, class BoundArg2, class... FreeArgs>
2077 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
2078  BoundArg1 arg1,
2079  BoundArg2 arg2) {
2080  return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2};
2081 }
2082 
2083 /**
2084  * An alternative function to make Callback::CallbackArg objects,
2085  * which is for use where a target function either receives a class
2086  * type bound argument by value, or receives a bound argument by
2087  * reference to const in a case where the generated CallbackArg object
2088  * is to store a copy of that argument instead of just keeping a
2089  * reference.
2090  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2091  * is exhausted and the system throws in that case (this exception
2092  * will not be thrown if the library has been installed using the
2093  * \--with-glib-memory-slices-no-compat configuration option: instead
2094  * glib will terminate the program if it is unable to obtain memory
2095  * from the operating system). It will also throw if the copy or move
2096  * constructor of a bound argument throws.
2097  *
2098  * Since 2.0.0-rc3
2099  */
2100 template <class BoundArg1, class BoundArg2, class Arg1, class Arg2, class... FreeArgs>
2101 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
2102  Arg1&& arg1,
2103  Arg2&& arg2) {
2104  return new Callback2_static<true, BoundArg1, BoundArg2, FreeArgs...>{func,
2105  std::forward<Arg1>(arg1),
2106  std::forward<Arg2>(arg2)};
2107 }
2108 
2109 /**
2110  * A convenience function to make Callback::CallbackArg objects
2111  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2112  * is exhausted and the system throws in that case (this exception
2113  * will not be thrown if the library has been installed using the
2114  * \--with-glib-memory-slices-no-compat configuration option: instead
2115  * glib will terminate the program if it is unable to obtain memory
2116  * from the operating system). It will also throw if the copy
2117  * constructor of a bound argument throws and it is not a reference
2118  * argument.
2119  */
2120 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2121 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2122  BoundArg1 arg1,
2123  BoundArg2 arg2,
2124  BoundArg3 arg3) {
2125  return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3};
2126 }
2127 
2128 /**
2129  * An alternative function to make Callback::CallbackArg objects,
2130  * which is for use where a target function either receives a class
2131  * type bound argument by value, or receives a bound argument by
2132  * reference to const in a case where the generated CallbackArg object
2133  * is to store a copy of that argument instead of just keeping a
2134  * reference.
2135  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2136  * is exhausted and the system throws in that case (this exception
2137  * will not be thrown if the library has been installed using the
2138  * \--with-glib-memory-slices-no-compat configuration option: instead
2139  * glib will terminate the program if it is unable to obtain memory
2140  * from the operating system). It will also throw if the copy or move
2141  * constructor of a bound argument throws.
2142  *
2143  * Since 2.0.0-rc3
2144  */
2145 template <class BoundArg1, class BoundArg2, class BoundArg3,
2146  class Arg1, class Arg2, class Arg3, class... FreeArgs>
2147 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2148  Arg1&& arg1,
2149  Arg2&& arg2,
2150  Arg3&& arg3) {
2151  return new Callback3_static<true, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func,
2152  std::forward<Arg1>(arg1),
2153  std::forward<Arg2>(arg2),
2154  std::forward<Arg3>(arg3)};
2155 }
2156 
2157 /**
2158  * A convenience function to make Callback::CallbackArg objects
2159  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2160  * is exhausted and the system throws in that case (this exception
2161  * will not be thrown if the library has been installed using the
2162  * \--with-glib-memory-slices-no-compat configuration option: instead
2163  * glib will terminate the program if it is unable to obtain memory
2164  * from the operating system). It will also throw if the copy
2165  * constructor of a bound argument throws and it is not a reference
2166  * argument.
2167  */
2168 template <class BoundArg1, class BoundArg2, class BoundArg3,
2169  class BoundArg4, class... FreeArgs>
2170 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3,
2171  BoundArg4, FreeArgs...),
2172  BoundArg1 arg1,
2173  BoundArg2 arg2,
2174  BoundArg3 arg3,
2175  BoundArg4 arg4) {
2176  return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3,
2177  BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4};
2178 }
2179 
2180 /**
2181  * An alternative function to make Callback::CallbackArg objects,
2182  * which is for use where a target function either receives a class
2183  * type bound argument by value, or receives a bound argument by
2184  * reference to const in a case where the generated CallbackArg object
2185  * is to store a copy of that argument instead of just keeping a
2186  * reference.
2187  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2188  * is exhausted and the system throws in that case (this exception
2189  * will not be thrown if the library has been installed using the
2190  * \--with-glib-memory-slices-no-compat configuration option: instead
2191  * glib will terminate the program if it is unable to obtain memory
2192  * from the operating system). It will also throw if the copy or move
2193  * constructor of a bound argument throws.
2194  *
2195  * Since 2.0.0-rc3
2196  */
2197 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4,
2198  class Arg1, class Arg2, class Arg3, class Arg4, class... FreeArgs>
2199 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3,
2200  BoundArg4, FreeArgs...),
2201  Arg1&& arg1,
2202  Arg2&& arg2,
2203  Arg3&& arg3,
2204  Arg4&& arg4) {
2205  return new Callback4_static<true, BoundArg1, BoundArg2, BoundArg3,
2206  BoundArg4, FreeArgs...>{func,
2207  std::forward<Arg1>(arg1),
2208  std::forward<Arg2>(arg2),
2209  std::forward<Arg3>(arg3),
2210  std::forward<Arg4>(arg4)};
2211 }
2212 
2213 /**
2214  * A convenience function to make Callback::CallbackArg objects
2215  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2216  * is exhausted and the system throws in that case (this exception
2217  * will not be thrown if the library has been installed using the
2218  * \--with-glib-memory-slices-no-compat configuration option: instead
2219  * glib will terminate the program if it is unable to obtain memory
2220  * from the operating system). It will also throw if the copy
2221  * constructor of a bound argument throws and it is not a reference
2222  * argument.
2223  */
2224 template <class BoundArg1, class BoundArg2, class BoundArg3,
2225  class BoundArg4, class BoundArg5, class... FreeArgs>
2226 CallbackArg<FreeArgs...>* make(void (*func)(BoundArg1, BoundArg2, BoundArg3,
2227  BoundArg4, BoundArg5, FreeArgs...),
2228  BoundArg1 arg1,
2229  BoundArg2 arg2,
2230  BoundArg3 arg3,
2231  BoundArg4 arg4,
2232  BoundArg5 arg5) {
2233  return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3,
2234  BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5};
2235 }
2236 
2237 /**
2238  * An alternative function to make Callback::CallbackArg objects,
2239  * which is for use where a target function either receives a class
2240  * type bound argument by value, or receives a bound argument by
2241  * reference to const in a case where the generated CallbackArg object
2242  * is to store a copy of that argument instead of just keeping a
2243  * reference.
2244  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2245  * is exhausted and the system throws in that case (this exception
2246  * will not be thrown if the library has been installed using the
2247  * \--with-glib-memory-slices-no-compat configuration option: instead
2248  * glib will terminate the program if it is unable to obtain memory
2249  * from the operating system). It will also throw if the copy or move
2250  * constructor of a bound argument throws.
2251  *
2252  * Since 2.0.0-rc3
2253  */
2254 template <class BoundArg1, class BoundArg2, class BoundArg3, class BoundArg4, class BoundArg5,
2255  class Arg1, class Arg2, class Arg3, class Arg4, class Arg5, class... FreeArgs>
2256 CallbackArg<FreeArgs...>* make_ref(void (*func)(BoundArg1, BoundArg2, BoundArg3,
2257  BoundArg4, BoundArg5, FreeArgs...),
2258  Arg1&& arg1,
2259  Arg2&& arg2,
2260  Arg3&& arg3,
2261  Arg4&& arg4,
2262  Arg5&& arg5) {
2263  return new Callback5_static<true, BoundArg1, BoundArg2, BoundArg3,
2264  BoundArg4, BoundArg5, FreeArgs...>{func,
2265  std::forward<Arg1>(arg1),
2266  std::forward<Arg2>(arg2),
2267  std::forward<Arg3>(arg3),
2268  std::forward<Arg4>(arg4),
2269  std::forward<Arg5>(arg5)};
2270 }
2271 
2272 /* for std::function objects */
2273 
2274 /**
2275  * A convenience function to make Callback::CallbackArg objects from
2276  * std::function objects.
2277  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2278  * is exhausted and the system throws in that case (this exception
2279  * will not be thrown if the library has been installed using the
2280  * \--with-glib-memory-slices-no-compat configuration option: instead
2281  * glib will terminate the program if it is unable to obtain memory
2282  * from the operating system). It will also throw if the copy
2283  * constructor of a bound argument throws and it is not a reference
2284  * argument.
2285  */
2286 template <class... FreeArgs>
2287 CallbackArg<FreeArgs...>* make(const std::function<void(FreeArgs...)>& f) {
2288  typedef std::function<void(FreeArgs...)> LType;
2289  return new Callback_lambda<LType, FreeArgs...>{f};
2290 }
2291 
2292 /**
2293  * A convenience function to make Callback::Callback objects from
2294  * std::function objects. Since this function takes no bound argument
2295  * (and bound arguments are bound into the std::function object), it
2296  * is a synonym for make() (the two are identical).
2297  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2298  * is exhausted and the system throws in that case (this exception
2299  * will not be thrown if the library has been installed using the
2300  * \--with-glib-memory-slices-no-compat configuration option: instead
2301  * glib will terminate the program if it is unable to obtain memory
2302  * from the operating system). It will also throw if the copy
2303  * constructor of a bound argument throws and it is not a reference
2304  * argument.
2305  */
2306 template <class... FreeArgs>
2307 CallbackArg<FreeArgs...>* make_ref(const std::function<void(FreeArgs...)>& f) {
2308  typedef std::function<void(FreeArgs...)> LType;
2309  return new Callback_lambda<LType, FreeArgs...>{f};
2310 }
2311 
2312 /**
2313  * A convenience function to make Callback::CallbackArg objects from
2314  * std::function objects.
2315  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2316  * is exhausted and the system throws in that case (this exception
2317  * will not be thrown if the library has been installed using the
2318  * \--with-glib-memory-slices-no-compat configuration option: instead
2319  * glib will terminate the program if it is unable to obtain memory
2320  * from the operating system). It will also throw if the copy
2321  * constructor of a bound argument throws and it is not a reference
2322  * argument.
2323  */
2324 template <class... FreeArgs>
2325 CallbackArg<FreeArgs...>* make(std::function<void(FreeArgs...)>&& f) {
2326  typedef std::function<void(FreeArgs...)> LType;
2327  return new Callback_lambda<LType, FreeArgs...>{std::move(f)};
2328 }
2329 
2330 /**
2331  * A convenience function to make Callback::Callback objects from
2332  * std::function objects. Since this function takes no bound argument
2333  * (and bound arguments are bound into the std::function object), it
2334  * is a synonym for make() (the two are identical).
2335  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2336  * is exhausted and the system throws in that case (this exception
2337  * will not be thrown if the library has been installed using the
2338  * \--with-glib-memory-slices-no-compat configuration option: instead
2339  * glib will terminate the program if it is unable to obtain memory
2340  * from the operating system). It will also throw if the copy or move
2341  * constructor of a bound argument throws and it is not a reference
2342  * argument.
2343  */
2344 template <class... FreeArgs>
2345 CallbackArg<FreeArgs...>* make_ref(std::function<void(FreeArgs...)>&& f) {
2346  typedef std::function<void(FreeArgs...)> LType;
2347  return new Callback_lambda<LType, FreeArgs...>{std::move(f)};
2348 }
2349 
2350 // This helper function to construct Callback_lambda objects could be
2351 // implemented as a further overload of Callback::make(). No best
2352 // match ambiguities would arise, because even when Callback::make()
2353 // is passed a function pointer without bound arguments, the overload
2354 // of Callback::make taking a function pointer (as opposed to a
2355 // generic callable object) would still comprise the best match.
2356 // However, to construct Callback_lambda objects, the unbound
2357 // arguments need to be specified by hand, which doesn't happen with
2358 // Callback::make() (it would only be necessary to specify an explicit
2359 // type where a mutable reference argument is to be bound to the
2360 // callback object). It seems to me to be less confusing to the user
2361 // therefore to have a separate Callback::lambda() helper function.
2362 // However, if you disagree please let me know.
2363 
2364 // template parameter packs do not need to be placed last in the case
2365 // of function templates, as type deduction is available for the last
2366 // parameter: there is in fact no function parameter pack in
2367 // Callback::lambda() (function parameter packs must come last).
2368 /**
2369  * A convenience function to make Callback::CallbackArg objects from
2370  * C++11 lambda expressions, or from any other arbitrary callable
2371  * object. The types of the unbound arguments (if any) must be
2372  * explicitly specified as template parameters, as they cannot be
2373  * deduced. From version 2.0.10, this function can be called for
2374  * lambda expressions which are declared mutable (in version 2.0.9,
2375  * this function could only be called for non-mutable lambda
2376  * expressions). From version 2.0.16, this function can be passed
2377  * callable objects which are lvalues as well as rvalues (prior to
2378  * version 2.0.16, it could only be passed callable objects which are
2379  * rvalues).
2380  * @exception std::bad_alloc It might throw std::bad_alloc if memory
2381  * is exhausted and the system throws in that case (this exception
2382  * will not be thrown if the library has been installed using the
2383  * \--with-glib-memory-slices-no-compat configuration option: instead
2384  * glib will terminate the program if it is unable to obtain memory
2385  * from the operating system). It will also throw if the copy or move
2386  * constructor of an object captured by the lambda expression throws.
2387  *
2388  * Since 2.0.9
2389  */
2390 template <class... FreeArgs, class Lambda>
2391 CallbackArg<FreeArgs...>* lambda(Lambda&& l) {
2392  typedef typename std::remove_const<typename std::remove_reference<Lambda>::type>::type LType;
2393  return new Callback_lambda<LType, FreeArgs...>{std::forward<Lambda>(l)};
2394 }
2395 
2396 #ifndef DOXYGEN_PARSING
2397 /*
2398  * DEPRECATED. These make_val() functions are retained for API
2399  * compatibility only, but should not be used in new code and are not
2400  * documented. Use make_ref() instead.
2401  */
2402 template <class T, class... FreeArgs>
2403 CallbackArg<FreeArgs...>* make_val(T& t,
2404  void (T::*func)(FreeArgs...)) {
2405  return new Callback0<T, FreeArgs...>{t, func};
2406 }
2407 template <class T, class BoundArg, class... FreeArgs>
2408 CallbackArg<FreeArgs...>* make_val(T& t,
2409  void (T::*func)(BoundArg, FreeArgs...),
2410  const BoundArg& arg) {
2411  return new Callback1<false, T, BoundArg, FreeArgs...>{t, func, arg};
2412 }
2413 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2414 CallbackArg<FreeArgs...>* make_val(T& t,
2415  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...),
2416  const BoundArg1& arg1,
2417  const BoundArg2& arg2) {
2418  return new Callback2<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2419 }
2420 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2421 CallbackArg<FreeArgs...>* make_val(T& t,
2422  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2423  const BoundArg1& arg1,
2424  const BoundArg2& arg2,
2425  const BoundArg3& arg3) {
2426  return new Callback3<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2427 }
2428 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2429  class BoundArg4, class... FreeArgs>
2430 CallbackArg<FreeArgs...>* make_val(T& t,
2431  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2432  BoundArg4, FreeArgs...),
2433  const BoundArg1& arg1,
2434  const BoundArg2& arg2,
2435  const BoundArg3& arg3,
2436  const BoundArg4& arg4) {
2437  return new Callback4<false, T, BoundArg1, BoundArg2, BoundArg3,
2438  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2439 }
2440 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2441  class BoundArg4, class BoundArg5, class... FreeArgs>
2442 CallbackArg<FreeArgs...>* make_val(T& t,
2443  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2444  BoundArg4, BoundArg5, FreeArgs...),
2445  const BoundArg1& arg1,
2446  const BoundArg2& arg2,
2447  const BoundArg3& arg3,
2448  const BoundArg4& arg4,
2449  const BoundArg5& arg5) {
2450  return new Callback5<false, T, BoundArg1, BoundArg2, BoundArg3,
2451  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2452 }
2453 template <class T, class... FreeArgs>
2454 CallbackArg<FreeArgs...>* make_val(const T& t,
2455  void (T::*func)(FreeArgs...) const) {
2456  return new Callback0_const<T, FreeArgs...>{t, func};
2457 }
2458 template <class T, class BoundArg, class... FreeArgs>
2459 CallbackArg<FreeArgs...>* make_val(const T& t,
2460  void (T::*func)(BoundArg, FreeArgs...) const,
2461  const BoundArg& arg) {
2462  return new Callback1_const<false, T, BoundArg, FreeArgs...>{t, func, arg};
2463 }
2464 template <class T, class BoundArg1, class BoundArg2, class... FreeArgs>
2465 CallbackArg<FreeArgs...>* make_val(const T& t,
2466  void (T::*func)(BoundArg1, BoundArg2, FreeArgs...) const,
2467  const BoundArg1& arg1,
2468  const BoundArg2& arg2) {
2469  return new Callback2_const<false, T, BoundArg1, BoundArg2, FreeArgs...>{t, func, arg1, arg2};
2470 }
2471 template <class T, class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2472 CallbackArg<FreeArgs...>* make_val(const T& t,
2473  void (T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const,
2474  const BoundArg1& arg1,
2475  const BoundArg2& arg2,
2476  const BoundArg3& arg3) {
2477  return new Callback3_const<false, T, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{t, func, arg1, arg2, arg3};
2478 }
2479 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2480  class BoundArg4, class... FreeArgs>
2481 CallbackArg<FreeArgs...>* make_val(const T& t,
2482  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2483  BoundArg4, FreeArgs...) const,
2484  const BoundArg1& arg1,
2485  const BoundArg2& arg2,
2486  const BoundArg3& arg3,
2487  const BoundArg4& arg4) {
2488  return new Callback4_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2489  BoundArg4, FreeArgs...>{t, func, arg1, arg2, arg3, arg4};
2490 }
2491 template <class T, class BoundArg1, class BoundArg2, class BoundArg3,
2492  class BoundArg4, class BoundArg5, class... FreeArgs>
2493 CallbackArg<FreeArgs...>* make_val(const T& t,
2494  void (T::*func)(BoundArg1, BoundArg2, BoundArg3,
2495  BoundArg4, BoundArg5, FreeArgs...) const,
2496  const BoundArg1& arg1,
2497  const BoundArg2& arg2,
2498  const BoundArg3& arg3,
2499  const BoundArg4& arg4,
2500  const BoundArg5& arg5) {
2501  return new Callback5_const<false, T, BoundArg1, BoundArg2, BoundArg3,
2502  BoundArg4, BoundArg5, FreeArgs...>{t, func, arg1, arg2, arg3, arg4, arg5};
2503 }
2504 template <class... FreeArgs>
2505 CallbackArg<FreeArgs...>* make_val(void (*func)(FreeArgs...)) {
2506  return new Callback0_static<FreeArgs...>{func};
2507 }
2508 template <class BoundArg, class... FreeArgs>
2509 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg, FreeArgs...),
2510  const BoundArg& arg) {
2511  return new Callback1_static<false, BoundArg, FreeArgs...>{func, arg};
2512 }
2513 template <class BoundArg1, class BoundArg2, class... FreeArgs>
2514 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, FreeArgs...),
2515  const BoundArg1& arg1,
2516  const BoundArg2& arg2) {
2517  return new Callback2_static<false, BoundArg1, BoundArg2, FreeArgs...>{func, arg1, arg2};
2518 }
2519 template <class BoundArg1, class BoundArg2, class BoundArg3, class... FreeArgs>
2520 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...),
2521  const BoundArg1& arg1,
2522  const BoundArg2& arg2,
2523  const BoundArg3& arg3) {
2524  return new Callback3_static<false, BoundArg1, BoundArg2, BoundArg3, FreeArgs...>{func, arg1, arg2, arg3};
2525 }
2526 template <class BoundArg1, class BoundArg2, class BoundArg3,
2527  class BoundArg4, class... FreeArgs>
2528 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3,
2529  BoundArg4, FreeArgs...),
2530  const BoundArg1& arg1,
2531  const BoundArg2& arg2,
2532  const BoundArg3& arg3,
2533  const BoundArg4& arg4) {
2534  return new Callback4_static<false, BoundArg1, BoundArg2, BoundArg3,
2535  BoundArg4, FreeArgs...>{func, arg1, arg2, arg3, arg4};
2536 }
2537 template <class BoundArg1, class BoundArg2, class BoundArg3,
2538  class BoundArg4, class BoundArg5, class... FreeArgs>
2539 CallbackArg<FreeArgs...>* make_val(void (*func)(BoundArg1, BoundArg2, BoundArg3,
2540  BoundArg4, BoundArg5, FreeArgs...),
2541  const BoundArg1& arg1,
2542  const BoundArg2& arg2,
2543  const BoundArg3& arg3,
2544  const BoundArg4& arg4,
2545  const BoundArg5& arg5) {
2546  return new Callback5_static<false, BoundArg1, BoundArg2, BoundArg3,
2547  BoundArg4, BoundArg5, FreeArgs...>{func, arg1, arg2, arg3, arg4, arg5};
2548 }
2549 template <class... FreeArgs>
2550 CallbackArg<FreeArgs...>* make_val(const std::function<void(FreeArgs...)>& f) {
2551  typedef std::function<void(FreeArgs...)> LType;
2552  return new Callback_lambda<LType, FreeArgs...>{f};
2553 }
2554 template <class... FreeArgs>
2555 CallbackArg<FreeArgs...>* make_val(std::function<void(FreeArgs...)>&& f) {
2556  typedef std::function<void(FreeArgs...)> LType;
2557  return new Callback_lambda<LType, FreeArgs...>{std::move(f)};
2558 }
2559 #endif // DOXYGEN_PARSING
2560 
2561 } // namespace Callback
2562 
2563 class Releaser;
2564 
2565 namespace Callback {
2566 
2567 /**
2568  * Posts a callback for execution by a glib main loop. It is
2569  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
2570  * has been called. glib >= 2.32 does not require g_thread_init() to
2571  * be called. This function will not throw.
2572  * @param cb The callback object. Ownership is taken of this object,
2573  * and it will be deleted when it has been finished with.
2574  * @param priority The priority to be given to the callback in the
2575  * main loop. In ascending order of priorities, priorities are
2576  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
2577  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
2578  * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the
2579  * callback will appear in the event list in the main loop, not the
2580  * priority which the OS will adopt
2581  * @param context The glib main loop context in which the callback is
2582  * to be executed (the default of NULL will cause the callback to be
2583  * executed in the main program loop, and this is usually what is
2584  * wanted).
2585  * @note Cancellation of the receiving thread is blocked when the
2586  * callback executes.
2587  */
2588 void post(const Callback* cb, gint priority = G_PRIORITY_DEFAULT_IDLE,
2589  GMainContext* context = 0);
2590 
2591 /**
2592  * Posts a callback for execution by a glib main loop. It is
2593  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
2594  * has been called. glib >= 2.32 does not require g_thread_init() to
2595  * be called. This function will not throw.
2596  * @param cb The callback object. Ownership is taken of this object,
2597  * and it will be deleted when it has been finished with.
2598  * @param r A Releaser object for automatic disconnection of the
2599  * callback before it executes in the main loop (mainly relevant if
2600  * the callback represents a non-static member function of an object
2601  * which may be destroyed before the callback executes).
2602  * @param priority The priority to be given to the callback in the
2603  * main loop. In ascending order of priorities, priorities are
2604  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
2605  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
2606  * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the
2607  * callback will appear in the event list in the main loop, not the
2608  * priority which the OS will adopt.
2609  * @param context The glib main loop context in which the callback is
2610  * to be executed (the default of NULL will cause the callback to be
2611  * executed in the main program loop, and this is usually what is
2612  * wanted).
2613  * @exception std::bad_alloc This function might throw std::bad_alloc
2614  * if memory is exhausted and the system throws in that case. If it
2615  * does so, the Callback object will be disposed of.
2616  * @exception Cgu::Thread::MutexError This method might throw
2617  * Cgu:Thread::MutexError if initialisation of the mutex in a
2618  * SafeEmitterArg object constructed by this method fails. If it does
2619  * so, the Callback object will be disposed of. (It is often not
2620  * worth checking for this exception, as it means either memory is
2621  * exhausted or pthread has run out of other resources to create new
2622  * mutexes.)
2623  * @note 1. Cancellation of the receiving thread is blocked when the
2624  * callback executes.
2625  * @note 2. By virtue of the Releaser object, it is in theory possible
2626  * (if memory is exhausted and the system throws in that case) that an
2627  * internal SafeEmitterArg object will throw std::bad_alloc when
2628  * emitting/executing the callback in the glib main loop, with the
2629  * result that the relevant callback will not execute (instead the
2630  * exception will be consumed and a g_critical() warning will be
2631  * issued). This is rarely of any relevance because glib will abort
2632  * the program if it is itself unable to obtain memory from the
2633  * operating system. However, where it is relevant, design the
2634  * program so that it is not necessary to provide a releaser object.
2635  */
2636 void post(const Callback* cb, Releaser& r,
2637  gint priority = G_PRIORITY_DEFAULT_IDLE, GMainContext* context = 0);
2638 
2639 
2640 /**
2641  * Posts a callable object for execution by a glib main loop. It is
2642  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
2643  * has been called. glib >= 2.32 does not require g_thread_init() to
2644  * be called. This function will not throw unless the copy or move
2645  * constructor of the callable object throws.
2646  * @param func A callable object, such as formed by a lambda
2647  * expression or the result of std::bind. It must be fully bound
2648  * (that is, its must take no arguments when called).
2649  * @param priority The priority to be given to the callable object in
2650  * the main loop. In ascending order of priorities, priorities are
2651  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
2652  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
2653  * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the
2654  * callback will appear in the event list in the main loop, not the
2655  * priority which the OS will adopt
2656  * @param context The glib main loop context in which the callable
2657  * object is to be executed (the default of NULL will cause the
2658  * callback to be executed in the main program loop, and this is
2659  * usually what is wanted).
2660  * @note Cancellation of the receiving thread is blocked when the
2661  * callback executes.
2662  *
2663  * Since 2.1.0
2664  */
2665 // we need to use enable_if so that where this function is passed a
2666 // pointer to non-const Callback, or some other convertible pointer,
2667 // this templated overload is dropped from the overload set, in order
2668 // to support the Callback pointer overloads of this function. This
2669 // overload calls into the version of this function taking a pointer
2670 // to const Callback in order to perform type erasure.
2671 template <class F,
2672  class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type,
2673  const Callback*>::value>::type>
2674 void post(F&& func, gint priority = G_PRIORITY_DEFAULT_IDLE,
2675  GMainContext* context = 0) {
2676  post(lambda<>(std::forward<F>(func)), priority, context);
2677 }
2678 
2679 /**
2680  * Posts a callable object for execution by a glib main loop. It is
2681  * thread-safe provided that (if glib < 2.32 is used) g_thread_init()
2682  * has been called. glib >= 2.32 does not require g_thread_init() to
2683  * be called.
2684  * @param func A callable object, such as formed by a lambda
2685  * expression or the result of std::bind. It must be fully bound
2686  * (that is, its must take no arguments when called).
2687  * @param r A Releaser object for automatic disconnection of the
2688  * callback before it executes in the main loop (mainly relevant if
2689  * the callback represents or calls into a non-static member function
2690  * of an object which may be destroyed before the callback executes).
2691  * @param priority The priority to be given to the callback in the
2692  * main loop. In ascending order of priorities, priorities are
2693  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
2694  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
2695  * G_PRIORITY_DEFAULT_IDLE. This determines the order in which the
2696  * callback will appear in the event list in the main loop, not the
2697  * priority which the OS will adopt.
2698  * @param context The glib main loop context in which the callable
2699  * object is to be executed (the default of NULL will cause the
2700  * callback to be executed in the main program loop, and this is
2701  * usually what is wanted).
2702  * @exception std::bad_alloc This function might throw std::bad_alloc
2703  * if memory is exhausted and the system throws in that case.
2704  * @exception Cgu::Thread::MutexError This method might throw
2705  * Cgu:Thread::MutexError if initialisation of the mutex in a
2706  * SafeEmitterArg object constructed by this method fails. (It is
2707  * often not worth checking for this exception, as it means either
2708  * memory is exhausted or pthread has run out of other resources to
2709  * create new mutexes.)
2710  * @note 1. This function may also throw if the copy or move
2711  * constructor of the callable object throws.
2712  * @note 2. Cancellation of the receiving thread is blocked when the
2713  * callback executes.
2714  * @note 3. By virtue of the Releaser object, it is in theory possible
2715  * (if memory is exhausted and the system throws in that case) that an
2716  * internal SafeEmitterArg object will throw std::bad_alloc when
2717  * emitting/executing the callback in the glib main loop, with the
2718  * result that the relevant callback will not execute (instead the
2719  * exception will be consumed and a g_critical() warning will be
2720  * issued). This is rarely of any relevance because glib will abort
2721  * the program if it is itself unable to obtain memory from the
2722  * operating system. However, where it is relevant, design the
2723  * program so that it is not necessary to provide a releaser object.
2724  *
2725  * Since 2.1.0
2726  */
2727 // we need to use enable_if so that where this function is passed a
2728 // pointer to non-const Callback, or some other convertible pointer,
2729 // this templated overload is dropped from the overload set, in order
2730 // to support the Callback pointer overloads of this function. This
2731 // overload calls into the version of this function taking a pointer
2732 // to const Callback in order to perform type erasure.
2733 template <class F,
2734  class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type,
2735  const Callback*>::value>::type>
2736 void post(F&& func, Releaser& r,
2737  gint priority = G_PRIORITY_DEFAULT_IDLE, GMainContext* context = 0) {
2738  post(lambda<>(std::forward<F>(func)), r, priority, context);
2739 }
2740 
2741 } // namespace Callback
2742 
2743 } // namespace Cgu
2744 
2745 #endif