zerodds-flatdata 1.0.0-rc.1

FlatStruct-Trait fuer Zero-Copy Same-Host-Pub/Sub (zerodds-flatdata-1.0): SlotBackend-Trait, In-Memory-Allocator, POSIX shm/mmap, Iceoryx2-Bridge.
Documentation

zerodds-flatdata

License: Apache-2.0 docs.rs

Zero-Copy Same-Host-Pub/Sub fuer den ZeroDDS-Stack: FlatStruct-Trait, Slot-Layout per Spec, drei produktive SlotBackend-Implementationen (in-memory + POSIX shm/mmap + Iceoryx2-Bridge). Safety classification: STANDARD (mit per-Block-SAFETY-Kommentaren um die unsafe trait FlatStruct-Garantien herum lokalisiert).

Spec-Mapping

Spec Abschnitt
ZeroDDS-flatdata 1.0 §1 (FlatStruct + derive), §2 (Slot-Layout), §4 (Wire-Pfad), §5 (Lifetime + Refcount), §6 (Schema-Versioning), §7 (Sicherheit), §8/§9 (Writer-/Reader-API)
ADR-0003 Drei-Backend-Architektur (in-memory / POSIX shm / Iceoryx2)

Was ist drin

  • FlatStruct-Trait — unsafe trait mit Copy + 'static + Send + Sync und TYPE_HASH-Konstante. Garantiert Layout-Stabilitaet, sodass as_bytes() und from_bytes_unchecked() per Layout safe sind.
  • SlotHeader + Slot-Layout — 16-Byte-Header (sequence_number, sample_size, reader_mask, reserved) + Payload (Spec §2).
  • SlotBackend-Trait — abstrahiert das Backend; Reader/Writer sind generisch.
  • InMemorySlotAllocator — Default-Backend fuer Tests + Single-Process-Pub/Sub.
  • PosixSlotAllocator (Feature posix-mmap, default an) — shm_open+mmap, Cross-Process Same-Host. Owner/Consumer-Modell mit flink-Datei.
  • Iceoryx2Publisher<T> / Iceoryx2Subscriber<T> (Feature iceoryx2-bridge) — separate Pub/Sub-API gegen Eclipse iceoryx2 v0.8. Mappt auf loan_slice_uninit + send / receive. Type-Hash-Cross-Validation per Service-Name-Komposition.
  • FlatWriter<T> + FlatSlot<T> — Spec §8.1/§8.2: write + loan_slot + commit/Drop-discard.
  • FlatReader<T> + FlatSampleRef<T> — Spec §9.1: read mit Type-Hash-Cross-Validation (Spec §6.1) + last_sn-Re-Read-Suppression.
  • ShmLocator + is_same_host + FNV-1a-Helper — Discovery-Vendor-PID-Hilfen.

Schichten-Position

Layer 4 — Core Services. Keine ZeroDDS-Crate-Deps; einzige externe Dep ist shared_memory (optional, hinter posix-mmap-Feature).

Quickstart

use std::sync::Arc;
use zerodds_flatdata::{FlatStruct, FlatWriter, FlatReader, InMemorySlotAllocator};

#[derive(Copy, Clone, Debug, PartialEq)]
#[repr(C)]
struct Pose { x: f64, y: f64, z: f64 }

unsafe impl FlatStruct for Pose {
    const TYPE_HASH: [u8; 16] = [0xAA; 16];
}

let alloc = Arc::new(InMemorySlotAllocator::new(0, 4, Pose::WIRE_SIZE));
let writer = FlatWriter::<Pose>::new(Arc::clone(&alloc), 0b1);
let reader = FlatReader::<Pose>::new(Arc::clone(&alloc), 0);

writer.write(&Pose { x: 1.0, y: 2.0, z: 3.0 }).unwrap();
let got = reader.read().unwrap().unwrap();
assert_eq!(got, Pose { x: 1.0, y: 2.0, z: 3.0 });

Feature-Flags

Feature Default Zweck
std ✅ Standard-Library + Mutex + Threads.
alloc ✅ (via std) Vec/Arc.
posix-mmap ✅ PosixSlotAllocator (POSIX shm_open + mmap). Hangt an shared_memory.
iceoryx2-bridge ❌ Iceoryx2-Adapter-Skelett (Bridge zu iceoryx2-Service).

Stabilitaet

Alle pub-Items sind ab 1.0.0 stabil. Die unsafe trait FlatStruct ist API-stabil; Implementer müssen die Layout-Garantien per unsafe impl zusichern.

Tests

cargo test -p zerodds-flatdata

Lizenz

Apache-2.0. Siehe LICENSE.

Siehe auch