Cgu::Callback Namespace Reference

This namespace provides classes encapsulating callbacks. More...

## Classes

class | CallbackArg
| The callback interface class. More...
class | FunctorArg
| Functor class holding a Callback::CallbackArg object. More...
class | SafeFunctorArg
| Functor class holding a Callback::CallbackArg object, with thread-safe reference count. More...
class | Callback0
class | Callback1
class | Callback2
class | Callback3
class | Callback4
class | Callback5
class | Callback0_const
class | Callback1_const
class | Callback2_const
class | Callback3_const
class | Callback4_const
class | Callback5_const
class | Callback0_static
class | Callback1_static
class | Callback2_static
class | Callback3_static
class | Callback4_static
class | Callback5_static
class | Callback_function
class | Callback_lambda

## Typedefs

typedef CallbackArg | Callback
typedef FunctorArg | Functor
typedef SafeFunctorArg | SafeFunctor

## Functions

template<class... T>
bool | operator== (const FunctorArg< T...> &f1, const FunctorArg< T...> &f2)
template<class... T>
bool | operator!= (const FunctorArg< T...> &f1, const FunctorArg< T...> &f2)
template<class... T>
bool | operator< (const FunctorArg< T...> &f1, const FunctorArg< T...> &f2)
template<class... T>
bool | operator== (const SafeFunctorArg< T...> &f1, const SafeFunctorArg< T...> &f2)
template<class... T>
bool | operator!= (const SafeFunctorArg< T...> &f1, const SafeFunctorArg< T...> &f2)
template<class... T>
bool | operator< (const SafeFunctorArg< T...> &f1, const SafeFunctorArg< T...> &f2)
template<class T , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (T &t, void(T::*func)(FreeArgs...))
template<class T , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (T &t, void(T::*func)(FreeArgs...))
template<class T , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (T &t, void(T::*func)(FreeArgs...))
template<class T , class BoundArg , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (T &t, void(T::*func)(BoundArg, FreeArgs...), BoundArg arg)
template<class T , class BoundArg , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (T &t, void(T::*func)(BoundArg, FreeArgs...), const BoundArg &arg)
template<class T , class BoundArg , class Arg , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (T &t, void(T::*func)(BoundArg, FreeArgs...), Arg &&arg)
template<class T , class BoundArg1 , class BoundArg2 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (T &t, void(T::*func)(BoundArg1, BoundArg2, FreeArgs...), BoundArg1 arg1, BoundArg2 arg2)
template<class T , class BoundArg1 , class BoundArg2 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (T &t, void(T::*func)(BoundArg1, BoundArg2, FreeArgs...), const BoundArg1 &arg1, const BoundArg2 &arg2)
template<class T , class BoundArg1 , class BoundArg2 , class Arg1 , class Arg2 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (T &t, void(T::*func)(BoundArg1, BoundArg2, FreeArgs...), Arg1 &&arg1, Arg2 &&arg2)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), BoundArg1 arg1, BoundArg2 arg2, BoundArg3 arg3)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), const BoundArg1 &arg1, const BoundArg2 &arg2, const BoundArg3 &arg3)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class Arg1 , class Arg2 , class Arg3 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), Arg1 &&arg1, Arg2 &&arg2, Arg3 &&arg3)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...), BoundArg1 arg1, BoundArg2 arg2, BoundArg3 arg3, BoundArg4 arg4)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...), const BoundArg1 &arg1, const BoundArg2 &arg2, const BoundArg3 &arg3, const BoundArg4 &arg4)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...), Arg1 &&arg1, Arg2 &&arg2, Arg3 &&arg3, Arg4 &&arg4)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...), BoundArg1 arg1, BoundArg2 arg2, BoundArg3 arg3, BoundArg4 arg4, BoundArg5 arg5)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...), const BoundArg1 &arg1, const BoundArg2 &arg2, const BoundArg3 &arg3, const BoundArg4 &arg4, const BoundArg5 &arg5)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class Arg5 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...), Arg1 &&arg1, Arg2 &&arg2, Arg3 &&arg3, Arg4 &&arg4, Arg5 &&arg5)
template<class T , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (const T &t, void(T::*func)(FreeArgs...) const)
template<class T , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (const T &t, void(T::*func)(FreeArgs...) const)
template<class T , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (const T &t, void(T::*func)(FreeArgs...) const)
template<class T , class BoundArg , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (const T &t, void(T::*func)(BoundArg, FreeArgs...) const, BoundArg arg)
template<class T , class BoundArg , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (const T &t, void(T::*func)(BoundArg, FreeArgs...) const, const BoundArg &arg)
template<class T , class BoundArg , class Arg , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (const T &t, void(T::*func)(BoundArg, FreeArgs...) const, Arg &&arg)
template<class T , class BoundArg1 , class BoundArg2 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (const T &t, void(T::*func)(BoundArg1, BoundArg2, FreeArgs...) const, BoundArg1 arg1, BoundArg2 arg2)
template<class T , class BoundArg1 , class BoundArg2 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (const T &t, void(T::*func)(BoundArg1, BoundArg2, FreeArgs...) const, const BoundArg1 &arg1, const BoundArg2 &arg2)
template<class T , class BoundArg1 , class BoundArg2 , class Arg1 , class Arg2 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (const T &t, void(T::*func)(BoundArg1, BoundArg2, FreeArgs...) const, Arg1 &&arg1, Arg2 &&arg2)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (const T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const, BoundArg1 arg1, BoundArg2 arg2, BoundArg3 arg3)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (const T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const, const BoundArg1 &arg1, const BoundArg2 &arg2, const BoundArg3 &arg3)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class Arg1 , class Arg2 , class Arg3 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (const T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const, Arg1 &&arg1, Arg2 &&arg2, Arg3 &&arg3)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (const T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const, BoundArg1 arg1, BoundArg2 arg2, BoundArg3 arg3, BoundArg4 arg4)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (const T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const, const BoundArg1 &arg1, const BoundArg2 &arg2, const BoundArg3 &arg3, const BoundArg4 &arg4)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (const T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const, Arg1 &&arg1, Arg2 &&arg2, Arg3 &&arg3, Arg4 &&arg4)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (const T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) const, BoundArg1 arg1, BoundArg2 arg2, BoundArg3 arg3, BoundArg4 arg4, BoundArg5 arg5)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (const T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) const, const BoundArg1 &arg1, const BoundArg2 &arg2, const BoundArg3 &arg3, const BoundArg4 &arg4, const BoundArg5 &arg5)
template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class Arg5 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (const T &t, void(T::*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) const, Arg1 &&arg1, Arg2 &&arg2, Arg3 &&arg3, Arg4 &&arg4, Arg5 &&arg5)
template<class... FreeArgs>
CallbackArg< FreeArgs...> * | make (void(*func)(FreeArgs...))
template<class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (void(*func)(FreeArgs...))
template<class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (void(*func)(FreeArgs...))
template<class BoundArg , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (void(*func)(BoundArg, FreeArgs...), BoundArg arg)
template<class BoundArg , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (void(*func)(BoundArg, FreeArgs...), const BoundArg &arg)
template<class BoundArg , class Arg , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (void(*func)(BoundArg, FreeArgs...), Arg &&arg)
template<class BoundArg1 , class BoundArg2 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (void(*func)(BoundArg1, BoundArg2, FreeArgs...), BoundArg1 arg1, BoundArg2 arg2)
template<class BoundArg1 , class BoundArg2 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (void(*func)(BoundArg1, BoundArg2, FreeArgs...), const BoundArg1 &arg1, const BoundArg2 &arg2)
template<class BoundArg1 , class BoundArg2 , class Arg1 , class Arg2 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (void(*func)(BoundArg1, BoundArg2, FreeArgs...), Arg1 &&arg1, Arg2 &&arg2)
template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (void(*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), BoundArg1 arg1, BoundArg2 arg2, BoundArg3 arg3)
template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (void(*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), const BoundArg1 &arg1, const BoundArg2 &arg2, const BoundArg3 &arg3)
template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class Arg1 , class Arg2 , class Arg3 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (void(*func)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...), Arg1 &&arg1, Arg2 &&arg2, Arg3 &&arg3)
template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (void(*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...), BoundArg1 arg1, BoundArg2 arg2, BoundArg3 arg3, BoundArg4 arg4)
template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (void(*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...), const BoundArg1 &arg1, const BoundArg2 &arg2, const BoundArg3 &arg3, const BoundArg4 &arg4)
template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (void(*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...), Arg1 &&arg1, Arg2 &&arg2, Arg3 &&arg3, Arg4 &&arg4)
template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make (void(*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...), BoundArg1 arg1, BoundArg2 arg2, BoundArg3 arg3, BoundArg4 arg4, BoundArg5 arg5)
template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (void(*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...), const BoundArg1 &arg1, const BoundArg2 &arg2, const BoundArg3 &arg3, const BoundArg4 &arg4, const BoundArg5 &arg5)
template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class Arg5 , class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (void(*func)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...), Arg1 &&arg1, Arg2 &&arg2, Arg3 &&arg3, Arg4 &&arg4, Arg5 &&arg5)
template<class... FreeArgs>
CallbackArg< FreeArgs...> * | make (const std::function< void(FreeArgs...)> &f)
template<class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (const std::function< void(FreeArgs...)> &f)
template<class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (const std::function< void(FreeArgs...)> &f)
template<class... FreeArgs>
CallbackArg< FreeArgs...> * | make (std::function< void(FreeArgs...)> &&f)
template<class... FreeArgs>
CallbackArg< FreeArgs...> * | make_val (std::function< void(FreeArgs...)> &&f)
template<class... FreeArgs>
CallbackArg< FreeArgs...> * | make_ref (std::function< void(FreeArgs...)> &&f)
template<class... FreeArgs, class Lambda >
CallbackArg< FreeArgs...> * | lambda (Lambda &&l)
void | post (const Callback *cb, gint priority=G_PRIORITY_DEFAULT_IDLE, GMainContext *context=0)
void | post (const Callback *cb, Releaser &r, gint priority=G_PRIORITY_DEFAULT_IDLE, GMainContext *context=0)

