Module executor

Expand description

Embedded executor with build-time configured arena.

Provides Executor and Node that work with the compile-time selected RMW backend (zenoh, XRCE-DDS, or C FFI).

§Example

use nros_node::executor::*;
use std_msgs::msg::Int32;

let config = ExecutorConfig::from_env().node_name("my_node");
let mut executor = Executor::open(&config)?;
let mut node = executor.create_node("my_node")?;

let publisher = node.create_publisher::<Int32>("/chatter")?;
publisher.publish(&Int32 { data: 42 })?;

loop {
    executor.spin_once(core::time::Duration::from_millis(10));
}

Re-exports§

pub use action::ActionClientRawHandle;
pub use action::ActionServerHandle;
pub use action::ActionServerRawHandle;
pub use action::RawActionClientSpec;
pub use action::RawActionServerSpec;
pub use action_core::ActionClientCore;
pub use action_core::ActionServerCore;
pub use action_core::RawActiveGoal;
pub use action_core::action_channel_type;
pub use crate::timer::TimerClockSource;
pub use node_record::NodeBuilder;
pub use node_record::NodeId;
pub use node_record::NodeRecord;

Modules§

action: Action server and client registration on the executor and handle types.
action_core: Type-agnostic action protocol core types.
arena_oracle: phase-412 #4 — the arena’s HOST ORACLE, held to at compile time.
declared_shape: phase-457 W5 (issue 1522) — which registration entry point a DECLARED subscription reaches, as ONE value.
monitor: RFC-0052 / phase-296 W3b.4/.5 — on-target contract monitors.
node_record: Phase 104.C.2 — multi-Node-per-Executor storage.
port_park: phase-436 W7 — installing a port’s park primitive, with the wake-object constraint stated once instead of per board. phase-436 W7 — installing a port’s park primitive, in one place.
sched_context: Phase 110.B — SchedContext API + supporting types.

Structs§

