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
//! Sleeping, with units.
//!
//! Every call here turns a [`Duration`](core::time::Duration) into the kernel's only clock
//! — the slice tick — and hands it to the scheduler, which *records the deadline* and
//! switches the caller away until it is reached. Nothing here spins: a sleeping task costs
//! no CPU, and no other task's load can stretch its sleep.
//!
//! The resolution is one slice. Durations are therefore **rounded up**, never down: asking
//! to sleep 1 ns sleeps a tick, because returning early would be a lie about the contract.
//!
//! ```ignore
//! use core::time::Duration;
//!
//! rrkernel::sleep(Duration::from_millis(250)); // explicit
//! rrkernel::sleep_ms(250); // shorthand
//! rrkernel::sleep_us(500);
//! rrkernel::sleep_secs(1);
//! rrkernel::sleep_minutes(2);
//! rrkernel::sleep_hours(1);
//!
//! // Periodic work that must not drift: schedule the *next* absolute deadline from the
//! // previous one, not from "now", so a late wake-up is corrected instead of accumulated.
//! let period = Duration::from_millis(100);
//! let mut next = rrkernel::deadline_after(period);
//! loop {
//! rrkernel::sleep_until(next);
//! let _ = rrkernel::now();
//! next = rrkernel::deadline_add(next, period);
//! }
//! ```
use cratescheduler;
use Duration;
/// How long one tick lasts, in nanoseconds: the resolution of every sleep in this module.
/// Ticks needed to cover `d`, rounded **up**. Public because periodic code needs it to
/// decide whether it fell more than a whole period behind.
/// The current tick, i.e. the kernel's clock since `configure(...)`.
/// Sleep for `d` (rounded up to a whole tick). Returns once the deadline is reached; the
/// caller is *not* on the CPU in between.
/// An absolute deadline `d` from now — the starting point for drift-free periodic work.
/// `deadline + d`: the next period from a previous absolute deadline.
/// Sleep until an absolute deadline from [`deadline_after`] / [`deadline_add`]. Already
/// being past the deadline is not an error: it returns immediately, and the caller decides
/// whether to skip ahead (see [`ticks_for`]).
///
/// This re-checks the deadline in a loop, so a wake-up that arrives early is harmless — it just
/// blocks again. (A clock that jumps forward is a different fault: see
/// [`crate::scheduler::sleep_until_tick`].)
/// Sleep for `ns` nanoseconds (rounded up to a whole tick).
/// Sleep for `us` microseconds (rounded up to a whole tick).
/// Sleep for `ms` milliseconds (rounded up to a whole tick). The natural shorthand when the
/// slice is 1 ms.
/// Sleep for `secs` seconds.
/// Sleep for `mins` minutes.
/// Sleep for `hours` hours.