embedded_hal/
timer.rs

Help
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}
embedded_hal/timer.rs

embedded_hal/
timer.rs
