nros_rmw/
lib.rs

1//! RMW (ROS Middleware) abstraction layer for nros.
2//!
3//! This crate provides the middleware-agnostic transport traits that
4//! backend crates (`nros-rmw-zenoh`, `nros-rmw-xrce`) implement.
5//! Application code depends on these traits, not on a concrete backend,
6//! so the transport can be swapped at compile time via Cargo features.
7//!
8//! # Trait hierarchy
9//!
10//! ```text
11//! Rmw              — top-level factory, creates Sessions
12//! └─ Session       — connection lifecycle, creates handles
13//!    ├─ Publisher   — publish serialised messages
14//!    ├─ Subscription  — receive messages (polling or callback)
15//!    ├─ ServiceServer — request/reply (server side)
16//!    └─ ServiceClient — request/reply (client side)
17//! ```
18//!
19//! See [`traits`] for the full trait definitions.
20//!
21//! # Features
22//!
23//! - `alloc` — Enable heap allocation
24//!
25//! # Synchronization Backends
26//!
27//! - `sync-spin` — Use `spin::Mutex` (default, works everywhere)
28//! - `sync-critical-section` — Use critical sections (RTIC/Embassy compatible)
29
30#![no_std]
31
32// phase-359 W10 — no `std` feature; the test harness is hosted.
33#[cfg(test)]
34extern crate std;
35
36#[cfg(feature = "alloc")]
37extern crate alloc;
38
39pub mod correlation;
40pub mod custom_transport;
41pub mod event;
42// issue 1551 — the one spelling of a fallible `Box::new` (`Box::try_new` is
43// unstable) for entity-creation paths that have an error return.
44#[cfg(feature = "alloc")]
45pub mod fallible;
46pub mod service_inbox;
47pub mod sync;
48pub mod traits;
49pub mod type_descriptor;
50
51#[cfg(feature = "safety-e2e")]
52pub mod safety;
53
54// Phase 108 — status-event surface.
55pub use event::{
56    CountStatus, DeadlineMissedStatus, EventCallback, EventKind, EventPayload,
57    IncompatibleTypeCounter, IncompatibleTypeStatus, LivelinessChangedStatus, MatchedCounter,
58    MatchedStatus, MessageLostStatus, payload_from_raw,
59};
60
61// Issue 2009 — the one request/reply correlation rule every client surface
62// applies to the ids `ClientTrait` carries.
63pub use correlation::{
64    MAX_STALE_DRAIN_PER_POLL, ReplyMatcher, RequestCorrelator, SEQUENCE_ID_UNKNOWN, SendRefusal,
65    take_correlated, take_matched,
66};
67
68// Phase 115.A — runtime-pluggable custom transport vtable.
69pub use custom_transport::{
70    NROS_TRANSPORT_OPS_ABI_VERSION_V1, NrosTransportOps, peek_custom_transport,
71    set_custom_transport, take_custom_transport,
72};
73
74// phase-461 W2 -- the caller-owned service inbox seam.
75pub use service_inbox::{CallerInbox, CallerInboxStorage, InboxEntry, ServiceInboxSpec};
76
77// Phase 248 (C2) — generic per-type descriptor registration seam.
78pub use type_descriptor::{
79    TypeDescriptorRegistrar, has_type_descriptor_registrar, register_type_descriptor,
80    set_type_descriptor_registrar,
81};
82
83// Re-export safety types when feature is enabled
84#[cfg(feature = "safety-e2e")]
85pub use safety::{IntegrityStatus, SafetyValidator, crc32};
86
87// Re-export main types
88pub use traits::{
89    ActionEndpointHashes, ActionInfo, BestAvailablePeers, BestAvailableRole, ClientTrait,
90    DEPTH_SYSTEM_DEFAULT, DURATION_BEST_AVAILABLE_MS, DURATION_INFINITE_MS, GraphEndpointInfo,
91    GraphEntityKind, LocatorProtocol, Publisher, QoSDurabilityPolicy, QoSHistoryPolicy,
92    QoSLivelinessPolicy, QoSOverride, QoSOverrideCode, QoSOverrideRole, QoSOverrideValue,
93    QoSPolicyMask, QoSProfile, QoSReliabilityPolicy, QoSSystemDefaults, ReadinessSource,
94    RefusedLen, Rmw, RmwConfig, ServiceInfo, ServiceRequest, ServiceTrait, Session, SessionMode,
95    Subscription, TopicInfo, Transport, TransportConfig, TransportError, decode_qos_override,
96    decode_qos_override_parts, decode_qos_override_role, decode_qos_override_value,
97    duration_to_qos_ms, locator_protocol, qos_override_policy, qos_override_role,
98    resolve_best_available_on, validate_locator,
99};
100
101// Re-export `MessageInfo` from nros-core so backends implementing
102// `Subscription::take_serialized_with_info` don't need their own direct
103// nros-core dep.
104pub use nros_core::MessageInfo;
105// Issue 1495 — and the `Time` its setters take, so a seam that BUILDS a
106// `MessageInfo` from a C backend's `rmw_message_info_t` (nros-rmw-cffi's
107// `take_with_info` dispatch) can name it without a direct nros-core dep.
108pub use nros_core::Time;
109// Issue 1942 — and the per-request metadata [`ServiceTrait::request_info`]
110// returns, for the same reason. Re-exported as `ServiceRequestInfo`, NOT under
111// its own name: this crate's `ServiceInfo` is the service DESCRIPTOR a
112// `create_service` call takes, and two unrelated types under one name is how
113// issue 1942 stayed hidden (the facade re-exported the descriptor as rclrs's
114// `ServiceInfo` until phase-506 W1).
115pub use nros_core::{REQUEST_WRITER_GUID_SIZE, RequestId, ServiceInfo as ServiceRequestInfo};
116
117// Same reason, one method over: [`Publisher::get_gid`]'s return type is
118// `[u8; PUBLISHER_GID_SIZE]`, so a backend implementing it — or a caller
119// sizing a buffer for it — would otherwise need a direct nros-core dep to
120// name the width of a signature this crate declares. `pad_publisher_gid`
121// rides along because a backend whose identity is narrower than 24 bytes
122// must zero-extend through it rather than inventing its own padding (the
123// phase-467 RMW gap-closure design study's Q1).
124pub use nros_core::{PUBLISHER_GID_SIZE, pad_publisher_gid};
125
126// Phase 99 — zero-copy raw API: SlotLending / SlotBorrowing traits.
127// Backends opt in by impl'ing these (and forwarding their own `lending`
128// feature to `nros-rmw/lending`).
129#[cfg(feature = "lending")]
130pub use traits::{SlotBorrowing, SlotLending};
nros_rmw/lib.rs

nros_rmw/
lib.rs