## Detailed Description

This namespace provides classes encapsulating callbacks.

#include <c++-gtk-utils/callback.h>

These classes encapsulate callbacks (they are closures). They comprise a generic callback creation and execution interface. There is a basic Callback::Callback type, which is an entire closure or 'thunk', where all the arguments are bound in the constructor and is completely opaque. Callback::CallbackArg<T...> is a class which takes unbound arguments of the template types when the callback is dispatched, with any other arguments being bound at construction time. (The opaque Callback::Callback type is in fact just a typedef for Callback::CallbackArg<>: the two types are interchangeable.)

The classes can represent static and non-static member functions and plain functions. In the case of a non-static member function, the object whose member function the callback represents must remain in existence until any invocations of the callback have completed. The function referred to must be one of void return type. A callback object can also be constructed from any function object, provided that it is of void return type (which would amongst other things enable, where necessary, the binding of the referenced object of a non-static member function by taking an internal copy of it using std::bind or by lambda capture).

They are particularly useful where a callback object may need to be handed between threads.

The classes can also be useful for general event passing when used together with the Callback::post() functions, or as the data argument of a call to g_signal_connect_data() in a case where a better design arises when passing arguments known at connect time by storing them in the callback object itself, or as the continuation for GIO async operations.

These classes are also used in the Emitter/EmitterArg classes in emitter.h, which enable callbacks to be connected to an emitter and provide for automatic disconnection where a class object whose member a callback represents ceases to exist.

