Module timer 

Timer driver for nexus-rt.

Integrates nexus_timer::Wheel as a driver following the Installer/Plugin pattern. Handlers access the timer wheel directly via ResMut<Wheel<S>> during dispatch — no command queues, no side-channel communication.

Architecture

• TimerInstaller is the installer — consumed at setup, registers the wheel into WorldBuilder and returns a TimerPoller.
• TimerPoller is the poll-time handle. poll(world, now) drains expired timers and fires their handlers.
• Handlers reschedule themselves directly via ResMut<Wheel<S>>.

Timing

The timer wheel records an epoch (Instant) at construction time (inside TimerInstaller::install). All deadlines are converted to integer ticks relative to this epoch:

ticks = (deadline - epoch).as_nanos() / tick_ns

• Default tick resolution: 1ms (configurable via WheelBuilder::tick_duration).
• Instants before the epoch saturate to tick 0 (fire immediately).
• Instants beyond the wheel’s range are clamped to the highest level’s last slot (they fire eventually, not exactly on time).
• Deadlines in the past at poll time fire immediately — no “missed timer” error.

The epoch is captured as Instant::now() during install(). This means the wheel’s zero point is the moment the driver is installed, which is fine for monotonic deadlines derived from the same clock.

Examples

use std::time::{Duration, Instant};
use nexus_rt::{WorldBuilder, ResMut, IntoHandler, Handler, WheelBuilder};
use nexus_rt::timer::{TimerInstaller, TimerPoller, TimerWheel};

fn on_timeout(mut state: ResMut<bool>, _poll_time: Instant) {
    *state = true;
}

let mut builder = WorldBuilder::new();
builder.register::<bool>(false);
let wheel = WheelBuilder::default().unbounded(64).build(Instant::now());
let mut timer: TimerPoller = builder.install_driver(
    TimerInstaller::new(wheel),
);
let mut world = builder.build();

// Schedule a one-shot timer
let handler = on_timeout.into_handler(world.registry());
world.resource_mut::<TimerWheel>().schedule_forget(
    Instant::now() + Duration::from_millis(100),
    Box::new(handler),
);

// In the poll loop:
// timer.poll(&mut world, Instant::now());

Structs

BoundedWheelBuilder

Terminal builder for a bounded timer wheel.

BoxedTimers

Boxed timer configuration — heap-allocates each handler.

FlexTimers

Flex timer configuration — inline with heap fallback.

Full

Error returned when a bounded allocator is full.

InlineTimers

Inline timer configuration — stores handlers in a fixed-size buffer.

Periodic

Periodic timer wrapper — automatically reschedules after each firing.

TimerHandle

Handle to a scheduled timer.

TimerInstaller

Timer driver installer — takes a pre-built TimerWheel.

TimerPoller

Timer driver poller — generic over handler storage and slab store.

UnboundedWheelBuilder

Terminal builder for an unbounded timer wheel.

WheelBuilder

Builder for configuring a timer wheel.

WheelEntry

Timer wheel entry stored inside a slab slot.

Traits

TimerConfig

Configuration trait for generic timer code.

Type Aliases

BoundedFlexTimerWheel

Type alias for a bounded timer wheel using inline storage with heap fallback.

BoundedInlineTimerWheel

Type alias for a bounded timer wheel using inline handler storage.

BoundedTimerInstaller

Type alias for a bounded timer installer.

BoundedTimerPoller

Type alias for a bounded timer poller.

BoundedTimerWheel

Type alias for a bounded timer wheel using boxed handlers (heap-allocated).

BoundedWheel

A timer wheel backed by a fixed-capacity slab.

FlexTimerWheel

Type alias for a timer wheel using inline storage with heap fallback.

InlineTimerWheel

Type alias for a timer wheel using inline handler storage.

TimerWheel

Type alias for a timer wheel using boxed handlers (heap-allocated).

Wheel

A timer wheel backed by a growable slab.