ActionClient: Typed action client handle.
ActionClientCallback: Send handle for a callback-based typed action client.
ActionServer: Typed action server with goal state management.
ActiveGoal: Active goal tracking for action server.
BakedBootConfig: Build-time-baked boot config, emitted (in W4b) into the .nros_boot_config linker section by the entry macro / cmake. Fixed-size + pointer-free so a future post-link tool can patch it in place (RFC-0045). The resolver reads it on embedded via BootConfig::from_baked (in nros-node).
BootConfig: Session-identity subset a caller supplies to ExecutorConfig::resolve.
CallbackGroup: A first-class callback group — a name-only token (rclcpp/rclrs shape).
CompletedGoal: Completed goal with result.
EmbeddedPublisher: Typed publisher handle.
EmbeddedRawPublisher: Typeless publisher handle. Use when the wire format is not ROS CDR (e.g. PX4 uORB raw POD bytes, custom binary protocols).
EmbeddedServiceClient: Typed service client handle with internal buffers.
EmbeddedServiceServer: Typed service server handle with internal buffers.
EnvRung: The environment rung of precedence model A, as VALUES.
Executor
ExecutorConfig: Configuration for opening an embedded executor session.
ExecutorInlineStorage: The exact #[repr(C)] byte layout the C/C++ FFI’s inline executor buffer must hold: an Executor<'static> header immediately followed by a default-sized (ExecutorSizing::DEFAULT) storage backing.
ExecutorSizing: Per-entry executor sizing — the entity counts an Executor is built to hold. Public + non-generic (the “C/C++ is a thin wrapper” principle): the entry / macro / FFI supplies these as plain usizes rather than as type/const generics C can’t name. Used to size + carve the backing.
FeedbackStream: A stream of feedback messages from an action server.
GoalFeedbackStream: A goal-filtered feedback stream.
GuardCondition: Handle for triggering a guard condition from outside the executor.
HandleId: Opaque handle identifier returned by registration methods.
HandleSet: A set of handle IDs, represented as a bitset.
LoanFuture: Future returned by EmbeddedRawPublisher::loan. Phase 99.H’ cancellation-safe variant: if dropped before resolving, it wakes the next pending waiter so the busy-flag-clear signal isn’t lost to the cancelled task.
Node: A ROS 2 node — rclrs’s Node, and the ONE node type (phase-483 W2).
NodeHandle: Backend-agnostic node — borrows the session to create typed entities.
Promise: A pending reply from a non-blocking service or action call.
PublishLoan: Writable loan into a EmbeddedRawPublisher’s slot.
RawServiceClient: Typeless service-client handle. L1 counterpart of EmbeddedServiceClient for the same audience as RawServiceServer.
RawServiceServer: Typeless service-server handle. L1 counterpart of EmbeddedServiceServer for callers that own their own scheduler (RTIC, embassy, FreeRTOS-task-per-entity) and the C / C++ FFI shims.
RawSubscription: Typeless subscription handle. Counterpart of EmbeddedRawPublisher.
ReadinessSnapshot: Snapshot of handle readiness at the start of a spin iteration.
RecvView: Read-only view into a RawSubscription’s receive buffer.
RegionUnit: The placement arithmetic and its data types live in nros-executor-layout (issue 1197) so a HOST build script can evaluate them for a target it is not compiling. Re-exported here because this is where every consumer already looks, and because NATIVE — the only part that names the types — has to live in the crate that owns them. Size and alignment of one region’s element type.
RegionUnits: The placement arithmetic and its data types live in nros-executor-layout (issue 1197) so a HOST build script can evaluate them for a target it is not compiling. Re-exported here because this is where every consumer already looks, and because NATIVE — the only part that names the types — has to live in the crate that owns them. Every element type the backing carves a table of, in declaration order.
ServiceClientCallback: Send handle for a callback-based typed service client.
SessionHandle: Phase 228.E — an opaque, Send handle to an Executor’s RMW session.
SessionSpec: Phase 128.F.1 — per-backend session declaration for Executor::open_multi. Each spec names an RMW backend (must match one a backend registered under via nros_rmw_cffi_register_named / the RMW_INIT_ENTRIES linker section) and the locator + domain id to open against it.
ShutdownCallbackHandle: Handle to a registered shutdown hook, returned by Executor::add_pre_shutdown_callback / Executor::add_on_shutdown_callback and consumed by the matching remove_*. rclcpp’s PreShutdownCallbackHandle / OnShutdownCallbackHandle.
SpinOnceResult: Result of a single spin iteration
SpinOptions: Options controlling a blocking spin loop — rclrs’s SpinOptions.
SpinPeriodPollingResult: Result from a single period of polling execution (no_std compatible).
SpinPeriodResult: Result from a single period with monotonic-clock measurement.
Subscription: Typed subscription handle with internal receive buffer.
TierBackingShort: issue 1571 — the tier backing a board was handed does not cover the tiers it must spawn. Carries both counts so the refusal names them.
TierExecutorBacking: issue 1571 — the spawned tiers’ executor backing, N slots in ONE named static that the ENTRY owns.
TierSetupGate: Issue 1733 — the ONE gate a tier runner holds across each tier’s open-and-setup so no two tiers declare entities on the shared session at once.
TierSetupGuard: Issue 1733 — proof of holding a TierSetupGate; dropping it opens the gate.
TierTaskMemory: issue 1598 — one spawned tier’s stack and control block, as ONE named static the entry owns. STACK_U64S is the tier’s stack in 8-byte words; TCB_U64S the control-block region, TIER_TASK_TCB_U64S by default and 0 for a kernel whose control block the port keeps itself (Zephyr’s struct k_thread, issue 1232 — a Rust entry cannot size it).
TierTaskMemoryRaw: issue 1598 — one spawned tier’s task memory as a board receives it: raw, Copy, no lifetime. The ENTRY owns the bytes (TierTaskMemory); the handout is once-only (TierTaskMemorySet::take), which is what makes the raw pointers exclusive.
TierTaskMemorySet: issue 1598 — the spawned tiers’ task memory, N rows in spawn (chain) order, behind a once-only latch.

Enums§

