Module executor 

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 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.

handoff

Phase 104.E.3 — cross-priority handoff queue.

monitor

RFC-0052 / phase-296 W3b.4/.5 — on-target contract monitors.

node_record

Phase 104.C.2 — multi-Node-per-Executor storage.

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.

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.

GuardConditionHandle

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.

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.

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.

SpinOnceResult

Result of a single spin iteration

SpinOptions

Options controlling blocking spin behavior.

SpinPeriodPollingResult

Result from a single period of polling execution (no_std compatible).

SpinPeriodResult

Result from a single period with wall-clock measurement (std only).

Subscription

Typed subscription handle with internal receive buffer.

Enums

BootConfigError

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).

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.

Trigger

Executor-level trigger condition.

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.

DEFAULT_LOAN_BUF

Default size of each per-publisher arena slot, in bytes.

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).

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.

Functions

baked_domain_from_c_abi

Map the C/C++ ABI’s u8 domain argument onto the resolver’s baked rung.

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 needed for a (cbs, sc, arena)-sized executor. Public + non-generic so the macro / FFI can size a raw backing.

executor_storage_u64_len

Number of u64 words a backing must hold for a (cbs, sc, arena)-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(N, SC, A)].

std_epoch_us

RFC-0052 W3b.2 — hosted wall-clock source: µs since the UNIX epoch.

Type Aliases

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.

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.