Trait Timer

Source

pub trait Timer: Send + Sync {
    // Required methods
    fn clock(&self) -> &dyn MonotonicClock;
    fn at(&self, deadline: MonotonicInstant) -> Result<TimerFuture, TimeError>;

    // Provided methods
    fn now(&self) -> MonotonicInstant { ... }
    fn deadline_after(
        &self,
        duration: Duration,
    ) -> Result<MonotonicInstant, TimeError> { ... }
    fn after(&self, duration: Duration) -> Result<TimerFuture, TimeError> { ... }
}

Expand description

Creates asynchronous notifications in one monotonic clock domain.

Calling at() or after() fixes the logical deadline and cancellation ownership before returning. The returned future waits for that fixed deadline. If the deadline is reached before the first poll, that first poll returns ready. As with every Future, callers must not poll it again after it first returns ready. A backend may defer enrollment with its native scheduler until the future is polled. Dropping an incomplete future cancels the outstanding notification.

Every call to clock() on one Timer must report the same clock domain for the Timer’s lifetime. Implementations must reject deadlines from a different domain with TimeError::ClockDomainMismatch. MonotonicInstant::validate_domain provides the canonical validation and error construction for custom Timer implementations.

Timer failures have two stages: the outer Result reports registration failures, while the returned TimerFuture reports failures observed after registration, such as an unavailable scheduler worker or a Tokio runtime that shut down. Custom implementations may document additional lifecycle preconditions and panic conditions.

Required Methods§

Source

fn clock(&self) -> &dyn MonotonicClock

Returns the monotonic clock whose domain this timer uses.

Successive calls may return different handles, but every returned clock must report the same domain for this Timer’s lifetime.

§Returns

The clock retained by this timer.

§Examples

Discarding the retained clock is diagnosed when unused results are denied:

#![deny(unused_must_use)]
use qubit_clock::{MonotonicClock, StdMonotonicClock, Timer};

let timer = StdMonotonicClock::new().new_timer();
timer.clock();

Source

fn at(&self, deadline: MonotonicInstant) -> Result<TimerFuture, TimeError>

Creates a notification for an absolute monotonic deadline.

The deadline is fixed before this method returns. A deadline at or before the current time produces a future that is already ready.

§Parameters

deadline - Absolute deadline in this timer’s clock domain.

§Returns

A future that returns Ok(()) when deadline is reached. The future returns a TimeError if the backend fails after registration.

§Errors

Returns TimeError::ClockDomainMismatch when deadline belongs to a different clock domain. Returns another TimeError when the notification cannot be created.

Provided Methods§

Source

fn now(&self) -> MonotonicInstant

Returns the current monotonic instant in this timer’s clock domain.

§Returns

The current instant sampled from this timer’s clock.

Source

fn deadline_after( &self, duration: Duration, ) -> Result<MonotonicInstant, TimeError>

Fixes an absolute deadline relative to the current timer instant.

This method samples the timer clock while it runs and returns the resulting deadline without registering a Timer waiter. Callers can carry the returned deadline through lock acquisition or other non-interruptible work while preserving one operation-wide budget. It does not guarantee that such work returns before the deadline.

§Parameters

duration - Duration from the current monotonic instant.

§Returns

The fixed deadline in this timer’s clock domain.

§Errors

Returns TimeError::InstantOverflow when the deadline cannot be represented.

Source

fn after(&self, duration: Duration) -> Result<TimerFuture, TimeError>

Registers a notification after a relative duration.

The deadline is fixed by sampling clock() during this call, not when the returned future is first polled.

§Parameters

duration - Duration from the current monotonic instant.

§Returns

A future that returns Ok(()) when the fixed deadline is reached. The future returns a TimeError if the backend later fails.

§Errors

Returns TimeError::InstantOverflow when the deadline cannot be represented. Returns any error produced while creating the notification for that deadline.