RTOS Cooperation

nano-ros runs on platforms that span pure cooperative bare-metal through multi-task preemptive RTOS to fully async / Future-driven runtimes. The executor’s spin loop has to cooperate with each of these without imposing a single execution model on all of them.

This page maps the common RTOS / runtime execution profiles to the configuration knobs the executor exposes. New apps pick a profile that matches their target’s scheduling discipline; the knobs translate that choice into bounded behaviour from drive_io.

The execution model spectrum

How drive_io behaves by default

The executor’s spin_once(timeout_ms) calls session.drive_io(...) and lets it drain all ready I/O before returning. After drive_io returns, the executor processes any expired timers and triggered guard conditions. If 10 messages arrived during the wait, all 10 callbacks fire in a single spin_once, then timer / GC dispatch happens once afterwards.

This is the right default for cooperative single-task apps and for async-runtime apps using spin_async. Both want throughput; neither benefits from per-callback scheduling opportunities.

For the other three models, the default has trade-offs the configuration knobs address.

Configuration knobs

The knobs live on SpinOptions (passed to Executor::spin_blocking(opts)), not on ExecutorConfig — the config struct carries identity/transport (locator, domain, node name, clock), while scheduling shape is a property of each spin call:

Backends opt into one additional behaviour automatically: Session::next_deadline_ms() tells the executor about the backend’s next internal event (lease keepalive, heartbeat). The executor caps drive_io’s timeout against it. No app configuration; transparent optimization.

Per-model recommended configuration

Cooperative single-task

#![allow(unused)]
fn main() {
// One dedicated task; drain everything each round.
executor.spin_blocking(SpinOptions::default())?;
}

Drain everything; one task, no fairness concern.

Preemptive priority RTOS — recommended

#![allow(unused)]
fn main() {
loop {
    executor.spin_blocking(SpinOptions::new().max_callbacks(1))?;
}
}

max_callbacks(1) matches upstream’s rclcpp single-threaded executor pattern. Each spin_once fires one callback and then re-checks timers + GCs. ROS-internal entities share the task priority, but the spin-loop iteration is the scheduling unit; timer expiries are bounded by one callback’s WCET, not the sum across all ready callbacks.

If max-callback dispatch latency is still too high in this profile (e.g., a single callback is slow), the remaining bound is that one callback’s WCET — split the slow callback, or move it to its own tier/task (see Scheduling Models).

WCET-bounded real-time (RTIC / Embassy)

Don’t use the spin loop. Use the async path — a buffered subscription handle whose recv() is an async fn with waker integration:

#![allow(unused)]
fn main() {
let mut sub = node.create_subscription::<MyMsg>("/topic")?;
loop {
    let msg = sub.recv().await?;        // suspends; waker integration
    handle(msg);
}
}

The async path doesn’t go through drive_io at all. Subscriptions register a Waker; the backend’s RX path wakes the waker; the async runtime schedules the receiving task. Per-task WCET analysis applies to each recv().await continuation, not to a spin loop.

Time-triggered cyclic

#![allow(unused)]
fn main() {
// Called once per cycle from the cyclic frame:
executor.spin_blocking(SpinOptions::new().timeout_ms(5))?;   // 5 ms ROS slot
}

The cycle gives ROS a fixed wall-clock slot; the timeout_ms bound returns control when the slot expires regardless of pending work. Pending work resumes next cycle. (There is no finer-grained per-callback budget knob today — if a single callback can overrun the slot, that callback’s WCET is your design constraint.)

Async runtime

drive_io not used in the hot path. The executor’s spin_async drives futures via wakers; drive_io becomes a polling tick internally with negligible overhead.

#![allow(unused)]
fn main() {
executor.spin_async().await
}

No knobs apply.

Trade-offs at a glance

Backends and their wait primitives

drive_io’s sleep behaviour is backend- and platform-dependent. The spin loop’s “where does the thread sleep” question maps as:

In all cases the user-visible API is Executor::spin_once(timeout); the platform-correct sleep happens transparently underneath.

See also

• RMW API Design — the architectural reasons the runtime / RMW boundary is shaped the way it is.
• RMW API: Differences from upstream rmw.h Section 4 — the drive_io vs rmw_wait comparison this page expands on.
• no_std Support — heap and threading constraints that shape the cooperative model.