DOCSEARCHbyAlgolia
Submit Docs

iceoryx2 Documentation

repository·main·Indexed 25 days ago

https://github.com/eclipse-iceoryx/iceoryx2

A high-performance, zero-copy, lock-free inter-process communication (IPC) middleware with a Rust core, designed for ultra-low latency data exchange. Includes guides on configuration, custom platform abstraction layers (PAL), Bazel integration via Bzlmod, and performance benchmarks for publish-subscribe, request-response, event, and queue patterns.

Tokens
112.7K
Snippets
253
Records
539
Agent score
78%

What's inside iceoryx2

  1. Overview of iceoryx2-services

    main
    The iceoryx2-services collection provides ready-to-use service crates designed to extend application capabilities through composable services. These crates build on top of the core iceoryx2 infrastructure and can be integrated into applications with minimal effort to provide common middleware functionality.

  2. What is iceoryx2?

    main

    iceoryx2 is an efficient, ultra-low latency inter-process communication (IPC) middleware designed for zero-copy and lock-free communication between multiple processes or applications. It uses a service-oriented architecture (SOA) to provide predictable transmission latency regardless of payload size.

    Key messaging patterns include:

    • Publish/Subscribe: Ideal for sharing large datasets.
    • Request/Response: For client-server style interactions.
    • Events: For quick and reliable signaling between processes.
    • Pipeline (Planned): For streaming data.
    • Blackboard (Planned): For shared state management.

  3. Overview of iceoryx2 communication examples

    main

    The examples/ directory provides various implementations of communication patterns using iceoryx2 across multiple languages (C, C++, Python, and Rust). Key patterns include:

    Communication Patterns

    • Publish-Subscribe: Standard messaging pattern between multiple processes.
    • Request-Response: Client-server pattern for sending requests and receiving response streams.
    • Blackboard: Unidirectional communication using an inter-process key-value store.
    • Event-based: Using event signals to wake up waiting processes or react to lifecycle changes (e.g., publisher/subscriber creation).

    Advanced Features

    • Cross-Language Communication: Examples for communicating between different languages (e.g., Rust to C++) using shared memory compatible containers and complex types.
    • Dynamic Data: Handling payloads with dynamic sizes in both Publish-Subscribe and Request-Response patterns.
    • Service Customization: Using different service types like local::Service (intra-process) or ipc_threadsafe::Service (threadsafe ports), and overriding OS mechanisms.
    • Complex Data Handling: Using the PlacementDefault trait for large data types to prevent stack overflows via in-place initialization.
    • Discovery: Listing all available services in a system.
    • Domains: Establishing independent communication domains.

  4. Available iceoryx2 Integrations

    main

    The iceoryx2 repository provides integrations to connect with external middlewares and frameworks. Each integration is maintained as a self-contained Cargo workspace to ensure dependency isolation from the core iceoryx2 library.

    Currently available integrations:

    • Zenoh: Connects iceoryx2 systems across different hosts and networks using Zenoh.
    • ROS 2: Enables interoperability between iceoryx2 and the ROS 2 ecosystem.

  6. Capabilities of the iceoryx2 ROS 2 tunnel backend

    main

    The tunnel backend connects native iceoryx2 applications with ROS 2 nodes using r2r_rcl bindings.

    Supported Communication Patterns:

    • Publish-subscribe: Both sending (iceoryx2 → ROS 2) and receiving (ROS 2 → iceoryx2) are implemented.
    • Event: Not applicable (no ROS 2 equivalent).

    Supported Features:

    • Static discovery: Configured topics are supported.
    • Dynamic discovery: ROS 2 graph discovery is supported.
    • Passthrough mode: CDR payloads are passed as-is.

    In Progress / Not Implemented:

    • Topic & QoS mapping
    • Translation mode (CDR transcoding)
    • CI integration

  7. Understand the core communication patterns in iceoryx2

    main

    Communication in iceoryx2 is built around Services, which act as factories for creating Ports (the participants that establish communication links). The behavior of a service is determined by its messaging pattern.

    Supported patterns include:

    • Publish-Subscribe: A publisher sends a continuous stream of data to one or more subscribers.
    • Event: Notifiers trigger events on a listener (used for push-notifications).
    • Request-Response: Clients send requests to a server for interactive or transactional communication.
    • Blackboard: A key-value store in shared memory with one writer and multiple readers.
    • Pipeline: (Planned) A data source produces data and transfers ownership to a sink for processing.

    Services and ports can be customized using service builders and port factories to configure Quality of Service (QoS) parameters.

  8. Avoid Stack Overflow with large payload types

    main

    If your payload type is too large, you may encounter a stack overflow. To prevent this, construct the data type in-place within the shared memory rather than on the stack.

    Use the PlacementDefault trait to enable in-place initialization. Refer to the complex_data_types example in the repository for implementation details.

  9. How the WaitSet event multiplexing works

    main

    The WaitSet is iceoryx2's event multiplexing mechanism. It allows a process to wait on multiple Listener ports and external file descriptor-based events (such as sockets) using a single call.

    To use a WaitSet:

    1. Use iox2_waitset_attach_notification() to attach a specific event to the iox2_waitset_t.
    2. This returns an iox2_waitset_guard_t (a RAII guard). You must manage this guard; the attachment is automatically detached when the guard is cleaned up using iox2_waitset_guard_drop().
    3. Call iox2_waitset_wait_and_process(), providing a callback. This callback is invoked for every triggered attachment and provides an iox2_waitset_attachment_id_h.
    4. Inside the callback, use iox2_waitset_attachment_id_has_event_from() to identify which specific object triggered the event.
    CAUTION

    The WaitSet wakes up as soon as there is data to read. If the data is not consumed within the callback, the WaitSet will immediately wake the process again, which can lead to an infinite loop and 100% CPU usage.

  10. Choose between Ipc and Local Service Types

    main

    When building a Node, you can choose between two primary service types:

    • ServiceType::Ipc: The default type for inter-process communication. It uses shared memory and is visible to other processes. All ports are thread-safe.
    • ServiceType::Local: Used for intra-process communication. Services are confined to the current process, making them ideal for inter-thread communication without creating external resources like shared memory. All ports are thread-safe.

    Note that in C++, all ports (such as Publisher, Subscriber, Server, and Client) are thread-safe by default to ensure safety across threads.

    auto node = NodeBuilder()
    .create<ServiceType::Ipc>()

  11. Customize communication using Service Types

    main

    iceoryx2 allows you to adapt communication mechanisms to specific environments (like unit tests, GPU memory sharing, or embedded systems) by specifying a Service Type when creating a Node. This allows you to change the underlying communication mechanism without modifying your application logic.

    In the C API, the service type is passed to iox2_node_builder_create via the third parameter.

    iox2_node_builder_create(node_builder_handle, NULL, iox2_service_type_e_IPC, &node);

  12. How the Request-Response pattern works in iceoryx2

    main

    The Request-Response pattern in iceoryx2 allows for a streaming of responses from a single request.

    Client Workflow

    1. Sends the initial request using the copy API.
    2. Enters a loop where it:
      • Loans memory and acquires a RequestMut.
      • Writes the payload into the RequestMut.
      • Sends the RequestMut to the Server to receive a PendingResponse object.
    3. Uses PendingResponse to:
      • Receive a stream of Responses for that specific request.
      • Signal the Server that it is no longer interested in data by letting the object go out of scope.
      • Check connection status via is_connected() (returns false if the Server's ActiveRequest is gone).

    Server Workflow

    1. Receives the RequestMut from the Client and obtains an ActiveRequest object.
    2. Uses ActiveRequest to:
      • Read the payload, header, and user header.
      • Loan memory for a ResponseMut.
      • Signal the Client that it is no longer sending responses by letting the object go out of scope.
      • Check connection status via is_connected() (returns false if the Client's PendingResponse is gone).
    3. Sends responses using either the copy API or by loaning memory via ActiveRequest for a ResponseMut (enabling streaming).