waiter-trait 0.9.2

Traits used to wait and timeout.
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
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

//! Traits used to wait and timeout in a `no-std` embedded system.
//!
//! # Features
//!
//!- `std`: Disabled by default.
//!
//! # Usage
//!
//! 1. New a [`Waiter`] or [`TimedWaiter`] implementation.
//! 2. Call `start()` to get a [`WaiterStatus`] implementation.
//! 3. Call [`timeout()`](WaiterStatus::timeout) to check if the time limit expires.
//!     1. [`Interval::interval`] is usually called in [`timeout()`](WaiterStatus::timeout)
//!        before the time limit expires. It also depends on your implementation.
//! 4. Call [`restart()`](WaiterStatus::restart) to reset the timeout condition if necessary.
//!
//! ## Example
//!
//! ```
//! use waiter_trait::prelude::*;
//!
//! fn foo(waiter: impl Waiter) {
//!     let mut t = waiter.start();
//!     loop {
//!         // Wait for something.
//!
//!         // Reset if it's necessary.
//!         t.restart();
//!
//!         if t.timeout() {
//!             break;
//!         }
//!     }
//! }
//! ```
//!
//! ## Pre-implemented
//!
//! - [`StdWaiter`] and [`StdInterval`]: Need the `std` feature enabled.
//! - [`NonInterval`]: implements [`Interval`] that does nothing.
//! - [`TickDelay`]: implements [`DelayNs`]
//!
//! # Implement Your Own
//!
//! For developers, you can choose one of the following options.
//! - Implement [`Waiter`] or [`TimedWaiter`], and [`WaiterStatus`] then use them.
//! - Implement [`TickInstant`] then use [`TickWaiter`] or [`TimedTickWaiter`].
//!     - Simply give [`NonInterval`] to `Waiter`, If you don't need interval.
//!       In this way, you can also use [`DelayNs`] or `sleep` separately.
//!     - Or you can implement [`Interval`] and use it.
//! - Using [`Counter`], if you don't have any tick source.

#![cfg_attr(not(feature = "std"), no_std)]

mod counter;
pub use counter::*;
mod non_interval;
pub use non_interval::*;
mod tick_waiter;
pub use tick_waiter::*;
mod tick_delay;
pub use tick_delay::*;
mod timed_tick_waiter;
pub use timed_tick_waiter::*;

#[cfg(feature = "std")]
mod std_impls;
#[cfg(feature = "std")]
pub use std_impls::*;

pub use embedded_hal::delay::DelayNs;
pub use fugit::{self, MicrosDurationU32};

pub mod prelude;

pub trait Waiter {
    /// Start waiting.
    fn start(&self) -> impl WaiterStatus;
}

/// The difference from [`Waiter`] is that it supports setting timeout at `start()`.
pub trait TimedWaiter {
    /// Set timeout and start waiting.
    fn start(&self, timeout: MicrosDurationU32) -> impl WaiterStatus;
}

pub trait WaiterStatus {
    /// Check if the time limit expires. This function may sleeps for a while,
    /// depends on the implementation.
    fn timeout(&mut self) -> bool;
    /// Reset the timeout condition.
    fn restart(&mut self);
}

pub trait TickInstant: Copy {
    fn now() -> Self;
    /// Returns the amount of ticks elapsed from another instant to this one.
    fn tick_since(self, earlier: Self) -> u32;
    /// Returns the amount of ticks elapsed since this instant.
    fn tick_elapsed(self) -> u32 {
        Self::now().tick_since(self)
    }
}

/// It is usually called at [`WaiterStatus::timeout`] before the time limit expires.
/// It can be implemented for `yield`, `sleep` or do nothing.
pub trait Interval: Clone {
    fn interval(&self);
}