wheel_machines 0.7.1-arm64-darwin

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 ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 5b6c8a14be5ea304e8c7fc97100bd2f4c2fca5dfb3279c1e18a511eb316d1267
4
+ data.tar.gz: b8a90b110dcfaab0cec116466934aaebe8f4a62d90d89f27849b6b35ca8d5aad
5
+ SHA512:
6
+ metadata.gz: de0f2e68343d97b644e49aeef3ef054c3bc943607844625370691655446a9dbead4e2587b77b17d4ef3f213286e2ab41eac6530d9d5af78131fdc36e63cef3a7
7
+ data.tar.gz: 7b7abb7909ea4f67197a702a3cc8b2836fc705de2085ae9658377022c2df961b83d8cc71fc5463f1b83704de5ed7076392c6bfbb6962f4fd8e51d069a4dd1f80
data/CHANGELOG.md ADDED
@@ -0,0 +1,95 @@
1
+ # Changelog
2
+
3
+ ## [0.7.1](https://github.com/seuros/wheel_machines/compare/wheel_machines/v0.7.0...wheel_machines/v0.7.1) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * fix wrapped classes at load so building a value runs no Ruby ([0920968](https://github.com/seuros/wheel_machines/commit/092096836b5c2a4cd90dff3629cbd6b64a068ae4))
9
+
10
+ ## [0.7.0](https://github.com/seuros/wheel_machines/compare/wheel_machines/v0.6.0...wheel_machines/v0.7.0) (2026-11-16)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * seal Wheel and Handle against subclassing
16
+
17
+ ### Features
18
+
19
+ * seal Wheel and Handle against subclassing ([3454640](https://github.com/seuros/wheel_machines/commit/3454640fb4173f6e67233f6bcf9f9674a40f5604))
20
+
21
+ ## [0.6.0](https://github.com/seuros/wheel_machines/compare/wheel_machines/v0.5.1...wheel_machines/v0.6.0) (2026-11-14)
22
+
23
+
24
+ ### ⚠ BREAKING CHANGES
25
+
26
+ * wheel handle refusals name the class received
27
+
28
+ ### Features
29
+
30
+ * wheel handle refusals name the class received ([f1edc66](https://github.com/seuros/wheel_machines/commit/f1edc6638ccb62c90dbb44cc1a6d37208ccb122d))
31
+
32
+ ## [0.5.1](https://github.com/seuros/wheel_machines/compare/wheel_machines/v0.5.0...wheel_machines/v0.5.1) (2026-11-14)
33
+
34
+
35
+ ### Bug Fixes
36
+
37
+ * **deps:** require matryona-machines >= 0.3 with a names_only refusal table ([5a85b47](https://github.com/seuros/wheel_machines/commit/5a85b472af8714f8d6a08ff08295032c5fd85c56))
38
+
39
+ ## [0.5.0](https://github.com/seuros/wheel_machines/compare/wheel_machines/v0.4.0...wheel_machines/v0.5.0) (2026-11-14)
40
+
41
+
42
+ ### ⚠ BREAKING CHANGES
43
+
44
+ * adopt matryona-machines 0.2: Status symbols! table, exact-class Handle, exact Due fields, keep test support out of the crate
45
+
46
+ ### Features
47
+
48
+ * 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))
49
+
50
+ ## [0.4.0](https://github.com/seuros/wheel_machines/compare/wheel_machines/v0.3.0...wheel_machines/v0.4.0) (2026-11-14)
51
+
52
+
53
+ ### ⚠ BREAKING CHANGES
54
+
55
+ * seal values, check exact classes natively, drain and tick never lose an entry
56
+
57
+ ### Features
58
+
59
+ * seal values, check exact classes natively, drain and tick never lose an entry ([92a1f59](https://github.com/seuros/wheel_machines/commit/92a1f593f23777cd0db0a24e6000aa06c0a66141))
60
+
61
+ ## [0.3.0](https://github.com/seuros/wheel_machines/compare/wheel_machines/v0.2.0...wheel_machines/v0.3.0) (2026-11-13)
62
+
63
+
64
+ ### ⚠ BREAKING CHANGES
65
+
66
+ * 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.
67
+
68
+ ### Features
69
+
70
+ * scope handles through periscope-machines, add Wheel::resumed and issued, starting_at takes the scope ([3d4b484](https://github.com/seuros/wheel_machines/commit/3d4b48460f280fc78ef504384942f38527992282))
71
+
72
+ ## [0.2.0](https://github.com/seuros/wheel_machines/compare/wheel_machines/v0.1.2...wheel_machines/v0.2.0) (2026-11-13)
73
+
74
+
75
+ ### ⚠ BREAKING CHANGES
76
+
77
+ * 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.
78
+
79
+ ### Features
80
+
81
+ * fold Regressed into Refusal, refuse stale cancels, Ruby Handle ([4fa0048](https://github.com/seuros/wheel_machines/commit/4fa00481e46931a9563d0ac024adeb4e5dd954a8))
82
+
83
+ ## [0.1.2](https://github.com/seuros/wheel_machines/compare/wheel_machines/v0.1.1...wheel_machines/v0.1.2) (2026-11-13)
84
+
85
+
86
+ ### Features
87
+
88
+ * implement Default for Due so drain buffers need no dummy id ([1dcc6aa](https://github.com/seuros/wheel_machines/commit/1dcc6aae2e0ac403e302ca0fac688d32497eac7f))
89
+
90
+ ## [0.1.1](https://github.com/seuros/wheel_machines/compare/wheel_machines-v0.1.0...wheel_machines/v0.1.1) (2026-11-12)
91
+
92
+
93
+ ### Features
94
+
95
+ * initial extraction ([5f1d698](https://github.com/seuros/wheel_machines/commit/5f1d698edae4429ef7e51ca07461b26197e77eb1))
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Abdelkader Boudih
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
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,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
+ ```
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module WheelMachines
4
+ VERSION = '0.7.1'
5
+ end
@@ -0,0 +1,65 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'wheel_machines/version'
4
+
5
+ module WheelMachines
6
+ # One due registration: the caller's id and the tick it was registered for.
7
+ # Like the core's `Due::new`, both are Integers in 0..2**64-1: TypeError for
8
+ # a non-Integer, RangeError outside the range.
9
+ Due = Data.define(:id, :deadline) do
10
+ def initialize(id:, deadline:)
11
+ id, deadline = WheelMachines.__send__(:__due, id, deadline)
12
+ super
13
+ end
14
+ end
15
+
16
+ # What one drain did: the due entries in order, the cascade moves charged, and
17
+ # why it stopped (:caught_up, :output_full or :budget_spent). The core writes
18
+ # the entries to a caller's buffer and reports `emitted`; here `due` is that
19
+ # buffer, cut to the entries written, stored as a frozen copy.
20
+ #
21
+ # Validated by the core's `Drain::new`: `due` must be an Array of `Due` and
22
+ # `status` a Symbol (TypeError otherwise); an unknown status, a negative
23
+ # `cascaded`, or work past the core's `usize` raises RangeError.
24
+ Drain = Data.define(:due, :cascaded, :status) do
25
+ def initialize(due:, cascaded:, status:)
26
+ due, cascaded, status = WheelMachines.__send__(:__drain, due, cascaded, status)
27
+ super
28
+ end
29
+
30
+ # Due entries handed out, the core's `emitted`.
31
+ def emitted = due.size
32
+
33
+ # Work units charged against the budget.
34
+ def work = emitted + cascaded
35
+
36
+ def caught_up? = status == :caught_up
37
+ end
38
+ end
39
+
40
+ # Native is required: no algorithm fallback. It validates and builds the Due
41
+ # and Drain values above, so those classes must exist first.
42
+ require 'wheel_machines_native/wheel_machines_native'
43
+
44
+ module WheelMachines
45
+ private_class_method :__due, :__drain
46
+
47
+ # The values are sealed. `initialize` is where each validates, and a
48
+ # subclass could override it, or `allocate` build an instance that never ran
49
+ # it: subclassing raises TypeError and `allocate` is gone. Sealing stops
50
+ # accidents, not reflection (a named subclass's constant is bound before
51
+ # `inherited` raises; `Marshal.load` skips `initialize`), so the native side
52
+ # is the authority: it takes a `Due` only of exactly that class and checks
53
+ # its fields again.
54
+ [Due, Drain].each do |value|
55
+ value.singleton_class.undef_method(:allocate)
56
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
57
+ end
58
+
59
+ # Wheel and Handle wrap native state and have no allocator: a subclass's
60
+ # `new` (or `with_scope`) would build the base class anyway, so subclassing
61
+ # raises too.
62
+ [Wheel, Handle].each do |native|
63
+ native.define_singleton_method(:inherited) { |_| raise TypeError, "#{native} cannot be subclassed" }
64
+ end
65
+ end
@@ -0,0 +1,89 @@
1
+ module WheelMachines
2
+ VERSION: String
3
+ CAPACITY: Integer
4
+ MAX_CASCADES: Integer
5
+
6
+ # Private native checks behind `Due.new` and `Drain.new`: the fields as the
7
+ # core holds them (`due` as a frozen copy), TypeError/RangeError for what it
8
+ # rejects.
9
+ private def self.__due: (Integer id, Integer deadline) -> [Integer, Integer]
10
+ private def self.__drain: (Array[Due] due, Integer cascaded, Drain::status status) -> [Array[Due], Integer, Drain::status]
11
+
12
+ # Both fields are Integers in 0..2**64-1: TypeError for a non-Integer,
13
+ # RangeError outside the range.
14
+ class Due < Data
15
+ attr_reader id: Integer
16
+ attr_reader deadline: Integer
17
+ def self.new: (Integer id, Integer deadline) -> Due
18
+ | (id: Integer, deadline: Integer) -> Due
19
+ end
20
+
21
+ # Validated by the core's `Drain::new`: TypeError when `due` is not an
22
+ # Array of Due or `status` not a Symbol; RangeError for an unknown status, a
23
+ # negative `cascaded`, or work past the core's usize. `due` is stored as a
24
+ # frozen copy.
25
+ class Drain < Data
26
+ type status = :caught_up | :output_full | :budget_spent
27
+
28
+ attr_reader due: Array[Due]
29
+ attr_reader cascaded: Integer
30
+ attr_reader status: status
31
+ def self.new: (Array[Due] due, Integer cascaded, status status) -> Drain
32
+ | (due: Array[Due], cascaded: Integer, status: status) -> Drain
33
+ # The core's `emitted`: how many entries are in `due`.
34
+ def emitted: () -> Integer
35
+ def work: () -> Integer
36
+ def caught_up?: () -> bool
37
+ end
38
+
39
+ # Mirrors the core's `Handle`: names one registration on the wheel that
40
+ # issued it and carries that wheel's scope. Opaque; it cannot be built or
41
+ # copied by hand. A wheel in another scope answers :stale to it. Sealed:
42
+ # subclassing raises TypeError.
43
+ class Handle
44
+ # The scope of the wheel that issued it, 0..65535.
45
+ def scope: () -> Integer
46
+ end
47
+
48
+ # Sealed: no allocator, and subclassing raises TypeError.
49
+ class Wheel
50
+ # Tick zero, scope zero, nothing issued.
51
+ def self.new: () -> Wheel
52
+ # Tick zero. `scope` is an Integer in 0..65535: TypeError otherwise,
53
+ # RangeError outside the range.
54
+ def self.with_scope: (Integer scope) -> Wheel
55
+ def self.starting_at: (Integer scope, Integer now) -> Wheel
56
+ # Continues `scope` after a restart from a saved `issued` count. Restores
57
+ # only the handle sequence: the wheel is empty. RangeError when `issued`
58
+ # is above 2**48 - 1.
59
+ def self.resumed: (Integer scope, Integer issued, Integer now) -> Wheel
60
+ # The scope carried by every Handle this wheel issues.
61
+ def scope: () -> Integer
62
+ # Handles issued in this scope so far: the count to save for `resumed`.
63
+ def issued: () -> Integer
64
+ def capacity: () -> Integer
65
+ def size: () -> Integer
66
+ def empty?: () -> bool
67
+ def now: () -> Integer
68
+ def next_wake: () -> Integer?
69
+ # Refusals are symbols, one per core variant, and a refused call changes
70
+ # nothing. `Refusal::Regressed { now }` is `:regressed`; the tick it
71
+ # carries is `now`.
72
+ # Honoured: a Handle. Refused: :elapsed, :full, :exhausted.
73
+ def register: (Integer id, Integer deadline) -> (Handle | :elapsed | :full | :exhausted)
74
+ # Honoured: the id that was registered. Refused: :stale, a Handle from a
75
+ # wheel in another scope included.
76
+ def cancel: (Handle) -> (Integer | :stale)
77
+ # nil for a Handle that names no live registration here.
78
+ def deadline: (Handle) -> Integer?
79
+ # Honoured: :advanced (repeating the current tick included). Records
80
+ # `now`: the answer depends on it. Refused: :regressed.
81
+ def advance: (Integer now) -> (:advanced | :regressed)
82
+ # Never refuses and records no clock: it drains against `now`. A budget
83
+ # or limit past usize raises RangeError before anything is drained.
84
+ def drain: (Integer budget, Integer limit) -> Drain
85
+ # Honoured: a Drain; records `now`. Refused: :regressed. A budget or
86
+ # limit past usize raises RangeError before the tick moves.
87
+ def tick: (Integer now, Integer budget, Integer limit) -> (Drain | :regressed)
88
+ end
89
+ end
metadata ADDED
@@ -0,0 +1,62 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: wheel_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.7.1
5
+ platform: arm64-darwin
6
+ authors:
7
+ - Abdelkader Boudih
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
+ dependencies: []
13
+ description: 'An expiry index: register ids with the tick they expire at, cancel them
14
+ by handle, and drain the due ids when you tell it the time. No threads, callbacks
15
+ or clock.'
16
+ email:
17
+ - oss@seuros.com
18
+ executables: []
19
+ extensions: []
20
+ extra_rdoc_files: []
21
+ files:
22
+ - CHANGELOG.md
23
+ - LICENSE.txt
24
+ - README.md
25
+ - ext/wheel_machines_native/core/CHANGELOG.md
26
+ - ext/wheel_machines_native/core/README.md
27
+ - ext/wheel_machines_native/extconf.rb
28
+ - lib/wheel_machines.rb
29
+ - lib/wheel_machines/version.rb
30
+ - lib/wheel_machines_native/wheel_machines_native.bundle
31
+ - sig/wheel_machines.rbs
32
+ homepage: https://github.com/seuros/wheel_machines
33
+ licenses:
34
+ - MIT
35
+ metadata:
36
+ source_code_uri: https://github.com/seuros/wheel_machines
37
+ rubygems_mfa_required: 'true'
38
+ cargo_crate_name: wheel_machines_native
39
+ cargo_manifest_path: ext/wheel_machines_native/ffi/Cargo.toml
40
+ post_install_message:
41
+ rdoc_options: []
42
+ require_paths:
43
+ - lib
44
+ required_ruby_version: !ruby/object:Gem::Requirement
45
+ requirements:
46
+ - - ">="
47
+ - !ruby/object:Gem::Version
48
+ version: '4.0'
49
+ - - "<"
50
+ - !ruby/object:Gem::Version
51
+ version: 4.1.dev
52
+ required_rubygems_version: !ruby/object:Gem::Requirement
53
+ requirements:
54
+ - - ">="
55
+ - !ruby/object:Gem::Version
56
+ version: '0'
57
+ requirements: []
58
+ rubygems_version: 3.5.23
59
+ signing_key:
60
+ specification_version: 4
61
+ summary: Hierarchical timing wheel over a native Rust core
62
+ test_files: []