c++-gtk-utils
Public Member Functions | Friends | List of all members
Cgu::SafeEmitterArg< FreeArg > Class Template Reference

A thread-safe 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< FreeArg >::ParamType arg) const
 
void emit (typename Cgu::Param< FreeArg >::ParamType arg) const
 
bool test_emit (typename Cgu::Param< FreeArg >::ParamType arg) const
 
Callback::SafeFunctorArg< FreeArg > connect (const Callback::SafeFunctorArg< FreeArg > &f)
 
Callback::SafeFunctorArg< FreeArg > connect (const Callback::SafeFunctorArg< FreeArg > &f, Releaser &r)
 
void disconnect (const Callback::SafeFunctorArg< FreeArg > &f)
 
void block (const Callback::SafeFunctorArg< FreeArg > &f)
 
void unblock (const Callback::SafeFunctorArg< FreeArg > &f)
 
 SafeEmitterArg ()
 
 ~SafeEmitterArg ()
 

Friends

class Releaser
 

Detailed Description

template<class FreeArg>
class Cgu::SafeEmitterArg< FreeArg >

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

See also
EmitterArg Releaser
emitter.h
Callback namespace

This is a thread-safe version of the EmitterArg class. Callback::SafeFunctorArg objects may be connected to SafeEmitter classes, and will be executed when SafeEmitterArg<>::emit() or SafeEmitterArg<>::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 any of its methods to be disconnected automatically from the SafeEmitterArg 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 type is the type of the unbound argument (or type container of unbound arguments), if any. SafeEmitterArg<void> is typedef'ed to SafeEmitter.

Usage

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

using namespace Cgu;
int arg = 1;
se.connect(Callback::make(my_obj, &MyClass::my_method, arg, "Hello\n"));
se();

Or for a partially bound functor and emitter:

using namespace Cgu;
int arg = 1;
se.connect(Callback::make(my_obj, &MyClass::my_method, arg));
se("Hello\n");

For further background, including about thread-safety, exception safety, the use of the Cgu::TypeTuple struct for calls involving two or three unbound arguments and other matters, read this: emitter.h

Constructor & Destructor Documentation

template<class FreeArg>
Cgu::SafeEmitterArg< FreeArg >::SafeEmitterArg ( )
inline
Exceptions
std::bad_allocThe constructor might throw std::bad_alloc if memory is exhausted and the system throws in that case.
Thread::MutexErrorThe constructor might throw Thread::MutexError if initialisation of the contained mutex fails. (It is often not worth checking for this, as it means either memory is exhausted or pthread has run out of other resources to create new mutexes.)
template<class FreeArg >
Cgu::SafeEmitterArg< FreeArg >::~SafeEmitterArg ( )

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). It is thread-safe as regards the dropping of any connected functors and of any relevant Releaser objects.

Member Function Documentation

template<class FreeArg>
void Cgu::SafeEmitterArg< FreeArg >::block ( const Callback::SafeFunctorArg< FreeArg > &  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). It is thread safe.

Parameters
fThe functor to block.
Note
1. If the same functor has been connected more than once to the same SafeEmitterArg object, this call will block all of them.
2. This function is specialised for SafeEmitter (ie SafeEmitterArg<void>) to take a Callback::SafeFunctor argument, and for SafeEmitterArg<TypeTuple<T1, T2> > and SafeEmitterArg<TypeTuple<T1, T2, T3> > to take a Callback::SafeFunctorArg<TypeTuple<T1, T2> > and Callback::SafeFunctorArg<TypeTuple<T1, T2, T3> > argument respectively.
template<class FreeArg>
Callback::SafeFunctorArg< FreeArg > Cgu::SafeEmitterArg< FreeArg >::connect ( const Callback::SafeFunctorArg< FreeArg > &  f)

Connects a functor. It is thread safe.

Parameters
fThe functor to connect.
Returns
The functor connected.
Exceptions
std::bad_allocThe method might throw std::bad_alloc if memory is exhausted and the system throws in that case.
Note
This function is specialised for SafeEmitter (ie SafeEmitterArg<void>) to take and return a Callback::SafeFunctor argument, and for SafeEmitterArg<TypeTuple<T1, T2> > and SafeEmitterArg<TypeTuple<T1, T2, T3> > to take and return a Callback::SafeFunctorArg<TypeTuple<T1, T2> > and Callback::SafeFunctorArg<TypeTuple<T1, T2, T3> > argument respectively.
template<class FreeArg>
Callback::SafeFunctorArg< FreeArg > Cgu::SafeEmitterArg< FreeArg >::connect ( const Callback::SafeFunctorArg< FreeArg > &  f,
Releaser r 
)

