nros_node/

timer.rs

//! Timer API for nros
//!
//! This module provides timer support matching rclrs patterns while maintaining
//! `no_std` compatibility for embedded systems.
//!
//! # Overview
//!
//! Timers allow scheduling periodic or one-shot callbacks. In embedded environments
//! without background threads, timers must be processed manually via `process_timers()`.
//!
//! # Timer Modes
//!
//! - **Repeating**: Fires at regular intervals until canceled
//! - **OneShot**: Fires once after a delay, then becomes inert
//! - **Inert**: Never fires, useful as a placeholder
//!
//! # Example (with std)
//!
//! ```ignore
//! use nros::prelude::*;
//! use nros::timer::Duration;
//!
//! let mut node = ConnectedNode::connect(config, locator)?;
//!
//! // Create a repeating timer
//! let timer = node.create_timer_repeating(
//!     Duration::from_millis(100),
//!     || println!("Timer fired!"),
//! )?;
//!
//! // Process timers periodically
//! loop {
//!     node.process_timers(10); // 10ms elapsed
//!     std::thread::sleep(core::time::Duration::from_millis(10));
//! }
//! ```
//!
//! # Example (RTIC)
//!
//! ```ignore
//! // In RTIC, use a periodic task to process timers
//! #[task(priority = 2, shared = [node])]
//! async fn timer_process(mut cx: timer_process::Context) {
//!     loop {
//!         cx.shared.node.lock(|node| {
//!             node.process_timers(TIMER_PROCESS_INTERVAL_MS as u64);
//!         });
//!         Systick::delay(TIMER_PROCESS_INTERVAL_MS.millis()).await;
//!     }
//! }
//! ```

use core::marker::PhantomData;

/// Duration type for timer periods
///
/// This is a simple millisecond-based duration for `no_std` compatibility.
/// It can be converted to/from the ROS Duration type.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct TimerDuration {
    /// Duration in microseconds.
    ///
    /// Issue #505: this was milliseconds, so `from_micros` silently
    /// truncated — `from_micros(500)` produced a ZERO period (which the
    /// dispatcher treats as "every spin") and `from_micros(1_500)` a
    /// 1 ms one, a 50% rate error with no diagnostic. The executor's
    /// timer accounting is microsecond-based, so store microseconds and
    /// keep the millisecond constructors/accessors as exact wrappers.
    micros: u64,
}

impl TimerDuration {
    /// Create a new duration from milliseconds
    pub const fn from_millis(millis: u64) -> Self {
        Self {
            micros: millis.saturating_mul(1000),
        }
    }

    /// Create a new duration from seconds
    pub const fn from_secs(secs: u64) -> Self {
        Self {
            micros: secs.saturating_mul(1_000_000),
        }
    }

    /// Create a new duration from microseconds
    pub const fn from_micros(micros: u64) -> Self {
        Self { micros }
    }

    /// Create a zero duration
    pub const fn zero() -> Self {
        Self { micros: 0 }
    }

    /// Get duration as milliseconds (truncated; prefer
    /// [`Self::as_micros`] for sub-millisecond periods)
    pub const fn as_millis(&self) -> u64 {
        self.micros / 1000
    }

    /// Get duration as microseconds
    pub const fn as_micros(&self) -> u64 {
        self.micros
    }

    /// Get duration as seconds (truncated)
    pub const fn as_secs(&self) -> u64 {
        self.micros / 1_000_000
    }

    /// Check if duration is zero
    pub const fn is_zero(&self) -> bool {
        self.micros == 0
    }

    /// Saturating subtraction
    pub const fn saturating_sub(self, rhs: Self) -> Self {
        Self {
            micros: self.micros.saturating_sub(rhs.micros),
        }
    }
}

impl From<nros_core::Duration> for TimerDuration {
    fn from(d: nros_core::Duration) -> Self {
        let micros = (d.sec as i64 * 1_000_000 + d.nanosec as i64 / 1_000) as u64;
        Self { micros }
    }
}

