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