1 //! Support for creating futures that represent timeouts. 2 //! 3 //! This module contains the `Timeout` type which is a future that will resolve 4 //! at a particular point in the future. 5 6 use std::io; 7 use std::time::{Duration, Instant}; 8 9 use futures::{Future, Poll}; 10 use tokio_timer::Delay; 11 12 use reactor::Handle; 13 14 /// A future representing the notification that a timeout has occurred. 15 /// 16 /// Timeouts are created through the `Timeout::new` or 17 /// `Timeout::new_at` methods indicating when a timeout should fire at. 18 /// Note that timeouts are not intended for high resolution timers, but rather 19 /// they will likely fire some granularity after the exact instant that they're 20 /// otherwise indicated to fire at. 21 #[must_use = "futures do nothing unless polled"] 22 #[derive(Debug)] 23 pub struct Timeout { 24 delay: Delay 25 } 26 27 impl Timeout { 28 /// Creates a new timeout which will fire at `dur` time into the future. 29 /// 30 /// This function will return a Result with the actual timeout object or an 31 /// error. The timeout object itself is then a future which will be 32 /// set to fire at the specified point in the future. new(dur: Duration, handle: &Handle) -> io::Result<Timeout>33 pub fn new(dur: Duration, handle: &Handle) -> io::Result<Timeout> { 34 Timeout::new_at(Instant::now() + dur, handle) 35 } 36 37 /// Creates a new timeout which will fire at the time specified by `at`. 38 /// 39 /// This function will return a Result with the actual timeout object or an 40 /// error. The timeout object itself is then a future which will be 41 /// set to fire at the specified point in the future. new_at(at: Instant, handle: &Handle) -> io::Result<Timeout>42 pub fn new_at(at: Instant, handle: &Handle) -> io::Result<Timeout> { 43 Ok(Timeout { 44 delay: handle.remote.timer_handle.delay(at) 45 }) 46 } 47 48 /// Resets this timeout to an new timeout which will fire at the time 49 /// specified by `at`. 50 /// 51 /// This method is usable even of this instance of `Timeout` has "already 52 /// fired". That is, if this future has resolved, calling this method means 53 /// that the future will still re-resolve at the specified instant. 54 /// 55 /// If `at` is in the past then this future will immediately be resolved 56 /// (when `poll` is called). 57 /// 58 /// Note that if any task is currently blocked on this future then that task 59 /// will be dropped. It is required to call `poll` again after this method 60 /// has been called to ensure that a task is blocked on this future. reset(&mut self, at: Instant)61 pub fn reset(&mut self, at: Instant) { 62 self.delay.reset(at) 63 } 64 } 65 66 impl Future for Timeout { 67 type Item = (); 68 type Error = io::Error; 69 poll(&mut self) -> Poll<(), io::Error>70 fn poll(&mut self) -> Poll<(), io::Error> { 71 self.delay.poll() 72 .map_err(|err| io::Error::new(io::ErrorKind::Other, err)) 73 } 74 } 75