impl From<TimerDuration> for nros_core::Duration {
    fn from(d: TimerDuration) -> Self {
        let sec = (d.micros / 1_000_000) as i32;
        let nanosec = ((d.micros % 1_000_000) * 1_000) as u32;
        nros_core::Duration { sec, nanosec }
    }
}

// phase-430 W4 — this enum lives HERE, in the ungated `timer` module, rather
// than in `executor::arena` where phase-425 W4 first wrote it. `mod arena` is
// `#[cfg(any(has_rmw, test))]`, so the type could not be named by the
// DECLARATIVE layer (`nros::node_metadata::EntityMetadata`, which a
// metadata-mode build compiles with no transport) — and a metadata field that
// cannot name the enum is how a second spelling of it gets invented one layer
// up, which is the 0135/0160 drift. One enum, one spelling, reachable from
// both halves; `executor` re-exports it so every existing path still resolves.
/// Which clock advances a timer (phase-425 W4, RFC-0075-adjacent: this is the
/// distinction rclcpp draws between `create_wall_timer` and `create_timer`).
///
/// The default is [`Steady`](Self::Steady) and it is the only source that costs
/// nothing: it consumes the spin delta the executor already measured. The other
/// two READ a clock on every poll of the timer, which is one relaxed atomic load
/// plus whatever the platform's time call costs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[repr(u8)]
pub enum TimerClockSource {
    /// The executor's monotonic spin delta — a WALL timer in rclcpp's sense.
    /// Unaffected by `/clock`: a paused simulator does not pause it, which is
    /// exactly what a watchdog or a transport keep-alive wants.
    #[default]
    Steady = 0,
    /// `ClockType::RosTime`: simulated time when a `/clock` source is active,
    /// and system time when none is (the same fallback `rclcpp::Clock` has, so
    /// a node built for simulation still runs standalone).
    Ros = 1,
    /// `ClockType::SystemTime`: the wall clock, NTP steps and all. Present
    /// because rclrs offers it (`TimerClock::SystemTime`); a timer that must
    /// not jump wants `Steady`.
    System = 2,
}

// The helpers are the EXECUTOR's half: only `timer_try_process` and the timer
// registrar read a clock, and both live behind `mod arena` / `mod spin`, which
// are `#[cfg(any(has_rmw, test))]`. The TYPE stays ungated — the declarative
// metadata layer names it with no transport linked — so without a backend these
// two would be dead code under `-D warnings`.
#[cfg(any(has_rmw, test))]
impl TimerClockSource {
    /// The `nros_core` clock this source reads, or `None` for [`Steady`](Self::Steady),
    /// which reads no clock at all.
    pub(crate) fn clock(self) -> Option<nros_core::clock::Clock> {
        match self {
            TimerClockSource::Steady => None,
            TimerClockSource::Ros => Some(nros_core::clock::Clock::ros_time()),
            TimerClockSource::System => Some(nros_core::clock::Clock::system()),
        }
    }

    /// The clock's current reading in nanoseconds, or 0 for [`Steady`](Self::Steady).
    pub(crate) fn now_ns(self) -> i64 {
        self.clock().map(|c| c.now().to_nanos()).unwrap_or(0)
    }

