nuclei 0.5.0

Proactive IO & runtime system
Documentation 
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

//! [`Interval`]: ticks at a fixed period.

use core::future::{Future, poll_fn};
use core::pin::Pin;
use core::task::{Context, Poll};
use std::time::Duration;

use super::Instant;

use super::sleep::{Sleep, sleep_until};

/// What an interval does with ticks it missed because it was polled late.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum MissedTickBehavior {
    /// Every missed tick fires as soon as it can, one after the other, until
    /// the interval is back on its schedule.
    #[default]
    Burst,
    /// The next tick comes one period after the late one: the schedule moves.
    Delay,
    /// Missed ticks are skipped: the next tick is the next one on the
    /// original schedule after now.
    Skip,
}

/// Ticks every `period`, the first tick at once.
///
/// # Panics
///
/// If `period` is zero.
pub fn interval(period: Duration) -> Interval {
    interval_at(Instant::now(), period)
}

/// Ticks every `period`, the first tick at `start`.
///
/// # Panics
///
/// If `period` is zero.
pub fn interval_at(start: impl Into<Instant>, period: Duration) -> Interval {
    let start = start.into();
    assert!(
        period > Duration::ZERO,
        "an interval needs a period above zero"
    );
    Interval {
        period,
        sleep: sleep_until(start),
        missed: MissedTickBehavior::default(),
    }
}

/// Ticks at a fixed period. Made by [`interval`] and [`interval_at`].
#[derive(Debug)]
pub struct Interval {
    period: Duration,
    /// Until the next tick.
    sleep: Sleep,
    missed: MissedTickBehavior,
}

impl Interval {
    /// Waits for the next tick and returns the instant it was due at.
    pub async fn tick(&mut self) -> Instant {
        poll_fn(|cx| self.poll_tick(cx)).await
    }

    /// Polls for the next tick; see [`tick`](Self::tick).
    pub fn poll_tick(&mut self, cx: &mut Context<'_>) -> Poll<Instant> {
        if Pin::new(&mut self.sleep).poll(cx).is_pending() {
            return Poll::Pending;
        }
        let due = self.sleep.deadline();
        let now = Instant::now();
        let next = match self.missed {
            MissedTickBehavior::Burst => due + self.period,
            MissedTickBehavior::Delay => now + self.period,
            MissedTickBehavior::Skip => {
                let late = now.saturating_duration_since(due);
                // The next deadline on the schedule after now.
                let periods = late.as_nanos() / self.period.as_nanos() + 1;
                due + self.period * u32::try_from(periods).unwrap_or(u32::MAX)
            }
        };
        Pin::new(&mut self.sleep).reset(next);
        Poll::Ready(due)
    }

    /// Restarts the schedule: the next tick is one period from now.
    pub fn reset(&mut self) {
        Pin::new(&mut self.sleep).reset(Instant::now() + self.period);
    }

    /// The period.
    pub fn period(&self) -> Duration {
        self.period
    }

    /// What happens to missed ticks.
    pub fn missed_tick_behavior(&self) -> MissedTickBehavior {
        self.missed
    }

    /// Sets what happens to missed ticks.
    pub fn set_missed_tick_behavior(&mut self, behavior: MissedTickBehavior) {
        self.missed = behavior;
    }
}