Skip to content

README.md

Latest commit

 

History

History
106 lines (83 loc) · 3.83 KB

README.md

File metadata and controls

106 lines (83 loc) · 3.83 KB

Request-Response

Caution

Every payload you transmit with iceoryx2 must be compatible with shared memory. Specifically, it must:

  • be self contained, no heap, no pointers to external sources
  • have a uniform memory representation, ensuring that shared structs have the same data layout
    • therefore, only ctypes and ctypes.Structure can be transferred
  • not use pointers to manage their internal structure

Any other python data type, except ctypes or ctypes.Structures, like will cause undefined behavior and may result in segmentation faults. Take a look at the publish subscribe example to see how ctypes can be transferred.

This example demonstrates the request-response messaging pattern between two separate processes using iceoryx2. A key feature of request-response in iceoryx2 is that the Client can receive a stream of responses instead of being limited to just one.

Client Side

The Client uses the following approach:

  1. Sends first request by using the slower copy API and then enters a loop.
  2. Inside the loop: Loans memory and acquires a RequestMut.
  3. Writes the payload into the RequestMut.
  4. Sends the RequestMut to the Server and receives a PendingResponse object. The PendingResponse can be used to:
    • Receive Responses for this specific RequestMut.
    • Signal the Server that the Client is no longer interested in data by going out of scope.
    • Check whether the corresponding ActiveRequest on the Server side is still connected.

Server Side

The Server uses the following approach:

  1. Receives the RequestMut sent by the Client and obtains an ActiveRequest object.
  2. The ActiveRequest can be used to:
    • Read the payload, header, and user header.
    • Loan memory for a ResponseMut.
    • Signal the Client that it is no longer sending responses by going out of scope.
    • Check whether the corresponding PendingResponse on the Client side is still connected.
  3. Sends one Response by using the slower copy API.
  4. Loans memory via the ActiveRequest for a ResponseMut to send a response.

Sending multiple responses demonstrates the streaming API. The ActiveRequest and the PendingResponse can call is_connected() to see if the corresponding counterpart is still sending/receiving responses. As soon as the ActiveRequest or PendingResponse went out-of-scope is_connected() will return false.

In this example, both the client and server print the received and sent data to the console.

How to Build

Before proceeding, a virtual environment with all dependencies needs to be created. You can find the detailed instructions in the Python Examples Readme.

poetry --project iceoryx2-ffi/python install

Then, the iceoryx2 python bindings can be built and installed into the virtual environment:

poetry --project iceoryx2-ffi/python run maturin develop --manifest-path iceoryx2-ffi/python/Cargo.toml --target-dir target/ff/python

How to Run

To observe the communication in action, open two terminals and execute the following commands:

Terminal 1

poetry --project iceoryx2-ffi/python run python examples/python/request_response/server.py

Terminal 2

poetry --project iceoryx2-ffi/python run python examples/python/request_response/client.py

Feel free to run multiple instances of the client or server processes simultaneously to explore how iceoryx2 handles request-response communication efficiently.

Tip

You may hit the maximum supported number of ports when too many client or server processes run. Take a look at the iceoryx2 config to set the limits globally or at the API of the Service builder to set them for a single service.