    /// Whether the time left on a timer with this source is a quantity of WALL
    /// microseconds — issue 1321.
    ///
    /// The executor asks this in two places, and both are asking the same
    /// thing: `period_us - elapsed_us` is offered to
    /// `next_wake_bound_attributed_us` as a park bound, and `period_us` is
    /// compared against the declared spin period by
    /// `audit_spin_quantization`. Both quantities on the other side of those
    /// comparisons are wall microseconds — what the port's park primitive
    /// waits and what the tier loop paces — so a timer whose `elapsed_us`
    /// advances on some OTHER clock must take part in neither.
    ///
    /// * [`Steady`](Self::Steady) — **yes.** It consumes the executor's own
    ///   spin delta, which is wall time by construction. This is phase-436 W1
    ///   / issue 1192, and it is unchanged.
    /// * [`System`](Self::System) — **yes**, and it is decided separately
    ///   rather than by "not `Steady`". Its clock IS wall time (the port's
    ///   `nros_platform_time_now_ns`), so there is no rate indirection and
    ///   nothing can hold it still. It can STEP — NTP, `settimeofday` — and a
    ///   step makes the bound an estimate rather than a fact, but a bounded
    ///   one in both directions: the bound only ever shortens a park (it is
    ///   one member of a `min` whose first member is the caller's budget) and
    ///   `timer_try_process` re-reads the clock before dispatching, so a step
    ///   costs at worst one extra wake and can never fire a callback early.
    /// * [`Ros`](Self::Ros) — **no.** Its `elapsed_us` advances by the
    ///   `/clock` step, so the remainder is SIMULATED microseconds, related to
    ///   wall time by the bag's replay rate — which the executor does not know
    ///   and by design cannot. On a paused `/clock` the remainder freezes and
    ///   the image would wake once per timer period forever. Contributing
    ///   nothing restores the pre-436 bound for these timers, which is the
    ///   caller's budget — never unbounded, because
    ///   `next_wake_bound_attributed_us` seeds the `min` with it — and that
    ///   bound IS property 1 of phase-430: a ROS-time timer's wake source is a
    ///   `/clock` MESSAGE, and a message wakes `drive_io` like any sample, so
    ///   the timer's own deadline tells the executor nothing it does not
    ///   already have.
    ///
    ///   The answer does not become "yes" when no `/clock` source is attached,
    ///   and issue 1334 changed WHY. When this rule was written, the fallback
    ///   was measured to read `nros_core`'s in-image steady counter — a value
    ///   nothing in the tree advances — so the remainder was a constant in
    ///   that state too and the rule was true twice over. 1334 fixed that
    ///   arm: `ClockType::RosTime` with no override now reads the wall clock,
    ///   exactly as its own doc, rclcpp and the C surface always said, so the
    ///   remainder there IS wall microseconds and the first reason is gone.
    ///   The decision stands on the two that remain, and both are about the
    ///   RULE rather than about one image's state:
    ///
    ///   * property 1 of phase-430 — a ROS-time timer's wake source is a
    ///     `/clock` MESSAGE. A rule that flipped with whether a publisher
    ///     happened to be running would make the park bound change under a
    ///     live image for a reason no declaration named, and it would flip at
    ///     the worst moment: the first `/clock` sample, the instant the
    ///     remainder stops being wall microseconds. Deciding it per-timer at
    ///     REGISTRATION is not available either — the source can attach later
    ///     (`use_sim_time` is settable at runtime, phase-430 W2).
    ///   * what it costs is LATENCY and nothing else, bounded by the caller.
    ///     A `Ros` timer standing alone is paced by `spin_once`'s own budget
    ///     instead of by its period, so a 10 ms timer under a 100 ms budget
    ///     fires late — the pre-436 behaviour of every timer in the tree, and
    ///     never unbounded, because `next_wake_bound_attributed_us` seeds its
    ///     `min` with that budget. An image that wants its standalone ROS
    ///     timer paced to the millisecond spins to the millisecond, which is
    ///     what `bins/sim-clock-listener` already does at 5 ms.
    pub(crate) fn remaining_is_wall_time(self) -> bool {
        match self {
            TimerClockSource::Steady | TimerClockSource::System => true,
            TimerClockSource::Ros => false,
        }
    }
}

/// Timer mode (repeating, one-shot, or inert)
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TimerMode {
    /// Timer fires repeatedly at the specified period
    Repeating,
    /// Timer fires once then becomes inert
    OneShot,
    /// Timer never fires (placeholder)
    Inert,
}

/// Timer callback as a bare function pointer (`no_std`, no heap required).
pub type TimerCallbackFn = fn();

