6 releases
0.3.2 | Jul 29, 2023 |
---|---|
0.3.1 | Jul 28, 2023 |
0.2.2 |
|
0.1.0 | Jul 11, 2023 |
#592 in Asynchronous
32 downloads per month
39KB
789 lines
⏲ 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
, Arc
s, Mutex
es, 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.
Dependencies
~1–12MB
~137K SLoC