|
c++-gtk-utils
|
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< FreeArgs >::ParamType... args) const |
| void | emit (typename Cgu::Param< FreeArgs >::ParamType... args) const |
| bool | test_emit (typename Cgu::Param< FreeArgs >::ParamType... args) const |
| Callback::SafeFunctorArg< FreeArgs... > | connect (const Callback::SafeFunctorArg< FreeArgs... > &f) |
| Callback::SafeFunctorArg< FreeArgs... > | connect (const Callback::SafeFunctorArg< FreeArgs... > &f, Releaser &r) |
| template<class F , class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type, const Callback::SafeFunctorArg<FreeArgs...>>::value>::type> | |
| Callback::SafeFunctorArg< FreeArgs... > | connect (F &&f) |
| template<class F , class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type, const Callback::SafeFunctorArg<FreeArgs...>>::value>::type> | |
| Callback::SafeFunctorArg< FreeArgs... > | connect (F &&f, Releaser &r) |
| void | disconnect (const Callback::SafeFunctorArg< FreeArgs... > &f) |
| void | block (const Callback::SafeFunctorArg< FreeArgs... > &f) |
| void | unblock (const Callback::SafeFunctorArg< FreeArgs... > &f) |
| SafeEmitterArg ()=default | |
| SafeEmitterArg (const SafeEmitterArg &)=delete | |
| SafeEmitterArg & | operator= (const SafeEmitterArg &)=delete |
| ~SafeEmitterArg () | |
Friends | |
| class | Releaser |
A thread-safe class to execute callbacks connected to it, with provision for automatic disconnection.
This is a thread-safe version of the EmitterArg class. Callable objects (such as lambda expressions or the return value of std::bind) or Callback::SafeFunctorArg objects may be connected to SafeEmitter classes (referred to be below as "connected callables"), 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 connected callables representing (or calling into) 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 types are the types of the unbound arguments, if any. SafeEmitterArg<> is typedef'ed to SafeEmitter.
Usage
These are examples:
Callback::SafeFunctorArg 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):
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.
|
default |
| std::bad_alloc | The constructor might throw std::bad_alloc if memory is exhausted and the system throws in that case. |
| Thread::MutexError | The 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.) |
|
delete |
This class cannot be copied. The copy constructor is deleted.
| Cgu::SafeEmitterArg< FreeArgs >::~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.
| void Cgu::SafeEmitterArg< FreeArgs >::block | ( | const Callback::SafeFunctorArg< 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). It is thread safe.
| f | The functor to block. |
| Callback::SafeFunctorArg< FreeArgs... > Cgu::SafeEmitterArg< FreeArgs >::connect | ( | const Callback::SafeFunctorArg< FreeArgs... > & | f | ) |
Connects a Callback::SafeFunctorArg object.
| f | The Callback::SafeFunctorArg object to connect. |
| std::bad_alloc | The method might throw std::bad_alloc if memory is exhausted and the system throws in that case. |
| Callback::SafeFunctorArg< FreeArgs... > Cgu::SafeEmitterArg< FreeArgs >::connect | ( | const Callback::SafeFunctorArg< FreeArgs... > & | f, |
| Releaser & | r | ||
| ) |
Connects a Callback::SafeFunctorArg object.
| f | The Callback::SafeFunctorArg object to connect. |
| r | A Releaser object for automatic disconnection of the Callback::SafeFunctorArg object if the object whose method it represents is destroyed. |
| std::bad_alloc | The method might throw std::bad_alloc if memory is exhausted and the system throws in that case. |
|
inline |
Connects a callable object, such as formed by a lambda expression or the result of std::bind.
| f | The callable object to connect. If must have the same unbound argument types as the SafeEmitterArg object concerned. |
| 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
|
inline |
Connects a callable object, such as formed by a lambda expression or the result of std::bind.
| f | The callable object to connect. If must have the same unbound argument types as the SafeEmitterArg 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. |
| 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
| void Cgu::SafeEmitterArg< FreeArgs >::disconnect | ( | const Callback::SafeFunctorArg< 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). It is thread safe.
| f | The functor to disconnect. |
| void Cgu::SafeEmitterArg< FreeArgs >::emit | ( | typename Cgu::Param< FreeArgs >::ParamType... | args | ) | 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.
| args | The unbound arguments to be passed to the referenced function or class method, if any. |
| 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). |
|
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.
| args | The unbound arguments to be passed to the referenced function or class method, if any. |
| 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). |
|
delete |
This class cannot be copied. The assignment operator is deleted.
| bool Cgu::SafeEmitterArg< 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 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.)
| args | The unbound arguments to be passed to the referenced function or class method, if any. |
| 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). |
| void Cgu::SafeEmitterArg< FreeArgs >::unblock | ( | const Callback::SafeFunctorArg< 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). It is thread safe.
| f | The functor to unblock. |
|
friend |
1.8.20