Crate safina_timer

This is a safe Rust library providing async sleep_for and sleep_until functions. These functions return futures that complete at the specified time.

It works well with safina.

Features

• forbid(unsafe_code)
• Depends only on std
• Good test coverage (95%)
• Source of time is std::thread::park_timeout via std::sync::mpsc::Receiver::recv_timeout.

Limitations

• Requires Rust nightly, for OnceCell
• Timers complete around 2ms late, but never early
• Allocates memory

Examples

safina_timer::start_timer_thread();
safina_timer::sleep_for(Duration::from_secs(10)).await;

safina_timer::start_timer_thread();
let deadline =
    Instant::now() + Duration::from_millis(500);
safina_timer::sleep_until(deadline).await;

use safina_timer::with_deadline;
safina_timer::start_timer_thread();
let deadline =
    Instant::now() + Duration::from_millis(500);
let req =
    with_deadline(read_request(), deadline).await??;
let data =
    with_deadline(read_data(req), deadline).await??;
with_deadline(write_data(data), deadline).await??;
with_deadline(send_response(data), deadline).await??;

use safina_timer::with_timeout;
safina_timer::start_timer_thread();
let req = with_timeout(
    read_request(), Duration::from_millis(500)
).await??;
let data = with_timeout(
    read_data(req), Duration::from_millis(1000)
).await??;
with_timeout(
    write_data(data), Duration::from_millis(1000)
).await??;
with_timeout(
    send_response(data), Duration::from_millis(5000)
).await??;

Documentation

https://docs.rs/safina-timer

Alternatives

• futures-timer
  • popular
  • Supports: Wasm, Linux, Windows, macOS
  • Contains generous amounts of unsafe code
  • Uses std::thread::park_timeout as its source of time
• async-io
  • popular
  • single and repeating timers
  • Supports: Linux, Windows, macOS, iOS, Android, and many others.
  • Uses polling crate which makes unsafe calls to OS.
• async-timer
  • Supports: Linux & Android
  • Makes unsafe calls to OS
• tokio
  • very popular
  • single and repeating timers
  • Supports: Linux, macOS, other unix-like OSes, Windows
  • Fast, internally complicated, and full of unsafe
• embedded-async-timer
  • no_std
  • Supports: bare_metal

Release Process

1. Edit Cargo.toml and bump version number.
2. Run ./release.sh

Changelog

• v0.1.2
  • Update with_deadline and with_timeout:
    • Make them panic on TimerThreadNotStarted error and return new DeadlineExceeded struct instead of DeadlineError enum. This allows callers to write a match clause like Err(DeadlineExceeded).
    • Make them use std::boxed::Box::pin so callers don't have to.
  • Make sleep_until and sleep_for return () and panic if start_timer_thread() has not been called.
• v0.1.1
  • Use most recent waker passed to SleepFuture::poll, as required by the std::future::Future::poll contract.
  • Add with_deadline and with_timeout functions.
• v0.1.0 - First published version

TO DO

• DONE - Implement sleep_until
• DONE - Implement sleep_for
• DONE - Add tests
• Add docs
• Publish on crates.io

Structs

DeadlineExceeded
DeadlineFuture	A future wrapper that returns DeadlineExceeded at a specified deadline.
SleepFuture	A future that completes after the specified time.
TimerThreadNotStarted	Call start_timer_thread to prevent this error.

Enums

DeadlineError

DeadlineError::TimerThreadNotStarted DeadlineError::DeadlineExceeded

Functions

sleep_for	Returns duration time from now.
sleep_until	Returns after deadline.
start_timer_thread	Starts the worker thread, if it's not already started. You must call this before calling sleep_until or sleep_for.
with_deadline	Awaits inner, but returns DeadlineExceeded after deadline.
with_timeout	Awaits inner, but returns DeadlineExceeded after duration time from now.