zerodds_transport_shm/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 ZeroDDS Contributors
3//! Crate `zerodds-transport-shm`. Safety classification: **STANDARD**.
4//!
5//! Cross-Process Shared-Memory-Transport für ZeroDDS — POSIX
6//! `shm_open`/`mmap` mit Lock-free Single-Producer-Single-Consumer-
7//! Ringbuffer.
8//!
9//! ## Spec
10//!
11//! - **DDSI-RTPS 2.5 §9.4** — Locator-Kind `LOCATOR_KIND_SHM` (vendor-
12//!   reserved range; ZeroDDS-Wert in `crates/rtps/src/wire_types.rs`).
13//! - **ZeroDDS-SHM-Transport 1.0** — vendor-spezifischer Transport-
14//!   Spec (Segment-Layout, SpSc-Ringbuffer, Cleanup-Semantik),
15//!   `docs/spec-coverage/zerodds-shm-transport-1.0.md`.
16//!
17//! ## Hinweis zur OMG-Normativität
18//!
19//! OMG normiert keinen SHM-Transport für DDS. Vendoren haben jeweils
20//! eigene Implementationen: Cyclone DDS integriert iceoryx (third-
21//! party), FastDDS hat einen eigenen SHM-Transport, RTI hat
22//! RTI-Connext-DDS-SHM. ZeroDDS definiert seine eigene Variante
23//! explizit als ZeroDDS-SHM-Transport-1.0-Spec.
24//!
25//! ## Implementiert (RC1)
26//!
27//! - POSIX `shm_open` + `mmap` via `shared_memory`-Crate.
28//! - SpSc-Ringbuffer pro (Writer, Reader)-Paar — lock-free
29//!   `head`/`tail`-AcqRel-Atomics auf shared memory.
30//! - Owner-Crash-Recovery via predictable `os_id` + `shm_unlink` vor
31//!   jedem Owner-`create()`. Idempotent.
32//! - Advisory `flock`-Race-Protection beim Owner-Create (Linux/macOS).
33//! - Length-Prefix-Frame-Format mit Wraparound-Padding-Marker.
34//! - Shutdown-Flag im Segment-Header für Owner→Consumer-Termination-
35//!   Signaling.
36//!
37//! ## Plattform-Support
38//!
39//! | Plattform | Status |
40//! |---|---|
41//! | Linux | ✅ primary |
42//! | macOS | ✅ supported |
43//! | Windows | nicht-getestet (`shared_memory`-Crate liefert die Mapping-Primitives, aber unsere `flock`-Race-Protection und `shm_unlink`-Cleanup sind unix-only) |
44//!
45//! ## Public API
46//!
47//! - [`PosixShmTransport`] — `Transport`-Trait-Impl.
48//! - [`ShmConfig`] — Segment-Konfiguration.
49//! - [`ShmRole`] — Owner / Consumer.
50//! - [`PosixShmError`] — typisierte Fehler.
51//!
52//! ## Unsafe-Scope
53//!
54//! Begrenzt auf das `posix`-Modul: zwei `ptr::read`/`ptr::write` auf
55//! mapped memory plus die `libc::flock`-FFI. Alles andere ist
56//! `AtomicU{32,64}` über shared memory; Rust garantiert wohldefiniertes
57//! Verhalten von Atomic-Operationen über Prozess-Grenzen, wenn beide
58//! Prozesse dieselbe Adresse mappen.
59
60#![cfg_attr(not(feature = "std"), no_std)]
61#![warn(missing_docs)]
62
63#[cfg(feature = "alloc")]
64extern crate alloc;
65
66#[cfg(feature = "std")]
67pub mod posix;
68
69#[cfg(feature = "std")]
70pub use posix::{PosixShmError, PosixShmTransport, ShmConfig, ShmRole};
zerodds_transport_shm/lib.rs

zerodds_transport_shm/
lib.rs
