ndn_face_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_face_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// ─── Unified error type ───────────────────────────────────────────────────────
31
32#[derive(Debug, thiserror::Error)]
33pub enum ShmError {
34    #[error("I/O error: {0}")]
35    Io(#[from] std::io::Error),
36    #[error("SHM name contains an interior NUL byte")]
37    InvalidName,
38    #[error("SHM region has wrong magic number (stale or wrong name?)")]
39    InvalidMagic,
40    #[error("packet exceeds the SHM slot size")]
41    PacketTooLarge,
42    #[error("SHM face closed (peer died or cancelled)")]
43    Closed,
44}
45
46// ─── Type aliases ─────────────────────────────────────────────────────────────
47
48/// Engine-side SHM face — register with `ForwarderEngine::add_face`.
49#[cfg(all(unix, feature = "spsc-shm"))]
50pub type ShmFace = spsc::SpscFace;
51
52/// Application-side SHM handle.
53#[cfg(all(unix, feature = "spsc-shm"))]
54pub type ShmHandle = spsc::SpscHandle;
ndn_face_local/shm/mod.rs

ndn_face_local/shm/
mod.rs
