Event Slots

A slot is a callable target that is called in response to a signal (the signal being the event topic in this case). The term slot, borrowed from Qt's signals and slots, is used to distinguish a event handler from an asynchronous operation completion handler.

A callable target can be:

a free function,
a bound member function (using std::bind),
a function object,
a lambda function, etc.

An event slot represents an event handler that does not have any expectations on the event payload arguments. If necessary, the payload arguments must be checked during runtime, in the body of the event handler.

wamp::Session::subscribe expects an event slot with the following signature:

void function(wamp::Event)

where wamp::Event is an object containing information and payload arguments related to the publication.

The following table summarizes the different types of event slots that can be used with the library:

Slot Type	Wrapper Function	Slot Signature
Simple Event Slot	`wamp::simpleEvent<TArgs...>`	`void function(TArgs...)`
Simple Coroutine Event Slot	`wamp::simpleCoroEvent<TArgs...>`	`void function(TArgs..., Yield)`
Unpacked Event Slot	`wamp::unpackedEvent<TArgs...>`	`void function(Event, TArgs...)`
Unpacked Coroutine Event Slot	`wamp::unpackedCoroEvent<TArgs...>`	`void function(Event, TArgs..., Yield)`

where Yield represents the type boost::asio::yield_context.

Simple Event Slots

A simple event slot represents an event handler that expects one or more payload arguments having specific, static types. The wamp::simpleEvent function can be used when registering such event slots. It takes a simple event slot, and converts it into a regular event slot that can be passed to wamp::Session::subscribe.

wamp::simpleEvent expects an event slot with the following signature:

void function(TArgs...)

where TArgs... matches the template parameter pack that was passed to wamp::simpleEvent.

Examples of simple event slots are:

void onSensorSampled(float value) { ... }
//                     ^
//                    TArgs
 
void onPurchase(std::string item, int cost, int qty) { ... }
//                      ^          ^          ^
//                      \----------|----------/
//                               TArgs

The above slots can be registered as follows:

session->subscribe(Topic("sensorSampled"),
                   simpleEvent<float>(&onSensorSampled),
                   handler);
 
session->subscribe(Topic("itemPurchased"),
                   simpleEvent<std::string, int, int>(&onPurchase),
                   handler);

where handler is the asynchronous handler (or coroutine yield context) for the subscribe operation itself.

Whenever a wamp::Session dispatches an event to the above slots, it automatically unpacks the event payload positional arguments, and passes them to the slot's argument list. If Session cannot convert the event payload arguments to their target types, it issues a warning that can be captured via wamp::Session::setWarningHandler.

Simple Coroutine Event Slots

A simple coroutine event slot is like a regular simple event slot, except that it is executed within the context of a coroutine. This is useful for event handlers that need to perform asynchronous operations themselves. The wamp::simpleCoroEvent function can be used when registering such event slots. It takes a simple coroutine event slot, and converts it into a regular event slot that can be passed to wamp::Session::subscribe.

wamp::simpleCoroEvent expects an event slot with the following signature:

void function(TArgs..., boost::asio::yield_context)

where

TArgs... matches the template parameter pack that was passed to wamp::simpleEvent.
boost::asio::yield_context represents the event handler's coroutine context.

Examples of simple coroutine event slots are:

using Yield = boost::asio::yield_context;
 
void onSensorSampled(float value, Yield yield) { ... }
//                     ^
//                    TArgs
 
void onPurchase(std::string item, int cost, int qty, Yield yield) { ... }
//                      ^          ^          ^
//                      \----------|----------/
//                               TArgs

The above slots can be registered as follows:

session->subscribe(Topic("sensorSampled"),
                   simpleCoroEvent<float>(&onSensorSampled),
                   handler);
 
session->subscribe(Topic("itemPurchased"),
                   simpleCoroEvent<std::string, int, int>(&onPurchase),
                   handler);

where handler is the asynchronous handler (or coroutine yield context) for the subscribe operation itself.