## The Callback::make() functions

The templated helper Callback::make() functions make it trivial to create a callback object of the correct type. The ordinary Callback::make() functions (that is, those not taking a std::function object) provide for a maximum of five bound arguments to pass to the relevant function or class method, and an unlimited number of unbound arguments, but unbound arguments must be the last (trailing) arguments of the relevant function or method to be called if there is a bound argument. Callback/CallbackArg classes do not provide for a return value. If a result is wanted, users should pass an unbound argument by reference or pointer (or pointer to pointer).

Although as mentioned above only five bound arguments are provided for by callbacks constructed by the ordinary Callback::make() functions, as any of those arguments can be a struct, any number of arguments can be passed as members of a struct or a std::tuple. In addition, a callback object can be constructed using Callback::make() from a std::function object, which can have any number of arguments bound to it, and in any order (that is, unbound arguments may precede bound arguments).

The Callback::make() functions not taking a std::function object do a direct type mapping from the bound arguments of the function or method represented by the callback object to the arguments stored by the callback object. Bound value arguments of the relevant function or method to be called are therefore stored by value in the callback object. A bound argument can comprise a reference argument (T& or const T&) if the template parameters of the Callback::make() call are qualified by hand to avoid a type mismatch: see under "Usage" below for further particulars, and if the reference argument is non-const this allows the referenced argument to be mutated. However as this would result in the lifetime of the argument not being controlled by the callback object (it would not keep its own copy), it will often be unsafe to do so. (The documentation on Thread::JoinableHandle gives a usage where where binding a reference argument would be safe.)

From version 2.0.0-rc3, the library also provides Callback::make_ref() functions, which force the callback object to keep a copy of the value passed where a target function argument is a const reference. It is therefore safe with const reference arguments. No explicit type qualification is required by Callback::make_ref(). In addition the Callback::make_ref() functions provide for more efficient passing of class type bound arguments (by l-value or r-value reference) than does Callback::make(): see further below.

## The Callback::make_ref() functions

In order to enable the widest variety of types to be accepted as arguments (including reference arguments in those cases where it is safe, and also string literals), as mentioned above when constructing a callback object from other than a std::function object, Callback::make() receives non-reference bound arguments by value, and if unoptimised these may be copied up to two times, and once more when the target function is dispatched. Where a bound argument is a pointer or a fundamental type (an integral or floating-point type), optimization by copy elision will reduce the number of times argument copying takes place when constructing a callback object to once, but the standard does not permit that with class types where the constructor or destructor have side effects or it cannot be ascertained whether they have side effects.

Therefore, to cater for cases where a target function takes a class type argument by const reference or value, from version 2.0.0-rc3 the Callback::make_ref() functions are provided. Unlike Callback::make(), when constructing a callback for a target function taking a const reference bound argument, Callback::make_ref() will force the callback object to keep a copy of the argument instead of a reference to that argument. This makes the use of const reference arguments safe (at the cost of the storing of that copy). It cannot be used with non-const references. In addition Callback::make_ref() automatically chooses the most efficient means of passing class type arguments for storage by the callback object, that is by l-value reference or r-value reference, as appropriate.

In the case of a value argument, at callback dispatch time one additional copy will be made in the normal way when the target function is called, but in the case of a const reference argument no such additional copy will be made. What all this means is that, where bound arguments include a non-trivial class type, the most efficient and exception safe strategy is usually:

1. If that class type has a rvalue constructor, to have the target function take that type by const reference argument, and pass a newly constructed object of that type to Callback::make_ref() as a temporary (so that it is passed by r-value reference and stored in the callback object without any copying at all), or
2. To construct the object of the class type on free store and held by Cgu::SharedPtr, Cgu::SharedLockPtr or std::shared_ptr, have the target function take it by const Cgu::SharedPtr&, const Cgu::SharedLockPtr& or const std::shared_ptr&, and construct the callback object using Callback::make_ref().

This flexibility of Callback::make_ref() has a downside: unlike Callback::make(), Callback::make_ref() cannot resolve overloaded functions by argument type. Where a function has two or more overloads taking the same number of arguments, explicit disambiguation by the user is required (see further below under Overloaded Functions).

Summary: If a callback object's bound arguments are all simple fundamental types such as pointers (including C strings), integers or floating points, use Callback::make(). Where bound arguments include class types, use Callback::make_ref().

## The Callback::make_val() functions

The library also provides Callback::make_val() functions. These are provided to retain code compatibility with version 1.2 of the library. They were optimised for use where a target function takes bound arguments of class type by value, but are now deprecated and superseded by the automatic variable type mapping of Callback::make_ref(). Callback::make_ref() should now be used instead of Callback::make_val().

## Constructing callbacks from std::function objects

The Callback::make() factory functions can also construct a callback object from a std::function object, which would enable a callback to take more than 5 bound arguments, or to have a bound argument which is passed after (or mixed with) unbound arguments, or to have its own copy of the referenced object of a non-static member function bound to it.

