How eclipse-iceoryx/iceoryx2 works
Project type and purpose
• iceoryx2 is a monorepo for a zero-copy, lock-free, service-oriented IPC middleware.
• It provides a Rust core engine plus pluggable language bindings (C, C++, Python), platform-abstraction layers, tools (CLI, tunnel, services), examples and benchmarks.
Top-level architectural components
• Rust Core Engine (“iceoryx2”)
– Manages ports, chunks, samples, connections, service builders (publish-subscribe, request-response, event).
• Platform Abstraction Layer (“iceoryx2-pal”)
– Concurrency primitives (mutex, barrier, semaphore), OS API wrappers (posix, linux, macOS, QNX, Windows), configuration, testing hooks.
• Core Utility Crates
– Container and lock-free data structures (iceoryx2-bb/container, lock-free, elementary-traits, memory).
– Conformance test macros and trait tests.
• Communication Abstraction Layer (“iceoryx2-cal”)
– Policy-driven implementations for shared memory, sockets, zero-copy connections, dynamic/static storage, event signalers.
• Language Bindings
– C API wrapper (iceoryx2-c) generated via cbindgen.
– C++ API (iceoryx2-cxx) consuming core C API and offering RAII, error types, service builders.
– Python extension (iceoryx2-ffi/python) via PyO3, mapping Rust core to Python idioms.
• CLI Tools (iceoryx2-cli)
– Subcommands: iox2-config, iox2-node, iox2-service, iox2-tunnel. Uses core crates for configuration, filtering, output.
• Service Discovery Services (iceoryx2-services/discovery)
– A library offering service registration, lookup, tracking for dynamic topologies.
• Tunnel Framework (iceoryx2-tunnel)
– Backend traits, transport implementations, end-to-end tests, zenoh bridge.
• Userland Utilities (iceoryx2-userland/record-and-replay)
– Record and replay library and tools.
• Examples & Benchmarks
– Multi-language examples demonstrating each messaging pattern.
– Benchmarks for mechanism and architecture performance.
• Documentation, CI, Build Scripts
– Doxygen, Sphinx, Bazel and CMake build configs, GitHub workflows, internal scripts.
Relationships and data-flow
• Core Engine ←─ depends on ── PAL crates, utility crates, CAL
• C API → wraps → Core Engine
• C++ API → consumes → C API + Core Engine types
• Python API → binds → Core Engine via FFI
• CLI Tools → link → CLI library → use → Core Engine & Bindings
• Service Discovery → library → uses → Core Engine ports & samples
• Tunnel → implements → discovery & relay → uses → Core Engine ports
• Record-&-Replay → side-channel → uses → Core Engine’s serialization
• Examples & Benchmarks → client apps → use → Bindings & Core Engine
Architectural patterns
• Modular crate-per-component, using Cargo + Bazel as a polyglot build system.
• Service-Oriented Architecture: services expose ports, use builders.
• Policy pattern in CAL: pluggable implementations selected at compile time.
• Layered binding pattern: Rust core → C API → C++/Python consumers.
• Tunnel and CLI use adapter pattern to integrate with core IPC.
Essential elements to capture
• Core Engine internal modules: port management, service builder, sample life-cycle.
• PAL providing OS primitives.
• CAL policy plug-ins (shared memory, sockets, dynamic/static storage).
• Language layering: C API sits atop Core, then C++/Python libraries.
• High-level tools (CLI, Tunnel, Service Discovery) as clients of Core and Bindings.
• Example applications as users of the public API.
• Build system integration: Bazel and Cargo, but keep build nuance in a side annotation.
Final advice
• How data flows from publisher to subscriber (shared memory buffer → port → sample → callback).
• Zero-copy and lock-free nature by annotating the shared memory and PAL layer.