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