Cgu::EmitterArg< FreeArgs > Class Template Reference

A class to execute callbacks connected to it, with provision for automatic disconnection. More...

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

Public Member Functions
void	operator() (typename Cgu::Param< FreeArgs >::ParamType... args) const
void	emit (typename Cgu::Param< FreeArgs >::ParamType... args) const
bool	test_emit (typename Cgu::Param< FreeArgs >::ParamType... args) const
Callback::FunctorArg< FreeArgs... >	connect (const Callback::FunctorArg< FreeArgs... > &f)
Callback::FunctorArg< FreeArgs... >	connect (const Callback::FunctorArg< FreeArgs... > &f, Releaser &r)
template<class F , class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type, const Callback::FunctorArg<FreeArgs...>>::value>::type>
Callback::FunctorArg< FreeArgs... >	connect (F &&f)
template<class F , class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type, const Callback::FunctorArg<FreeArgs...>>::value>::type>
Callback::FunctorArg< FreeArgs... >	connect (F &&f, Releaser &r)
void	disconnect (const Callback::FunctorArg< FreeArgs... > &f)
void	block (const Callback::FunctorArg< FreeArgs... > &f)
void	unblock (const Callback::FunctorArg< FreeArgs... > &f)
	EmitterArg ()=default
	EmitterArg (const EmitterArg &)=delete
EmitterArg &	operator= (const EmitterArg &)=delete
	~EmitterArg ()

Friends
class	Releaser

Detailed Description

template<class... FreeArgs>
class Cgu::EmitterArg< FreeArgs >

A class to execute callbacks connected to it, with provision for automatic disconnection.

See also

SafeEmitterArg Releaser

emitter.h

Callback namespace

Callable objects (such as lambda expressions or the return value of std::bind) or Callback::FunctorArg objects may be connected to Emitter classes, and will be executed when EmitterArg::emit() or EmitterArg::operator()() are called.

One version of the connect() method takes a Releaser object as an argument. Such a Releaser object should be a public member of any target class which wants functors representing (or calling into) any of its methods to be disconnected automatically from the EmitterArg object when the target class object is destroyed.

A connection may be explicitly disconnected by calling the disconnect() method, and may also be temporarily blocked and subsequently unblocked with the block() and unblock() methods.

The template types are the types of the unbound arguments, if any. EmitterArg<> is typedef'ed to Emitter.

Usage

These are examples:

using namespace Cgu;
 
Emitter e1;
e1.connect([] () {std::cout << "Hello world\n";});
e1();
 
int res;
EmitterArg<int, int&> e2;
e2.connect([] (int i, int& j) {j = 10 * i;});
e2(2, res);
std::cout << "10 times 2 is " << res << '\n';

Callback::FunctorArg objects may be connected to an emitter, and the connect() method may be directly initialized with the result of Callback::make(), Callback::make_ref() or Callback::lambda() and implicit conversion will take place. Here is an example using Callback::make_ref(), with a class object my_obj of type MyClass, with a method void MyClass::my_method(const Something&, int):

using namespace Cgu;
 
Something arg;
EmitterArg<int> e;
e.connect(Callback::make_ref(my_obj, &MyClass::my_method, arg));
e(5);

For further background, including about thread-safety and exception safety and other matters, read this: emitter.h, or for more information about bound and unbound arguments, read this: Cgu::Callback.

Constructor & Destructor Documentation

EmitterArg() [1/2]

template<class... FreeArgs>

Cgu::EmitterArg< FreeArgs >::EmitterArg ( )

default

Exceptions

std::bad_alloc

The constructor might throw std::bad_alloc if memory is exhausted and the system throws in that case.

EmitterArg() [2/2]

template<class... FreeArgs>

Cgu::EmitterArg< FreeArgs >::EmitterArg ( const EmitterArg< FreeArgs > &  )

delete

This class cannot be copied. The copy constructor is deleted.

~EmitterArg()

template<class... FreeArgs>

Cgu::EmitterArg< FreeArgs >::~EmitterArg

The destructor does not throw provided that the destructors of any bound arguments do not throw (as they should not do), and assuming that merely iterating through a list does not throw (as it would not on any sane implementation).

Member Function Documentation

block()

template<class... FreeArgs>

void Cgu::EmitterArg< FreeArgs >::block

(

const Callback::FunctorArg< FreeArgs... > &

f

)

Blocks a connected functor from executing when emit() or operator()() is called until unblock() is called. This method does not throw (assuming that merely iterating through a list does not throw, as it would not on any sane implementation).

Parameters

f	The functor to block.

Note

If the same functor has been connected more than once to the same EmitterArg object, this call will block all of them.

connect() [1/4]

template<class... FreeArgs>

Callback::FunctorArg< FreeArgs... > Cgu::EmitterArg< FreeArgs >::connect

(

const Callback::FunctorArg< FreeArgs... > &

f

)

Connects a Callback::FunctorArg object.

Parameters

f	The Callback::FunctorArg object to connect.

Returns

The Callback::FunctorArg object connected.

Exceptions

std::bad_alloc

The method might throw std::bad_alloc if memory is exhausted and the system throws in that case.

connect() [2/4]

template<class... FreeArgs>