/// Internal timer state
///
/// Stored in the node's timer collection.
///
/// ADOPT-BOUNDED against rclrs's `Timer` (`Arc<TimerState>`), which is created per
/// use and dropped when done. Here a timer is an entry in the executor's STATIC
/// table: declared once (in `register`) and re-armed in place with
/// [`set_repeating`](Self::set_repeating) / [`set_oneshot`](Self::set_oneshot) /
/// [`set_inert`](Self::set_inert), because a static table cannot grow a timer at
/// runtime. The mode vocabulary is rclrs's; the lifetime is not.
pub struct TimerState {
    /// Timer period in milliseconds
    period_ms: u64,
    /// Time elapsed since last fire in milliseconds
    elapsed_ms: u64,
    /// Timer mode
    mode: TimerMode,
    /// Whether the timer is canceled
    canceled: bool,
    /// Callback function pointer (no heap)
    callback_fn: Option<TimerCallbackFn>,
}

impl core::fmt::Debug for TimerState {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("TimerState")
            .field("period_ms", &self.period_ms)
            .field("elapsed_ms", &self.elapsed_ms)
            .field("mode", &self.mode)
            .field("canceled", &self.canceled)
            .field("has_callback_fn", &self.callback_fn.is_some())
            .finish()
    }
}

impl TimerState {
    /// Create a new timer state with function pointer callback
    pub fn new_with_fn(period: TimerDuration, mode: TimerMode, callback: TimerCallbackFn) -> Self {
        Self {
            period_ms: period.as_millis(),
            elapsed_ms: 0,
            mode,
            canceled: false,
            callback_fn: Some(callback),
        }
    }

    /// Create an inert timer state
    pub fn new_inert(period: TimerDuration) -> Self {
        Self {
            period_ms: period.as_millis(),
            elapsed_ms: 0,
            mode: TimerMode::Inert,
            canceled: false,
            callback_fn: None,
        }
    }

    /// Get the timer period
    pub fn period(&self) -> TimerDuration {
        TimerDuration::from_millis(self.period_ms)
    }

    /// Get the timer mode
    pub fn mode(&self) -> TimerMode {
        self.mode
    }

    /// Check if the timer is canceled
    pub fn is_canceled(&self) -> bool {
        self.canceled
    }

    /// Cancel the timer
    pub fn cancel(&mut self) {
        self.canceled = true;
    }

    /// Reset the timer (uncancels and resets elapsed time)
    pub fn reset(&mut self) {
        self.canceled = false;
        self.elapsed_ms = 0;
    }

    /// Check if the timer is ready to fire
    pub fn is_ready(&self) -> bool {
        !self.canceled && self.mode != TimerMode::Inert && self.elapsed_ms >= self.period_ms
    }

    /// Get time until next call (0 if ready)
    pub fn time_until_next_call(&self) -> TimerDuration {
        if self.canceled || self.mode == TimerMode::Inert {
            return TimerDuration::from_millis(u64::MAX);
        }
        if self.elapsed_ms >= self.period_ms {
            TimerDuration::zero()
        } else {
            TimerDuration::from_millis(self.period_ms - self.elapsed_ms)
        }
    }

    /// Get time since last call
    pub fn time_since_last_call(&self) -> TimerDuration {
        TimerDuration::from_millis(self.elapsed_ms)
    }

    /// Set callback to function pointer
    pub fn set_callback_fn(&mut self, callback: TimerCallbackFn) {
        self.callback_fn = Some(callback);
    }

    /// Set timer to repeating mode
    pub fn set_repeating(&mut self) {
        self.mode = TimerMode::Repeating;
    }

    /// Set timer to one-shot mode
    pub fn set_oneshot(&mut self) {
        self.mode = TimerMode::OneShot;
    }

    /// Set timer to inert mode
    pub fn set_inert(&mut self) {
        self.mode = TimerMode::Inert;
    }

    /// Update elapsed time and return true if timer should fire
    #[allow(dead_code)] // Used by ConnectedNode when zenoh feature is enabled
    pub(crate) fn update(&mut self, delta_ms: u64) -> bool {
        if self.canceled || self.mode == TimerMode::Inert {
            return false;
        }

        self.elapsed_ms = self.elapsed_ms.saturating_add(delta_ms);

        self.elapsed_ms >= self.period_ms
    }