However, the genericity of the binding of arguments implemented in std::function and std::bind comes at a cost. Arguments bound to a std::function object can be copied a significant number of times (libstdc++ for example can copy class types four times when constructing a std::function object and two more times when executing the function, unless they have a r-value constructor, in which case they are copied twice and once respectively with two and one additional calls to the r-value constructor). Non-trivial class types should therefore only be passed as bound arguments to std::function objects by pointer or smart pointer.

Note that the overload of Callback::make() for std::function objects has a version taking a r-value reference for the lossless passing through of temporaries to the callback object, and a version taking a const reference for std::function objects which are l-values. For std::function objects, Callback::make() and Callback::make_ref() are all synonyms (the way arguments are dealt with for std::function objects is determined by std::bind() and std::ref()).

From version 2.0.9, in many uses it is better to pass a function object (such as the return value of std::bind(), or one generated by a lambda expression) to Callback::lambda(), which takes any arbitrary callable object directly as a template parameter.

## The Callback::lambda() functions

Callback objects for C++11 lambda expressions can be constructed using Callback::make() by passing the lambda object via a temporary std::function object (see under Usage below for an example). However, from version 2.0.9 the Callback::lambda() factory function is provided enabling callbacks for C++11 lambda expressions to be constructed more directly. This is nice, as by using Callback::lambda() a callback can, for example, be executed by a glib main loop using Callback::post() with:

using namespace Cgu;
post(Callback::lambda<>([]() {std::cout << "Hello glib\n";})); // post() found by argument dependent lookup

Further examples are given under Usage below.

Callback::lambda() can construct a callback object from any arbitrary function object, such as the return value of std::bind(). Using Callback::lambda() to construct such a callback object, rather than using Callback::make() with a temporary std::function object, will also be more efficient, as when executed it would normally avoid the additional virtual function call that would arise with std::function.

When using Callback::lambda(), the unbound argument types must be specified explicitly (they cannot be deduced from the lambda expression).

From version 2.0.10, Callback::lambda() can be called for lambda expressions which are declared mutable capturing bound arguments by value (in version 2.0.9, the function could only be called for non-mutable lambda expressions). From version 2.0.16, it can be passed callable objects which are lvalues as well as rvalues (prior to version 2.0.16, it could only be passed callable objects which are rvalues).

One other feature of Callback::lambda() is that the callable object passed to it need not be of void return type. However, if the callable object does return a value, that value is discarded. If a result is wanted, an unbound reference or pointer argument should be passed when the callback is executed, to which the result can be assigned.

If using lambda expressions with gcc, gcc-4.5 or greater is needed. The header file callback.h can be included without error with gcc-4.4, but callable objects cannot be constructed using C++11 lambda syntax.

## Functors

If a functor class of void return type is required (say for passing to a c++ algorithm or container, or for automatic lifetime management of the Callback object), the Callback::Functor and Callback::FunctorArg wrapper classes can be used. However, for many c++ algorithms where anonymous functors created as temporaries can be used, the std::ptr_fun(), std::mem_fn() and std::bind() factory functions or a lambda expression will be a more obvious choice. Callback::Functor and Callback::FunctorArg are to be preferred to std::function where value arguments are to be bound (see above), unless something other than a void return type is required.

Callback::SafeFunctor and Callback::SafeFunctorArg classes are the same as Callback::Functor and Callback::FunctorArg classes, except that objects of the safe version may be passed and copied between threads and put in different containers in different threads (that is, the reference count maintained with respect to the contained callback object is thread-safe). They use a SharedLockPtr object to hold the referenced callback object.

## Memory allocation