BindError: RFC-0045 / issue #206 — boot-config resolution error. Malformed or out-of-range identity input (env or baked) is an ERROR, never a silent fallback: a typo’d ROS_DOMAIN_ID must not invisibly move a node to domain 0 (the pre-#206 C++ behavior) or be silently ignored (the pre-#206 behavior of this resolver). Why a filter or sched binding could not be recorded.
BootConfigError
ExecutorSemantics: Data communication semantics for the executor.
InvocationMode: Per-callback invocation mode.
LoanError: Error type for EmbeddedRawPublisher::try_loan.
NodeError: Error type for generic embedded node operations.
ServerVisibility: Issue 1686 — what a server-readiness probe answered, read the way a WAIT loop must read it.
ShutdownPhase: Which of the two ordered shutdown phases a hook belongs to.
TimerOverrunPolicy: What a periodic timer does with periods it missed while its executor was blocked (issue #505).
Trigger: Executor-level trigger condition.
WakeSourceId: phase-436 — which deadline source bounded the last park.

Constants§

BOOT_SET_DOMAIN: Bit 2 — domain_id field is set.
BOOT_SET_LOCATOR: Bit 1 — locator field is set.
BOOT_SET_NAMESPACE: Bit 3 — namespace field is set.
BOOT_SET_NODE_NAME: Bit 0 — node_name field is set.
BOOT_SET_RMW: Bit 4 — rmw field is set (issue 1050 defect (3); layout version 2).
DEFAULT_LOAN_BUF: Default size of each per-publisher arena slot, in bytes.
DEFAULT_SPIN_POLL_INTERVAL: Default per-iteration budget handed to spin_once by the spin loops.
DOMAIN_ID_EXPLICIT_ZERO_C_ABI: Issue #227 — C/C++-ABI escape for an EXPLICIT domain 0.
DOMAIN_ID_MAX: RFC-0045 / issue #206 — maximum valid ROS 2 domain ID. The ROS 2 / DDS convention (RTPS port arithmetic) caps usable domains at 232; values above it are a configuration error in EVERY language front-end (never a silent clamp or silent 0). Mirrored into the generated C header — keep the mirror in sync (the #160 drift class).
EXECUTOR_BACKING_DEFAULT_U64S: The reservation’s size when nothing overrides it: one default-sized executor’s worth.
HANDLE_SLOT_BITS: Bits of a packed HandleId that hold the slot index.
MAX_WAKE_SOURCES: How many platform sources one executor can carry. A plain const, not a sizing knob: the table is inline, so no allocator is required on the no_std targets this seam mainly exists for.
NROS_BOOT_CONFIG_MAGIC: 0x4E524243 = ASCII “NRBC”. A post-link tool scans for this magic to locate the struct in a firmware image.
NROS_BOOT_CONFIG_VERSION: Layout version — lets the resolver reject a mismatched baked struct.
RMW_SELECTOR_CAP: Capacity of a backend selector name, matching Executor::primary_rmw_name.
TIER_TASK_TCB_U64S: issue 1598 — the control-block region every TierTaskMemory carries, in 8-byte words. An UPPER BOUND over the kernels that take it (a FreeRTOS StaticTask_t on Cortex-M is about a hundred bytes); the port REFUSES a region smaller than its own control block at spawn, by name, so a kernel whose block outgrows this fails loudly rather than overrunning the stack that follows. Rust cannot name a C type’s size at macro time, which is why this one number is a bound and the stack beside it is exact.

Functions§

baked_domain_from_c_abi: Map the C/C++ ABI’s u8 domain argument onto the resolver’s baked rung.
check_tier_executor_backing: issue 1571 — the ONE refusal every board’s run_tiers makes before it opens anything: n_tiers tiers run, one on the boot executor, so n_tiers - 1 must each find a slot. Checked up front rather than at each spawn, so a short block never leaves a half-spawned tier chain.
default_epoch_us: RFC-0052 W3b.2 — the default wall-clock source: µs since the UNIX epoch.
default_epoch_us_fn: The default wall clock, or None when this build has neither a platform port nor a host to ask.
epoch_us_to_stamp: RFC-0052 W3b.3 — split epoch-µs into the builtin_interfaces/Time field pair (sec, nanosec) for header.stamp population. Types-free (each workspace has its own generated Time); assign the tuple to the struct’s fields.
executor_storage_layout: Byte Layout of the backing a sizing-sized executor needs. Public + non-generic so the macro / FFI can size a raw backing.
executor_storage_layout_with: Byte Layout of the backing, evaluated against a SUPPLIED unit table.
executor_storage_u64_len: Number of u64 words a backing must hold for a sizing-sized executor. u64 backing is 8-aligned, which covers every field (all align_of ≤ 8; asserted in tests), so the entry never hand-aligns. The macro emits [MaybeUninit<u64>; executor_storage_u64_len(sizing)].

Type Aliases§

NextDeadlineFn: When this source will next need the executor, in the executor’s clock, as microseconds FROM NOW.
ParkUntilFn: Park until deadline_us from now, or until something signals, whichever comes first.
RawAcceptedCallback: Raw accepted-goal hook.
RawCancelCallback: Raw action cancel callback.
RawFeedbackCallback: Raw action client feedback callback.
RawGoalCallback: Raw action goal callback that receives CDR bytes without deserialization.
RawGoalResponseCallback: Raw action client goal-response callback.
RawMessageDeserializeFn: phase-417 W5.a — the deserialiser half of the TYPED C subscription path.
RawResponseCallback: Raw service-client response callback.
RawResultCallback: Raw action client result callback.
RawServiceCallback: Raw service callback that receives and produces CDR bytes.
RawSubscriptionCallback: Raw subscription callback that receives CDR bytes without deserialization.
RawSubscriptionInfoCallback: Raw subscription callback that also receives the incoming sample’s wire-level attachment (Phase 189.M3.4 — the C analog of the Rust FnMut(&[u8], &RawMessageInfo) builder path). attachment is valid for attachment_len bytes during the call; attachment_len == 0 means the sample carried no attachment. Cross-RMW bridges read the bridge_origin tag from it.
ShutdownCallbackFn: A shutdown hook: extern "C" so the same slot serves Rust, C and C++ without a second registry, and so no allocator is involved.
TierExecutorBackingSlot: issue 1571 — one spawned tier executor’s backing: exactly the words an executor opened with ExecutorSizing::DEFAULT carves.
TypedSubscriptionCallback: phase-417 W5.a — a subscription callback that receives the DESERIALISED message rather than its CDR bytes.

Module executor

Module executor Copy item path

§Example

Re-exports§

Modules§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Module executor