1 use timer::{HandlePriv, Registration};
2 use Error;
3 
4 use futures::{Future, Poll};
5 
6 use std::time::{Duration, Instant};
7 
8 /// A future that completes at a specified instant in time.
9 ///
10 /// Instances of `Delay` perform no work and complete with `()` once the
11 /// specified deadline has been reached.
12 ///
13 /// `Delay` has a resolution of one millisecond and should not be used for tasks
14 /// that require high-resolution timers.
15 ///
16 /// # Cancellation
17 ///
18 /// Canceling a `Delay` is done by dropping the value. No additional cleanup or
19 /// other work is required.
20 ///
21 /// [`new`]: #method.new
22 #[derive(Debug)]
23 pub struct Delay {
24     /// The link between the `Delay` instance at the timer that drives it.
25     ///
26     /// This also stores the `deadline` value.
27     registration: Registration,
28 }
29 
30 impl Delay {
31     /// Create a new `Delay` instance that elapses at `deadline`.
32     ///
33     /// Only millisecond level resolution is guaranteed. There is no guarantee
34     /// as to how the sub-millisecond portion of `deadline` will be handled.
35     /// `Delay` should not be used for high-resolution timer use cases.
new(deadline: Instant) -> Delay36     pub fn new(deadline: Instant) -> Delay {
37         let registration = Registration::new(deadline, Duration::from_millis(0));
38 
39         Delay { registration }
40     }
41 
new_timeout(deadline: Instant, duration: Duration) -> Delay42     pub(crate) fn new_timeout(deadline: Instant, duration: Duration) -> Delay {
43         let registration = Registration::new(deadline, duration);
44         Delay { registration }
45     }
46 
new_with_handle(deadline: Instant, handle: HandlePriv) -> Delay47     pub(crate) fn new_with_handle(deadline: Instant, handle: HandlePriv) -> Delay {
48         let mut registration = Registration::new(deadline, Duration::from_millis(0));
49         registration.register_with(handle);
50 
51         Delay { registration }
52     }
53 
54     /// Returns the instant at which the future will complete.
deadline(&self) -> Instant55     pub fn deadline(&self) -> Instant {
56         self.registration.deadline()
57     }
58 
59     /// Returns true if the `Delay` has elapsed
60     ///
61     /// A `Delay` is elapsed when the requested duration has elapsed.
is_elapsed(&self) -> bool62     pub fn is_elapsed(&self) -> bool {
63         self.registration.is_elapsed()
64     }
65 
66     /// Reset the `Delay` instance to a new deadline.
67     ///
68     /// Calling this function allows changing the instant at which the `Delay`
69     /// future completes without having to create new associated state.
70     ///
71     /// This function can be called both before and after the future has
72     /// completed.
reset(&mut self, deadline: Instant)73     pub fn reset(&mut self, deadline: Instant) {
74         self.registration.reset(deadline);
75     }
76 
reset_timeout(&mut self)77     pub(crate) fn reset_timeout(&mut self) {
78         self.registration.reset_timeout();
79     }
80 
81     /// Register the delay with the timer instance for the current execution
82     /// context.
register(&mut self)83     fn register(&mut self) {
84         self.registration.register();
85     }
86 }
87 
88 impl Future for Delay {
89     type Item = ();
90     type Error = Error;
91 
poll(&mut self) -> Poll<Self::Item, Self::Error>92     fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
93         // Ensure the `Delay` instance is associated with a timer.
94         self.register();
95 
96         self.registration.poll_elapsed()
97     }
98 }
99