If the library is installed using the --with-glib-memory-slices-compat or --with-glib-memory-slices-no-compat configuration options, any Callback::Functor, Callback::FunctorArg, Callback::SafeFunctor or Callback::SafeFunctorArg objects constructed on free store (usually they won't be) will be constructed in glib memory slices. A contained Callback::Callback or Callback::CallbackArg object, which will always be constructed on free store, will be constructed in glib memory slices if the --with-glib-memory-slices-no-compat configuration option is chosen.

## Usage

For a class object my_obj of type MyClass, with a method void MyClass::my_method(int, int, const char*), usage for a fully bound callback or functor would be:

using namespace Cgu;
int arg1 = 1, arg2 = 5;
Callback::Callback* cb =
Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n");
cb->dispatch();
delete cb;
Callback::Functor f{Callback::make(my_obj, &MyClass::my_method, arg1, arg2, "Hello\n")};
f();

Or for a partially bound callback or functor:

using namespace Cgu;
int arg1 = 1, arg2 = 5;
Callback::CallbackArg<int, const char*>* cb =
Callback::make(my_obj, &MyClass::my_method, arg1);
cb->dispatch(arg2, "Hello\n");
delete cb;
Callback::FunctorArg<int, const char*> f{Callback::make(my_obj, &MyClass::my_method, arg1)};
f(arg2, "Hello\n");

The syntax for the construction of a callback object representing a static member function with a signature void MyClass::my_func(int, const char*), or for a normal function, is similar to the non-static member function case, except that the call to Callback::make would comprise:

Callback::make(&MyClass::my_func, arg1, arg2, "Hello\n");

(fully bound), or

Callback::make(&MyClass::my_func, arg1);

(partially bound), and so on.

To bind to reference arguments, the call to Callback::make() must be explicitly typed. For a class object my_obj of type MyClass, with a method void MyClass::my_method(int&), usage for a fully bound callback or functor would be:

int arg = 1;
Callback::Callback* cb =
Callback::make<MyClass, int&>(my_obj, &MyClass::my_method, arg);

Note however the caveats above about binding to reference arguments.

No similar explicit typing is required by Callback::make_ref(). Thus for a class object my_obj of type MyClass, with a method void MyClass::my_method(int, const Something&), usage for a fully bound callback or functor would be:

int arg1 = 1;
Something arg2;
Callback::Callback* cb =
Callback::make_ref(my_obj, &MyClass::my_method, arg1, arg2);

From version 2.0.9, Callback::lambda() provides an easy way of dealing with lambda expressions, for example:

Callback::Callback* cb;
{
std::string s("Hello");
cb = Callback::lambda<>([=](){std::cout << s << std::endl;});
}
cb->dispatch(); // 's' is now out of scope, but it has been captured by value
// by the lambda object and is now held by the callback object
delete cb;

With Callback::lambda(), the types of the unbound arguments must be explicitly specified as they cannot be deduced. Unbound arguments can comprise reference arguments. For example:

int res;
auto cb = Callback::lambda<int, int, int&>([](int j, int k, int& r) {r = j * k;});
cb->dispatch(2, 3, res);
std::cout << res << std::endl;
delete cb;

Callback::lambda() can take any function object, such as one returned by std::bind(). So, constructing a callback object representing a class object my_obj of type MyClass, with a method void MyClass::my_method(int, int, int, double, const char*), where a value is to be bound to the second argument could comprise:

using namespace std::placeholders; // for _1, _2, _3 and _4
int arg = 1;
auto cb = Callback::lambda<int, int, double, const char*>(
std::bind(&MyClass::my_method, &my_obj,
_1, arg, _2, _3, _4)
);
cb->dispatch(5, 3, 10.2, "Hello\n");
delete cb;

Using std::bind, if the bound argument were a reference (that is, the signature of MyClass::my_method were (int, int&, int, double, const char*) and it were safe to do so (see above), it could be bound with std::ref(), as in:

using namespace std::placeholders; // for _1, _2, _3 and _4
int arg;
auto cb = Callback::lambda<int, int, double, const char*>(
std::bind(&MyClass::my_method, &my_obj,
_1, std::ref(arg), _2, _3, _4)
);

Prior to version 2.0.9, lambda expressions and the return value of std::bind() would have to be passed by using a temporary std::function object and Callback::make, as follows:

Callback::Callback* cb;
{
std::string s("Hello");
cb = Callback::make(std::function<void()>{[=](){std::cout << s << std::endl;}});
}
cb->dispatch();
delete cb;

## Overloaded functions

Note that creating callbacks for overloaded functions can give rise to an ambiguity when using Callback::make(), arising from the fact that the callback object may have an unbound argument. For example:

class MyClass {
...
void add(int i);
void add(int i, int j);
void add(double d);
};
MyClass obj;
using namespace Cgu;
Callback::Callback* cb1 = Callback::make(obj, &MyClass::add, 1, 2); // ok
Callback::Callback* cb2 = Callback::make(obj, &MyClass::add, 1.0); // ok
Callback::Callback* cb3 = Callback::make(obj, &MyClass::add, 1); // ambiguous - compilation failure

The third call to Callback::make() is ambiguous, as it could be creating a callback for either the function MyClass::add(int) with no unbound argument (that is, creating a Callback::Callback object), or the function MyClass::add(int, int) with an unbound int argument (that is, creating a Callback::CallbackArg<int> object). This situation could be disambiguated by specifically stating the type of the function which is to be chosen, namely, to instantiate the callback in the third call with:

// either:
Callback::Callback* cb3 =
Callback::make(obj, static_cast<void (MyClass::*)(int)>(&MyClass::add), 1);
// or:
Callback::CallbackArg<int>* cb3 =
Callback::make(obj, static_cast<void (MyClass::*)(int, int)>(&MyClass::add), 1);

Callback::make_ref() is less capable than Callback::make() at deducing template types. It cannot resolve overloaded functions by examining the arguments passed to it. For example, take a class MyClass as follows:

class MyClass {
...
void add(int i, const double& d);
void add(const int& j, const int& k);
};

Callback::make_ref() would require explicit disambiguation like this:

Callback::Callback* cb1 =
Callback::make_ref(obj, static_cast<void (MyClass::*)(int, const double&)>(&MyClass::add), 1, 2.2);
Callback::Callback* cb2 =
Callback::make_ref(obj, static_cast<void (MyClass::*)(const int&, const int&)>(&MyClass::add), 4, 5);

Note also that, for CallbackArg objects created from std::function objects, the std::function constructors and the std::mem_fn() and std::bind() functions normally do not allow any function overloading without explicit disambiguation.

## Posting of callbacks

This file also provides Callback::post() functions which will execute a callback in a glib main loop and can be used (amongst other things) to pass an event from a worker thread to the main program thread. In that respect, it provides an alternative to the Notifier class. It is passed a pointer to a Callback::Callback object created with a call to Callback::make() or Callback::lambda().

To provide for thread-safe automatic disconnection of the callback if the object whose method it represents is destroyed before the callback executes in the main loop, include a Releaser as a public member of that object and pass the Releaser object as the second argument of Callback::post(). Note that for this to be race free, the lifetime of the remote object whose method is to be invoked must be determined by the thread to whose main loop the callback has been attached. When the main loop begins invoking the execution of the callback, the remote object must either wholly exist (in which case the callback will be invoked) or have been destroyed (in which case the callback will be ignored), and not be in some transient half-state governed by another thread.

Advantages as against Notifier:

1. If there are a lot of different events requiring callbacks to be dispatched in the program from worker threads to the main thread, this avoids having separate Notifier objects for each event.
2. It is easier to pass arguments with varying values - they can be passed as arguments to the Callback::make functions and no special synchronisation is normally required (the call to g_source_attach() invokes locking of the main loop which will have the effect of ensuring memory visibility). With a Notifier object it may be necessary to use an asynchronous queue to pass variable values (or to bind a reference to the data, thus normally requiring separate synchronisation).
3. Although the callback would normally be sent for execution by the main program loop, and that is the default, it can be sent for execution by any thread which has its own GMainContext/GMainLoop objects. Thus callbacks can be passed for execution between worker threads, or from the main program thread to worker threads, as well as from worker threads to the main program thread.

Disadvantages as against Notifier:

1. Less efficient, as a new callback object has to be created on freestore every time the callback is invoked, together with a new Emitter object if a Releaser is used to track the callback.
2. Multiple callbacks relevant to a single event cannot be invoked from a single call for the event - each callback has to be separately dispatched.

## Typedef Documentation

typedef CallbackArg Cgu::Callback::Callback

typedef FunctorArg Cgu::Callback::Functor

typedef SafeFunctorArg Cgu::Callback::SafeFunctor

## Function Documentation

template<class... FreeArgs, class Lambda >

CallbackArg<FreeArgs...>* Cgu::Callback::lambda | ( | Lambda && | l | ) |

A convenience function to make Callback::CallbackArg objects from C++11 lambda expressions, or from any other arbitrary callable object. The types of the unbound arguments (if any) must be explicitly specified as template parameters, as they cannot be deduced. From version 2.0.10, this function can be called for lambda expressions which are declared mutable (in version 2.0.9, this function could only be called for non-mutable lambda expressions). From version 2.0.16, this function can be passed callable objects which are lvalues as well as rvalues (prior to version 2.0.16, it could only be passed callable objects which are rvalues).

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of an object captured by the lambda expression throws.

Since 2.0.9

template<class T , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | T & | t,
|  | void(T::*)(FreeArgs...) | func
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc | It might throw std::bad_alloc if memory is exhausted and the system throws in that case. This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option (instead glib will terminate the program if it is unable to obtain memory from the operating system).

template<class T , class BoundArg , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | T & | t,
|  | void(T::*)(BoundArg, FreeArgs...) | func,
|  | BoundArg | arg
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, FreeArgs...) | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2,
|  | BoundArg3 | arg3
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2,
|  | BoundArg3 | arg3,
|  | BoundArg4 | arg4
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2,
|  | BoundArg3 | arg3,
|  | BoundArg4 | arg4,
|  | BoundArg5 | arg5
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | const T & | t,
|  | void(T::*)(FreeArgs...) const | func
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc | It might throw std::bad_alloc if memory is exhausted and the system throws in that case. This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option (instead glib will terminate the program if it is unable to obtain memory from the operating system).

template<class T , class BoundArg , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | const T & | t,
|  | void(T::*)(BoundArg, FreeArgs...) const | func,
|  | BoundArg | arg
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, FreeArgs...) const | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2,
|  | BoundArg3 | arg3
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2,
|  | BoundArg3 | arg3,
|  | BoundArg4 | arg4
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) const | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2,
|  | BoundArg3 | arg3,
|  | BoundArg4 | arg4,
|  | BoundArg5 | arg5
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | void(*)(FreeArgs...) | func | ) |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc | It might throw std::bad_alloc if memory is exhausted and the system throws in that case. This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option (instead glib will terminate the program if it is unable to obtain memory from the operating system).