Whenever a wamp::Session dispatches an event to the above slots, it spawns a new coroutine to be executed on wamp::Session::userIosvc(). It then automatically unpacks the event payload positional arguments, and passes them to the slot's argument list. If Session cannot convert the event payload arguments to their target types, it issues a warning that can be captured via wamp::Session::setWarningHandler.

Unpacked Event Slots

An unpacked event slot represents an event handler that expects one or more payload arguments having specific, static types. The wamp::unpackedEvent function can be used when registering such event slots. It takes an unpacked event slot, and converts it into a regular event slot that can be passed to wamp::Session::subscribe.

wamp::unpackedEvent expects an event slot with the following signature:

void function(wamp::Event, TArgs...)

where

wamp::Event is an object containing information and payload arguments related to the publication, and,
TArgs... matches the template parameter pack that was passed to wamp::unpackedEvent.

Note: Unpacked event slots differ from simple event slots in the following way: Unpacked event slots are passed a wamp::Event object, which contains metadata on the event itself.

Examples of unpacked event slots are:

void onSensorSampled(Event event, float value) { ... }
//                                  ^
//                                TArgs
 
void onPurchase(Event event, std::string item, int cost, int qty) { ... }
//                                  ^          ^          ^
//                                  \----------|----------/
//                                           TArgs

The above slots can be registered as follows:

session->subscribe(Topic("sensorSampled"),
                   unpackedEvent<float>(&onSensorSampled),
                   handler);
 
session->subscribe(Topic("itemPurchased"),
                   unpackedEvent<std::string, int, int>(&onPurchase),
                   handler);

where handler is the asynchronous handler (or coroutine yield context) for the subscribe operation itself.

Whenever a wamp::Session dispatches an event to the above slots, it automatically unpacks the event payload positional arguments, and passes them to the slot's argument list. If Session cannot convert the event payload arguments to their target types, it issues a warning that can be captured via wamp::Session::setWarningHandler.

Unpacked Coroutine Event Slots

An unpacked coroutine event slot is like an unpacked event slot, except that the slot is executed within the context of a coroutine. The wamp::unpackedCoroEvent function can be used when registering such event slots.

wamp::unpackedCoroEvent expects an event slot with the following signature:

void function(wamp::Event, TArgs..., boost::asio::yield_context)

where

wamp::Event is an object containing information and payload arguments related to the publication, and,
TArgs... matches the template parameter pack that was passed to wamp::unpackedEvent.
boost::asio::yield_context represents the event handler's coroutine context.

Scoped Subscriptions

A wamp::ScopedSubscription object can be used to limit a subscription's lifetime to a particular scope. When a ScopedSubscription object is destroyed, it automatically unsubscribes the subscription. This helps in automating the lifetime management of topic subscriptions using RAII techniques.

Here's an example illustrating how ScopedSubscription can be used to manage the lifetime of several subscriptions:

using namespace wamp;
 
class Observer // One of several classes using the same Session
{
public:
    void start(Session::Ptr session)
    {
        // The session has already connected and joined when this is called.
 
        auto s1 = session_->subscribe(Topic("foo"), &Observer::onFoo,
                                      yield).value();
        auto s2 = session_->subscribe(Topic("bar"), &Observer::onBar,
                                      yield).value();
 
        // Store scoped subscripions in private member
        subscriptions_.push_back(s1);
        subscriptions_.push_back(s2);
    }
 
private:
    static void onFoo(Event event)
    {
        std::cout << "Foo happened\n";
    }
 
    static void onBar(Event event)
    {
        std::cout << "Bar happened\n";
    }
 
    // When the Observer is destroyed, the stored elements will also be
    // destroyed, performing automatic unsubscription for each subscribed topic.
    std::vector<ScopedSubscription> subscriptions_;
};

Table of Contents

Event Slots

Simple Event Slots

Simple Coroutine Event Slots

Unpacked Event Slots

Unpacked Coroutine Event Slots

Scoped Subscriptions