# 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`](https://crates.io/crates/safina).
## Features
- `forbid(unsafe_code)`
- Depends only on `std`
- Good test coverage (95%)
- 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).
## Limitations
- Requires Rust `nightly`, for [OnceCell](https://doc.rust-lang.org/std/lazy/struct.OnceCell.html)
- Timers complete around 2ms late, but never early
- Allocates memory
## Examples
```rust
safina_timer::start_timer_thread();
safina_timer::sleep_for(Duration::from_secs(10)).await.unwrap();
```
```rust
safina_timer::start_timer_thread();
let deadline = Instant::now() + Duration::from_millis(500);
safina_timer::sleep_until(deadline).await.unwrap();
```
## Documentation
https://docs.rs/safina-timer
## 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 OSes, Windows
- Fast, internally complicated, and full of `unsafe`
- [embedded-async-timer](https://crates.io/crates/embedded-async-timer)
- no_std
- Supports: bare_metal
## Release Process
1. Edit `Cargo.toml` and bump version number.
1. Run `./release.sh`
## Changelog
- 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/0.1.0/safina_timer/fn.with_deadline.html)
and [`with_timeout`](https://docs.rs/safina-timer/0.1.0/safina_timer/fn.with_timeout.html)
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
License: Apache-2.0