template<class BoundArg , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | void(*)(BoundArg, FreeArgs...) | func,
|  | BoundArg | arg
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class BoundArg1 , class BoundArg2 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | void(*)(BoundArg1, BoundArg2, FreeArgs...) | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | void(*)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2,
|  | BoundArg3 | arg3
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | void(*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2,
|  | BoundArg3 | arg3,
|  | BoundArg4 | arg4
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | void(*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) | func,
|  | BoundArg1 | arg1,
|  | BoundArg2 | arg2,
|  | BoundArg3 | arg3,
|  | BoundArg4 | arg4,
|  | BoundArg5 | arg5
| ) |  |

A convenience function to make Callback::CallbackArg objects

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | const std::function< void(FreeArgs...)> & | f | ) |

A convenience function to make Callback::CallbackArg objects from std::function objects.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make | ( | std::function< void(FreeArgs...)> && | f | ) |

A convenience function to make Callback::CallbackArg objects from std::function objects.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | T & | t,
|  | void(T::*)(FreeArgs...) | func
| ) |  |

Since this function constructs a callback which does not take a bound argument, it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc | It might throw std::bad_alloc if memory is exhausted and the system throws in that case. This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option (instead glib will terminate the program if it is unable to obtain memory from the operating system).

Since 2.0.0-rc3

template<class T , class BoundArg , class Arg , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | T & | t,
|  | void(T::*)(BoundArg, FreeArgs...) | func,
|  | Arg && | arg
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class T , class BoundArg1 , class BoundArg2 , class Arg1 , class Arg2 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, FreeArgs...) | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class Arg1 , class Arg2 , class Arg3 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2,
|  | Arg3 && | arg3
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2,
|  | Arg3 && | arg3,
|  | Arg4 && | arg4
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class Arg5 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2,
|  | Arg3 && | arg3,
|  | Arg4 && | arg4,
|  | Arg5 && | arg5
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class T , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | const T & | t,
|  | void(T::*)(FreeArgs...) const | func
| ) |  |

Since this function constructs a callback which does not take a bound argument, it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc | It might throw std::bad_alloc if memory is exhausted and the system throws in that case. This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option (instead glib will terminate the program if it is unable to obtain memory from the operating system).

Since 2.0.0-rc3

