ndn_faces/local/shm/
mod.rs

1//! Shared-memory NDN faces.
2//!
3//! The `spsc-shm` feature (Unix only, enabled by default on Unix targets)
4//! provides a custom lock-free SPSC ring buffer in a POSIX `shm_open` region,
5//! with Unix datagram sockets for wakeup.
6//!
7//! Both types expose the same pair of types: `ShmFace` (engine side) and
8//! `ShmHandle` (application side).  The engine registers `ShmFace` via
9//! `ForwarderEngine::add_face`; the application uses `ShmHandle` to send and
10//! receive NDN packets over shared memory.
11//!
12//! # Quick start
13//!
14//! ```no_run
15//! # use ndn_faces::local::shm::{ShmFace, ShmHandle};
16//! # use ndn_transport::FaceId;
17//! // ── Engine process ────────────────────────────────────────────────────────
18//! let face = ShmFace::create(FaceId(5), "myapp").unwrap();
19//! // engine.add_face(face, cancel);
20//!
21//! // ── Application process ───────────────────────────────────────────────────
22//! let handle = ShmHandle::connect("myapp").unwrap();
23//! // handle.send(interest_bytes).await?;
24//! // let data = handle.recv().await?;
25//! ```
26
27#[cfg(all(unix, feature = "spsc-shm"))]
28pub mod spsc;
29
30/// Compute the slot_size required to carry a Data packet whose content
31/// can be up to `mtu` bytes. Mirrors [`spsc::slot_size_for_mtu`] so
32/// callers that don't depend on the `spsc` submodule can still derive
33/// a correct SHM ring sizing.
34#[cfg(all(unix, feature = "spsc-shm"))]
35pub fn slot_size_for_mtu(mtu: usize) -> u32 {
36    spsc::slot_size_for_mtu(mtu)
37}
38
39// ─── Unified error type ───────────────────────────────────────────────────────
40
41#[derive(Debug, thiserror::Error)]
42pub enum ShmError {
43    #[error("I/O error: {0}")]
44    Io(#[from] std::io::Error),
45    #[error("SHM name contains an interior NUL byte")]
46    InvalidName,
47    #[error("SHM region has wrong magic number (stale or wrong name?)")]
48    InvalidMagic,
49    #[error("packet exceeds the SHM slot size")]
50    PacketTooLarge,
51    #[error("SHM face closed (peer died or cancelled)")]
52    Closed,
53}
54
55// ─── Type aliases ─────────────────────────────────────────────────────────────
56
57/// Engine-side SHM face — register with `ForwarderEngine::add_face`.
58#[cfg(all(unix, feature = "spsc-shm"))]
59pub type ShmFace = spsc::SpscFace;
60
61/// Application-side SHM handle.
62#[cfg(all(unix, feature = "spsc-shm"))]
63pub type ShmHandle = spsc::SpscHandle;
ndn_faces/local/shm/mod.rs

ndn_faces/local/shm/
mod.rs
