wheel_machines 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +95 -0
- data/Cargo.lock +314 -0
- data/Cargo.toml +28 -0
- data/LICENSE.txt +21 -0
- data/README.md +316 -0
- data/ext/wheel_machines_native/core/CHANGELOG.md +70 -0
- data/ext/wheel_machines_native/core/Cargo.toml +20 -0
- data/ext/wheel_machines_native/core/README.md +119 -0
- data/ext/wheel_machines_native/core/src/lib.rs +535 -0
- data/ext/wheel_machines_native/core/src/test_support.rs +56 -0
- data/ext/wheel_machines_native/core/src/values.rs +104 -0
- data/ext/wheel_machines_native/extconf.rb +2 -0
- data/ext/wheel_machines_native/ffi/Cargo.toml +21 -0
- data/ext/wheel_machines_native/ffi/extconf.rb +14 -0
- data/ext/wheel_machines_native/ffi/src/init.rs +43 -0
- data/ext/wheel_machines_native/ffi/src/lib.rs +206 -0
- data/ext/wheel_machines_native/ffi/src/values.rs +105 -0
- data/lib/wheel_machines/version.rb +5 -0
- data/lib/wheel_machines.rb +65 -0
- data/sig/wheel_machines.rbs +89 -0
- metadata +87 -0
|
@@ -0,0 +1,535 @@
|
|
|
1
|
+
#![no_std]
|
|
2
|
+
#![doc = include_str!("../README.md")]
|
|
3
|
+
|
|
4
|
+
#[cfg(test)]
|
|
5
|
+
extern crate std;
|
|
6
|
+
|
|
7
|
+
use core::fmt;
|
|
8
|
+
|
|
9
|
+
use periscope_machines::{Issuer, scope_of};
|
|
10
|
+
|
|
11
|
+
mod values;
|
|
12
|
+
|
|
13
|
+
pub use values::{Drain, Due, Status};
|
|
14
|
+
|
|
15
|
+
/// Wheel levels; eleven six-bit digits cover every `u64` tick.
|
|
16
|
+
const LEVELS: usize = 11;
|
|
17
|
+
/// Slots per level.
|
|
18
|
+
const SLOTS: usize = 64;
|
|
19
|
+
/// Bits of the tick consumed by one level.
|
|
20
|
+
const BITS: usize = 6;
|
|
21
|
+
/// The low `BITS` bits of a tick: its digit within one level.
|
|
22
|
+
const DIGIT_MASK: u64 = SLOTS as u64 - 1;
|
|
23
|
+
/// "No node" link.
|
|
24
|
+
const NIL: usize = usize::MAX;
|
|
25
|
+
|
|
26
|
+
/// Most cascade moves one registration can ever be charged before it is due.
|
|
27
|
+
pub const MAX_CASCADES: usize = LEVELS - 1;
|
|
28
|
+
|
|
29
|
+
/// Opaque registration: the entry it sits in and the scoped id it was issued
|
|
30
|
+
/// under. Only the wheel that issued it honours it.
|
|
31
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
32
|
+
pub struct Handle {
|
|
33
|
+
slot: usize,
|
|
34
|
+
/// Scoped id from the wheel's issuer; never reissued.
|
|
35
|
+
key: u64,
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
impl Handle {
|
|
39
|
+
/// The scope of the wheel that issued this handle.
|
|
40
|
+
#[must_use]
|
|
41
|
+
pub const fn scope(&self) -> u16 {
|
|
42
|
+
scope_of(self.key)
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/// Why a call was refused. A refused call changes nothing: not the tick, not
|
|
47
|
+
/// a registration, not an issued id.
|
|
48
|
+
///
|
|
49
|
+
/// This is the crate's one refusal type. [`Wheel::register`] answers
|
|
50
|
+
/// [`Elapsed`](Self::Elapsed), [`Full`](Self::Full) or
|
|
51
|
+
/// [`Exhausted`](Self::Exhausted); [`Wheel::cancel`] answers
|
|
52
|
+
/// [`Stale`](Self::Stale); [`Wheel::advance`] and [`Wheel::tick`] answer
|
|
53
|
+
/// [`Regressed`](Self::Regressed). [`Wheel::drain`] never refuses.
|
|
54
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
55
|
+
pub enum Refusal {
|
|
56
|
+
/// The deadline is at or before the wheel's tick: it is due now, and the
|
|
57
|
+
/// caller already knows it.
|
|
58
|
+
Elapsed,
|
|
59
|
+
/// Every entry is in use by a registration that is neither cancelled nor drained.
|
|
60
|
+
Full,
|
|
61
|
+
/// Every handle id of this wheel's scope has been issued; none is reissued.
|
|
62
|
+
Exhausted,
|
|
63
|
+
/// The tick is earlier than the one the wheel already holds.
|
|
64
|
+
Regressed {
|
|
65
|
+
/// The tick the wheel holds.
|
|
66
|
+
now: u64,
|
|
67
|
+
},
|
|
68
|
+
/// The handle does not name a live registration: it was already cancelled
|
|
69
|
+
/// or drained, or this wheel never issued it (another scope, or an id not
|
|
70
|
+
/// issued yet).
|
|
71
|
+
Stale,
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
impl fmt::Display for Refusal {
|
|
75
|
+
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
76
|
+
match self {
|
|
77
|
+
Self::Elapsed => f.write_str("deadline is not after the wheel's tick"),
|
|
78
|
+
Self::Full => f.write_str("every entry is in use"),
|
|
79
|
+
Self::Exhausted => f.write_str("every handle of this scope has been issued"),
|
|
80
|
+
Self::Regressed { now } => write!(f, "tick is earlier than the wheel's tick {now}"),
|
|
81
|
+
Self::Stale => f.write_str("handle does not name a live registration"),
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
impl core::error::Error for Refusal {}
|
|
87
|
+
|
|
88
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
89
|
+
struct Node<I> {
|
|
90
|
+
/// `None` while the entry is on the free list.
|
|
91
|
+
id: Option<I>,
|
|
92
|
+
deadline: u64,
|
|
93
|
+
/// Scoped id of the registration last filed here.
|
|
94
|
+
key: u64,
|
|
95
|
+
prev: usize,
|
|
96
|
+
next: usize,
|
|
97
|
+
level: usize,
|
|
98
|
+
slot: usize,
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
impl<I> Node<I> {
|
|
102
|
+
const FREE: Self = Self {
|
|
103
|
+
id: None,
|
|
104
|
+
deadline: 0,
|
|
105
|
+
key: 0,
|
|
106
|
+
prev: NIL,
|
|
107
|
+
next: NIL,
|
|
108
|
+
level: 0,
|
|
109
|
+
slot: 0,
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/// Fixed-capacity hierarchical timing wheel over caller-supplied ticks.
|
|
114
|
+
///
|
|
115
|
+
/// Index invariants the list primitives (`settle`, `push_back`, `unlink`,
|
|
116
|
+
/// `release`, `register`) index on directly, because they are `const fn` and
|
|
117
|
+
/// `<[T]>::get` is not callable there: `free`, every `heads` cell and every
|
|
118
|
+
/// filed node's `prev`/`next` is `NIL` or below `N`, and `NIL` is checked
|
|
119
|
+
/// before it is followed; a handle's slot is bounds-checked once, in `lookup`.
|
|
120
|
+
/// Every level is below `LEVELS` (`level_of` answers at most 63 / 6 = 10 and
|
|
121
|
+
/// `next_slot` enumerates `occupied`) and every slot below `SLOTS` (a six-bit
|
|
122
|
+
/// `digit`, or `trailing_zeros` of a non-zero `u64`).
|
|
123
|
+
///
|
|
124
|
+
/// Holds at most `N` registrations of ids `I`. Eleven levels of 64 slots index
|
|
125
|
+
/// every `u64` deadline, so no deadline is too far away. The wheel has no
|
|
126
|
+
/// clock: [`Wheel::advance`] is the only way its tick moves.
|
|
127
|
+
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
128
|
+
pub struct Wheel<I, const N: usize> {
|
|
129
|
+
nodes: [Node<I>; N],
|
|
130
|
+
/// First node of each slot's circular list, or `NIL`.
|
|
131
|
+
heads: [[usize; SLOTS]; LEVELS],
|
|
132
|
+
/// One bit per non-empty slot.
|
|
133
|
+
occupied: [u64; LEVELS],
|
|
134
|
+
/// Slot whose entries are being moved down; finished before anything else.
|
|
135
|
+
cascade: Option<(usize, usize)>,
|
|
136
|
+
free: usize,
|
|
137
|
+
len: usize,
|
|
138
|
+
/// Tick the slots are indexed against; trails `now` while a drain is pending.
|
|
139
|
+
elapsed: u64,
|
|
140
|
+
now: u64,
|
|
141
|
+
issuer: Issuer,
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
impl<I: Copy, const N: usize> Default for Wheel<I, N> {
|
|
145
|
+
fn default() -> Self {
|
|
146
|
+
Self::new()
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
impl<I: Copy, const N: usize> Wheel<I, N> {
|
|
151
|
+
/// Empty wheel at tick zero, in scope zero, with no handle issued.
|
|
152
|
+
#[must_use]
|
|
153
|
+
pub const fn new() -> Self {
|
|
154
|
+
Self::with_scope(0)
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/// Empty wheel at tick zero whose handles carry `scope`.
|
|
158
|
+
///
|
|
159
|
+
/// Handles are only meaningful to the wheel that issued them. Two wheels
|
|
160
|
+
/// in the same scope issue the same handles, so give every wheel whose
|
|
161
|
+
/// handles could meet its own scope.
|
|
162
|
+
#[must_use]
|
|
163
|
+
pub const fn with_scope(scope: u16) -> Self {
|
|
164
|
+
Self::starting_at(scope, 0)
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/// Empty wheel whose handles carry `scope` and whose tick starts at `now`.
|
|
168
|
+
#[must_use]
|
|
169
|
+
pub const fn starting_at(scope: u16, now: u64) -> Self {
|
|
170
|
+
Self::build(Issuer::new(scope), now)
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/// Empty wheel that continues `scope` after a restart: `issued` is what
|
|
174
|
+
/// [`Wheel::issued`] answered when the caller saved it, and the tick
|
|
175
|
+
/// starts at `now`.
|
|
176
|
+
///
|
|
177
|
+
/// Only the handle sequence is restored. Nothing is registered: every
|
|
178
|
+
/// handle issued before the restart is [`Refusal::Stale`] here, and
|
|
179
|
+
/// re-registering what was pending is the caller's job. The next handle
|
|
180
|
+
/// carries sequence `issued + 1`, so none is reissued as long as the saved
|
|
181
|
+
/// count is not lower than what the wheel had really issued; save it
|
|
182
|
+
/// before handing a handle out.
|
|
183
|
+
///
|
|
184
|
+
/// `None` when `issued` is beyond `periscope_machines::SEQUENCE_MAX`,
|
|
185
|
+
/// which no wheel reaches.
|
|
186
|
+
#[must_use]
|
|
187
|
+
pub const fn resumed(scope: u16, issued: u64, now: u64) -> Option<Self> {
|
|
188
|
+
match Issuer::resumed(scope, issued) {
|
|
189
|
+
Some(sequence) => Some(Self::build(sequence, now)),
|
|
190
|
+
None => None,
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
const fn build(issuer: Issuer, now: u64) -> Self {
|
|
195
|
+
let mut nodes = [Node::<I>::FREE; N];
|
|
196
|
+
let mut index = 0;
|
|
197
|
+
while index < N {
|
|
198
|
+
nodes[index].next = if index + 1 < N { index + 1 } else { NIL };
|
|
199
|
+
index += 1;
|
|
200
|
+
}
|
|
201
|
+
Self {
|
|
202
|
+
nodes,
|
|
203
|
+
heads: [[NIL; SLOTS]; LEVELS],
|
|
204
|
+
occupied: [0; LEVELS],
|
|
205
|
+
cascade: None,
|
|
206
|
+
free: if N == 0 { NIL } else { 0 },
|
|
207
|
+
len: 0,
|
|
208
|
+
elapsed: now,
|
|
209
|
+
now,
|
|
210
|
+
issuer,
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/// The scope carried by every handle this wheel issues.
|
|
215
|
+
#[must_use]
|
|
216
|
+
pub const fn scope(&self) -> u16 {
|
|
217
|
+
self.issuer.scope()
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/// Handles issued in this scope so far, live or not: the count to save
|
|
221
|
+
/// for [`Wheel::resumed`].
|
|
222
|
+
#[must_use]
|
|
223
|
+
pub const fn issued(&self) -> u64 {
|
|
224
|
+
self.issuer.issued()
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/// Compiled capacity `N`.
|
|
228
|
+
#[must_use]
|
|
229
|
+
pub const fn capacity(&self) -> usize {
|
|
230
|
+
N
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/// Registrations neither cancelled nor drained, due ones included.
|
|
234
|
+
#[must_use]
|
|
235
|
+
pub const fn len(&self) -> usize {
|
|
236
|
+
self.len
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/// `true` when nothing is registered.
|
|
240
|
+
#[must_use]
|
|
241
|
+
pub const fn is_empty(&self) -> bool {
|
|
242
|
+
self.len == 0
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/// The latest tick accepted by [`Wheel::advance`].
|
|
246
|
+
#[must_use]
|
|
247
|
+
pub const fn now(&self) -> u64 {
|
|
248
|
+
self.now
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/// Deadline of a live registration; `None` for a handle that names none,
|
|
252
|
+
/// one this wheel never issued included.
|
|
253
|
+
#[must_use]
|
|
254
|
+
pub fn deadline(&self, handle: Handle) -> Option<u64> {
|
|
255
|
+
self.lookup(handle)
|
|
256
|
+
.and_then(|(index, _)| self.nodes.get(index))
|
|
257
|
+
.map(|node| node.deadline)
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/// Tick at which a drain next has work: never later than the earliest
|
|
261
|
+
/// registered deadline, and equal to [`Wheel::now`] when work is already
|
|
262
|
+
/// pending. `None` when the wheel is empty.
|
|
263
|
+
///
|
|
264
|
+
/// It can be earlier than the earliest deadline: a far entry is first
|
|
265
|
+
/// visited to be cascaded, not emitted.
|
|
266
|
+
#[must_use]
|
|
267
|
+
pub fn next_wake(&self) -> Option<u64> {
|
|
268
|
+
let (level, slot) = self.next_slot()?;
|
|
269
|
+
let start = match self.cascade {
|
|
270
|
+
Some((level, slot)) if self.heads[level][slot] != NIL => self.elapsed,
|
|
271
|
+
Some(_) | None => slot_start(self.elapsed, level, slot),
|
|
272
|
+
};
|
|
273
|
+
Some(start.max(self.now))
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/// Index `id` to become due at tick `deadline`, which must be after
|
|
277
|
+
/// [`Wheel::now`]. A refusal changes nothing.
|
|
278
|
+
///
|
|
279
|
+
/// # Errors
|
|
280
|
+
///
|
|
281
|
+
/// [`Refusal::Elapsed`] for a deadline at or before the tick,
|
|
282
|
+
/// [`Refusal::Full`] when all `N` entries are in use, and
|
|
283
|
+
/// [`Refusal::Exhausted`] once all `periscope_machines::SEQUENCE_MAX`
|
|
284
|
+
/// (2^48 - 1) handle ids of the wheel's scope have been issued.
|
|
285
|
+
pub const fn register(&mut self, id: I, deadline: u64) -> Result<Handle, Refusal> {
|
|
286
|
+
if deadline <= self.now {
|
|
287
|
+
return Err(Refusal::Elapsed);
|
|
288
|
+
}
|
|
289
|
+
if self.free == NIL {
|
|
290
|
+
return Err(Refusal::Full);
|
|
291
|
+
}
|
|
292
|
+
// Last check: an id is only spent on a registration that is honoured.
|
|
293
|
+
let key = match self.issuer.issue() {
|
|
294
|
+
Ok(key) => key,
|
|
295
|
+
Err(periscope_machines::Refusal::Exhausted) => return Err(Refusal::Exhausted),
|
|
296
|
+
};
|
|
297
|
+
let index = self.free;
|
|
298
|
+
self.free = self.nodes[index].next;
|
|
299
|
+
// A free entry exists, so fewer than `N` are live: no overflow.
|
|
300
|
+
self.len += 1;
|
|
301
|
+
let node = &mut self.nodes[index];
|
|
302
|
+
node.id = Some(id);
|
|
303
|
+
node.deadline = deadline;
|
|
304
|
+
node.key = key;
|
|
305
|
+
// A deadline inside the range being cascaded queues behind the entries
|
|
306
|
+
// still waiting there, so equal deadlines keep registration order.
|
|
307
|
+
match self.cascade {
|
|
308
|
+
Some((level, slot)) if level_of(self.elapsed, deadline) < level => {
|
|
309
|
+
self.push_back(level, slot, index);
|
|
310
|
+
}
|
|
311
|
+
Some(_) | None => self.settle(index),
|
|
312
|
+
}
|
|
313
|
+
Ok(Handle { slot: index, key })
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/// Remove a registration that has not been emitted, returning its id.
|
|
317
|
+
///
|
|
318
|
+
/// # Errors
|
|
319
|
+
///
|
|
320
|
+
/// [`Refusal::Stale`] for a handle that does not name a live registration:
|
|
321
|
+
/// already cancelled, already drained, or never issued by this wheel
|
|
322
|
+
/// (another scope). The wheel is unchanged. A repeat on a dead handle is
|
|
323
|
+
/// never honoured: the wheel keeps no record of how a registration ended.
|
|
324
|
+
pub fn cancel(&mut self, handle: Handle) -> Result<I, Refusal> {
|
|
325
|
+
let (index, id) = self.lookup(handle).ok_or(Refusal::Stale)?;
|
|
326
|
+
Ok(self.release(index, id).id)
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/// Move the wheel's tick forward. Emits nothing; call [`Wheel::drain`].
|
|
330
|
+
///
|
|
331
|
+
/// # Errors
|
|
332
|
+
///
|
|
333
|
+
/// [`Refusal::Regressed`] when `now` is earlier than the tick already
|
|
334
|
+
/// held; the wheel is unchanged. Repeating the current tick is accepted.
|
|
335
|
+
pub const fn advance(&mut self, now: u64) -> Result<(), Refusal> {
|
|
336
|
+
if now < self.now {
|
|
337
|
+
return Err(Refusal::Regressed { now: self.now });
|
|
338
|
+
}
|
|
339
|
+
self.now = now;
|
|
340
|
+
Ok(())
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/// Emit ids due at [`Wheel::now`] into the front of `out`, doing at most
|
|
344
|
+
/// `budget` work units. Each emitted id and each cascade move costs one.
|
|
345
|
+
///
|
|
346
|
+
/// Ids come out in deadline order, equal deadlines in registration order.
|
|
347
|
+
/// The call stops when caught up, when `out` is full, or when the budget is
|
|
348
|
+
/// spent; call again to resume exactly where it stopped. It never moves the
|
|
349
|
+
/// tick.
|
|
350
|
+
pub fn drain(&mut self, budget: usize, out: &mut [Due<I>]) -> Drain {
|
|
351
|
+
let mut drain = Drain {
|
|
352
|
+
emitted: 0,
|
|
353
|
+
cascaded: 0,
|
|
354
|
+
status: Status::CaughtUp,
|
|
355
|
+
};
|
|
356
|
+
loop {
|
|
357
|
+
if let Some((level, slot)) = self.cascade {
|
|
358
|
+
loop {
|
|
359
|
+
let head = self.heads[level][slot];
|
|
360
|
+
if head == NIL {
|
|
361
|
+
break;
|
|
362
|
+
}
|
|
363
|
+
if !drain.affords(budget) {
|
|
364
|
+
return drain;
|
|
365
|
+
}
|
|
366
|
+
self.unlink(head);
|
|
367
|
+
self.settle(head);
|
|
368
|
+
drain.cascaded += 1;
|
|
369
|
+
}
|
|
370
|
+
self.cascade = None;
|
|
371
|
+
}
|
|
372
|
+
let next = self
|
|
373
|
+
.next_slot()
|
|
374
|
+
.map(|(level, slot)| (level, slot, slot_start(self.elapsed, level, slot)));
|
|
375
|
+
let Some((level, slot, start)) = next.filter(|next| next.2 <= self.now) else {
|
|
376
|
+
self.elapsed = self.now;
|
|
377
|
+
return drain;
|
|
378
|
+
};
|
|
379
|
+
self.elapsed = start;
|
|
380
|
+
if level > 0 {
|
|
381
|
+
self.cascade = Some((level, slot));
|
|
382
|
+
continue;
|
|
383
|
+
}
|
|
384
|
+
loop {
|
|
385
|
+
let head = self.heads[0][slot];
|
|
386
|
+
if head == NIL {
|
|
387
|
+
break;
|
|
388
|
+
}
|
|
389
|
+
if !drain.affords(budget) {
|
|
390
|
+
return drain;
|
|
391
|
+
}
|
|
392
|
+
let Some(place) = out.get_mut(drain.emitted) else {
|
|
393
|
+
drain.status = Status::OutputFull;
|
|
394
|
+
return drain;
|
|
395
|
+
};
|
|
396
|
+
let Some(id) = self.nodes[head].id else {
|
|
397
|
+
debug_assert!(false, "every entry filed in a slot is live");
|
|
398
|
+
// The one arm that cannot stop with nothing changed: a
|
|
399
|
+
// drain that left this entry filed would find it first on
|
|
400
|
+
// every call and never emit what is due behind it, so the
|
|
401
|
+
// wheel would stall for good. Taking it off the slot is the
|
|
402
|
+
// conservative move: it is already on the free list, so
|
|
403
|
+
// unlinking it frees nothing twice and emits nothing.
|
|
404
|
+
self.unlink(head);
|
|
405
|
+
continue;
|
|
406
|
+
};
|
|
407
|
+
*place = self.release(head, id);
|
|
408
|
+
drain.emitted += 1;
|
|
409
|
+
}
|
|
410
|
+
}
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
/// [`Wheel::advance`] then [`Wheel::drain`] in one call.
|
|
414
|
+
///
|
|
415
|
+
/// # Errors
|
|
416
|
+
///
|
|
417
|
+
/// [`Refusal::Regressed`] when `now` is earlier than the tick already
|
|
418
|
+
/// held; nothing is drained, `out` is not written and the wheel is
|
|
419
|
+
/// unchanged.
|
|
420
|
+
pub fn tick(&mut self, now: u64, budget: usize, out: &mut [Due<I>]) -> Result<Drain, Refusal> {
|
|
421
|
+
self.advance(now)?;
|
|
422
|
+
Ok(self.drain(budget, out))
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
/// Origin first: a handle this wheel's issuer never handed out names
|
|
426
|
+
/// nothing here, whatever entry it points at. Answers the live entry and
|
|
427
|
+
/// its id.
|
|
428
|
+
fn lookup(&self, handle: Handle) -> Option<(usize, I)> {
|
|
429
|
+
if !self.issuer.owns(handle.key) {
|
|
430
|
+
return None;
|
|
431
|
+
}
|
|
432
|
+
let node = self.nodes.get(handle.slot)?;
|
|
433
|
+
let id = node.id.filter(|_| node.key == handle.key)?;
|
|
434
|
+
Some((handle.slot, id))
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
/// Earliest non-empty slot: lower levels always expire before higher ones,
|
|
438
|
+
/// and within a level the lowest set bit is the soonest.
|
|
439
|
+
fn next_slot(&self) -> Option<(usize, usize)> {
|
|
440
|
+
self.occupied
|
|
441
|
+
.iter()
|
|
442
|
+
.enumerate()
|
|
443
|
+
.find(|(_, bits)| **bits != 0)
|
|
444
|
+
.map(|(level, bits)| (level, bits.trailing_zeros() as usize))
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
/// File a node under the slot its deadline has relative to `elapsed`.
|
|
448
|
+
const fn settle(&mut self, index: usize) {
|
|
449
|
+
let deadline = self.nodes[index].deadline;
|
|
450
|
+
let level = level_of(self.elapsed, deadline);
|
|
451
|
+
self.push_back(level, digit(deadline, level), index);
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
const fn push_back(&mut self, level: usize, slot: usize, index: usize) {
|
|
455
|
+
let head = self.heads[level][slot];
|
|
456
|
+
if head == NIL {
|
|
457
|
+
self.heads[level][slot] = index;
|
|
458
|
+
self.occupied[level] |= 1 << slot;
|
|
459
|
+
self.nodes[index].prev = index;
|
|
460
|
+
self.nodes[index].next = index;
|
|
461
|
+
} else {
|
|
462
|
+
let tail = self.nodes[head].prev;
|
|
463
|
+
self.nodes[index].prev = tail;
|
|
464
|
+
self.nodes[index].next = head;
|
|
465
|
+
self.nodes[tail].next = index;
|
|
466
|
+
self.nodes[head].prev = index;
|
|
467
|
+
}
|
|
468
|
+
self.nodes[index].level = level;
|
|
469
|
+
self.nodes[index].slot = slot;
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
const fn unlink(&mut self, index: usize) {
|
|
473
|
+
let Node {
|
|
474
|
+
prev,
|
|
475
|
+
next,
|
|
476
|
+
level,
|
|
477
|
+
slot,
|
|
478
|
+
..
|
|
479
|
+
} = self.nodes[index];
|
|
480
|
+
if next == index {
|
|
481
|
+
self.heads[level][slot] = NIL;
|
|
482
|
+
self.occupied[level] &= !(1 << slot);
|
|
483
|
+
} else {
|
|
484
|
+
self.nodes[prev].next = next;
|
|
485
|
+
self.nodes[next].prev = prev;
|
|
486
|
+
if self.heads[level][slot] == index {
|
|
487
|
+
self.heads[level][slot] = next;
|
|
488
|
+
}
|
|
489
|
+
}
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
/// Unlink a live node holding `id` and return it to the free list.
|
|
493
|
+
const fn release(&mut self, index: usize, id: I) -> Due<I> {
|
|
494
|
+
self.unlink(index);
|
|
495
|
+
let node = &mut self.nodes[index];
|
|
496
|
+
node.id = None;
|
|
497
|
+
node.next = self.free;
|
|
498
|
+
self.free = index;
|
|
499
|
+
// `index` held a live registration, so `len` is at least one.
|
|
500
|
+
self.len -= 1;
|
|
501
|
+
Due {
|
|
502
|
+
id,
|
|
503
|
+
deadline: node.deadline,
|
|
504
|
+
}
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/// Level of the highest six-bit digit in which `deadline` differs from `elapsed`.
|
|
509
|
+
const fn level_of(elapsed: u64, deadline: u64) -> usize {
|
|
510
|
+
// Setting the lowest digit puts equal ticks on level zero.
|
|
511
|
+
// `masked` is at least `DIGIT_MASK`, so it has at most 58 leading zeros.
|
|
512
|
+
let masked = (elapsed ^ deadline) | DIGIT_MASK;
|
|
513
|
+
(u64::BITS - 1 - masked.leading_zeros()) as usize / BITS
|
|
514
|
+
}
|
|
515
|
+
|
|
516
|
+
/// The six-bit digit of `tick` at `level`.
|
|
517
|
+
const fn digit(tick: u64, level: usize) -> usize {
|
|
518
|
+
((tick >> (BITS * level)) & DIGIT_MASK) as usize
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
/// First tick covered by `slot` of `level` in the rotation `elapsed` is in.
|
|
522
|
+
const fn slot_start(elapsed: u64, level: usize, slot: usize) -> u64 {
|
|
523
|
+
let shift = BITS * (level + 1);
|
|
524
|
+
let high = if shift >= u64::BITS as usize {
|
|
525
|
+
0
|
|
526
|
+
} else {
|
|
527
|
+
(elapsed >> shift) << shift
|
|
528
|
+
};
|
|
529
|
+
high | ((slot as u64) << (BITS * level))
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
#[cfg(test)]
|
|
533
|
+
mod test_support;
|
|
534
|
+
#[cfg(test)]
|
|
535
|
+
mod tests;
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
//! Helpers shared by the crate's test modules.
|
|
2
|
+
|
|
3
|
+
use std::vec::Vec;
|
|
4
|
+
|
|
5
|
+
use crate::{BITS, Due, LEVELS, Refusal, Wheel};
|
|
6
|
+
|
|
7
|
+
/// A wheel resumed after `issued` handle ids, to reach the end of the sequence.
|
|
8
|
+
pub fn resumed<const N: usize>(scope: u16, issued: u64, now: u64) -> Wheel<u64, N> {
|
|
9
|
+
let Some(wheel) = Wheel::resumed(scope, issued, now) else {
|
|
10
|
+
panic!("{issued} is past the last sequence of a scope");
|
|
11
|
+
};
|
|
12
|
+
wheel
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/// The tests' deterministic draws.
|
|
16
|
+
pub use matryona_machines::testing::SplitMix64 as Rng;
|
|
17
|
+
|
|
18
|
+
/// What the tests draw besides `below`.
|
|
19
|
+
pub trait Draws {
|
|
20
|
+
/// An index into a collection of `len` elements.
|
|
21
|
+
fn pick(&mut self, len: usize) -> usize;
|
|
22
|
+
/// A span whose magnitude is uniform over the wheel's eleven levels.
|
|
23
|
+
fn span(&mut self) -> u64;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
impl Draws for Rng {
|
|
27
|
+
fn pick(&mut self, len: usize) -> usize {
|
|
28
|
+
usize::try_from(self.below(len as u64)).unwrap_or(0)
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
fn span(&mut self) -> u64 {
|
|
32
|
+
let level = self.below(LEVELS as u64);
|
|
33
|
+
1 + self.below(1 << (BITS as u64 * level))
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/// The value of an honoured call; panics with the refusal otherwise.
|
|
38
|
+
pub fn honoured<T: core::fmt::Debug>(result: Result<T, Refusal>) -> T {
|
|
39
|
+
match result {
|
|
40
|
+
Ok(value) => value,
|
|
41
|
+
Err(refusal) => panic!("expected an honoured call, got {refusal:?}"),
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/// Drain to completion with a roomy budget and return the emitted ids.
|
|
46
|
+
pub fn drain_ids<const N: usize>(wheel: &mut Wheel<u64, N>) -> Vec<u64> {
|
|
47
|
+
let mut ids = Vec::new();
|
|
48
|
+
loop {
|
|
49
|
+
let mut out = [Due::new(0, 0); 4];
|
|
50
|
+
let drain = wheel.drain(64, &mut out);
|
|
51
|
+
ids.extend(out[..drain.emitted].iter().map(|due| due.id));
|
|
52
|
+
if drain.is_caught_up() {
|
|
53
|
+
return ids;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
//! What a drain hands back: the due entries and what the call did.
|
|
2
|
+
|
|
3
|
+
/// One due registration: the caller's id and the deadline it was registered with.
|
|
4
|
+
///
|
|
5
|
+
/// `Due::default()` (for `I: Default`) is a placeholder for pre-filling a
|
|
6
|
+
/// drain buffer: its deadline is 0, which is always [`Refusal::Elapsed`], so
|
|
7
|
+
/// the wheel never emits it.
|
|
8
|
+
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
|
|
9
|
+
pub struct Due<I> {
|
|
10
|
+
/// Caller-supplied identifier.
|
|
11
|
+
pub id: I,
|
|
12
|
+
/// Tick the id was registered for; `now - deadline` is its lateness.
|
|
13
|
+
pub deadline: u64,
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
impl<I> Due<I> {
|
|
17
|
+
/// Build a value, typically to compare against a drained one or to
|
|
18
|
+
/// pre-fill a drain buffer when `I` has no `Default`.
|
|
19
|
+
#[must_use]
|
|
20
|
+
pub const fn new(id: I, deadline: u64) -> Self {
|
|
21
|
+
Self { id, deadline }
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/// Why a drain call returned.
|
|
26
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
27
|
+
pub enum Status {
|
|
28
|
+
/// Every id due at the wheel's tick has been emitted; nothing is left to do
|
|
29
|
+
/// until the tick advances.
|
|
30
|
+
CaughtUp,
|
|
31
|
+
/// The output buffer is full and more ids are due; drain again.
|
|
32
|
+
OutputFull,
|
|
33
|
+
/// The work budget is spent and work remains; drain again.
|
|
34
|
+
BudgetSpent,
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/// What one drain call did.
|
|
38
|
+
///
|
|
39
|
+
/// Its work, emitted ids plus cascade moves, always fits a `usize`: the
|
|
40
|
+
/// wheel never charges more than the budget it was given, and
|
|
41
|
+
/// [`Drain::new`] refuses a pair whose sum would not fit.
|
|
42
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
43
|
+
pub struct Drain {
|
|
44
|
+
pub(crate) emitted: usize,
|
|
45
|
+
pub(crate) cascaded: usize,
|
|
46
|
+
pub(crate) status: Status,
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
impl Drain {
|
|
50
|
+
/// Build a value, typically to compare against a drained one. `None`
|
|
51
|
+
/// when `emitted + cascaded` does not fit a `usize`: no drain charges
|
|
52
|
+
/// that much work.
|
|
53
|
+
#[must_use]
|
|
54
|
+
pub const fn new(emitted: usize, cascaded: usize, status: Status) -> Option<Self> {
|
|
55
|
+
if emitted.checked_add(cascaded).is_none() {
|
|
56
|
+
return None;
|
|
57
|
+
}
|
|
58
|
+
Some(Self {
|
|
59
|
+
emitted,
|
|
60
|
+
cascaded,
|
|
61
|
+
status,
|
|
62
|
+
})
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/// Due ids written to the front of the output buffer; one work unit each.
|
|
66
|
+
#[must_use]
|
|
67
|
+
pub const fn emitted(&self) -> usize {
|
|
68
|
+
self.emitted
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/// Entries moved one level down; one work unit each.
|
|
72
|
+
#[must_use]
|
|
73
|
+
pub const fn cascaded(&self) -> usize {
|
|
74
|
+
self.cascaded
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/// Why the call returned.
|
|
78
|
+
#[must_use]
|
|
79
|
+
pub const fn status(&self) -> Status {
|
|
80
|
+
self.status
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/// Work units charged: emitted ids plus cascade moves.
|
|
84
|
+
#[must_use]
|
|
85
|
+
pub const fn work(&self) -> usize {
|
|
86
|
+
self.emitted + self.cascaded
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/// Whether one more work unit fits `budget`; marks the call
|
|
90
|
+
/// [`Status::BudgetSpent`] when it does not.
|
|
91
|
+
pub(crate) const fn affords(&mut self, budget: usize) -> bool {
|
|
92
|
+
if self.work() == budget {
|
|
93
|
+
self.status = Status::BudgetSpent;
|
|
94
|
+
return false;
|
|
95
|
+
}
|
|
96
|
+
true
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/// `true` when the wheel is caught up with its tick.
|
|
100
|
+
#[must_use]
|
|
101
|
+
pub const fn is_caught_up(&self) -> bool {
|
|
102
|
+
matches!(self.status, Status::CaughtUp)
|
|
103
|
+
}
|
|
104
|
+
}
|