template<class T , class BoundArg , class Arg , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | const T & | t,
|  | void(T::*)(BoundArg, FreeArgs...) const | func,
|  | Arg && | arg
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class T , class BoundArg1 , class BoundArg2 , class Arg1 , class Arg2 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, FreeArgs...) const | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class Arg1 , class Arg2 , class Arg3 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2,
|  | Arg3 && | arg3
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2,
|  | Arg3 && | arg3,
|  | Arg4 && | arg4
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class Arg5 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) const | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2,
|  | Arg3 && | arg3,
|  | Arg4 && | arg4,
|  | Arg5 && | arg5
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | void(*)(FreeArgs...) | func | ) |

Since this function constructs a callback which does not take a bound argument, it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc | It might throw std::bad_alloc if memory is exhausted and the system throws in that case. This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option (instead glib will terminate the program if it is unable to obtain memory from the operating system).

Since 2.0.0-rc3

template<class BoundArg , class Arg , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | void(*)(BoundArg, FreeArgs...) | func,
|  | Arg && | arg
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class BoundArg1 , class BoundArg2 , class Arg1 , class Arg2 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | void(*)(BoundArg1, BoundArg2, FreeArgs...) | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class Arg1 , class Arg2 , class Arg3 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | void(*)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2,
|  | Arg3 && | arg3
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | void(*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2,
|  | Arg3 && | arg3,
|  | Arg4 && | arg4
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class Arg1 , class Arg2 , class Arg3 , class Arg4 , class Arg5 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | void(*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) | func,
|  | Arg1 && | arg1,
|  | Arg2 && | arg2,
|  | Arg3 && | arg3,
|  | Arg4 && | arg4,
|  | Arg5 && | arg5
| ) |  |

An alternative function to make Callback::CallbackArg objects, which is for use where a target function either receives a class type bound argument by value, or receives a bound argument by reference to const in a case where the generated CallbackArg object is to store a copy of that argument instead of just keeping a reference.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws.

Since 2.0.0-rc3

template<class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | const std::function< void(FreeArgs...)> & | f | ) |

A convenience function to make Callback::Callback objects from std::function objects. Since this function takes no bound argument (and bound arguments are bound into the std::function object), it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_ref | ( | std::function< void(FreeArgs...)> && | f | ) |

A convenience function to make Callback::Callback objects from std::function objects. Since this function takes no bound argument (and bound arguments are bound into the std::function object), it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws and it is not a reference argument.

template<class T , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | T & | t,
|  | void(T::*)(FreeArgs...) | func
| ) |  |

DEPRECATED.

Since this function constructs a callback which does not take a bound argument, it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc | It might throw std::bad_alloc if memory is exhausted and the system throws in that case. This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option (instead glib will terminate the program if it is unable to obtain memory from the operating system).

template<class T , class BoundArg , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | T & | t,
|  | void(T::*)(BoundArg, FreeArgs...) | func,
|  | const BoundArg & | arg
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, FreeArgs...) | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2,
|  | const BoundArg3 & | arg3
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2,
|  | const BoundArg3 & | arg3,
|  | const BoundArg4 & | arg4
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2,
|  | const BoundArg3 & | arg3,
|  | const BoundArg4 & | arg4,
|  | const BoundArg5 & | arg5
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | const T & | t,
|  | void(T::*)(FreeArgs...) const | func
| ) |  |

DEPRECATED.

Since this function constructs a callback which does not take a bound argument, it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc | It might throw std::bad_alloc if memory is exhausted and the system throws in that case. This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option (instead glib will terminate the program if it is unable to obtain memory from the operating system).

template<class T , class BoundArg , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | const T & | t,
|  | void(T::*)(BoundArg, FreeArgs...) const | func,
|  | const BoundArg & | arg
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, FreeArgs...) const | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) const | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2,
|  | const BoundArg3 & | arg3
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) const | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2,
|  | const BoundArg3 & | arg3,
|  | const BoundArg4 & | arg4
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class T , class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | const T & | t,
|  | void(T::*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) const | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2,
|  | const BoundArg3 & | arg3,
|  | const BoundArg4 & | arg4,
|  | const BoundArg5 & | arg5
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | void(*)(FreeArgs...) | func | ) |

DEPRECATED.

Since this function constructs a callback which does not take a bound argument, it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc | It might throw std::bad_alloc if memory is exhausted and the system throws in that case. This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option (instead glib will terminate the program if it is unable to obtain memory from the operating system).

template<class BoundArg , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | void(*)(BoundArg, FreeArgs...) | func,
|  | const BoundArg & | arg
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class BoundArg1 , class BoundArg2 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | void(*)(BoundArg1, BoundArg2, FreeArgs...) | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | void(*)(BoundArg1, BoundArg2, BoundArg3, FreeArgs...) | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2,
|  | const BoundArg3 & | arg3
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | void(*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, FreeArgs...) | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2,
|  | const BoundArg3 & | arg3,
|  | const BoundArg4 & | arg4
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class BoundArg1 , class BoundArg2 , class BoundArg3 , class BoundArg4 , class BoundArg5 , class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | void(*)(BoundArg1, BoundArg2, BoundArg3, BoundArg4, BoundArg5, FreeArgs...) | func,
|  | const BoundArg1 & | arg1,
|  | const BoundArg2 & | arg2,
|  | const BoundArg3 & | arg3,
|  | const BoundArg4 & | arg4,
|  | const BoundArg5 & | arg5
| ) |  |

DEPRECATED: use Callback::make_ref() instead.

An alternative function to make Callback::CallbackArg objects, which is for use where a target function receives an argument of class type by value which is to be a bound argument, so the compiler is not able to carry out copy elision when constructing the callback object.

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | const std::function< void(FreeArgs...)> & | f | ) |