Connects a functor. It is thread safe.

Parameters
fThe functor to connect.
rA Releaser object for automatic disconnection of the functor if the object whose method it represents is destroyed.
Returns
The functor connected.
Exceptions
std::bad_allocThe method might throw std::bad_alloc if memory is exhausted and the system throws in that case.
Note
This function is specialised for SafeEmitter (ie SafeEmitterArg<void>) to take and return a Callback::SafeFunctor argument, and for SafeEmitterArg<TypeTuple<T1, T2> > and SafeEmitterArg<TypeTuple<T1, T2, T3> > to take and return a Callback::SafeFunctorArg<TypeTuple<T1, T2> > and Callback::SafeFunctorArg<TypeTuple<T1, T2, T3> > argument respectively.
template<class FreeArg>
void Cgu::SafeEmitterArg< FreeArg >::disconnect ( const Callback::SafeFunctorArg< FreeArg > &  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). It is thread safe.

Parameters
fThe functor to disconnect.
Note
1. If the same functor has been connected more than once to the same SafeEmitterArg object, this call will disconnect all of them.
2. This function is specialised for SafeEmitter (ie SafeEmitterArg<void>) to take a Callback::SafeFunctor argument, and for SafeEmitterArg<TypeTuple<T1, T2> > and SafeEmitterArg<TypeTuple<T1, T2, T3> > to take a Callback::SafeFunctorArg<TypeTuple<T1, T2> > and Callback::SafeFunctorArg<TypeTuple<T1, T2, T3> > argument respectively.
template<class FreeArg>
void Cgu::SafeEmitterArg< FreeArg >::emit ( typename Cgu::Param< FreeArg >::ParamType  arg) const

This will execute the connected functors. It is thread safe if the functions or class methods referenced by the connected functors are thread safe.

Parameters
argThe argument to be passed to the referenced function or class method, if any.
Exceptions
std::bad_allocThe 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).
Note
This function is specialised for SafeEmitter (ie SafeEmitterArg<void>) to take no argument, and for SafeEmitterArg<TypeTuple<T1, T2> > and SafeEmitterArg<TypeTuple<T1, T2, T3> > to take two and three arguments respectively.
template<class FreeArg>
void Cgu::SafeEmitterArg< FreeArg >::operator() ( typename Cgu::Param< FreeArg >::ParamType  arg) const
inline

This will execute the connected functors. It is thread safe if the functions or class methods referenced by the connected functors are thread safe.

Parameters
argThe argument, if any, to be passed to the functions or class methods referenced by the connected functors.
Exceptions
std::bad_allocThe 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).
Note
This function is specialised for SafeEmitter (ie SafeEmitterArg<void>) to take no argument, and for SafeEmitterArg<TypeTuple<T1, T2> > and SafeEmitterArg<TypeTuple<T1, T2, T3> > to take two and three arguments respectively.
template<class FreeArg>
bool Cgu::SafeEmitterArg< FreeArg >::test_emit ( typename Cgu::Param< FreeArg >::ParamType  arg) const

This will execute the connected functors, but it also reports whether in fact there were any connected functors to execute. It is thread safe if the functions or class methods referenced by the connected functors are thread safe. (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
argThe argument 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_allocThe 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).
Note
This function is specialised for SafeEmitter (ie SafeEmitterArg<void>) to take no argument, and for SafeEmitterArg<TypeTuple<T1, T2> > and SafeEmitterArg<TypeTuple<T1, T2, T3> > to take two and three arguments respectively.
template<class FreeArg>
void Cgu::SafeEmitterArg< FreeArg >::unblock ( const Callback::SafeFunctorArg< FreeArg > &  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). It is thread safe.

Parameters
fThe functor to unblock.
Note
1. If the same functor has been connected more than once to the same SafeEmitterArg object, this call will unblock all of them.
2. This function is specialised for SafeEmitter (ie SafeEmitterArg<void>) to take a Callback::SafeFunctor argument, and for SafeEmitterArg<TypeTuple<T1, T2> > and SafeEmitterArg<TypeTuple<T1, T2, T3> > to take a Callback::SafeFunctorArg<TypeTuple<T1, T2> > and Callback::SafeFunctorArg<TypeTuple<T1, T2, T3> > argument respectively.

Friends And Related Function Documentation

template<class FreeArg>
friend class Releaser
friend

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