1//! Timers
2
3use nb;
4use void::Void;
5
6/// A count down timer
7///
8/// # Contract
9///
10/// - `self.start(count); block!(self.wait());` MUST block for AT LEAST the time specified by
11/// `count`.
12///
13/// *Note* that the implementer doesn't necessarily have to be a *downcounting* timer; it could also
14/// be an *upcounting* timer as long as the above contract is upheld.
15///
16/// # Examples
17///
18/// You can use this timer to create delays
19///
20/// ```
21/// extern crate embedded_hal as hal;
22/// #[macro_use(block)]
23/// extern crate nb;
24///
25/// use hal::prelude::*;
26///
27/// fn main() {
28/// let mut led: Led = {
29/// // ..
30/// # Led
31/// };
32/// let mut timer: Timer6 = {
33/// // ..
34/// # Timer6
35/// };
36///
37/// Led.on();
38/// timer.start(1.s());
39/// block!(timer.wait()); // blocks for 1 second
40/// Led.off();
41/// }
42///
43/// # extern crate void;
44/// # use void::Void;
45/// # struct Seconds(u32);
46/// # trait U32Ext { fn s(self) -> Seconds; }
47/// # impl U32Ext for u32 { fn s(self) -> Seconds { Seconds(self) } }
48/// # struct Led;
49/// # impl Led {
50/// # pub fn off(&mut self) {}
51/// # pub fn on(&mut self) {}
52/// # }
53/// # struct Timer6;
54/// # impl hal::timer::CountDown for Timer6 {
55/// # type Time = Seconds;
56/// # fn start<T>(&mut self, _: T) where T: Into<Seconds> {}
57/// # fn wait(&mut self) -> ::nb::Result<(), Void> { Ok(()) }
58/// # }
59/// ```
60pub trait CountDown {
61 /// The unit of time used by this timer
62 type Time;
63
64 /// Starts a new count down
65 fn start<T>(&mut self, count: T)
66 where
67 T: Into<Self::Time>;
68
69 /// Non-blockingly "waits" until the count down finishes
70 ///
71 /// # Contract
72 ///
73 /// - If `Self: Periodic`, the timer will start a new count down right after the last one
74 /// finishes.
75 /// - Otherwise the behavior of calling `wait` after the last call returned `Ok` is UNSPECIFIED.
76 /// Implementers are suggested to panic on this scenario to signal a programmer error.
77 fn wait(&mut self) -> nb::Result<(), Void>;
78}
79
80/// Marker trait that indicates that a timer is periodic
81pub trait Periodic {}
82
83/// Trait for cancelable countdowns.
84pub trait Cancel: CountDown {
85 /// Error returned when a countdown can't be canceled.
86 type Error;
87
88 /// Tries to cancel this countdown.
89 ///
90 /// # Errors
91 ///
92 /// An error will be returned if the countdown has already been canceled or was never started.
93 /// An error is also returned if the countdown is not `Periodic` and has already expired.
94 fn cancel(&mut self) -> Result<(), Self::Error>;
95}
96