Skip to content

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.

Communication graph of Ultrasonic Sensor and Emergency Brake

The communication graph of the Ultrasonic Sensor and Emergency Brake participants

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
type
  TDistance = record
  public
    DistanceInMeters: Double;
    SomeOtherProperty: Single;
  end;  

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:

var Publisher := Service
  .PublisherBuilder
  .Create
  .Value;

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:

var Subscriber := Service
  .SubscriberBuilder
  .Create
  .Value;

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.