Publish–Subscribe
Larry’s hardware and algorithms are already built. Now we want to send the distance measured by his ultrasonic sensor to another participant that can slam the brakes if an obstacle gets closer than X meters.
In iceoryx2, that’s a perfect job for the publish-subscribe pattern: one participant publishes a stream of distances, another subscribes and reacts.
Publisher
Everything in iceoryx2 starts with a node. A node represents a communication point (like a process or thread) and acts as a factory for services. To keep things sane when debugging later, we’ll give this node a name:
var Node := TNodeBuilder.New
.Name(TNodeName.Create('UltraSonicSensor').Value)
.Create(TServiceType.Ipc)
.Value;
Tip
Note the fluent interface used to set attributes of the node.
See Delphi Topics for more information about Delphi-specific constructs used in the API.
Now we can create a service called "distance_to_obstacle", using a record TDistance as the payload type. Payloads must be shared-memory compatible, meaning:
- self-contained
- no internal pointers
- identical memory representation
With the payload defined, we can set up the service:
var Service := Node
.ServiceBuilder(TServiceName.Create('distance_to_obstacle').Value)
.PublishSubscribe<TDistance>
.OpenOrCreate
.Value;
Now we create our publisher:
Larry isn’t exactly Formula 1 material, so publishing every 100 ms is plenty. We set up a loop that waits 100 ms, reads the sensor, and sends the data. To fully benefit from zero-copy, we don’t allocate or clone data; instead we loan an uninitialized sample from the publisher’s memory pool, fill it, and then send it:
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;
end;
Tip
Note that we check the result of the Send call by accessing its Value property. This will raise an exception if the send failed. You can also choose to check the result yourself instead of using the Value property. See Delphi Topics for more information about this.
Whenever we acquire an uninitialized sample, we must write the payload to it and convert it into an initialized sample. This ensures we don’t accidentally ship uninitialized garbage across participants. Once the payload is written, the sample is safe to send.
Subscriber
The subscriber setup starts the same: create a node, open the "distance_to_obstacle" service, and specify the payload type.
var Node := TNodeBuilder.New
.Create(TServiceType.Ipc)
.Value;
var Service := Node
.ServiceBuilder(TServiceName.Create('distance_to_obstacle').Value)
.PublishSubscribe<TDistance>
.OpenOrCreate
.Value;
Now we create the subscriber side:
Since the publisher sends updates every 100 ms, we loop at the same pace and check for new data. If we receive something, we print it:
while (Node.Wait(TDuration.FromMillis(100)).HasValue) do
begin
var Sample := Subscriber.Receive.Value;
while (Sample.HasValue) do
begin
WriteLn('received distance: ', Sample.Value.Payload.DistanceInMeters);
Sample := Subscriber.Receive.Value;
end;
end;
From here, reacting is easy: if the distance falls below a threshold, Larry can hit the emergency brake before smashing into a wall.