WaitSet🔗
Thread Safety🔗
The WaitSet is not thread-safe!
- It is not allowed to attach or detach Triggerable
classes with
attachEvent
ordetachEvent
when another thread is currently waiting for notifications withwait
ortimedWait
. - Do not call any of the WaitSet methods concurrently.
The TriggerHandle on the other hand, is thread-safe! Therefore you are allowed to attach/detach a TriggerHandle to a Triggerable while another thread may trigger the TriggerHandle.
Introduction🔗
The WaitSet is a set to which you can attach objects so that they can signal a wide variety of events to one single notifiable. The typical approach is that one creates a WaitSet, attaches multiple subscribers, user triggers or other Triggerables to it and then wait until one or many of the attached entities signal an event. If that happens one receives a list of NotificationInfos which is corresponding to all occurred events.
Events and States🔗
In this context, we define the state of an object as a specified set of values to which the members of that object are set. An event on the other hand is defined as a state change. Usually, an event changes the state of the corresponding object but this is not mandatory.
States and events can be attached to a WaitSet. The user will be informed only once by the WaitSet for every event which occurred. If the event occurred multiple times before the user has requested an event update from the WaitSet the user will still be informed only once. State changes are induced by events and the user will be informed about a specific state as long as the state persists.
The subscriber for instance has the state SubscriberState::HAS_DATA
and the event
SubscriberEvent::DATA_RECEIVED
. If you attach the subscriber event
SubscriberEvent::DATA_RECEIVED
to a WaitSet you will be notified about every new
incoming sample whenever you call WaitSet::wait
or WaitSet::timedWait
. If multiple
samples were sent before you called those methods you will still receive only one
notification.
If you attach the state SubscriberState::HAS_DATA
you will
be notified by WaitSet::wait
or WaitSet::timedWait
as long as there are received
samples present in the subscriber queue.
Expected Output🔗
Glossary🔗
- Event a state change of an object; a Triggerable will signal an event via a TriggerHandle to
a Notifyable. For instance one can attach the subscriber event
DATA_RECEIVED
to WaitSet. This will cause the subscriber to notify the WaitSet via the TriggerHandle everytime a sample was received. - NotificationCallback a callback attached to a NotificationInfo. It must have the
following signature
void ( NotificationOrigin )
. Any free function, static class method and non capturing lambda expression is allowed. You have to ensure the lifetime of that callback. This can become important when you would like to use lambda expressions. - NotificationId an id which is tagged to an event. It does not need to be unique
or follow any restrictions. The user can choose any arbitrary
uint64_t
. Assigning the same NotificationId to multiple Events can be useful when you would like to group Events. - NotificationInfo a class that corresponds to Triggers and is used to inform the user which Event occurred. You can use the NotificationInfo to acquire the NotificationId, call the NotificationCallback or acquire the NotificationOrigin.
- NotificationOrigin the pointer to the class where the Event originated from, short pointer to the Triggerable.
- Notifyable is a class which listens to events. A TriggerHandle which corresponds to a Trigger is used to notify the Notifyable that an event occurred. The WaitSet is a Notifyable.
- State a specified set of values to which the members of an object are set.
- Trigger a class which is used by the Notifyable to acquire the information which events were signalled. It corresponds to a TriggerHandle. If the Notifyable goes out of scope the corresponding TriggerHandle will be invalidated and if the Triggerable goes out of scope the corresponding Trigger will be invalidated.
- Triggerable a class which has attached a TriggerHandle to itself to signal certain Events to a Notifyable.
- TriggerHandle a thread-safe class which can be used to trigger a Notifyable. If a TriggerHandle goes out of scope it will detach itself from the Notifyable. A TriggerHandle is logical equal to another Trigger if they:
- are attached to the same Notifyable (or in other words they are using the
same
ConditionVariable
) - they have the same NotificationOrigin
- they have the same callback to verify that they were triggered
(
hasNotificationCallback
) - they have the same NotificationId
- WaitSet a Notifyable which manages a set of Triggers which are corresponding to Events. A user may attach or detach events. The Waitset is listening to the whole set of Triggers and if one or more Triggers are triggered by an event it will notify the user. If a WaitSet goes out of scope all attached Triggers will be invalidated.
Quick Overview🔗
Events or States can be attached to a Notifyable like the WaitSet.
The WaitSet will listen on Triggers for a signal that an Event has occurred and it hands out
TriggerHandles to Triggerable objects. The TriggerHandle is used to inform the WaitSet
about the occurrence of an Event. When returning from WaitSet::wait()
the user is provided with a vector of NotificationInfos
associated with Events which had occurred and States which persists. The NotificationOrigin, NotificationId and NotificationCallback
are stored inside of the NotificationInfo and can be acquired by the user.
Warning
Please be aware of the thread-safety restrictions of the WaitSet and read the Thread Safety chapter carefully.
Reference🔗
task | call |
---|---|
attach subscriber event to a WaitSet | waitset.attachEvent(subscriber, iox::popo::SubscriberEvent::DATA_RECEIVED, 123, &mySubscriberCallback) |
attach subscriber state to a WaitSet | waitset.attachState(subscriber, iox::popo::SubscriberState::HAS_DATA, 123, &mySubscriberCallback) |
attach user trigger to a WaitSet | waitset.attachEvent(userTrigger, 456, &myUserTriggerCallback) |
wait for triggers | auto triggerVector = myWaitSet.wait(); |
wait for triggers with timeout | auto triggerVector = myWaitSet.timedWait(1_s); |
check if event/state originated from some object | notification->doesOriginateFrom(ptrToSomeObject) |
get id of the event/state | notification->getNotificationId() |
call eventCallback | (*notification)() |
acquire NotificationOrigin | notification->getOrigin<OriginType>(); |
Use Cases🔗
This example consists of 6 use cases.
-
ice_waitset_basic
: A single subscriber is notified by the WaitSet if data arrives. -
ice_waitset_gateway.cpp
: We build a gateway to forward data to another network. A list of subscriber events are handled in an uniform way by defining a callback which is executed for every subscriber who has received data. -
ice_waitset_grouping
: We would like to group multiple subscribers into 2 distinct groups and handle them whenever they have a specified state according to their group membership. -
ice_waitset_individual
: A list of subscribers where every subscriber is handled differently. -
ice_waitset_timer_driven_execution
: We use the WaitSet to trigger a cyclic call which should execute an algorithm every 1 s. -
ice_waitset_trigger
: We create our own class which can be attached to a WaitSet to signal states and events.
Examples🔗
All our examples require a running iox-roudi
and some data to receive which will be
send by iox-cpp-waitset-publisher
. The publisher does not contain any WaitSet specific
logic and is explained in detail in the
icedelivery example.
Basic🔗
We create one subscriber and attach it to the WaitSet. Afterwards we wait for data in
a loop and process it on arrival. To leave the loop and exit the application
we have to register a signal handler that calls waitset.markForDestruction()
which wakes up the blocking waitset->wait()
whenever Ctrl+C is pressed.
std::atomic_bool keepRunning{true};
iox::cxx::optional<iox::popo::WaitSet<>> waitset;
static void sigHandler(int sig IOX_MAYBE_UNUSED)
{
keepRunning = false;
if (waitset)
{
waitset->markForDestruction();
}
}
In the beginning we create the WaitSet. It is important to construct it only after the runtime has already been initialized since it internally depends on facilities set up by the runtime.
Afterwards we register our signal handler which will unblock the WaitSet. Finally we attach the subscriber to the WaitSet stating that we want to be notified when it has data (indicated by iox::popo::SubscriberState::HAS_DATA
).
It is good practice to handle potential failure while attaching, otherwise warnings will emerge since the return value cxx::expected
is marked to require handling.
In our case no errors should occur since the WaitSet can accomodate the two triggers we want to attach.
waitset.emplace();
// register signal handler to handle termination of the loop
auto signalGuard = iox::posix::registerSignalHandler(iox::posix::Signal::INT, sigHandler);
auto signalTermGuard = iox::posix::registerSignalHandler(iox::posix::Signal::TERM, sigHandler);
// create subscriber
iox::popo::Subscriber<CounterTopic> subscriber({"Radar", "FrontLeft", "Counter"});
// attach subscriber to waitset
waitset->attachState(subscriber, iox::popo::SubscriberState::HAS_DATA).or_else([](auto) {
std::cerr << "failed to attach subscriber" << std::endl;
std::exit(EXIT_FAILURE);
});
We create a loop which we will exit as soon as someone presses CTRL+C and our
signal handler sets keepRunning
to false. If this happens markForDestruction
turns
the waitset->wait()
into an empty non-blocking method and makes sure that we do
not wait indefinitely.
while (keepRunning)
{
// We block and wait for samples to arrive.
auto notificationVector = waitset->wait();
for (auto& notification : notificationVector)
{
// We woke up and hence there must be at least one sample. When the sigHandler has called
// markForDestruction the notificationVector is empty otherwise we know which subscriber received samples
// since we only attached one.
// Best practice is to always acquire the notificationVector and iterate over all elements and then react
// accordingly. When this is not done and more elements are attached to the WaitSet it can cause
// problems since we either miss events or handle events for objects which never occurred.
if (notification->doesOriginateFrom(&subscriber))
{
// Consume a sample
subscriber.take()
.and_then([](auto& sample) { std::cout << " got value: " << sample->counter << std::endl; })
.or_else([](auto& reason) {
std::cout << "got no data, return code: " << static_cast<uint64_t>(reason) << std::endl;
});
// We could consume all samples but do not need to.
// If there is more than one sample we will wake up again since the state of the subscriber is still
// iox::popo::SubscriberState::HAS_DATA in this case.
}
}
}
Processing just one sample even if more might have arrived will cause wait
to
unblock again immediately to process the next sample (or shut down if requested).
Due to the overhead of the wait
call it may still be more efficient to process
all samples in a loop until there are none left before waiting again, but it is
not required. It would be required if we attach via attachEvent
instead of
attachState
, since we might wake up due to the arrival of a second sample,
only process the first and will not receive a wake up until a third sample
arrives (which could be much later or never).
Gateway🔗
We have a list of subscribers which can be subscribed to any arbitrary topic
and everytime we receive a sample we would like to send the bytestream to a socket,
write it into a file or print it to the console. But whatever we choose to do
we perform the same task for all the subscribers. And since we process all incoming
data right away we attach the SubscriberEvent::DATA_RECEIVED
which notifies us
only once.
Let's start by implementing our callback which prints the subscriber pointer, the
payload size and the payload pointer to the console. We have to process all samples
as long as there are samples in the subscriber queue since we attached an event that notifies
us only once. But it is impossible to miss samples since the notification is reset
right after wait
or timedWait
is returned - this means if a sample arrives after
those calls we will be notified again.
Additionally, since we would like to count the sum of all processed samples, we
add a second argument called sumOfAllSamples
to the user defined context data.
void subscriberCallback(iox::popo::UntypedSubscriber* const subscriber, uint64_t* const sumOfAllSamples)
{
while (subscriber->hasData())
{
subscriber->take().and_then([&](auto& userPayload) {
auto chunkHeader = iox::mepoo::ChunkHeader::fromUserPayload(userPayload);
auto flags = std::cout.flags();
std::cout << "subscriber: " << std::hex << subscriber << " length: " << std::dec
<< chunkHeader->userPayloadSize() << " ptr: " << std::hex << chunkHeader->userPayload()
<< std::dec << std::endl;
std::cout.setf(flags);
});
// no nullptr check required since it is guaranteed != nullptr
++(*sumOfAllSamples);
}
}
The Event callback requires a signature of either void (NotificationOrigin)
or
void(NotificationOrigin, ContextDataType *)
when one would like to provide an additional
data pointer to the callback.
In our example the NotificationOrigin is a
iox::popo::UntypedSubscriber
pointer which we use to acquire the latest sample by calling
take()
and the ContextDataType
is an uint64_t
used to count the processed
samples. When take()
was successful we print our message to
the console inside of the and_then
lambda.
The shutdownTrigger
uses a simpler callback which just informs us that we are
exiting the program. Therefore we do not need an additional ContextDataType
pointer.
void shutdownCallback(iox::popo::UserTrigger*)
{
std::cout << "CTRL+C pressed - exiting now" << std::endl;
}
In our main
function we create a WaitSet which has storage capacity for 3 events,
2 subscribers and one shutdown trigger, after we registered us at our central
broker RouDi. Then we attach our shutdownTrigger
to handle CTRL+C
events.
iox::popo::WaitSet<NUMBER_OF_SUBSCRIBERS + ONE_SHUTDOWN_TRIGGER> waitset;
// attach shutdownTrigger to handle CTRL+C
waitset.attachEvent(shutdownTrigger, iox::popo::createNotificationCallback(shutdownCallback)).or_else([](auto) {
std::cerr << "failed to attach shutdown trigger" << std::endl;
std::exit(EXIT_FAILURE);
});
After that we define our sumOfAllSamples
variable and create a vector to hold our subscribers. We create and then
attach the subscribers to our WaitSet with the SubscriberEvent::DATA_RECEIVED
event and the subscriberCallback
.
Everytime one of the subscribers is receiving a new sample it will trigger the WaitSet.
Attention
The user has to ensure that the contextData (sumOfAllSamples
) in attachEvent
lives as long as the attachment, with its callback, is attached otherwise
the callback context data pointer is dangling.
uint64_t sumOfAllSamples = 0U;
// create subscribers and subscribe them to our service
iox::cxx::vector<iox::popo::UntypedSubscriber, NUMBER_OF_SUBSCRIBERS> subscriberVector;
for (auto i = 0U; i < NUMBER_OF_SUBSCRIBERS; ++i)
{
subscriberVector.emplace_back(iox::capro::ServiceDescription{"Radar", "FrontLeft", "Counter"});
auto& subscriber = subscriberVector.back();
/// important: the user has to ensure that the contextData (sumOfAllSamples) lives as long as
/// the subscriber with its callback is attached to the listener
waitset
.attachEvent(subscriber,
iox::popo::SubscriberEvent::DATA_RECEIVED,
0,
createNotificationCallback(subscriberCallback, sumOfAllSamples))
.or_else([&](auto) {
std::cerr << "failed to attach subscriber" << i << std::endl;
std::exit(EXIT_FAILURE);
});
}
attachEvent
is returning a cxx::expected
which informs us if attaching the event
succeeded. In the .or_else([&](auto){/*...*/})
part we perform the error handling
whenever attachEvent
fails.
Now our system is prepared and ready to work. We enter the event loop which
starts with a call to our WaitSet (waitset.wait()
). This call will block until
one or more events triggered the WaitSet. After the call returned we get a
vector filled with NotificationInfos which are corresponding to all the events which
triggered the WaitSet.
We iterate through this vector. If an Event originated from the shutdownTrigger
we exit the program, otherwise we just call the assigned callback by calling
the trigger. This will then call the subscriberCallback
with the NotificationOrigin
(the pointer to the untyped subscriber) and the contextData (sumOfAllSamples
) as parameters.
while (keepRunning)
{
auto notificationVector = waitset.wait();
for (auto& notification : notificationVector)
{
if (notification->doesOriginateFrom(&shutdownTrigger))
{
(*notification)();
keepRunning = false;
}
else
{
// call the callback which was assigned to the notification
(*notification)();
}
}
auto flags = std::cout.flags();
std::cout << "sum of all samples: " << std::dec << sumOfAllSamples << std::endl;
std::cout.setf(flags);
}
Grouping🔗
In our next use case we would like to divide the subscribers into two groups
and we do not want to attach a callback to them. Instead we perform the calls on the
subscribers directly. Additionally, we would like to be notified as long as there
are samples in the subscriber queue therefore we have to attach the SubscriberState::HAS_DATA
.
We again start by creating a WaitSet with a capacity of 5 (4 subscribers and 1 shutdownTrigger),
and attach the shutdownTrigger
to handle CTRL+C
.
iox::popo::WaitSet<NUMBER_OF_SUBSCRIBERS + ONE_SHUTDOWN_TRIGGER> waitset;
// attach shutdownTrigger to handle CTRL+C
waitset.attachEvent(shutdownTrigger).or_else([](auto) {
std::cerr << "failed to attach shutdown trigger" << std::endl;
std::exit(EXIT_FAILURE);
});
Now we create a vector of 4 subscribers.
iox::cxx::vector<iox::popo::UntypedSubscriber, NUMBER_OF_SUBSCRIBERS> subscriberVector;
for (auto i = 0U; i < NUMBER_OF_SUBSCRIBERS; ++i)
{
subscriberVector.emplace_back(iox::capro::ServiceDescription{"Radar", "FrontLeft", "Counter"});
}
After that, we define our two groups with the ids FIRST_GROUP_ID
and SECOND_GROUP_ID
and attach the first two subscribers with the state SubscriberState::HAS_DATA
to the first group and the remaining subscribers to the second group.
// attach the first two subscribers to waitset with a id of FIRST_GROUP_ID
for (auto i = 0U; i < NUMBER_OF_SUBSCRIBERS / 2; ++i)
{
waitset.attachState(subscriberVector[i], iox::popo::SubscriberState::HAS_DATA, FIRST_GROUP_ID)
.or_else([&](auto) {
std::cerr << "failed to attach subscriber" << i << std::endl;
std::exit(EXIT_FAILURE);
});
}
// attach the remaining subscribers to waitset with a id of SECOND_GROUP_ID
for (auto i = NUMBER_OF_SUBSCRIBERS / 2; i < NUMBER_OF_SUBSCRIBERS; ++i)
{
waitset.attachState(subscriberVector[i], iox::popo::SubscriberState::HAS_DATA, SECOND_GROUP_ID)
.or_else([&](auto) {
std::cerr << "failed to attach subscriber" << i << std::endl;
std::exit(EXIT_FAILURE);
});
}
The event loop calls auto notificationVector = waitset.wait()
in a blocking call to
receive a vector of all the NotificationInfos which are corresponding to the occurred events.
If the Event originated from the shutdownTrigger
we terminate the program.
while (keepRunning)
{
auto notificationVector = waitset.wait();
for (auto& notification : notificationVector)
{
if (notification->doesOriginateFrom(&shutdownTrigger))
{
keepRunning = false;
}
// ...
}
std::cout << std::endl;
}
The remaining part of the loop is handling the subscribers. In the first group we would like to print the received data to the console and in the second group we just dismiss the received data.
// we print the received data for the first group
else if (notification->getNotificationId() == FIRST_GROUP_ID)
{
auto subscriber = notification->getOrigin<iox::popo::UntypedSubscriber>();
subscriber->take().and_then([&](auto& userPayload) {
const CounterTopic* data = static_cast<const CounterTopic*>(userPayload);
auto flags = std::cout.flags();
std::cout << "received: " << std::dec << data->counter << std::endl;
std::cout.setf(flags);
subscriber->release(userPayload);
});
}
// dismiss the received data for the second group
else if (notification->getNotificationId() == SECOND_GROUP_ID)
{
std::cout << "dismiss data\n";
auto subscriber = notification->getOrigin<iox::popo::UntypedSubscriber>();
// We need to release the data to reset the trigger hasData
// otherwise the WaitSet would notify us in `waitset.wait()` again
// instantly.
subscriber->releaseQueuedData();
}
Attention
For the second group we have to call releaseQueuedData
to release the
unread data. Otherwise we would be notified by the WaitSet immediately again
since the subscriber has still the state HAS_DATA
.
Individual🔗
When every Triggerable requires a different reaction we need to know the
origin of an Event. We can call event.doesOriginateFrom(NotificationOrigin)
which will return true if the event originated from NotificationOrigin and
otherwise false.
We start this example by creating a WaitSet with the default capacity and
attaching the shutdownTrigger
to handle CTRL+C
.
iox::popo::WaitSet<> waitset;
// attach shutdownTrigger to handle CTRL+C
waitset.attachEvent(shutdownTrigger).or_else([](auto) {
std::cerr << "failed to attach shutdown trigger" << std::endl;
std::exit(EXIT_FAILURE);
});
Additionally, we create two subscribers and attach them with the state SubscriberState::HAS_DATA
to the WaitSet to let them inform us whenever they have samples in their queue.
iox::popo::Subscriber<CounterTopic> subscriber1({"Radar", "FrontLeft", "Counter"});
iox::popo::Subscriber<CounterTopic> subscriber2({"Radar", "FrontLeft", "Counter"});
waitset.attachState(subscriber1, iox::popo::SubscriberState::HAS_DATA).or_else([](auto) {
std::cerr << "failed to attach subscriber1" << std::endl;
std::exit(EXIT_FAILURE);
});
waitset.attachState(subscriber2, iox::popo::SubscriberState::HAS_DATA).or_else([](auto) {
std::cerr << "failed to attach subscriber2" << std::endl;
std::exit(EXIT_FAILURE);
});
With that set up we enter the event loop and handle the program termination first.
while (keepRunning)
{
auto notificationVector = waitset.wait();
for (auto& notification : notificationVector)
{
if (notification->doesOriginateFrom(&shutdownTrigger))
{
keepRunning = false;
}
// ...
}
std::cout << std::endl;
}
When the origin is subscriber1
we would like to print the received data to the
console. But for subscriber2
we just dismiss the received samples.
We accomplish this by asking the event
if it originated from the
corresponding subscriber. If so, we act.
while (keepRunning)
{
auto notificationVector = waitset.wait();
for (auto& notification : notificationVector)
{
// ...
// process sample received by subscriber1
else if (notification->doesOriginateFrom(&subscriber1))
{
subscriber1.take().and_then(
[&](auto& sample) { std::cout << "subscriber 1 received: " << sample->counter << std::endl; });
}
// dismiss sample received by subscriber2
if (notification->doesOriginateFrom(&subscriber2))
{
// We need to release the samples to reset the trigger hasSamples
// otherwise the WaitSet would notify us in `waitset.wait()` again
// instantly.
subscriber2.releaseQueuedData();
std::cout << "subscriber 2 received something - dont care\n";
}
}
std::cout << std::endl;
}
Timer Driven Execution🔗
Let's say we have SomeClass
and would like to execute a cyclic static method cyclicRun
every second. We could execute any arbitrary algorithm in there
but for now we just print activation callback
. The class could look like
class SomeClass
{
public:
static void cyclicRun(iox::popo::UserTrigger*)
{
std::cout << "activation callback\n";
}
};
Attention
The user trigger is event based and always reset after the WaitSet has acquired all triggered objects.
As always, we begin by creating a WaitSet with the default capacity and by
attaching the shutdownTrigger
to
it. In this case we do not set an event id when calling attachEvent
which means
the default event id NotificationInfo::INVALID_ID
is set.
iox::popo::WaitSet<> waitset;
// attach shutdownTrigger to handle CTRL+C
waitset.attachEvent(shutdownTrigger).or_else([](auto) {
std::cerr << "failed to attach shutdown trigger" << std::endl;
std::exit(EXIT_FAILURE);
});
After that we require a cyclicTrigger
to trigger our
cyclicRun
every second. Therefore, we attach it to the waitset
with
eventId 0
and the callback SomeClass::cyclicRun
iox::popo::UserTrigger cyclicTrigger;
waitset.attachEvent(cyclicTrigger, 0U, createNotificationCallback(SomeClass::cyclicRun)).or_else([](auto) {
std::cerr << "failed to attach cyclic trigger" << std::endl;
std::exit(EXIT_FAILURE);
});
The next thing we need is something which will trigger our cyclicTrigger
every second. We use an infinite loop packed inside of a thread.
std::thread cyclicTriggerThread([&] {
while (keepRunning.load())
{
cyclicTrigger.trigger();
std::this_thread::sleep_for(std::chrono::seconds(1));
}
});
Everything is set up and we can implement the event loop. As usual we handle
CTRL+C
which is indicated by the shutdownTrigger
.
while (keepRunning.load())
{
auto notificationVector = waitset.wait();
for (auto& notification : notificationVector)
{
if (notification->doesOriginateFrom(&shutdownTrigger))
{
// CTRL+C was pressed -> exit
keepRunning.store(false);
}
// ...
}
std::cout << std::endl;
}
The cyclicTrigger
callback is called in the else part.
while (keepRunning.load())
{
auto notificationVector = waitset.wait();
for (auto& notification : notificationVector)
{
// ...
else
{
// call SomeClass::cyclicRun
(*notification)();
}
}
std::cout << std::endl;
}
Trigger🔗
In this example we describe how you would implement a Triggerable class which
can be attached to a WaitSet or a
Listener.
Our class in this example will be called MyTriggerClass
and it can signal the WaitSet
the two states HAS_PERFORMED_ACTION
and IS_ACTIVATED
. Furthermore, we can also attach the
two corresponding events PERFORM_ACTION_CALLED
and ACTIVATE_CALLED
. The
PERFORM_ACTION_CALLED
event is triggered whenever the method performAction
is called and
the state HAS_PERFORMED_ACTION
persists until someone resets the state with the method
reset()
. The same applies to the event ACTIVATE_CALLED
which is triggered by an activate()
call and the corresponding state IS_ACTIVATED
which stays until someone resets it with
reset()
.
MyTriggerClass🔗
Attaching States🔗
A class that would like to attach states to a WaitSet has to implement the following methods.
-
void enableState(iox::popo::TriggerHandle&&, const UserDefinedStateEnum )
Used by the WaitSet to attach a trigger handle to the object so that the object can notify the WaitSet that it entered a certain state.
-
void disableState(const UserDefinedStateEnum)
Called whenever the user detaches the state from the WaitSet.
-
void invalidateTrigger(const uint64_t uniqueTriggerId)
If the WaitSet goes out of scope it calls this method to invalidate the loan trigger.
-
iox::popo::WaitSetIsConditionSatisfiedCallback getCallbackForIsStateConditionSatisfied(const UserDefinedStateEnum)
With every iteration the WaitSet has to ask the object if the attached state still persists. This is done with the
isStateConditionSatisfied
callback which will be returned here.
The UserDefinedStateEnum
can be some arbitrary enum class which requires
iox::popo::StateEnumIdentifier
as underlying type so that it can be identified as
an enum which describes certain states. In our example it is called MyTriggerClassStates
.
enum class MyTriggerClassStates : iox::popo::StateEnumIdentifier
{
HAS_PERFORMED_ACTION,
IS_ACTIVATED
};
Attaching Events🔗
Events can be attached to WaitSets and Listeners. For this to work the class has to implement the following methods.
-
void enableEvent(iox::popo::TriggerHandle&&, const UserDefinedEventEnum)
Used by the WaitSet or the Listener to attach a trigger handle which signals certain events to them.
-
void disableEvent(const UserDefinedEventEnum)
Called whenever the user detaches the event from the WaitSet or the Listener.
-
void invalidateTrigger(const uint64_t uniqueTriggerId)
Used to clean up all loan trigger handles when the WaitSet or Listener goes out of scope.
Like with the state enum the event enum can be also any arbitrary enum class which
has iox::popo::EventEnumIdentifier
as an underlying type. In our example it is called
MyTriggerClassEvents
.
enum class MyTriggerClassEvents : iox::popo::EventEnumIdentifier
{
PERFORM_ACTION_CALLED,
ACTIVATE_CALLED
};
Further Requirements🔗
-
friend iox::popo::NotificationAttorney
Methods like
enableEvent
,disableEvent
etc. should never be accessible via the public API and should be therefore private. To avoid that every class has to befriend the WaitSet, Listener and other internal structures we implemented the client attorney pattern and the class has only to befriend theiox::popo::NotificationAttorney
. -
Deleted move and copy operations
At the moment the WaitSet does not support Triggerable classes which are movable
or copyable. This is caused by the resetCallback
and the isStateConditionSatisfied
callback
which are pointing to the Triggerable. After a move the callbacks inside of the WaitSet
would point to the wrong memory location and a copy could lead to an unattached object
if there is no more space left in the WaitSet. Therefore we have to delete the move
and copy operations for now.
MyTriggerClass(const MyTriggerClass&) = delete;
MyTriggerClass(MyTriggerClass&&) = delete;
MyTriggerClass& operator=(const MyTriggerClass&) = delete;
MyTriggerClass& operator=(MyTriggerClass&&) = delete;
Implementation🔗
The method implementation of the two actions activate
and performAction
which trigger an
event and causing a state change look like the following.
// When you call this method you will trigger the ACTIVATE event
void activate(const uint64_t activationCode) noexcept
{
m_activationCode = activationCode;
m_isActivated = true;
m_activateTrigger.trigger();
}
// Calling this method will trigger the PERFORMED_ACTION event
void performAction() noexcept
{
m_hasPerformedAction = true;
m_onActionTrigger.trigger();
}
As you can see we perform some internal action and when they are finished we signal the corresponding Trigger via our stored TriggerHandle that we performed the task. Internally we just set a boolean to signal that the method was called.
Every state based Trigger requires a corresponding class method which returns a boolean
stating if the state which led to the trigger still persists. In our case these are
the two const methods hasPerformedAction
and isActivated
.
// required by the m_onActionTrigger to ask the class if it was triggered
bool hasPerformedAction() const noexcept
{
return m_hasPerformedAction;
}
// required by the m_activateTrigger to ask the class if it was triggered
bool isActivated() const noexcept
{
return m_isActivated;
}
Since the following methods should not be accessible by the public but must be
accessible by any Notifyable like the WaitSet and to avoid that
we have to befriend every possible Notifyable we created the NotificationAttorney
.
Every Triggerable has to befriend the NotificationAttorney
which provides access
to the private methods enableEvent
/enableState
, disableEvent
/disableState
, invalidateTrigger
and
getCallbackForIsStateConditionSatisfied
to all Notifyables.
friend iox::popo::NotificationAttorney;
The method enableEvent
is called by the WaitSet when a MyTriggerClass
event
is being attached to it. During that process the WaitSet creates a triggerHandle
and forwards the event
to which this handle belongs.
In the switch case statement we assign the triggerHandle
to the corresponding
internal trigger handle.
void enableEvent(iox::popo::TriggerHandle&& triggerHandle, const MyTriggerClassEvents event) noexcept
{
switch (event)
{
case MyTriggerClassEvents::PERFORM_ACTION_CALLED:
m_onActionTrigger = std::move(triggerHandle);
break;
case MyTriggerClassEvents::ACTIVATE_CALLED:
m_activateTrigger = std::move(triggerHandle);
break;
}
}
Attaching a state works in a similar way.
void enableState(iox::popo::TriggerHandle&& triggerHandle, const MyTriggerClassStates state) noexcept
{
switch (state)
{
case MyTriggerClassStates::HAS_PERFORMED_ACTION:
m_onActionTrigger = std::move(triggerHandle);
break;
case MyTriggerClassStates::IS_ACTIVATED:
m_activateTrigger = std::move(triggerHandle);
break;
}
}
It is possible to use the same trigger for either a state or an event attachment but then we loose the ability to attach the state and the corresponding event at the same time to a WaitSet. In most cases it is not a problem and when you attach an event when the corresponding state is already attached you will get a warning message on the terminal and the already attached event is detached so that the state can be attached. This is realized via the RAII idiom.
The next thing on our checklist is the invalidateTrigger
method used by the WaitSet
to reset the Trigger when it goes out of scope. Therefore we look up the
correct unique trigger id first and then invalidate
it to make them unusable
in the future.
void invalidateTrigger(const uint64_t uniqueTriggerId)
{
if (m_onActionTrigger.getUniqueId() == uniqueTriggerId)
{
m_onActionTrigger.invalidate();
}
else if (m_activateTrigger.getUniqueId() == uniqueTriggerId)
{
m_activateTrigger.invalidate();
}
}
Detaching an event in the WaitSet will lead to a call to disableEvent
in
our class. In this case we have to reset
the corresponding trigger to invalidate
and release it from the WaitSet. Like before we use a switch case statement to
find the trigger corresponding to the event.
void disableEvent(const MyTriggerClassEvents event) noexcept
{
switch (event)
{
case MyTriggerClassEvents::PERFORM_ACTION_CALLED:
m_onActionTrigger.reset();
break;
case MyTriggerClassEvents::ACTIVATE_CALLED:
m_activateTrigger.reset();
break;
}
}
The same idea is used when detaching a state.
void disableState(const MyTriggerClassStates state) noexcept
{
switch (state)
{
case MyTriggerClassStates::HAS_PERFORMED_ACTION:
m_onActionTrigger.reset();
break;
case MyTriggerClassStates::IS_ACTIVATED:
m_activateTrigger.reset();
break;
}
}
The last method we have to implement is getCallbackForIsStateConditionSatisfied
. The
WaitSet can handle state based attachments and therefore it requires, beside the condition variable
which only states that something has happened, a callback to find the object
where it happened. This is the isStateConditionSatisfied
callback. In our case we either return
the method pointer to hasPerformedAction
or isActivated
depending on which
state was requested.
iox::popo::WaitSetIsConditionSatisfiedCallback
getCallbackForIsStateConditionSatisfied(const MyTriggerClassStates event) const noexcept
{
switch (event)
{
case MyTriggerClassStates::HAS_PERFORMED_ACTION:
return {*this, &MyTriggerClass::hasPerformedAction};
case MyTriggerClassStates::IS_ACTIVATED:
return {*this, &MyTriggerClass::isActivated};
}
return {};
}
Using MyTriggerClass🔗
The next thing we define is a free function, our eventLoop
, which will handle
all events of our WaitSet. Since we would like to attach the IS_ACTIVATED
state
we have to reset the state whenever it occurs otherwise the WaitSet will
notify us right away since the state still persists. The second attachment will
be an event attachment and the WaitSet informs us just once that the event
has occurred which makes the reset
call obsolete.
void eventLoop()
{
while (keepRunning)
{
auto notificationVector = waitset->wait();
for (auto& notification : notificationVector)
{
if (notification->getNotificationId() == ACTIVATE_ID)
{
// reset MyTriggerClass instance state
notification->getOrigin<MyTriggerClass>()->reset(MyTriggerClassStates::IS_ACTIVATED);
// call the callback attached to the trigger
(*notification)();
}
else if (notification->getNotificationId() == ACTION_ID)
{
// reset is not required since we attached an notification here. we will be notified once
(*notification)();
}
}
}
}
We start like in every other example by creating the waitset
first. In this
case the waitset
and the triggerClass
are stored inside of two global
optional
's and have to be created with an emplace
call.
waitset.emplace();
triggerClass.emplace();
After that we can attach the IS_ACTIVATED
state and PERFORM_ACTION_CALLED
event
to the waitset and provide a callback for them.
// attach the IS_ACTIVATED state to the waitset and assign a callback
waitset
->attachState(*triggerClass,
MyTriggerClassStates::IS_ACTIVATED,
ACTIVATE_ID,
iox::popo::createNotificationCallback(callOnActivate))
.or_else([](auto) {
std::cerr << "failed to attach MyTriggerClassStates::IS_ACTIVATED state " << std::endl;
std::exit(EXIT_FAILURE);
});
// attach the PERFORM_ACTION_CALLED event to the waitset and assign a callback
waitset
->attachEvent(*triggerClass,
MyTriggerClassEvents::PERFORM_ACTION_CALLED,
ACTION_ID,
iox::popo::createNotificationCallback(MyTriggerClass::callOnAction))
.or_else([](auto) {
std::cerr << "failed to attach MyTriggerClassEvents::PERFORM_ACTION_CALLED event " << std::endl;
std::exit(EXIT_FAILURE);
});
Now that everything is set up we can start our eventLoop
in a new thread.
std::thread eventLoopThread(eventLoop);
A thread which will trigger an event every second is started with the following lines.
std::thread triggerThread([&] {
uint64_t activationCode = 1U;
for (auto i = 0U; i < 10; ++i)
{
std::this_thread::sleep_for(std::chrono::seconds(1));
triggerClass->activate(activationCode++);
std::this_thread::sleep_for(std::chrono::seconds(1));
triggerClass->performAction();
}
std::cout << "Sending final trigger" << std::endl;
keepRunning = false;
triggerClass->activate(activationCode++);
triggerClass->performAction();
});