Design Principles
Zero-Copy First
Zero-Copy First
Local communication uses zero-copy shared memory whenever possible. Serialization only occurs when data crosses a network boundary β on the same machine, publishers and subscribers share memory directly via iceoryx2.Like a whiteboard in a shared office β the publisher writes on the board, and the subscriber reads it in place. Nobody makes a photocopy.
High Availability
High Availability
Network failures never block local communication. If Zenoh goes down, nodes on the same machine continue exchanging data at full speed. The system prioritizes availability over guaranteed network delivery.
Type Safety
Type Safety
Compile-time guarantees in Rust β message schemas are code-generated from
.msg files, so type mismatches and schema changes are caught before you run. The Rust compiler enforces correctness at every pub/sub boundary.Automatic Everything
Automatic Everything
Serialization, transport selection, and code generation are all automatic. You define inputs and outputs β Cerulion decides whether to use shared memory or network, serializes when needed, and generates Rust bindings from your
.msg files at build time.Latest-Message Semantics
Latest-Message Semantics
Network transport uses latest-message semantics. If the network is slow, newer messages replace older ones in the queue β critical for real-time systems where stale sensor data is worse than no data.
System Overview
Cerulion provides a unified pub/sub API that automatically selects the best transport for each communication path: The TopicManager owns a single Zenoh session shared across all pub/sub pairs β publishers send to both paths simultaneously, and the subscriber auto-selects the fastest available route.At a Glance
| Dimension | What Cerulion Does |
|---|---|
| β‘ Local latency | ~60 ns via shared memory (iceoryx2) |
| π Network latency | 1β10 ms via Zenoh |
| π Serialization | Only when crossing a network boundary |
| π§ Transport selection | Automatic β local-first, network fallback |
| π¦ Wire format | Contiguous, zero-copy friendly |
| β±οΈ Scheduling | Deterministic triggers β periodic, input, synced, external |
| π― Determinism | Same inputs β same execution order β same outputs |
| π¦ Backend | Rust β memory safe, no undefined behavior, no data races |
Workspace Structure
A typical Cerulion workspace follows this layout:my-workspace
nodes
camera_pub
camera_pub.rs
Cargo.toml
display_sub
graphs
camera_pipeline.crln
Cargo.toml
| Directory | Purpose |
|---|---|
nodes/ | Each node is a Rust crate with a #[node] macro entry point |
graphs/ | YAML .crln files that wire nodes together via typed topics |
Cargo.toml | Workspace-level Cargo manifest |