The callback interface class. More...

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

Public Member Functions
virtual void	dispatch (typename Cgu::Param< FreeArgs >::ParamType... args) const =0

	CallbackArg ()

virtual	~CallbackArg ()

Detailed Description

The callback interface class.

See also: Callback namespace; FunctorArg SafeFunctorArg

This class provides type erasure for callable objects. The CallbackArg type is constructed on free store and can wrap any callable object, such as a lambda expression or the return value of std::bind.

The class is particularly relevant where a callable object with bound values needs to be handed safely between threads, or in other cases where a callback object has to be passed by pointer (which will happen at some stage with glib or pthreads). They are therefore useful for general event passing when used together with the Callback::post() functions or as the continuation for GIO async operations, and are more efficient than constructing std::function objects on free store and passing them by pointer (they avoid one level of indirection and only require one rather than two allocations).

The classes are also used in the Emitter/EmitterArg and SafeEmitter/SafeEmitterArg classes in emitter.h, which enable callable objects to be connected to an emitter and provide for automatic disconnection where a class object whose member a callback represents or calls into ceases to exist. They are also used internally to implement the Thread::Future and Thread::TaskManager classes.

The template types are the types of the unbound arguments, if any. Callback::CallbackArg<> is typedef'ed to Callback::Callback. The main method of constructing a Callback/CallbackArg object is with the Callback::lambda() factory function. When using Callback::lambda(), the unbound argument types (if any) must be passed as explicit template parameters.

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).

Usage

These are examples:

using namespace Cgu;
 
// here cb1 is of type Callback::Callback*
auto cb1 = Callback::lambda<>([]() {std::cout << "Hello world\n";});
cb1->dispatch();
delete cb1;
 
// here Callback::to_unique() is used to make a std::unique_ptr object to
// manage the callback. cb2 is of type std::unique_ptr<const Callback::Callback>
auto cb2 = Callback::to_unique(Callback::lambda<>([]() {std::cout << "Hello world\n";}));
cb2->dispatch();
 
// here cb3 is of type std::unique_ptr<const Callback::CallbackArg<int, int&>>
auto cb3 = Callback::to_unique(Callback::lambda<int, int&>([] (int i, int& j) {j = 10 * i;}));
int res;
cb3->dispatch(2, res);
std::cout << "10 times 2 is " << res << '\n';

For further background, including about the Callback::make(), Callback::make_ref() and Callback::to_unique() functions, read this: Callback

Constructor & Destructor Documentation

◆ CallbackArg()

Cgu::Callback::CallbackArg::CallbackArg ( )

inline

The constructor will not throw unless the copy constructor of an argument bound to the derived implementation class throws.

◆ ~CallbackArg()

virtual Cgu::Callback::CallbackArg::~CallbackArg ( )

inlinevirtual

The destructor will not throw unless the destructor of an argument bound to the derived implementation class throws.

Member Function Documentation

◆ dispatch()

virtual void Cgu::Callback::CallbackArg::dispatch ( typename Cgu::Param< FreeArgs >::ParamType... args ) const

pure virtual

This will execute the referenced function, callable object or class method encapsulated by this class. It will only throw if the dispatched function, callable object or class method throws, or if the copy constructor of a free or bound argument throws and it is not a reference argument. It is thread safe if the referenced function or class method is thread safe.

Parameters

args	The unbound arguments to be passed to the referenced function, callable object or class method, if any.

Note: We use dispatch() to execute the callback, because the callback would normally be invoked through a base class pointer. To invoke it through operator()(), use the FunctorArg or SafeFunctorArg wrapper class.

The documentation for this class was generated from the following file:

callback.h