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.
@@ -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
+ }
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'