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
data/README.md
ADDED
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
# WheelMachines
|
|
2
|
+
|
|
3
|
+
> A deadline is not an alarm. Somebody still has to look at the clock. ⏱️
|
|
4
|
+
|
|
5
|
+
An expiry index for Ruby. You register an id with the tick it expires at and get a handle back. You tell the wheel what time it is. It hands you the ids that are now due, in order, as plain data. Cancel a handle and its id never comes out. No threads, no callbacks, no clock of its own: the wheel only knows the time you gave it.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
gem 'wheel_machines'
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```ruby
|
|
14
|
+
# The tick unit is yours. Here one tick is a millisecond of the monotonic clock.
|
|
15
|
+
TICK = 1_000_000
|
|
16
|
+
def tick_now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) / TICK
|
|
17
|
+
|
|
18
|
+
# Scope 1. Two wheels left in the same scope (Wheel.new is scope zero) alias:
|
|
19
|
+
# each issues the same handles and cancels the other's registrations. Give
|
|
20
|
+
# every wheel its own scope with with_scope / starting_at.
|
|
21
|
+
wheel = WheelMachines::Wheel.starting_at(1, tick_now)
|
|
22
|
+
|
|
23
|
+
# A lease that must be renewed within 30 seconds.
|
|
24
|
+
handle = wheel.register(lease.id, tick_now + 30_000)
|
|
25
|
+
raise "wheel refused #{lease.id}: #{handle}" if handle.is_a?(Symbol)
|
|
26
|
+
|
|
27
|
+
# Renewed in time? Drop the old deadline.
|
|
28
|
+
wheel.cancel(handle)
|
|
29
|
+
|
|
30
|
+
# In your own loop, on your own schedule:
|
|
31
|
+
drain = wheel.tick(tick_now, 256, 64) # now, work budget, max ids
|
|
32
|
+
drain.due.each { |due| expire_lease(due.id) }
|
|
33
|
+
reschedule_soon unless drain.caught_up?
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
One wheel, a handful of methods. Ids and ticks are Integers. A tick is whatever unit you pick, from a clock that only goes forward.
|
|
37
|
+
|
|
38
|
+
## A Message to the Resistance
|
|
39
|
+
|
|
40
|
+
So you have ten thousand leases, sessions, and retry timers, and each one expires at a different moment. You start with a `Thread.new { sleep ttl; expire(id) }` per item, and you know how that ends. So you keep a sorted set and scan it every second, and every renewal is a delete and a re-insert, and the scan holds a lock your hot path wants. So you reach for a timer library, and it owns a thread, and it calls your block on that thread, at a moment you didn't choose, while you were in the middle of something else.
|
|
41
|
+
|
|
42
|
+
What you wanted was never a timer. It was an answer to one question, asked when *you* are ready to hear it: **which of these ids are past their deadline now?** With cheap registration, cheap cancellation, and a bound on how much work the answer costs.
|
|
43
|
+
|
|
44
|
+
That index is this gem. It doesn't sleep, doesn't wake up, and doesn't call you. You ask.
|
|
45
|
+
|
|
46
|
+
## Chapter 1: Stardate 2026.316, the AMS Varghese
|
|
47
|
+
|
|
48
|
+
> **AMS Varghese**, NCC-4222, *Varghese*-class chronometer tender.
|
|
49
|
+
> The tender keeps the fleet's deadlines. It does not ring the bell.
|
|
50
|
+
|
|
51
|
+
The tender carries a rack of eleven wheels, sixty-four pegs each. A deadline an hour away hangs on a coarse wheel, where one peg covers a wide stretch of time. As the hour draws in, the tag is moved down to a finer wheel, and then a finer one, until it hangs on the peg for its exact tick. When the watch officer calls out the time, the quartermaster reads the tags off that peg and hands them over. What the fleet does about them is the fleet's business.
|
|
52
|
+
|
|
53
|
+
On a bridge somewhere, a cadet volunteers:
|
|
54
|
+
|
|
55
|
+
```ruby
|
|
56
|
+
def lease(id, ttl)
|
|
57
|
+
Thread.new do
|
|
58
|
+
sleep ttl
|
|
59
|
+
expire(id) # unless it was renewed. Probably.
|
|
60
|
+
end
|
|
61
|
+
end
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
"That," says the tender's quartermaster, "is ten thousand crewmen each staring at their own egg timer."
|
|
65
|
+
|
|
66
|
+
## The Flight Plan
|
|
67
|
+
|
|
68
|
+
Each registration is in one of these states:
|
|
69
|
+
|
|
70
|
+
```mermaid
|
|
71
|
+
stateDiagram-v2
|
|
72
|
+
[*] --> waiting: register, returns a Handle
|
|
73
|
+
waiting --> waiting: tick enters its range, moved to a finer wheel (cascade)
|
|
74
|
+
waiting --> due: advance reaches its deadline
|
|
75
|
+
waiting --> [*]: cancel(handle), returns the id
|
|
76
|
+
due --> [*]: drain emits the id
|
|
77
|
+
due --> [*]: cancel(handle), returns the id
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
And the afternoon a lease was renewed once and then forgotten:
|
|
81
|
+
|
|
82
|
+
```mermaid
|
|
83
|
+
sequenceDiagram
|
|
84
|
+
participant A as Your loop
|
|
85
|
+
participant W as Wheel
|
|
86
|
+
participant L as Lease table
|
|
87
|
+
|
|
88
|
+
A->>W: register(42, now + 30s)
|
|
89
|
+
W-->>A: Handle
|
|
90
|
+
Note over A: renewed at 20s
|
|
91
|
+
A->>W: cancel(handle)
|
|
92
|
+
W-->>A: 42
|
|
93
|
+
A->>W: register(42, now + 30s)
|
|
94
|
+
W-->>A: Handle
|
|
95
|
+
|
|
96
|
+
A->>W: tick(now, 256, 64)
|
|
97
|
+
W-->>A: Drain(due: [], status: :caught_up)
|
|
98
|
+
Note over A: nobody renews
|
|
99
|
+
|
|
100
|
+
A->>W: tick(now, 256, 64)
|
|
101
|
+
W-->>A: Drain(due: [Due(42)], status: :caught_up)
|
|
102
|
+
A->>L: fence and release lease 42
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## How the Wheel Works
|
|
106
|
+
|
|
107
|
+
### Register
|
|
108
|
+
|
|
109
|
+
```ruby
|
|
110
|
+
wheel = WheelMachines::Wheel.new # tick starts at 0
|
|
111
|
+
|
|
112
|
+
handle = wheel.register(42, 5_000) # id 42, due at tick 5000
|
|
113
|
+
handle.class # => WheelMachines::Handle
|
|
114
|
+
wheel.deadline(handle) # => 5000
|
|
115
|
+
wheel.size # => 1
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
A `Handle` names that one registration. The same id may be registered as often as you like. Each registration is its own entry with its own handle.
|
|
119
|
+
|
|
120
|
+
A deadline that isn't in the future is refused, not queued:
|
|
121
|
+
|
|
122
|
+
```ruby
|
|
123
|
+
wheel.register(43, 0) # => :elapsed
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
It's due already and you're holding it. Handle it.
|
|
127
|
+
|
|
128
|
+
### Cancel
|
|
129
|
+
|
|
130
|
+
```ruby
|
|
131
|
+
wheel.cancel(handle) # => 42
|
|
132
|
+
wheel.cancel(handle) # => :stale, already gone
|
|
133
|
+
wheel.deadline(handle) # => nil
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Cancel returns the id once, and `:stale` after that. `:stale` is the answer for any handle that names no live registration: cancelled, drained, or issued by a wheel in another scope. It changes nothing. A cancelled id is never emitted. An id that is due but hasn't been drained yet can still be cancelled. Once drained, its handle is dead.
|
|
137
|
+
|
|
138
|
+
### Advance
|
|
139
|
+
|
|
140
|
+
```ruby
|
|
141
|
+
wheel = WheelMachines::Wheel.new
|
|
142
|
+
wheel.register(1, 70)
|
|
143
|
+
wheel.register(2, 5)
|
|
144
|
+
|
|
145
|
+
wheel.advance(70) # => :advanced
|
|
146
|
+
wheel.now # => 70
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
`advance` only moves the wheel's tick. It emits nothing and does no indexing work.
|
|
150
|
+
|
|
151
|
+
### Drain
|
|
152
|
+
|
|
153
|
+
```ruby
|
|
154
|
+
drain = wheel.drain(64, 64) # work budget, max ids
|
|
155
|
+
drain.due # => [#<data WheelMachines::Due id=2, deadline=5>,
|
|
156
|
+
# #<data WheelMachines::Due id=1, deadline=70>]
|
|
157
|
+
drain.status # => :caught_up
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Ids come out in deadline order. Equal deadlines come out in the order they were registered. Each `Due` carries the deadline it was registered with, so `wheel.now - due.deadline` is how late you are.
|
|
161
|
+
|
|
162
|
+
`tick(now, budget, limit)` is `advance` followed by `drain`:
|
|
163
|
+
|
|
164
|
+
```ruby
|
|
165
|
+
wheel.tick(71, 64, 64).due # => []
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### Budgets and resuming
|
|
169
|
+
|
|
170
|
+
A drain stops for one of three reasons, and tells you which:
|
|
171
|
+
|
|
172
|
+
```ruby
|
|
173
|
+
wheel = WheelMachines::Wheel.new
|
|
174
|
+
5.times { |i| wheel.register(i, 9) }
|
|
175
|
+
wheel.advance(9)
|
|
176
|
+
|
|
177
|
+
first = wheel.drain(64, 2)
|
|
178
|
+
first.due.map(&:id) # => [0, 1]
|
|
179
|
+
first.status # => :output_full
|
|
180
|
+
|
|
181
|
+
second = wheel.drain(1, 64)
|
|
182
|
+
second.due.map(&:id) # => [2]
|
|
183
|
+
second.status # => :budget_spent
|
|
184
|
+
|
|
185
|
+
wheel.drain(64, 64).due.map(&:id) # => [3, 4], status :caught_up
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Call `drain` again and it resumes exactly where it stopped. You may register and cancel between calls.
|
|
189
|
+
|
|
190
|
+
### Cascades cost work
|
|
191
|
+
|
|
192
|
+
A tick is not free and not constant. An entry registered far ahead hangs on a coarse wheel and is moved to a finer one each time the tick enters its range. Every move is charged to the budget, just like every emitted id:
|
|
193
|
+
|
|
194
|
+
```ruby
|
|
195
|
+
wheel = WheelMachines::Wheel.new
|
|
196
|
+
wheel.register(1, 5_000)
|
|
197
|
+
|
|
198
|
+
drain = wheel.tick(5_000, 64, 64)
|
|
199
|
+
drain.cascaded # => 2
|
|
200
|
+
drain.emitted # => 1, the same as drain.due.size
|
|
201
|
+
drain.work # => 3
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
One registration is moved at most `WheelMachines::MAX_CASCADES` (10) times in its life, and that worst case needs a deadline 2**60 ticks out. Size your budget for the burst you can afford per loop turn; the rest waits for the next call.
|
|
205
|
+
|
|
206
|
+
### Next wake
|
|
207
|
+
|
|
208
|
+
```ruby
|
|
209
|
+
wheel = WheelMachines::Wheel.new
|
|
210
|
+
wheel.next_wake # => nil, nothing registered
|
|
211
|
+
wheel.register(1, 5_000)
|
|
212
|
+
wheel.next_wake # => 4096
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
`next_wake` is the tick at which a drain next has something to do. It is never later than the earliest deadline, but it can be earlier: at 4096 the wheel only moves that entry down a level. Use it to decide how long your loop may sleep. If work is already pending it returns `now`.
|
|
216
|
+
|
|
217
|
+
### Capacity
|
|
218
|
+
|
|
219
|
+
The wheel holds 1024 registrations at a time. Past that, `register` says `:full` until something is cancelled or drained:
|
|
220
|
+
|
|
221
|
+
```ruby
|
|
222
|
+
wheel = WheelMachines::Wheel.new
|
|
223
|
+
wheel.capacity # => 1024
|
|
224
|
+
handles = 1024.times.map { |i| wheel.register(i, 100) }
|
|
225
|
+
wheel.register(5_000, 100) # => :full
|
|
226
|
+
|
|
227
|
+
wheel.cancel(handles.first) # => 0
|
|
228
|
+
wheel.register(5_000, 100).class # => WheelMachines::Handle
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
A live registration is never evicted to make room.
|
|
232
|
+
|
|
233
|
+
### Time only moves forward
|
|
234
|
+
|
|
235
|
+
```ruby
|
|
236
|
+
wheel = WheelMachines::Wheel.starting_at(0, 100) # scope 0, tick 100
|
|
237
|
+
wheel.advance(99) # => :regressed
|
|
238
|
+
wheel.tick(99, 64, 64) # => :regressed
|
|
239
|
+
wheel.now # => 100
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
A tick earlier than the last one is refused and changes nothing. Repeating the current tick is fine.
|
|
243
|
+
|
|
244
|
+
### Scopes
|
|
245
|
+
|
|
246
|
+
A handle is only meaningful to the wheel that issued it. Run more than one wheel and each needs its own scope, an Integer in `0..65535` that every handle it issues carries:
|
|
247
|
+
|
|
248
|
+
```ruby
|
|
249
|
+
leases = WheelMachines::Wheel.with_scope(1)
|
|
250
|
+
retries = WheelMachines::Wheel.starting_at(2, tick_now)
|
|
251
|
+
|
|
252
|
+
handle = leases.register(42, 5_000)
|
|
253
|
+
handle.scope # => 1
|
|
254
|
+
retries.cancel(handle) # => :stale, not one of mine
|
|
255
|
+
retries.deadline(handle) # => nil
|
|
256
|
+
leases.cancel(handle) # => 42
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
`Wheel.new` is scope zero at tick zero. The wheel can't pick a scope for you: it reads no clock and rolls no dice. Leave two wheels in the same scope and they issue the same handles, so one will happily cancel the other's registration.
|
|
260
|
+
|
|
261
|
+
A restarted wheel counts from one again, so a handle that outlived the restart could name a new registration. Resume from a saved count with `Wheel.resumed(scope, wheel.issued, tick_now)`, or give each incarnation a new scope. `resumed` brings back the handle sequence and nothing else: the wheel is empty, earlier handles are `:stale`, and an `issued` above 2**48-1 raises `RangeError`.
|
|
262
|
+
|
|
263
|
+
### What each call answers
|
|
264
|
+
|
|
265
|
+
| Call | Honoured | Refused, nothing changed | Records the clock |
|
|
266
|
+
| --- | --- | --- | --- |
|
|
267
|
+
| `register` | a `Handle` | `:elapsed`, `:full`, `:exhausted` | no: judged against the tick already held |
|
|
268
|
+
| `cancel` | the id, an Integer | `:stale` | no: takes no tick |
|
|
269
|
+
| `advance` | `:advanced` | `:regressed` | yes, `now` (the tick already held, again, changes nothing) |
|
|
270
|
+
| `tick` | a `Drain` | `:regressed` | yes, `now` |
|
|
271
|
+
| `drain` | a `Drain` | never refuses | no: drains against `wheel.now` |
|
|
272
|
+
| `deadline` | the tick, or `nil` for a handle that names no live registration | a query, never refuses | no |
|
|
273
|
+
| `next_wake` | the tick, or `nil` when the wheel is empty | a query, never refuses | no |
|
|
274
|
+
|
|
275
|
+
`:exhausted` means this wheel has issued all 2**48-1 handles of its scope; none is ever reissued. Every refusal has its own symbol; there is no catch-all. `:regressed` is the core's `Regressed { now }`, and the tick it carries is `wheel.now`.
|
|
276
|
+
|
|
277
|
+
## The Rules of the Chronometer Tender
|
|
278
|
+
|
|
279
|
+
- **Ids, ticks, budgets, and limits are Integers** in `0..2**64-1`. Floats, nil, and strings raise `TypeError`. Out of range raises `RangeError`; so does a budget or limit past the platform's `usize` (only reachable on a 32-bit build), which is never quietly read as "no limit". Both are checked before the wheel moves, so `tick` raising leaves the tick where it was.
|
|
280
|
+
- **Values are valid or do not exist.** `Due.new` and `Drain.new` validate through the core, whether the wheel built the value or you did: a `Due` holds two Integers in `0..2**64-1`; a `Drain` holds a frozen copy of an Array of `Due`, a cascade count, and one of `:caught_up`, `:output_full`, `:budget_spent`. Wrong type raises `TypeError`; a value the core's `Drain::new` refuses (unknown status, negative count, work past `usize`) raises `RangeError`. Both classes are sealed (subclassing raises `TypeError`, `allocate` is undefined); sealing stops accidents, not reflection, so the binding is the authority: a `Due` it reads must be exactly a `Due`, and its fields are checked again, so a forged one raises. `Wheel` and `Handle` wrap native state and are sealed too: no `allocate`, and subclassing raises `TypeError`.
|
|
281
|
+
- **The binding never loses work.** Arguments are checked before the core moves, and `drain` and `tick` decide on a copy of the wheel kept only once the `Drain` is built: a build that raises (a redefined `Due.new`) has drained nothing, one that freezes the wheel raises `FrozenError`, and one that changes the wheel meanwhile raises `RuntimeError`, in each case with nothing applied.
|
|
282
|
+
- **Every tick is reachable.** Eleven wheels cover the whole 64-bit range. No deadline is too far away.
|
|
283
|
+
- **Scopes.** A `Handle` is only meaningful to the wheel that issued it. Give each wheel its own scope with `with_scope(scope)` or `starting_at(scope, now)`; the core cannot pick one. A `Handle` from a wheel in another scope is `:stale`, and its `deadline` there is `nil`. Two wheels in the same scope issue the same handles, so two `Wheel.new` alias: each cancels the other's registrations. Handles can't be built or copied by hand.
|
|
284
|
+
- **Restarts.** Resume from a saved count with `Wheel.resumed(scope, issued, now)`, or give each incarnation a new scope. `resumed` restores the handle sequence only; re-registering is yours.
|
|
285
|
+
- **Refusals don't raise, and don't change anything.** `:elapsed`, `:full`, `:exhausted`, `:regressed`, and `:stale` are answers. Only malformed input raises.
|
|
286
|
+
- **Draining never moves time.** Only `advance` and `tick` do, and only to the tick you pass.
|
|
287
|
+
- **Frozen means frozen.** `freeze` the wheel and `register`, `cancel`, `advance`, `drain`, and `tick` all raise `FrozenError`.
|
|
288
|
+
|
|
289
|
+
## What You Think You're Doing vs Reality
|
|
290
|
+
|
|
291
|
+
### You Think: "Timing wheels are O(1). I'll tick it in my hot path."
|
|
292
|
+
### Reality: Start, stop, and an empty tick are cheap. A busy tick costs what it costs.
|
|
293
|
+
|
|
294
|
+
The tick where a thousand sessions expire emits a thousand ids. The tick that crosses into a new coarse range moves everything hanging there. That work is real, so the wheel charges for it instead of hiding it: you pass a budget, it stops when the budget is spent, and `status` tells you there's more.
|
|
295
|
+
|
|
296
|
+
### You Think: "The wheel says the lease expired, so the old owner is gone."
|
|
297
|
+
### Reality: The wheel says a number got bigger than another number.
|
|
298
|
+
|
|
299
|
+
A due id means the tick you supplied reached the deadline you supplied. The old lease holder may still be mid-write. Revoking it takes fencing at the resource, which is not something an index can do.
|
|
300
|
+
|
|
301
|
+
### You Think: "I'll feed it my stream's watermark."
|
|
302
|
+
### Reality: This is scheduling time, not event time.
|
|
303
|
+
|
|
304
|
+
The wheel keeps one tick, the one you hand to `advance`. It doesn't read, hold, or advance an event-time watermark, and a due id says nothing about which events have arrived.
|
|
305
|
+
|
|
306
|
+
## What's Yours
|
|
307
|
+
|
|
308
|
+
This is a pre-1.0 policy core; breaking changes land in minor versions. It is not a timer runtime. You own the clock and the tick unit, the loop that calls `tick` and how often, the budget and what to do when a drain isn't caught up, and everything that happens to a due id. You own the mapping from ids to whatever they mean; the wheel stores Integers, not payloads.
|
|
309
|
+
|
|
310
|
+
The wheel lives in your process and forgets everything when the process does. If deadlines must survive a restart, keep them somewhere durable and register them again on boot. One wheel is not safe to share across threads or Ractors without your own lock.
|
|
311
|
+
|
|
312
|
+
## License
|
|
313
|
+
|
|
314
|
+
MIT License. See [LICENSE.txt](LICENSE.txt) for details.
|
|
315
|
+
|
|
316
|
+
**Remember: the wheel knows what's due. It doesn't know what time it is until you tell it.**
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.8.0](https://github.com/seuros/wheel_machines/compare/wheel-machines-v0.7.0...wheel-machines-v0.8.0) (2026-11-16)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### ⚠ BREAKING CHANGES
|
|
7
|
+
|
|
8
|
+
* seal Wheel and Handle against subclassing
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* seal Wheel and Handle against subclassing ([3454640](https://github.com/seuros/wheel_machines/commit/3454640fb4173f6e67233f6bcf9f9674a40f5604))
|
|
13
|
+
|
|
14
|
+
## [0.7.0](https://github.com/seuros/wheel_machines/compare/wheel-machines-v0.6.0...wheel-machines-v0.7.0) (2026-11-14)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### ⚠ BREAKING CHANGES
|
|
18
|
+
|
|
19
|
+
* adopt matryona-machines 0.2: Status symbols! table, exact-class Handle, exact Due fields, keep test support out of the crate
|
|
20
|
+
|
|
21
|
+
### Features
|
|
22
|
+
|
|
23
|
+
* adopt matryona-machines 0.2: Status symbols! table, exact-class Handle, exact Due fields, keep test support out of the crate ([a7c8651](https://github.com/seuros/wheel_machines/commit/a7c8651e40b8573af6853ef2a4bef45c8027eeb2))
|
|
24
|
+
|
|
25
|
+
## [0.6.0](https://github.com/seuros/wheel_machines/compare/wheel-machines-v0.5.0...wheel-machines-v0.6.0) (2026-11-14)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### ⚠ BREAKING CHANGES
|
|
29
|
+
|
|
30
|
+
* seal values, check exact classes natively, drain and tick never lose an entry
|
|
31
|
+
|
|
32
|
+
### Features
|
|
33
|
+
|
|
34
|
+
* seal values, check exact classes natively, drain and tick never lose an entry ([92a1f59](https://github.com/seuros/wheel_machines/commit/92a1f593f23777cd0db0a24e6000aa06c0a66141))
|
|
35
|
+
|
|
36
|
+
## [0.5.0](https://github.com/seuros/wheel_machines/compare/wheel-machines-v0.4.0...wheel-machines-v0.5.0) (2026-11-13)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
### ⚠ BREAKING CHANGES
|
|
40
|
+
|
|
41
|
+
* handles are issued through periscope-machines. Every instance can be built with a scope; a handle from another scope is refused before any lookup; all handle kinds of an instance share one sequence; resumed restores the sequence after a restart. A handle from another wheel answers Stale. with_scope_starting_at is gone.
|
|
42
|
+
|
|
43
|
+
### Features
|
|
44
|
+
|
|
45
|
+
* scope handles through periscope-machines, add Wheel::resumed and issued, starting_at takes the scope ([3d4b484](https://github.com/seuros/wheel_machines/commit/3d4b48460f280fc78ef504384942f38527992282))
|
|
46
|
+
|
|
47
|
+
## [0.4.0](https://github.com/seuros/wheel_machines/compare/wheel-machines-v0.3.0...wheel-machines-v0.4.0) (2026-11-13)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
### ⚠ BREAKING CHANGES
|
|
51
|
+
|
|
52
|
+
* see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. cancel returns Result<I, Refusal>; the Ruby Timer class is Handle.
|
|
53
|
+
|
|
54
|
+
### Features
|
|
55
|
+
|
|
56
|
+
* fold Regressed into Refusal, refuse stale cancels, Ruby Handle ([4fa0048](https://github.com/seuros/wheel_machines/commit/4fa00481e46931a9563d0ac024adeb4e5dd954a8))
|
|
57
|
+
|
|
58
|
+
## [0.3.0](https://github.com/seuros/wheel_machines/compare/wheel-machines-v0.2.0...wheel-machines-v0.3.0) (2026-11-13)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
### Features
|
|
62
|
+
|
|
63
|
+
* implement Default for Due so drain buffers need no dummy id ([1dcc6aa](https://github.com/seuros/wheel_machines/commit/1dcc6aae2e0ac403e302ca0fac688d32497eac7f))
|
|
64
|
+
|
|
65
|
+
## [0.2.0](https://github.com/seuros/wheel_machines/compare/wheel-machines-v0.1.0...wheel-machines-v0.2.0) (2026-11-12)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
### Features
|
|
69
|
+
|
|
70
|
+
* initial extraction ([5f1d698](https://github.com/seuros/wheel_machines/commit/5f1d698edae4429ef7e51ca07461b26197e77eb1))
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
[package]
|
|
2
|
+
name = "wheel-machines"
|
|
3
|
+
version = "0.8.0"
|
|
4
|
+
edition.workspace = true
|
|
5
|
+
rust-version.workspace = true
|
|
6
|
+
license.workspace = true
|
|
7
|
+
description = "Fixed-capacity hierarchical timing wheel: register/cancel handles, due IDs on explicit ticks"
|
|
8
|
+
readme = "README.md"
|
|
9
|
+
exclude = ["src/**/tests.rs", "src/tests/", "src/test_support.rs", "tests/"]
|
|
10
|
+
keywords = ["timing-wheel", "timer", "expiry", "timeout", "no-std"]
|
|
11
|
+
categories = ["no-std", "algorithms"]
|
|
12
|
+
|
|
13
|
+
[dependencies]
|
|
14
|
+
periscope-machines.workspace = true
|
|
15
|
+
|
|
16
|
+
[dev-dependencies]
|
|
17
|
+
matryona-machines = { workspace = true, features = ["testing"] }
|
|
18
|
+
|
|
19
|
+
[lints]
|
|
20
|
+
workspace = true
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# wheel-machines
|
|
2
|
+
|
|
3
|
+
> **AMS Varghese**, NCC-4222, *Varghese*-class chronometer tender.
|
|
4
|
+
|
|
5
|
+
Engine-room flight manual: index deadlines in a bounded hierarchical timing
|
|
6
|
+
wheel and hand back the ids that are due.
|
|
7
|
+
|
|
8
|
+
Allocation-free `no_std` expiry index. A `Wheel<I, N>` holds at most `N`
|
|
9
|
+
registrations of caller ids `I` in eleven levels of 64 slots, which together
|
|
10
|
+
cover every `u64` tick: no deadline is too far away, and a full wheel refuses
|
|
11
|
+
new registrations instead of evicting live ones. `register` returns a
|
|
12
|
+
`Handle` carrying a scoped id that is never reissued; `cancel` removes a
|
|
13
|
+
registration that has not been emitted and returns its id. A handle that no
|
|
14
|
+
longer names a live registration (cancelled, drained, or its entry reused) is
|
|
15
|
+
refused as `Stale`, so it can never cancel the entry that reused its slot.
|
|
16
|
+
|
|
17
|
+
Time is explicit. The wheel has no clock and fires no callbacks: `advance`
|
|
18
|
+
moves its tick, a backwards tick is refused as `Regressed { now }`, and `drain`
|
|
19
|
+
writes due ids into a caller buffer in deadline order, equal deadlines in
|
|
20
|
+
registration order. The tick is whatever unit the caller chooses; it is a
|
|
21
|
+
scheduling tick, not an event-time watermark, and the wheel neither reads nor
|
|
22
|
+
advances one.
|
|
23
|
+
|
|
24
|
+
A tick is not O(1) and the crate does not pretend otherwise. An entry
|
|
25
|
+
registered far ahead sits in a coarse slot and is moved to a finer one each
|
|
26
|
+
time the tick enters its range, at most `MAX_CASCADES` (ten) times in its
|
|
27
|
+
life. `drain` takes a work budget and charges one unit per cascade move and one
|
|
28
|
+
per emitted id. It stops when caught up, when the buffer is full, or when the
|
|
29
|
+
budget is spent, and the next call resumes exactly there. Registering and
|
|
30
|
+
cancelling between resumed drains is allowed. `next_wake` reports the tick at
|
|
31
|
+
which a drain next has work, which is never later than the earliest deadline.
|
|
32
|
+
|
|
33
|
+
A deadline at or before the current tick is refused as `Elapsed` rather than
|
|
34
|
+
queued: the caller already knows it is due. This in-memory index has no
|
|
35
|
+
persistence and no wire format. The slot table costs 704 `usize` words
|
|
36
|
+
regardless of `N`.
|
|
37
|
+
|
|
38
|
+
**Scopes.** A handle is only meaningful to the wheel that issued it. Handle
|
|
39
|
+
ids come from a `periscope_machines::Issuer`: the wheel's scope in the top 16
|
|
40
|
+
bits, a sequence counted from one below. `Wheel::with_scope(scope)` and
|
|
41
|
+
`Wheel::starting_at(scope, now)` choose the scope; `new()` is scope zero at
|
|
42
|
+
tick zero. `Wheel::scope` and `Handle::scope` read it.
|
|
43
|
+
`cancel` answers `Stale` and `deadline` answers `None` for a handle the wheel
|
|
44
|
+
did not issue, before looking at any entry. Give each wheel its own scope: the
|
|
45
|
+
core reads no clock and no random source, so it cannot pick one, and two wheels
|
|
46
|
+
left in the same scope issue the same handles, so two `Wheel::new()` alias: each
|
|
47
|
+
cancels the other's registrations. A scope is `Exhausted` after
|
|
48
|
+
2^48 - 1 handles.
|
|
49
|
+
|
|
50
|
+
**Restarts.** A fresh wheel counts from one again, so a handle that outlived a
|
|
51
|
+
restart could name a new registration. Save `Wheel::issued` and rebuild with
|
|
52
|
+
`Wheel::resumed(scope, issued, now)`, or give each incarnation a new scope.
|
|
53
|
+
`resumed` restores only the handle sequence: the wheel is empty, every earlier
|
|
54
|
+
handle is `Stale`, and re-registering what was pending is the caller's job. It
|
|
55
|
+
is `None` when `issued` is beyond `periscope_machines::SEQUENCE_MAX`.
|
|
56
|
+
|
|
57
|
+
`Refusal` is the crate's one refusal type and a refused call changes nothing:
|
|
58
|
+
`register` answers `Elapsed`, `Full` or `Exhausted`, `cancel` answers `Stale`,
|
|
59
|
+
`advance` and `tick` answer `Regressed { now }` with the tick the wheel holds.
|
|
60
|
+
`drain` never refuses; its `Status` says why it stopped.
|
|
61
|
+
|
|
62
|
+
**Broken invariants.** The core never panics at run time. Every entry filed
|
|
63
|
+
in a slot is live; if that ever broke, `drain` would meet a filed entry that
|
|
64
|
+
is already free. That arm `debug_assert!`s, so tests catch it, and in release
|
|
65
|
+
takes the entry off its slot and carries on. It is the one arm that does not
|
|
66
|
+
stop with nothing changed, because it cannot: an entry left filed would be met
|
|
67
|
+
first on every later drain and the wheel would never emit what is due behind
|
|
68
|
+
it. The entry is already on the free list, so the unlink frees nothing twice
|
|
69
|
+
and emits nothing.
|
|
70
|
+
|
|
71
|
+
**Values.** `Drain` keeps its fields private behind `emitted()`,
|
|
72
|
+
`cascaded()` and `status()`; `Drain::new` builds one and answers `None` when
|
|
73
|
+
`emitted + cascaded` does not fit a `usize`, which no drain charges. `Due`
|
|
74
|
+
holds any id and deadline (`Due::new` never refuses).
|
|
75
|
+
|
|
76
|
+
**Which answers record the clock.** Only `advance` and an honoured `tick`
|
|
77
|
+
record `now`; re-advancing to the tick already held records the same value
|
|
78
|
+
and changes nothing. `register` judges `Elapsed` against the tick already held
|
|
79
|
+
and records none; `cancel`, `drain`, and the queries take no instant.
|
|
80
|
+
|
|
81
|
+
The Ruby gem mirrors `Handle`, `Due` and `Drain` under the same names; its
|
|
82
|
+
`Drain` carries the due entries where this one counts `emitted`.
|
|
83
|
+
|
|
84
|
+
`drain` and `tick` write the first `emitted` entries of `out` and leave the
|
|
85
|
+
rest untouched. `Due<I>` implements `Default` when `I` does, so the buffer is
|
|
86
|
+
`[Due::default(); N]`; the default is a placeholder the wheel never emits,
|
|
87
|
+
because a deadline of 0 is always refused. The wheel itself asks nothing of
|
|
88
|
+
`I` beyond `Copy`; for an id without `Default`, pre-fill with `Due::new`.
|
|
89
|
+
|
|
90
|
+
```rust
|
|
91
|
+
use wheel_machines::{Drain, Due, Refusal, Status, Wheel};
|
|
92
|
+
|
|
93
|
+
# fn main() -> Result<(), Refusal> {
|
|
94
|
+
let mut wheel = Wheel::<u64, 8>::new();
|
|
95
|
+
let lease = wheel.register(7, 5_000)?;
|
|
96
|
+
wheel.register(8, 90)?;
|
|
97
|
+
assert_eq!(wheel.register(9, 0), Err(Refusal::Elapsed));
|
|
98
|
+
assert_eq!(wheel.next_wake(), Some(64));
|
|
99
|
+
|
|
100
|
+
let mut out = [Due::default(); 4];
|
|
101
|
+
let drain = wheel.tick(100, 16, &mut out)?;
|
|
102
|
+
assert_eq!(Some(drain), Drain::new(1, 1, Status::CaughtUp));
|
|
103
|
+
assert_eq!(out[0], Due::new(8, 90));
|
|
104
|
+
|
|
105
|
+
assert_eq!(wheel.cancel(lease), Ok(7));
|
|
106
|
+
assert_eq!(wheel.cancel(lease), Err(Refusal::Stale));
|
|
107
|
+
assert_eq!(wheel.tick(99, 16, &mut out), Err(Refusal::Regressed { now: 100 }));
|
|
108
|
+
|
|
109
|
+
// Another wheel, another scope: it refuses a handle it did not issue.
|
|
110
|
+
let mut leases = Wheel::<u64, 8>::with_scope(1);
|
|
111
|
+
let mut retries = Wheel::<u64, 8>::with_scope(2);
|
|
112
|
+
let handle = leases.register(7, 5_000)?;
|
|
113
|
+
retries.register(8, 5_000)?;
|
|
114
|
+
assert_eq!(handle.scope(), 1);
|
|
115
|
+
assert_eq!(retries.cancel(handle), Err(Refusal::Stale));
|
|
116
|
+
assert_eq!(leases.cancel(handle), Ok(7));
|
|
117
|
+
# Ok(())
|
|
118
|
+
# }
|
|
119
|
+
```
|