async-timeouts 0.3.2

An instrument to start async tasks after timeouts
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

[reset]: https://docs.rs/async-timeouts/latest/async_timeouts/struct.Timeout.html#method.reset
[restart]: https://docs.rs/async-timeouts/latest/async_timeouts/struct.Timeout.html#method.restart
[stop]: https://docs.rs/async-timeouts/latest/async_timeouts/struct.Timeout.html#method.stop
[finished]: https://docs.rs/async-timeouts/latest/async_timeouts/struct.Timeout.html#method.finished
<!-- cargo-rdme start -->

# Async Timeouts Helper
It is a simple instrument to delay execution of an async task with additional methods:
* [reset] timeout with a new value, i.e. to delay execution of your task;
* [restart] timeout with a new or previous task;
* [stop] the timer before your task will be executed;
* [finished] — check if the timer of the task is over or not.

It is convinient to use this crate with [Notify] or different
channels (i.e. [async_channel]).

## Examples
Basic example
```rust
use std::time::{Duration, Instant};
use async_timeouts::Timeout;
use tokio::sync::Notify;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let event = Arc::new(Notify::new());
    let timer = Instant::now();
    {
        let event = event.clone();
        // Let's notify our event after 3 seconds
        Timeout::set(Duration::from_secs(3), async move {
            event.notify_one();
        }).await;
    }
    event.notified().await;
    assert!(timer.elapsed().as_secs() >= 3);
    println!("{} seconds elapsed", timer.elapsed().as_secs());
}
```

If you do not need to start timer when `Timeout` is created, use `Timeout::default()` with
a subsequent call to the [restart] method
```rust
use std::time::Duration;
use async_timeouts::Timeout;

#[tokio::main]
async fn main() {
    let mut task = Timeout::default();
    println!("Task timer is not running yet: {}", task.finished());
    assert!(task.finished());

    task.restart(Duration::from_secs(3), async move {
        // Some task here
        tokio::time::sleep(Duration::from_secs(1)).await;
    }).await;
    println!("Task timer is running: {}", !task.finished());
    assert!(!task.finished());

    task.stop().await;
    println!("Task timer is stoped: {}", task.finished());
    assert!(task.finished());
}
```

[async_channel]: https://crates.io/crates/async-channel
[Notify]: https://docs.rs/tokio/1.44.2/tokio/sync/struct.Notify.html
[reset]: Timeout::reset()
[restart]: Timeout::restart()
[stop]: Timeout::stop()
[finished]: Timeout::finished()

<!-- cargo-rdme end -->

Take a look at more complex examples:
* [example with channels],
* [restart timeout].

[example with channels]: https://altlinux.space/writers/async-timeouts/src/branch/main/examples/usage_with_channels.rs
[restart timeout]: https://altlinux.space/writers/async-timeouts/src/branch/main/examples/restart_timeout.rs