    /// Fire the timer callback and handle mode-specific behavior
    #[allow(dead_code)] // Used by ConnectedNode when zenoh feature is enabled
    pub(crate) fn fire(&mut self) {
        // Execute callback
        if let Some(ref callback) = self.callback_fn {
            callback();
        }

        // Handle mode-specific behavior
        match self.mode {
            TimerMode::Repeating => {
                // Reset elapsed time for next period
                self.elapsed_ms = self.elapsed_ms.saturating_sub(self.period_ms);
            }
            TimerMode::OneShot => {
                // Become inert after firing
                self.mode = TimerMode::Inert;
                self.elapsed_ms = 0;
            }
            TimerMode::Inert => {
                // Should not reach here
            }
        }
    }
}

/// A handle to a timer stored in a node
///
/// This is a lightweight handle that references a timer by index.
/// The actual timer state is stored in the `ConnectedNode`.
///
/// # Type Parameters
///
/// - `C`: Callback type marker (function pointer or boxed)
#[derive(Debug, Clone, Copy)]
pub struct TimerHandle<C = TimerCallbackFn> {
    /// Timer index in the node's timer collection
    index: usize,
    /// Phantom data for callback type
    _marker: PhantomData<C>,
}

impl<C> TimerHandle<C> {
    /// Create a new timer handle
    #[allow(dead_code)] // Used by ConnectedNode when zenoh feature is enabled
    pub(crate) fn new(index: usize) -> Self {
        Self {
            index,
            _marker: PhantomData,
        }
    }

    /// Get the timer index
    pub fn index(&self) -> usize {
        self.index
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_timer_duration() {
        let d = TimerDuration::from_millis(1500);
        assert_eq!(d.as_millis(), 1500);
        assert_eq!(d.as_secs(), 1);

        let d2 = TimerDuration::from_secs(2);
        assert_eq!(d2.as_millis(), 2000);

        let d3 = TimerDuration::from_micros(5500);
        assert_eq!(d3.as_millis(), 5);
    }

    #[test]
    fn test_timer_duration_conversion() {
        let ros_dur = nros_core::Duration::from_millis(1500);
        let timer_dur: TimerDuration = ros_dur.into();
        assert_eq!(timer_dur.as_millis(), 1500);

        let back: nros_core::Duration = timer_dur.into();
        assert_eq!(back.sec, 1);
        assert_eq!(back.nanosec, 500_000_000);
    }

    fn test_callback() {
        // Empty callback for testing
    }

    #[test]
    fn test_timer_state_repeating() {
        let mut state = TimerState::new_with_fn(
            TimerDuration::from_millis(100),
            TimerMode::Repeating,
            test_callback,
        );

        assert_eq!(state.period().as_millis(), 100);
        assert_eq!(state.mode(), TimerMode::Repeating);
        assert!(!state.is_canceled());
        assert!(!state.is_ready());

        // Advance time
        assert!(!state.update(50));
        assert!(!state.is_ready());
        assert_eq!(state.time_until_next_call().as_millis(), 50);
        assert_eq!(state.time_since_last_call().as_millis(), 50);

        // Advance to ready
        assert!(state.update(50));
        assert!(state.is_ready());
        assert_eq!(state.time_until_next_call().as_millis(), 0);

        // Fire and check it repeats
        state.fire();
        assert_eq!(state.mode(), TimerMode::Repeating);
        assert!(!state.is_ready());
    }

    #[test]
    fn test_timer_state_oneshot() {
        let mut state = TimerState::new_with_fn(
            TimerDuration::from_millis(100),
            TimerMode::OneShot,
            test_callback,
        );

        assert_eq!(state.mode(), TimerMode::OneShot);

        // Advance to ready
        state.update(100);
        assert!(state.is_ready());

        // Fire and check it becomes inert
        state.fire();
        assert_eq!(state.mode(), TimerMode::Inert);
        assert!(!state.is_ready());
    }

    #[test]
    fn test_timer_state_inert() {
        let state = TimerState::new_inert(TimerDuration::from_millis(100));

        assert_eq!(state.mode(), TimerMode::Inert);
        assert!(!state.is_ready());
    }

    #[test]
    fn test_timer_cancel_reset() {
        let mut state = TimerState::new_with_fn(
            TimerDuration::from_millis(100),
            TimerMode::Repeating,
            test_callback,
        );

        state.update(50);
        state.cancel();
        assert!(state.is_canceled());
        assert!(!state.is_ready());

        state.update(100);
        assert!(!state.is_ready()); // Still canceled

        state.reset();
        assert!(!state.is_canceled());
        assert_eq!(state.time_since_last_call().as_millis(), 0);
    }

    #[test]
    fn test_timer_mode_changes() {
        let mut state = TimerState::new_with_fn(
            TimerDuration::from_millis(100),
            TimerMode::Repeating,
            test_callback,
        );

        state.set_oneshot();
        assert_eq!(state.mode(), TimerMode::OneShot);

        state.set_inert();
        assert_eq!(state.mode(), TimerMode::Inert);

        state.set_repeating();
        assert_eq!(state.mode(), TimerMode::Repeating);
    }

    #[test]
    fn test_timer_handle() {
        let handle: TimerHandle = TimerHandle::new(5);
        assert_eq!(handle.index(), 5);
    }
}

// =============================================================================
// Ghost model validation
// =============================================================================

#[cfg(test)]
mod ghost_checks {
    use super::*;
    use nros_ghost_types::{TimerGhost, TimerModeGhost};

