README.md

⏲ 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.