⏲
situwaition
situwaition runs a closure continuously, until an Ok(..) is received, or a timeout period elapses.
Install
cargo add situwaition # only sync waiting is enabled by default
cargo add situwaition --features async-std # use async-std
cargo add situwaition --features tokio # use tokio
If you're editing Cargo.toml by hand:
[dependencies]
situwaition = "0.3"
#situwaition = { version = "0.3", features = [ "async-std" ] }
#situwaition = { version = "0.3", features = [ "tokio" ] }
Quickstart
Sync
To use situwaition in synchronous contexts:
use situwaition::wait_for;
// ...
// Do some waiting
let result = wait_for(|| {
// Get the current value from the mutex
if some_condition { Ok(value) } else { Err(SomeError) ]
});
// Act on the result
match result {
Ok(v) => { ... }
Err(SituwaitionError::TimeoutError(e)) => { ... }
}
// ...
situwaition will run the function continuously, ignoring Error(..) responses until:
- The function resolves to an
Ok(..)variant - The configured timeout (3s by default, checking every 250ms) is reached.
See a full example in examples/sync.rs. To run the sync example:
cargo run --example sync
Tokio
If you're using tokio, then your code looks like this:
use situwaition::runtime::tokio::wait_for;
// ...
// Do some waiting
let result = wait_for(|| async {
// Get the current value from the mutex
if some_condition { Ok(value) } else { Err(SomeError) ]
});
// Act on the result
match result {
Ok(v) => { ... }
Err(SituwaitionError::TimeoutError(e)) => { ... }
}
// ...
Note here that you are passing a Future factory to the function -- a function/closure (|| { ... }) that outputs a Future (async { .. }).
The usual async usage rules apply -- use move, Arcs, Mutexes, and other ownership/synchronization primitives where appropriate.
See a full example in examples/tokio.rs. To run the tokio example:
cargo run --example tokio --features=tokio
async-std
If you're using async-std, then your code looks like this:
use situwaition::runtime::tokio::wait_for;
// ...
// Do some waiting
let result = wait_for(|| async {
// Get the current value from the mutex
if some_condition { Ok(value) } else { Err(SomeError) ]
});
// Act on the result
match result {
Ok(v) => { ... }
Err(SituwaitionError::TimeoutError(e)) => { ... }
}
// ...
See a full example in examples/async_std.rs. To run the async-std example:
cargo run --example async-std --features=async-std
Verbose configuration
If you'd like to control more finely the intervals and how many times a check will occur, you can create the Waiter object(s) yourself:
use situwaition::runtime::AsyncWaiter;
use situwaition::runtime::SyncWaiter;
// Synchronous code
SyncWaiter::with_timeout(|| { ... }, Duration::from_millis(500))?;
// Asynchronous code (either tokio or async-std)
AsyncWaiter::with_timeout(|| async { ... }, Duration::from_millis(500))?
.exec()
.await;
See the methods on SyncWaiter and AsyncWaiter for more options.
Supported environments
situwaition works with the following environments:
| Name | Supported? |
|---|---|
| Synchronous |
|
Async w/ tokio |
|
Async w/ async-std |
|
Development
To get started working on developing situwatiion, run the following just targets:
just setup build
To check that your changes are fine, you'll probably want to run:
just test
If you want to see the full list of targets available that you can run just without any arguments.
just
There are a few useful targets like just build-watch which will continuously build the project thanks to cargo watch.
Contributing
Contributions are welcome! If you find a bug or an impovement that should be included in situwaition, create an issue or open a pull request.
12 Sep 29, 2021
15 Dec 26, 2022
15 Dec 11, 2022
61 Jan 8, 2023
15 Nov 20, 2022
2 Dec 30, 2021
11 Oct 30, 2022
3 Sep 19, 2022
2 Aug 22, 2022
5 Nov 3, 2022
12 Jan 21, 2023
9 Nov 30, 2022
10 Jun 17, 2022
1 Nov 15, 2021
4 May 5, 2022
198 Jan 2, 2023
2 Dec 5, 2022
6 May 6, 2022
458 Dec 27, 2022