      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170

    use crate::future::poll_fn;
    use crate::time::{sleep_until, Duration, Instant, Sleep};

    use std::future::Future;
    use std::pin::Pin;
    use std::task::{Context, Poll};

    /// Creates new `Interval` that yields with interval of `duration`. The first
    /// tick completes immediately.
    ///
    /// An interval will tick indefinitely. At any time, the `Interval` value can be
    /// dropped. This cancels the interval.
    ///
    /// This function is equivalent to `interval_at(Instant::now(), period)`.
    ///
    /// # Panics
    ///
    /// This function panics if `period` is zero.
    ///
    /// # Examples
    ///
    /// ```
    /// use tokio::time::{self, Duration};
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let mut interval = time::interval(Duration::from_millis(10));
    ///
    ///     interval.tick().await;
    ///     interval.tick().await;
    ///     interval.tick().await;
    ///
    ///     // approximately 20ms have elapsed.
    /// }
    /// ```
    ///
    /// A simple example using `interval` to execute a task every two seconds.
    ///
    /// The difference between `interval` and [`sleep`] is that an `interval`
    /// measures the time since the last tick, which means that `.tick().await`
    /// may wait for a shorter time than the duration specified for the interval
    /// if some time has passed between calls to `.tick().await`.
    ///
    /// If the tick in the example below was replaced with [`sleep`], the task
    /// would only be executed once every three seconds, and not every two
    /// seconds.
    ///
    /// ```
    /// use tokio::time;
    ///
    /// async fn task_that_takes_a_second() {
    ///     println!("hello");
    ///     time::sleep(time::Duration::from_secs(1)).await
    /// }
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let mut interval = time::interval(time::Duration::from_secs(2));
    ///     for _i in 0..5 {
    ///         interval.tick().await;
    ///         task_that_takes_a_second().await;
    ///     }
    /// }
    /// ```
    ///
    /// [`sleep`]: crate::time::sleep()
    pub fn interval(period: Duration) -> Interval {
        assert!(period > Duration::new(0, 0), "`period` must be non-zero.");

        interval_at(Instant::now(), period)
    }

    /// Creates new `Interval` that yields with interval of `period` with the
    /// first tick completing at `start`.
    ///
    /// An interval will tick indefinitely. At any time, the `Interval` value can be
    /// dropped. This cancels the interval.
    ///
    /// # Panics
    ///
    /// This function panics if `period` is zero.
    ///
    /// # Examples
    ///
    /// ```
    /// use tokio::time::{interval_at, Duration, Instant};
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let start = Instant::now() + Duration::from_millis(50);
    ///     let mut interval = interval_at(start, Duration::from_millis(10));
    ///
    ///     interval.tick().await;
    ///     interval.tick().await;
    ///     interval.tick().await;
    ///
    ///     // approximately 70ms have elapsed.
    /// }
    /// ```
    pub fn interval_at(start: Instant, period: Duration) -> Interval {
        assert!(period > Duration::new(0, 0), "`period` must be non-zero.");

        Interval {
            delay: Box::pin(sleep_until(start)),
            period,
        }
    }

    /// Stream returned by [`interval`](interval) and [`interval_at`](interval_at).
    #[derive(Debug)]
    pub struct Interval {
        /// Future that completes the next time the `Interval` yields a value.
        delay: Pin<Box<Sleep>>,

        /// The duration between values yielded by `Interval`.
        period: Duration,
    }

    impl Interval {
        /// Completes when the next instant in the interval has been reached.
        ///
        /// # Examples
        ///
        /// ```
        /// use tokio::time;
        ///
        /// use std::time::Duration;
        ///
        /// #[tokio::main]
        /// async fn main() {
        ///     let mut interval = time::interval(Duration::from_millis(10));
        ///
        ///     interval.tick().await;
        ///     interval.tick().await;
        ///     interval.tick().await;
        ///
        ///     // approximately 20ms have elapsed.
        /// }
        /// ```
        pub async fn tick(&mut self) -> Instant {
            poll_fn(|cx| self.poll_tick(cx)).await
        }

        /// Poll for the next instant in the interval to be reached.
        ///
        /// This method can return the following values:
        ///
        ///  * `Poll::Pending` if the next instant has not yet been reached.
        ///  * `Poll::Ready(instant)` if the next instant has been reached.
        ///
        /// When this method returns `Poll::Pending`, the current task is scheduled
        /// to receive a wakeup when the instant has elapsed. Note that on multiple
        /// calls to `poll_tick`, only the `Waker` from the `Context` passed to the
        /// most recent call is scheduled to receive a wakeup.
        pub fn poll_tick(&mut self, cx: &mut Context<'_>) -> Poll<Instant> {
            // Wait for the delay to be done
            ready!(Pin::new(&mut self.delay).poll(cx));

            // Get the `now` by looking at the `delay` deadline
            let now = self.delay.deadline();

            // The next interval value is `duration` after the one that just
            // yielded.
            let next = now + self.period;
            self.delay.as_mut().reset(next);

            // Return the current instant
            Poll::Ready(now)
        }
    }