Callback::FunctorArg< FreeArgs... > Cgu::EmitterArg< FreeArgs >::connect	(	const Callback::FunctorArg< FreeArgs... > &	f,
		Releaser &	r
	)

Connects a Callback::FunctorArg object.

Parameters

f	The Callback::FunctorArg object to connect.
r	A Releaser object for automatic disconnection of the Callback::FunctorArg object if the object whose method it represents is destroyed.

Returns

The Callback::FunctorArg object connected.

Exceptions

std::bad_alloc

The method might throw std::bad_alloc if memory is exhausted and the system throws in that case.

connect() [3/4]

template<class... FreeArgs>

template<class F , class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type, const Callback::FunctorArg<FreeArgs...>>::value>::type>

Callback::FunctorArg<FreeArgs...> Cgu::EmitterArg< FreeArgs >::connect ( F &&  f )

inline

Connects a callable object, such as formed by a lambda expression or the result of std::bind.

Parameters

f	The callable object to connect. If must have the same unbound argument types as the EmitterArg object concerned.

Returns

A Callback::FunctorArg object which can be passed to disconnect(), block() or unblock().

Exceptions

std::bad_alloc

The method might throw std::bad_alloc if memory is exhausted and the system throws in that case. If might also throw if the copy or move constructor of the callable object throws.

Since 2.1.0

connect() [4/4]

template<class... FreeArgs>

template<class F , class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type, const Callback::FunctorArg<FreeArgs...>>::value>::type>

Callback::FunctorArg<FreeArgs...> Cgu::EmitterArg< FreeArgs >::connect ( F &&  f, Releaser &  r  )

inline

Connects a callable object, such as formed by a lambda expression or the result of std::bind.

Parameters

f	The callable object to connect. If must have the same unbound argument types as the EmitterArg object concerned.
r	A Releaser object for automatic disconnection of the callable object if an object whose method it represents or calls into is destroyed.

Returns

A Callback::FunctorArg object which can be passed to disconnect(), block() or unblock().

Exceptions

std::bad_alloc

The method might throw std::bad_alloc if memory is exhausted and the system throws in that case. If might also throw if the copy or move constructor of the callable object throws.

Since 2.1.0

disconnect()

template<class... FreeArgs>

void Cgu::EmitterArg< FreeArgs >::disconnect

(

const Callback::FunctorArg< FreeArgs... > &

f

)

Disconnects a functor previously connected. This does not throw provided that the destructors of any bound arguments do not throw (as they should not do), and assuming that merely iterating through a list does not throw (as it would not on any sane implementation).

Parameters

f	The functor to disconnect.

Note

If the same functor has been connected more than once to the same EmitterArg object, this call will disconnect all of them.

emit()

template<class... FreeArgs>

void Cgu::EmitterArg< FreeArgs >::emit

(

typename Cgu::Param< FreeArgs >::ParamType...

args

)

const

This will execute the connected functors.

Parameters

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

Exceptions

std::bad_alloc

The method might throw std::bad_alloc if memory is exhausted and the system throws in that case. In addition, it will throw if the functions or class methods referenced by the functors throw (or if the copy constructor of a free or bound argument throws and it is not a reference argument).

operator()()

template<class... FreeArgs>

void Cgu::EmitterArg< FreeArgs >::operator() ( typename Cgu::Param< FreeArgs >::ParamType...  args ) const

inline

This will execute the connected functors.

Parameters

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

Exceptions

std::bad_alloc

The method might throw std::bad_alloc if memory is exhausted and the system throws in that case. In addition, it will throw if the functions or class methods referenced by the functors throw (or if the copy constructor of a free or bound argument throws and it is not a reference argument).

operator=()

template<class... FreeArgs>

EmitterArg& Cgu::EmitterArg< FreeArgs >::operator= ( const EmitterArg< FreeArgs > &  )

delete

This class cannot be copied. The assignment operator is deleted.

test_emit()

template<class... FreeArgs>

bool Cgu::EmitterArg< FreeArgs >::test_emit

(

typename Cgu::Param< FreeArgs >::ParamType...

args

)

const

This will execute the connected functors, but it also reports whether in fact there were any connected functors to execute. (It is not necessary to use this function just because it is not known whether a functor is connected - if the standard emit() function is called when no functor is connected, nothing will happen. The feature of this method is that it will report the outcome.)

Parameters

args	The unbound arguments to be passed to the connected functions or class methods, if any.

Returns

Returns false if there were no functors to execute, or true if functors have been executed.

Exceptions

std::bad_alloc

The method might throw std::bad_alloc if memory is exhausted and the system throws in that case. In addition, it will throw if the functions or class methods referenced by the functors throw (or if the copy constructor of a free or bound argument throws and it is not a reference argument).

unblock()

template<class... FreeArgs>

void Cgu::EmitterArg< FreeArgs >::unblock

(

const Callback::FunctorArg< FreeArgs... > &

f

)

Unblocks a previously blocked functor. This method does not throw (assuming that merely iterating through a list does not throw, as it would not on any sane implementation).

Parameters

f	The functor to unblock.

Note

If the same functor has been connected more than once to the same EmitterArg object, this call will unblock all of them.

Friends And Related Function Documentation

Releaser

template<class... FreeArgs>

friend class Releaser

friend

---

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

• emitter.h