Skip to content

Request-Response

With emergency brakes and some basic fault handling in place, it’s time for something a bit more sophisticated.

Imagine the user wants to send our robot Larry to a specific position: “Go to point B.” As Larry starts driving, the user expects status updates - position, speed, progress. At some point the user may even cancel the trip, or Larry himself may have to abort if he encounters, say, a canyon.

Request-Response Sequence Diagram between App and Larry Autopilot

Request-Response interactions between App and Larry Autopilot

This is where the request-response (stream) pattern in iceoryx2 comes into play. It behaves like regular non-blocking request-response, but with one extra trick: the server can send a stream of responses instead of just one. Either side can end the stream at any time if it’s no longer interested.

Client

The client is our user-facing app. The request can be a simple 2D position:

type
  TPosition = record
  public
    Position: array [0..1] of Single;
  end;

The server responds with Larry’s current state:

type
  TState = record
  public
    Position: array [0..1] of Single;
    Speed:a rray [0..1] of Single;
  end;

First we create a node:

var Node := TNodeBuilder.New
  .Create(TServiceType.Ipc)
  .Value;

Then the service, specifying request and response types:

var Service := Node
  .ServiceBuilder(TServiceName.Create('autopilot').Value)
  .RequestResponse<TPosition, TState>
  .OpenOrCreate
  .Value;

And create the client port:

var Client := Service
  .ClientBuilder
  .Create
  .Value;

Now we can send a request. The returned TPendingResponse object represents the stream of updates for this request. Dropping it automatically signals the server to stop sending further responses.

var Request := Client.LoanUninit.Value;

var Pos: TPosition;
Pos.Position[0] := 123.456;
Pos.Position[1] := 789.1;

var InitializedRequest := Request.WritePayload(Pos);

var PendingResponse := InitializedRequest.Send.Value;

In the event loop we poll every 100 ms and handle three cases:

  1. User pressed “stop” → drop TPendingResponse to cancel.
  2. Larry disconnected before reaching the goal → show “obstacle detected.”
  3. Normal update → display current position.
while (Node.Wait(TDuration.FromMillis(100)).HasValue) do
begin
  var Response := PendingResponse.Receive.Value;
  while (Response <> nil) do
  begin
    ShowLarryPositionInApp(Response);

    if (not PendingResponse.IsConnected) then
    begin
      if (IsAtDestination(Response)) then
        ShowLarryArrivedPopupInApp
      else
        ShowLarryEncounteredObstracleInApp;
    end;

    Response := PendingResponse.Receive.Value;
  end;

  if (UserHasPressedStopButton) then
    // dropping the pending response cancels the stream
    break;
end;

Server

On the server side, the setup looks similar:

var Node := TNodeBuilder.New
  .Create(TServiceType.Ipc)
  .Value;

var Service := Node
  .ServiceBuilder(TServiceName.Create('autopilot').Value)
  .RequestResponse<TPosition, TState>
  .OpenOrCreate
  .Value;

var Server := Service
  .ServerBuilder
  .Create
  .Value;

The server checks every 100 ms for new requests. (You could combine this with event messaging to block until a request arrives, but for the purpose of this tutorial, we keep it simple.) When a request is received, Larry starts driving and periodically sends status updates.

If an obstacle is detected, or the client disconnects, the active request is dropped and Larry stops.

var ActiveRequest := Server.Receive.Value;
while (Node.Wait(TDuration.FromMillis(100)).HasValue) do
begin
  if (ActiveRequest = nil) then
  begin
    ActiveRequest := Server.Receive.Value;
    if (ActiveRequest <> nil) then
      DriveToPosition(ActiveRequest);
  end;

  if (ActiveRequest <> nil) then
  begin
    if (not ActiveRequest.IsConnected) then
    begin
      StopDriving;
      ActiveRequest.Release;
    end
    else if (ArrivedAtDestination) then
      ActiveRequest.Release
    else
    begin
      var Response := ActiveRequest.LoanUninit.Value;
      var InitializedResponse := Response.WritePayload(
        GetCurrentState);
      InitializedResponse.Send.Value;
    end;
  end;
end;

This way, the client can receive a continuous stream of updates, either side can gracefully stop when necessary, and Larry doesn’t drive blindly into canyons (in theory).