# ARCHIVED ARCHIVED ARCHIVED This crate is archived and will not be updated. The code is now at [`safina::timer`](https://docs.rs/safina/latest/safina/timer/) in the [`safina`](https://crates.io/crates/safina) crate. ---- # safina-timer Provides async [`sleep_for`](https://docs.rs/safina-timer/latest/safina_timer/fn.sleep_for.html) and [`sleep_until`](https://docs.rs/safina-timer/latest/safina_timer/fn.sleep_until.html) functions. This crate is part of [`safina`](https://crates.io/crates/safina), a safe async runtime. # Features - `forbid(unsafe_code)` - Depends only on `std` - 100% test coverage - Source of time is [`std::thread::park_timeout`](https://doc.rust-lang.org/std/thread/fn.park_timeout.html) via [`std::sync::mpsc::Receiver::recv_timeout`](https://doc.rust-lang.org/std/sync/mpsc/struct.Receiver.html#method.recv_timeout). - Works with [`safina-executor`](https://crates.io/crates/safina-executor) or any async executor # Limitations - Building on `stable` requires the feature `once_cell`. This uses [`once_cell`](https://crates.io/crates/once_cell) crate which contains some unsafe code. This is necessary until [`std::lazy::OnceCell`](https://doc.rust-lang.org/std/lazy/struct.OnceCell.html) is stable. - Timers complete around 2ms late, but never early - Allocates memory # Examples ```rust safina_timer::start_timer_thread(); let duration = Duration::from_secs(10); safina_timer::sleep_for(duration).await; ``` ```rust safina_timer::start_timer_thread(); let deadline = Instant::now() + Duration::from_secs(1); safina_timer::sleep_until(deadline).await; ``` ```rust safina_timer::start_timer_thread(); let deadline = Instant::now() + Duration::from_secs(1); let req = safina_timer::with_deadline( read_request(), deadline).await??; let data = safina_timer::with_deadline( read_data(req), deadline).await??; safina_timer::with_deadline( write_data(data), deadline ).await??; safina_timer::with_deadline( send_response(data), deadline).await??; ``` ```rust safina_timer::start_timer_thread(); let req = safina_timer::with_timeout( read_request(), Duration::from_secs(1) ).await??; let data = safina_timer::with_timeout( read_data(req), Duration::from_secs(2) ).await??; safina_timer::with_timeout( write_data(data), Duration::from_secs(2) ).await??; safina_timer::with_timeout( send_response(data), Duration::from_secs(1) ).await??; ``` # Documentation # Alternatives - [futures-timer](https://crates.io/crates/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](https://crates.io/crates/async-io) - popular - single and repeating timers - Supports: Linux, Windows, macOS, iOS, Android, and many others. - Uses [polling](https://crates.io/crates/polling) crate which makes unsafe calls to OS. - [async-timer](https://crates.io/crates/async-timer) - Supports: Linux & Android - Makes unsafe calls to OS - [tokio](https://crates.io/crates/tokio) - very popular - single and repeating timers - Supports: Linux, macOS, other unix-like operating systems, Windows - Fast, internally complicated, and full of `unsafe` - [embedded-async-timer](https://crates.io/crates/embedded-async-timer) - `no_std` - Supports `bare_metal` # Changelog - v0.1.11 - Remove some type constraints. - v0.1.10 - Use `safina-executor` v0.2.0. - v0.1.9 - Name the timer thread. - v0.1.8 - Increase test coverage - v0.1.7 - Support stable with rust 1.51 and `once_cell`. - v0.1.6 - Update dependencies - v0.1.5 - Update docs - v0.1.4 - Upgrade to new safina-executor version which removes need for `Box::pin`. - v0.1.3 - Add badges to readme - v0.1.2 - Update [`with_deadline`](https://docs.rs/safina-timer/latest/safina_timer/fn.with_deadline.html) and [`with_timeout`](https://docs.rs/safina-timer/latest/safina_timer/fn.with_timeout.html): - Make them panic on `TimerThreadNotStarted` error and return new [`DeadlineExceeded`](https://docs.rs/safina-timer/latest/safina_timer/struct.DeadlineExceeded.html) struct instead of `DeadlineError` enum. This allows callers to write a match clause like `Err(DeadlineExceeded)`. - Make them use [`std::boxed::Box::pin`](https://doc.rust-lang.org/stable/std/boxed/struct.Box.html#method.pin) so callers don't have to. - Make [`sleep_until`](https://docs.rs/safina-timer/latest/safina_timer/fn.sleep_until.html) and [`sleep_for`](https://docs.rs/safina-timer/latest/safina_timer/fn.sleep_for.html) return `()` and panic if [`start_timer_thread()`](fn.start_timer_thread.html) has not been called. - v0.1.1 - Use most recent waker passed to `SleepFuture::poll`, as required by the [`std::future::Future::poll`](https://doc.rust-lang.org/stable/std/future/trait.Future.html#tymethod.poll) contract. - Add [`with_deadline`](https://docs.rs/safina-timer/latest/safina_timer/fn.with_deadline.html) and [`with_timeout`](https://docs.rs/safina-timer/latest/safina_timer/fn.with_timeout.html) functions. - v0.1.0 - First published version # TO DO - Add a way to schedule jobs (`FnOnce` structs). # Release Process 1. Edit `Cargo.toml` and bump version number. 1. Run `./release.sh`