Event-Driven Communication
Before jumping into the example, we need to clarify the difference between data flow and control flow.
In programming, control flow is about when a function executes, while data flow is about what inputs it receives. In iceoryx2 these two concepts are separated on purpose, unlike in many network protocols where receiving data automatically involves a syscall that wakes up the participant.
Messaging patterns like publish-subscribe and request-response define the data flow. The event messaging pattern handles control flow. Why split them? Because you don’t always want to pass data when triggering execution. Sometimes you just need to wake up a function with no additional input. Other times you need several inputs, and you don’t want to be interrupted until all of them have arrived. Mixing data and control flow forces you into hacks like sending empty messages or waking up too early.
By keeping them separate, iceoryx2 gives you explicit control over when your system reacts.
Why It Matters
Take the emergency brake system of our robot Larry. It doesn’t need every single distance sample from the ultrasonic sensor. If the next obstacle detected is on another planet, we can ignore it. But when an obstacle is close, we suddenly care. And not just about the raw number but also the trend over time. If the object is receding, no action is needed; if it’s approaching, we may need to hit the brakes.
Now consider failure cases. If the sensor participant dies and never sends another update, Larry shouldn’t drive happily into oblivion. A safe fallback (parking, for example) is required. Another factor to consider: the emergency brake participant might start after the sensor participant. In that case, it still needs the most recent three distance samples to compute not just position, but relative speed and acceleration.
These scenarios show why we want independent streams for data and control signals.
Publisher Setup
We start by creating a node and defining two services with the same name:
- a publish-subscribe service for distance samples,
- an event service for control signals.
The subscriber needs the last three samples whenever it connects, so we configure both the subscriber buffer and history size accordingly. The subscriber also needs to hold on to/borrow three samples in parallel to compute position, speed, and acceleration.
var Node := TNodeBuilder.New
.Create(TServiceType.Ipc)
.Value;
var PubSubService := Node
.ServiceBuilder(TServiceName.Create('distance_to_obstacle').Value)
.PublishSubscribe<TDistance>
.SubscriberMaxBufferSize(3)
.HistorySize(3)
.SubscriberMaxBorrowedSamples(3)
.OpenOrCreate
.Value;
For the event service, we configure a special event that fires if the sensor participant is identified as dead, allowing the emergency brake to switch to a safe state.
var UltraSonicServiceDead := TEventId.Create(10);
var EventService := Node
.ServiceBuilder(TServiceName.Create('distance_to_obstacle').Value)
.Event
.NotifierDeadEvent(UltraSonicServiceDead)
.OpenOrCreate
.Value;
Now we create a publisher for the distance samples and a notifier for control events.
var Publisher := PubSubService
.PublisherBuilder
.Create
.Value;
var Notifier := EventService
.NotifierBuilder
.Create
.Value;
var ObstacleTooClose := TEventId.Create(5);
The publishing loop: send the distance sample every 100 ms, and trigger an event if it’s below the threshold.
while (Node.Wait(TDuration.FromMillis(100)).HasValue) do
begin
var Sample := Publisher.LoanUninit.Value;
var Distance: TDistance;
Distance.DistanceInMeters := GetUltraSonicSensorDistance;
Distance.SomeOtherProperty := 42;
var InitializedSample := Sample.WritePayload(Distance);
InitializedSample.Send.Value;
if (Distance.DistanceInMeters < DistanceThreshold) then
Notifier.NotifyWithCustomEvent(ObstacleTooClose).Value;
end;
Subscriber Setup
On the other side, we again create both services and their ports:
var Node := TNodeBuilder.New
.Create(TServiceType.Ipc)
.Value;
var PubSubService := Node
.ServiceBuilder(TServiceName.Create('distance_to_obstacle').Value)
.PublishSubscribe<TDistance>
.SubscriberMaxBufferSize(3)
.HistorySize(3)
.SubscriberMaxBorrowedSamples(3)
.OpenOrCreate
.Value;
var UltraSonicServiceDead := TEventId.Create(10);
var EventService := Node
.ServiceBuilder(TServiceName.Create('distance_to_obstacle').Value)
.Event
.NotifierDeadEvent(UltraSonicServiceDead)
.OpenOrCreate
.Value;
var Subscriber := PubSubService
.SubscriberBuilder
.Create
.Value;
var Listener := EventService
.ListenerBuilder
.Create
.Value;
Instead of polling every 100 ms, the subscriber just waits for events. When woken up, it processes them and goes back to sleep.
while (Node.Wait(TDuration.FromSecs(0)).HasValue) do
begin
var SensorIsDead := False;
var ObstacleDetected := False;
Listener.BlockingWait(
procedure(const AEvent: TEventActivation)
begin
if (AEvent.Id = UltraSonicServiceDead) then
SensorIsDead := True;
if (AEvent.Id = ObstacleTooClose) then
ObstacleDetected := True;
end).Value;
if (SensorIsDead) then
GoIntoParkingPosition;
if (ObstacleDetected) then
begin
var LastSamples: TArray<TSample<TDistance, Void>> := nil;
var Sample := Subscriber.Receive.Value;
while (Sample.HasValue) do
begin
LastSamples := LastSamples + [Sample.Value];
if (Length(LastSamples) = 3) then
Break;
Sample := Subscriber.Receive.Value;
end;
PerformBreak(LastSamples);
end;
end;
Health Monitoring
The notifier’s “dead event” relies on health monitoring: iceoryx2 offers building blocks that detects when a participant dies. How this works in detail is covered in a separate tutorial.