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