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 level_liveness::MAX_LEVELS;
pub use level_liveness::every_level_alive;
pub use level_liveness::level_count;
pub use level_liveness::level_last_spin_us;
pub use level_liveness::level_spins;
pub use level_liveness::set_level_count;
pub use level_liveness::take_every_level_alive;
pub use level_liveness::tier_level;
pub use level_liveness::tier_level_by;
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::TimerCallInfo;
pub use crate::timer::TimerClockSource;
pub use node_record::NodeBuilder;
pub use node_record::NodeId;
pub use node_record::NodeRecord;
pub use launch_remap::BadLaunchRemap;
pub use launch_remap::LaunchRemap;
pub use launch_remap::launch_remaps;
pub use launch_remap::set_launch_remaps;
pub use session_props::BadSessionProperties;
pub use session_props::MAX_SESSION_PROPERTIES;
pub use session_props::SessionProperty;
pub use session_props::lent_session_properties;
pub use session_props::session_properties;
pub use session_props::set_session_properties;
pub use session_props::with_session_properties;

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.
exec_lock: phase-509 P9b – the executor’s lock (RFC-0108 “As built in P9b”). phase-509 P9b item 1 (RFC-0108 “As built in P9b”) – the executor’s lock.
ffi: phase-515 R9 (decision D4) – the sealed trait the C/C++ shims import for the executor’s FFI entry points. nros does not re-export it. The executor’s FFI surface (phase-515 R9, decision D4).
launch_remap: Launch remap rules as ONE const table in flash – issue 1971, RFC-0107 step 1.
level_liveness: phase-509 P7 (RFC-0108 D8.1, D8.2) – which level an executor is, and whether every level of the image is alive.
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.
session_props: A bringup’s own RMW session configuration, baked into the image as ONE const table – RFC-0109 D8, phase-514 W3.

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).
Band: A contiguous range of dispatch levels, inclusive at both ends; level 0 is the most urgent.
BandWaiter: phase-509 P9b item 3 (RFC-0108 D7, “As built in P9b”) – a band worker’s wake object and the slots it answers for. The transport’s arrival path reads it without the executor’s lock, so it is 'static and its fields are atomics or fixed at construction; it is linked into the executor’s arrival routing by Executor::attach_band_worker and never unlinked.
BandWorker: phase-509 P9b item 2 (RFC-0108 “As built in P9b”) – a worker of one band over an executor it shares with other workers: the record its own thread owns and hands to Executor::spin_band_once.
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.
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.
RawRequestId: Issue 2081 — upstream rmw_request_id_t, as a C or C++ request-id service callback receives it (RawServiceRequestIdCallback).
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, which its self-registration calls) and the locator + domain id to open against it.
ShutdownCallbackHandle: Handle to a registered shutdown hook, returned by ExecutorFfi::add_pre_shutdown_callback / ExecutorFfi::add_on_shutdown_callback (the FFI trait in executor::ffi) 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.
RemapRefused: Why Executor::declare_remap refused a rule – never a silently dropped routing rule.
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).
ENTRY_IDLE_BUDGET: phase-521 W6 (RFC-0113 D2) — the longest park an entry asks for when every source of work can end it early: 60 s.
ENTRY_POLL_BUDGET: phase-521 W6 — the budget an entry keeps while some source of work cannot end its wait: 10 ms, the cadence every entry had before. See Executor::entry_spin_budget.
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.
INLINE_BACKING_U64S: Issue 1970 – the inline backing’s length in u64 words.
INLINE_SIZING: Issue 1970 – the sizing an inline backing is carved at: the image’s (ExecutorSizing::DEFAULT), or None on an image whose executors are sized per tier (crate::config::TIER_SIZINGS is non-empty). There the inline backing is EMPTY – one whole-image backing per tier context is the cost this issue removes – and an executor opened over a context alone (rclc_executor_init, nros_cpp_init) is refused, naming the per-tier road, rather than carved short.
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.
PARK_EXPIRED: ParkUntilFn: the deadline expired (NROS_PLATFORM_PARK_EXPIRED).
PARK_SIGNALLED: ParkUntilFn: woken by an event (NROS_PLATFORM_PARK_SIGNALLED).
PARK_YIELDED: ParkUntilFn: the slot handed the wait to its framework’s scheduler and returned without waiting (NROS_PLATFORM_PARK_YIELDED); spin_once returns without dispatching. See ParkUntilFn.
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)].
levels_backing_bytes: phase-509 P9b item 4 – the backing bytes levels_executor_sizing carves, 0 on an image that sizes no tier. What nros::sizes::LEVELS_BACKING_SIZE publishes to the C/C++ header.
levels_executor_sizing: phase-509 P9b item 4 (RFC-0108 “As built in P9b”) – the sizing of the ONE executor a level runner opens per core: every level’s callbacks, nodes, arena and declared parameters, summed over the image’s tiers (each row of the tier table is one level). None when the image sizes no tier.
tier_backing_bytes: Issue 1970 – the backing bytes the index-th tier’s executor carves, 0 past the last tier. What nros::sizes::TIER_BACKING_SIZE_<i> publishes to the C/C++ header.
tier_executor_sizing: Issue 1970 – the ExecutorSizing one tier’s executor is carved at: its own callback slots, node slots, arena and declared parameters, and the image’s scheduling-context count. A tier that declares parameters on an image that carves no store carves none either (the store is built from the heap there, as it is for the image’s one executor).
tier_sizing: Issue 1970 – the sizing of the tier named name, None when the image sizes no tier of that name.

Type Aliases§

BandWaitFn: phase-509 P9b item 3 – how a band worker waits on its own wake object: at most us microseconds, returning early when the object is signalled (WorkerWakeFn). The answer is ignored: either way the worker re-scans.
DeferNotify: Issue 2146 (RFC-0112 D2, Defer) – the notifier Executor::set_defer_notifier installs: called with the host’s context and the HandleId of a deferred callback that has just been queued.
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.
RawCancelResponseCallback: Raw action client cancel-response callback — issue 2030.
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.
RawResponseRequestIdCallback: Issue 2136 — RawResponseCallback that also receives the id of the request the reply answers, as rclc’s rclc_client_callback_with_request_id_t does.
RawResultCallback: Raw action client result callback.
RawServiceCallback: Raw service callback that receives and produces CDR bytes.
RawServiceRequestIdCallback: Issue 2081 — RawServiceCallback that also receives the request’s RawRequestId — rclc’s rclc_service_callback_with_request_id_t argument order (request, request id, response), in 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.
WakeHookFn: Issue 2225 (RFC-0113 D9) – the wake half of a framework’s park slot: called after every signal of the executor’s wake object, from the signalling context. A framework whose tier is a scheduled item rather than a parked thread (a PX4 work item) re-schedules the tier here. Must be thread-safe, non-blocking and O(1).
WorkerWakeFn: How a scheduler signals a worker’s wake object (NodeWake on a real port; a mock kernel in the tests).

Module executor

Module executor Copy item path

§Example

Re-exports§

Modules§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Module executor