DEPRECATED.

A convenience function to make Callback::Callback objects from std::function objects. Since this function takes no bound argument (and bound arguments are bound into the std::function object), it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy constructor of a bound argument throws and it is not a reference argument.

template<class... FreeArgs>

CallbackArg<FreeArgs...>* Cgu::Callback::make_val | ( | std::function< void(FreeArgs...)> && | f | ) |

DEPRECATED.

A convenience function to make Callback::Callback objects from std::function objects. Since this function takes no bound argument (and bound arguments are bound into the std::function object), it is a synonym for make() (the two are identical).

Exceptions

  std::bad_alloc

  It might throw std::bad_alloc if memory is exhausted and the system throws in that case (this exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system). It will also throw if the copy or move constructor of a bound argument throws and it is not a reference argument.

template<class... T>

bool Cgu::Callback::operator!= | ( | const FunctorArg< T...> & | f1,
|  | const FunctorArg< T...> & | f2
| ) |  |

Two FunctorArg objects compare unequal if the addresses of the CallbackArg objects they contain are not the same. This comparison operator does not throw.

template<class... T>

bool Cgu::Callback::operator!= | ( | const SafeFunctorArg< T...> & | f1,
|  | const SafeFunctorArg< T...> & | f2
| ) |  |

Two SafeFunctorArg objects compare unequal if the addresses of the CallbackArg objects they contain are not the same. This comparison operator does not throw.

template<class... T>

bool Cgu::Callback::operator< | ( | const FunctorArg< T...> & | f1,
|  | const FunctorArg< T...> & | f2
| ) |  |

One FunctorArg object is less than another if the address of the CallbackArg object contained by the first is regarded by std::less as less than the address of the CallbackArg object contained by the other. This comparison operator does not throw.

template<class... T>

bool Cgu::Callback::operator< | ( | const SafeFunctorArg< T...> & | f1,
|  | const SafeFunctorArg< T...> & | f2
| ) |  |

One SafeFunctorArg object is less than another if the address of the CallbackArg object contained by the first is regarded by std::less as less than the address of the CallbackArg object contained by the other. This comparison operator does not throw.

template<class... T>

bool Cgu::Callback::operator== | ( | const FunctorArg< T...> & | f1,
|  | const FunctorArg< T...> & | f2
| ) |  |

Two FunctorArg objects compare equal if the addresses of the CallbackArg objects they contain are the same. This comparison operator does not throw.

template<class... T>

bool Cgu::Callback::operator== | ( | const SafeFunctorArg< T...> & | f1,
|  | const SafeFunctorArg< T...> & | f2
| ) |  |

Two SafeFunctorArg objects compare equal if the addresses of the CallbackArg objects they contain are the same. This comparison operator does not throw.

void Cgu::Callback::post | ( | const Callback * | cb,
|  | gint | priority = `G_PRIORITY_DEFAULT_IDLE`,
|  | GMainContext * | context = `0`
| ) |  |

Posts a callback for execution by a glib main loop. It is thread-safe provided that (if glib < 2.32 is used) g_thread_init() has been called. glib >= 2.32 does not require g_thread_init() to be called. This function will not throw.

Parameters

  cb | The callback object. Ownership is taken of this object, and it will be deleted when it has been finished with.
  priority | The priority to be given to the callback in the main loop. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT_IDLE. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt
  context | The glib main loop context in which the callback is to be executed (the default of NULL will cause the callback to be executed in the main program loop, and this is usually what is wanted).

Note
  Cancellation of the receiving thread is blocked when the callback executes.

void Cgu::Callback::post | ( | const Callback * | cb,
|  | Releaser & | r,
|  | gint | priority = `G_PRIORITY_DEFAULT_IDLE`,
|  | GMainContext * | context = `0`
| ) |  |

Posts a callback for execution by a glib main loop. It is thread-safe provided that (if glib < 2.32 is used) g_thread_init() has been called. glib >= 2.32 does not require g_thread_init() to be called. This function will not throw.

Parameters

  cb | The callback object. Ownership is taken of this object, and it will be deleted when it has been finished with.
  r | A Releaser object for automatic disconnection of the callback from the main loop.
  priority | The priority to be given to the callback in the main loop. In ascending order of priorities, priorities are G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is G_PRIORITY_DEFAULT_IDLE. This determines the order in which the callback will appear in the event list in the main loop, not the priority which the OS will adopt.
  context | The glib main loop context in which the callback is to be executed (the default of NULL will cause the callback to be executed in the main program loop, and this is usually what is wanted).

Exceptions

  std::bad_alloc | This function might throw std::bad_alloc if memory is exhausted and the system throws in that case. If it does so, the Callback object will be disposed of.
  Cgu::Thread::MutexError | This method might throw Cgu:Thread::MutexError if initialisation of the mutex in a SafeEmitterArg object constructed by this method fails. If it does so, the Callback object will be disposed of. (It is often not worth checking for this exception, as it means either memory is exhausted or pthread has run out of other resources to create new mutexes.)

Note
  1. Cancellation of the receiving thread is blocked when the callback executes.
  2. By virtue of the Releaser object, it is in theory possible (if memory is exhausted and the system throws in that case) that an internal SafeEmitterArg object will throw std::bad_alloc when emitting/executing the callback in the glib main loop, with the result that the relevant callback will not execute (instead the exception will be consumed and a g_critical() warning will be issued). This is rarely of any relevance because glib will abort the program if it is itself unable to obtain memory from the operating system. However, where it is relevant, design the program so that it is not necessary to provide a releaser object.