You.i Engine
Signals and Slots

Detailed Description

Provides a means of decoupled communication across objects.

Signals and slots are a communication paradigm which resembles callback or listener models of communication but with added advantages due to looser coupling between objects. CYISignal represents a signal, an entity which may be emitted and which may carry data, and which can be easily connected to a CYISignalHandler's slots at runtime. When a signal is emitted the slot to which it is connected is called with parameters that may be carried by the signal.

It is common to see CYISignal objects in the public API for You.i Engine classes. For example, CYIPushButtonView derivatives use CYISignal emissions to report user actions such as button clicks.

Connecting to a CYISignal

Suppose there is a UI element which can be clicked by a user or have its text modified by an API. In both of these cases the element will signal that these events have occurred so that the application developer may respond accordingly.

class ButtonLabel
{
public:
    CYISignal<> Clicked;
    CYISignal<CYIString> TextChanged;
    ...
};

In this example the click and text changes will simply be logged by another class which is a CYISignalHandler.

class ButtonLabelEventLogger : public CYISignalHandler
{
public:
    void LogClick();
    void LogTextChange(CYIString labelText);
};

The connection between these objects is accomplished using CYISignal::Connect

void MyScreen::Init()
{
    ButtonLabel &button = GetButton();
    ButtonLabelEventLogger &logger = GetButtonLogger();

    button.Clicked.Connect(logger, &ButtonLabelEventLogger::LogClick);
    button.TextChanged.Connect(logger, &ButtonLabelEventLogger::LogTextChange);
}

Note that the parameter CYIString of ButtonLabelEventLogger::LogTextChange matches the template arguments to ButtonLabel::TextChanged. It's possible to connect a signal containing template arguments to a slot containing fewer parameters, but it is not possible to connect a signal containing few arguments to a slot containing many parameters. Up to four parameters may be passed in this manner between an object containing a CYISignal and a CYISignalHandler.

Emitting a CYISignal

Using the example above.

class ButtonLabel
{
    ...
    void OnButtonClicked(); // Called when the user has clicked on the button
    void SetLabelText(CYIString labelText); //Called by the developer to set the label.
}

The implementation of the functions demonstrates how to emit the signals using operator(), which is equivalent to using CYISignal::Emit.

void ButtonLabel::OnButtonClicked()
{
    Clicked(); //Or Clicked.Emit()
}

void ButtonLabel::SetLabelText(CYIString labelText)
{
    ...
    TextChanged(labelText);
}

Classes

class  CYISignalAbstractConnection
 The base abstract class for signal connections. More...
 
struct  YiSlotTypesContainer< T >
 A templated struct used to pass multiple parameter packs to a templated class specialization or to a templated function. More...
 
class  CYISignalBaseConnection< SignalTypes >
 The templated abstract class for signal connections. More...
 
class  CYISignal< SignalTypes >
 Signals and slots are a thread-safe and flexible communication framework that will allow various objects to transfer data synchronously or asynchronously in a highly decoupled manner. The classes that are using signals and slots do not need to share any interfaces to each other of each other. Signals and slots are also highly resilient against short lived objects: if a slot is deleted, the connection will detach automatically even while a CYISignal::Emit() is in progress, in which the deletion of the slot will be delayed. More...
 
class  CYISignalBase
 The base abstract class for CYISignal. More...
 
class  CYISignalHandler
 

Enumerations

enum  EYIConnectionType : uint8_t {
  EYIConnectionType::Auto = 0,
  EYIConnectionType::Sync,
  EYIConnectionType::Async,
  EYIConnectionType::AsyncBlock
}
 

Enumeration Type Documentation

enum EYIConnectionType : uint8_t
strong

CYISignal connection types for connections between CYISignal and slots.

Enumerator
Auto 

This is the default connection mode.

In this mode, the CYISignal will look at the slot's thread affinity to determine if it should call it directly (synchronously), or if it should be queued on the slot's thread (asynchronously) if a CYIEventDispatcher is running on that given thread. The slot affinity is determined by the thread that instantiated it. In other word, if the CYISignal and the CYISignalHandler are on the same thread, it will be treated as EYIConnectionType::Sync. If the CYISignal and the CYISignalHandler are on different threads, it will be treated as EYIConnectionType::Async.

Note
For connections to static functions, the context of the default system dispatcher is used (instead of the slot's thread, since static functions do not have an associated thread).
Sync 

In this mode, emitting a signal will always call the slot directly using the CYISignal's caller context, but it is your responsibility to assure thread-safety in your slot implementation.

Async 

This connection type will always queue the CYISignal onto the CYIEventDispatcher of the context in which the CYISignalHandler resides. If there are no event dispatcher running on the given context, the default application event dispatcher will be used.

Note
For connections to static functions, the context of the default system dispatcher is used (instead of the slot's thread, since static functions do not have an associated thread).
AsyncBlock 
Deprecated:
This connection mode has been deprecated and may be removed in a future release. If 'sync async' behaviour is desired, use an instance of CYICountDownLatch or CYIFuture.

In this mode, the CYISignal call will be asynchronous while retaining a synchronous behaviour. The signal will still be queued on the slots's thread, but will block the caller until every connected slots are called.

Note
For connections to static functions, the context of the default system dispatcher is used (instead of the slot's thread, since static functions do not have an associated thread).
EYIConnectionType::AsyncBlock will be treated as EYIConnectionType::Sync if the CYISignal and the connected CYISignalHandler are on the same thread.