Crate timer_lib 

Tokio-based timers for one-shot and recurring async work.

timer-lib provides a handle-first API for scheduling async callbacks and observing their lifecycle.

Overview

• Timer runs one-shot or recurring work.
• TimerBuilder reduces setup boilerplate for common configurations.
• TimerRegistry tracks timers by ID and supports bulk operations.
• TimerEvents exposes broadcast lifecycle events.
• TimerCompletion exposes lossless completed-run delivery.
• TimerSnapshot and RegisteredTimer expose introspection-friendly state.

Examples

Start a one-shot timer and wait for it to finish:

use std::time::Duration;
use timer_lib::{Timer, TimerError, TimerFinishReason};

let timer = Timer::new();
timer
    .start_once(Duration::from_millis(10), || async { Ok::<(), TimerError>(()) })
    .await
    .unwrap();

let outcome = timer.join().await.unwrap();
assert_eq!(outcome.reason, TimerFinishReason::Completed);

Build a recurring timer:

use std::time::Duration;
use timer_lib::{RecurringSchedule, Timer, TimerError, TimerFinishReason};

let timer = Timer::recurring(RecurringSchedule::new(Duration::from_millis(10)).with_expiration_count(2))
    .start(|| async { Ok::<(), TimerError>(()) })
    .await
    .unwrap();

let outcome = timer.join().await.unwrap();
assert_eq!(outcome.reason, TimerFinishReason::Completed);
assert_eq!(outcome.statistics.execution_count, 2);

Observe completion without relying on lossy broadcast delivery:

use std::time::Duration;
use timer_lib::{Timer, TimerError};

let timer = Timer::new();
let mut completion = timer.completion();
let run_id = timer
    .start_once(Duration::from_millis(10), || async { Ok::<(), TimerError>(()) })
    .await
    .unwrap();

let outcome = completion.wait_for_run(run_id).await.unwrap();
assert_eq!(outcome.run_id, run_id);

Start a one-shot timer at an absolute deadline:

use std::time::Duration;
use timer_lib::{Timer, TimerError, TimerFinishReason};
use tokio::time::Instant;

let deadline = Instant::now() + Duration::from_millis(10);
let timer = Timer::at(deadline)
    .start(|| async { Ok::<(), TimerError>(()) })
    .await
    .unwrap();

let outcome = timer.join().await.unwrap();
assert_eq!(outcome.reason, TimerFinishReason::Completed);

Runtime

This crate currently targets Tokio.

Errors

Public operations return TimerError for invalid configuration or invalid lifecycle transitions.

Re-exports

pub use errors::TimerError;

pub use registry::TimerRegistry;

pub use registry::RegisteredTimer;

pub use timer::RecurringCadence;

pub use timer::RecurringSchedule;

pub use timer::RetryBackoff;

pub use timer::RetryPolicy;

pub use timer::Timer;

pub use timer::TimerBuilder;

pub use timer::TimerCallback;

pub use timer::TimerCompletion;

pub use timer::TimerEvent;

pub use timer::TimerEvents;

pub use timer::TimerFinishReason;

pub use timer::TimerMetadata;

pub use timer::TimerOutcome;

pub use timer::TimerSnapshot;

pub use timer::TimerState;

pub use timer::TimerStatistics;

Modules

errors

Error handling module for TimerLib.

registry

timer

Type Aliases

TimerManagerDeprecated