    /// Structural check: map TimerMode to TimerModeGhost.
    /// If a variant is added or removed, this fails to compile.
    fn ghost_mode(m: &TimerMode) -> TimerModeGhost {
        match m {
            TimerMode::Repeating => TimerModeGhost::Repeating,
            TimerMode::OneShot => TimerModeGhost::OneShot,
            TimerMode::Inert => TimerModeGhost::Inert,
        }
    }

    /// Structural check: construct TimerGhost from TimerState private fields.
    /// If a field is renamed or retyped, this fails to compile.
    fn ghost_from_timer(t: &TimerState) -> TimerGhost {
        TimerGhost {
            period_ms: t.period_ms,
            elapsed_ms: t.elapsed_ms,
            mode: ghost_mode(&t.mode),
            canceled: t.canceled,
        }
    }

    fn test_callback() {}

    #[test]
    fn ghost_new_state() {
        let state = TimerState::new_with_fn(
            TimerDuration::from_millis(100),
            TimerMode::Repeating,
            test_callback,
        );
        let ghost = ghost_from_timer(&state);
        assert_eq!(ghost.period_ms, 100);
        assert_eq!(ghost.elapsed_ms, 0);
        assert_eq!(ghost.mode, TimerModeGhost::Repeating);
        assert!(!ghost.canceled);
    }

    #[test]
    fn ghost_update_accumulates() {
        let mut state = TimerState::new_with_fn(
            TimerDuration::from_millis(100),
            TimerMode::Repeating,
            test_callback,
        );
        state.update(30);
        let ghost = ghost_from_timer(&state);
        assert_eq!(ghost.elapsed_ms, 30);

        state.update(25);
        let ghost2 = ghost_from_timer(&state);
        assert_eq!(ghost2.elapsed_ms, 55);
    }

    #[test]
    fn ghost_canceled_no_fire() {
        let mut state = TimerState::new_with_fn(
            TimerDuration::from_millis(100),
            TimerMode::Repeating,
            test_callback,
        );
        state.cancel();
        let fired = state.update(200);
        assert!(!fired);
        let ghost = ghost_from_timer(&state);
        assert!(ghost.canceled);
    }

    #[test]
    fn ghost_inert_no_fire() {
        let mut state = TimerState::new_inert(TimerDuration::from_millis(100));
        let fired = state.update(200);
        assert!(!fired);
        let ghost = ghost_from_timer(&state);
        assert_eq!(ghost.mode, TimerModeGhost::Inert);
    }

    #[test]
    fn ghost_oneshot_becomes_inert() {
        let mut state = TimerState::new_with_fn(
            TimerDuration::from_millis(100),
            TimerMode::OneShot,
            test_callback,
        );
        state.update(100);
        state.fire();
        let ghost = ghost_from_timer(&state);
        assert_eq!(ghost.mode, TimerModeGhost::Inert);
    }
}