pool_machines 0.1.3 → 0.5.3

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8bf6806bf7197bf167c8d59a5e27c8bf98061fa6a66763a539322efea61567d6
4
- data.tar.gz: 1fb90342597854b1665dda6f463ba08e1b62a68149b3d02e6fc7740d3b44fc77
3
+ metadata.gz: cf6928d85895ffb715341eff51a8bf49993bfa9b89e11b10c137cf0b19083039
4
+ data.tar.gz: 3773822719ec2d1a2f34f015b6c847bc49da7cf044030e2c0c7abf14008e4235
5
5
  SHA512:
6
- metadata.gz: 5703d5bc656afbd261e922167839d41ab2a2b177fd52fab0f5770254336379f315b6ab36da258f0fcb80b44b2fe8aceb67f229a34216f4b38a34f1a5e5539af7
7
- data.tar.gz: f0265330297e1a5433cd27984b6506fe2520d293e5fca9c6b632f058d1969a05a55c7d832861df87f87c295cace4d1729379b06eab35821174f6c8ca1e0a148a
6
+ metadata.gz: c6259e45d31ee73fcada18afe85f102487ce06a9964c7b3abba45572cfb6c8dc7b6a3123e32fc4ec891b43d90031f1f1775ee7c60fc428afa29aef2a19020f20
7
+ data.tar.gz: a16e1f769ff3953dc4ddd0f37c99e69cc58e1fc437caea5fc94c16e5392ffd9eff68cf12c4df6a79e4aee8f7f9809fc43d5190ba772905f832d88aad1ce4e073
data/CHANGELOG.md CHANGED
@@ -1,5 +1,70 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.5.3](https://github.com/seuros/pool_machines/compare/pool_machines/v0.5.2...pool_machines/v0.5.3) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * fix wrapped classes at load so building a value runs no Ruby ([61bdf02](https://github.com/seuros/pool_machines/commit/61bdf02fc2ea1ba944d42f192dff294d73f103f3))
9
+
10
+ ## [0.5.2](https://github.com/seuros/pool_machines/compare/pool_machines/v0.5.1...pool_machines/v0.5.2) (2026-11-16)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * drop slot indexing and name the real class in handle TypeErrors ([f17e7bb](https://github.com/seuros/pool_machines/commit/f17e7bbb58f6f5f4cb3047895cb554b7f2cbb0ca))
16
+
17
+ ## [0.5.1](https://github.com/seuros/pool_machines/compare/pool_machines/v0.5.0...pool_machines/v0.5.1) (2026-11-14)
18
+
19
+
20
+ ### Bug Fixes
21
+
22
+ * **deps:** require matryona-machines >= 0.4 ([cff1f7a](https://github.com/seuros/pool_machines/commit/cff1f7a938b6d5f2e47e0e298a1ecdc34eec47fb))
23
+
24
+ ## [0.5.0](https://github.com/seuros/pool_machines/compare/pool_machines/v0.4.0...pool_machines/v0.5.0) (2026-11-14)
25
+
26
+
27
+ ### ⚠ BREAKING CHANGES
28
+
29
+ * name the received class when checkin refuses a handle
30
+
31
+ ### Features
32
+
33
+ * name the received class when checkin refuses a handle ([572deb9](https://github.com/seuros/pool_machines/commit/572deb9b679f92af73a91f3cde859ba8125525ba))
34
+
35
+ ## [0.4.0](https://github.com/seuros/pool_machines/compare/pool_machines/v0.3.0...pool_machines/v0.4.0) (2026-11-14)
36
+
37
+
38
+ ### ⚠ BREAKING CHANGES
39
+
40
+ * adopt matryona-machines 0.2 (Class::pin, exact_typed, symbols!)
41
+
42
+ ### Features
43
+
44
+ * adopt matryona-machines 0.2 (Class::pin, exact_typed, symbols!) ([46a30f5](https://github.com/seuros/pool_machines/commit/46a30f5f8e7e2ed55852af8a510e036bf2b0904f))
45
+
46
+ ## [0.3.0](https://github.com/seuros/pool_machines/compare/pool_machines/v0.2.0...pool_machines/v0.3.0) (2026-11-14)
47
+
48
+
49
+ ### ⚠ BREAKING CHANGES
50
+
51
+ * drop flow-machines, record no clock on a retiring checkin, Handle sealed, resolved at load and checked by exact class
52
+
53
+ ### Features
54
+
55
+ * drop flow-machines, record no clock on a retiring checkin, Handle sealed, resolved at load and checked by exact class ([0af2455](https://github.com/seuros/pool_machines/commit/0af2455e73f0279d0c5bdcd8473f489633ae0ae3))
56
+
57
+ ## [0.2.0](https://github.com/seuros/pool_machines/compare/pool_machines/v0.1.3...pool_machines/v0.2.0) (2026-11-13)
58
+
59
+
60
+ ### ⚠ BREAKING CHANGES
61
+
62
+ * converted to the fleet conventions. One exhaustive Refusal per crate, Result from every operation that can refuse, a refusal changes nothing, provable idempotent repeats are honoured, Ruby mirrors the core. No compatibility aliases. Requires flow-machines >= 0.3. Handles are issued through periscope-machines; Ruby answers symbols and no longer raises on a stale handle.
63
+
64
+ ### Features
65
+
66
+ * one Refusal, scoped handles, and refusals that leave the clock alone ([f9e176a](https://github.com/seuros/pool_machines/commit/f9e176ae029835068e43bf4af75c3967fea56545))
67
+
3
68
  ## [0.1.3](https://github.com/seuros/pool_machines/compare/pool_machines/v0.1.2...pool_machines/v0.1.3) (2026-11-06)
4
69
 
5
70
 
data/Cargo.lock ADDED
@@ -0,0 +1,314 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 4
4
+
5
+ [[package]]
6
+ name = "aho-corasick"
7
+ version = "1.1.5"
8
+ source = "registry+https://github.com/rust-lang/crates.io-index"
9
+ checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
10
+ dependencies = [
11
+ "memchr",
12
+ ]
13
+
14
+ [[package]]
15
+ name = "bindgen"
16
+ version = "0.72.1"
17
+ source = "registry+https://github.com/rust-lang/crates.io-index"
18
+ checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
19
+ dependencies = [
20
+ "bitflags",
21
+ "cexpr",
22
+ "clang-sys",
23
+ "itertools",
24
+ "proc-macro2",
25
+ "quote",
26
+ "regex",
27
+ "rustc-hash",
28
+ "shlex",
29
+ "syn",
30
+ ]
31
+
32
+ [[package]]
33
+ name = "bitflags"
34
+ version = "2.13.2"
35
+ source = "registry+https://github.com/rust-lang/crates.io-index"
36
+ checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
37
+
38
+ [[package]]
39
+ name = "bytes"
40
+ version = "1.12.1"
41
+ source = "registry+https://github.com/rust-lang/crates.io-index"
42
+ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
43
+
44
+ [[package]]
45
+ name = "cexpr"
46
+ version = "0.6.0"
47
+ source = "registry+https://github.com/rust-lang/crates.io-index"
48
+ checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
49
+ dependencies = [
50
+ "nom",
51
+ ]
52
+
53
+ [[package]]
54
+ name = "cfg-if"
55
+ version = "1.0.5"
56
+ source = "registry+https://github.com/rust-lang/crates.io-index"
57
+ checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
58
+
59
+ [[package]]
60
+ name = "clang-sys"
61
+ version = "1.9.1"
62
+ source = "registry+https://github.com/rust-lang/crates.io-index"
63
+ checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
64
+ dependencies = [
65
+ "glob",
66
+ "libc",
67
+ "libloading",
68
+ ]
69
+
70
+ [[package]]
71
+ name = "either"
72
+ version = "1.19.0"
73
+ source = "registry+https://github.com/rust-lang/crates.io-index"
74
+ checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
75
+
76
+ [[package]]
77
+ name = "glob"
78
+ version = "0.3.4"
79
+ source = "registry+https://github.com/rust-lang/crates.io-index"
80
+ checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
81
+
82
+ [[package]]
83
+ name = "itertools"
84
+ version = "0.13.0"
85
+ source = "registry+https://github.com/rust-lang/crates.io-index"
86
+ checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
87
+ dependencies = [
88
+ "either",
89
+ ]
90
+
91
+ [[package]]
92
+ name = "lazy_static"
93
+ version = "1.5.1"
94
+ source = "registry+https://github.com/rust-lang/crates.io-index"
95
+ checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
96
+
97
+ [[package]]
98
+ name = "libc"
99
+ version = "0.2.191"
100
+ source = "registry+https://github.com/rust-lang/crates.io-index"
101
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
102
+
103
+ [[package]]
104
+ name = "libloading"
105
+ version = "0.8.9"
106
+ source = "registry+https://github.com/rust-lang/crates.io-index"
107
+ checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
108
+ dependencies = [
109
+ "cfg-if",
110
+ "windows-link",
111
+ ]
112
+
113
+ [[package]]
114
+ name = "magnus"
115
+ version = "0.9.3"
116
+ source = "registry+https://github.com/rust-lang/crates.io-index"
117
+ checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
118
+ dependencies = [
119
+ "bytes",
120
+ "magnus-macros",
121
+ "rb-sys",
122
+ "rb-sys-env",
123
+ "seq-macro",
124
+ ]
125
+
126
+ [[package]]
127
+ name = "magnus-macros"
128
+ version = "0.9.1"
129
+ source = "registry+https://github.com/rust-lang/crates.io-index"
130
+ checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
131
+ dependencies = [
132
+ "proc-macro2",
133
+ "quote",
134
+ "syn",
135
+ ]
136
+
137
+ [[package]]
138
+ name = "matryona-machines"
139
+ version = "0.6.0"
140
+ source = "registry+https://github.com/rust-lang/crates.io-index"
141
+ checksum = "cf8a06ab02efd767270815a1f515a40bbf3bfc77038e9360676ebe8d47833b07"
142
+ dependencies = [
143
+ "magnus",
144
+ ]
145
+
146
+ [[package]]
147
+ name = "memchr"
148
+ version = "2.8.3"
149
+ source = "registry+https://github.com/rust-lang/crates.io-index"
150
+ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
151
+
152
+ [[package]]
153
+ name = "minimal-lexical"
154
+ version = "0.2.1"
155
+ source = "registry+https://github.com/rust-lang/crates.io-index"
156
+ checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
157
+
158
+ [[package]]
159
+ name = "nom"
160
+ version = "7.1.3"
161
+ source = "registry+https://github.com/rust-lang/crates.io-index"
162
+ checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
163
+ dependencies = [
164
+ "memchr",
165
+ "minimal-lexical",
166
+ ]
167
+
168
+ [[package]]
169
+ name = "periscope-machines"
170
+ version = "0.5.0"
171
+ source = "registry+https://github.com/rust-lang/crates.io-index"
172
+ checksum = "1602a0bb66b4ba9529244868a2344cc39282c62c8ae4df357244adf49347bf51"
173
+
174
+ [[package]]
175
+ name = "pool-machines"
176
+ version = "0.5.1"
177
+ dependencies = [
178
+ "matryona-machines",
179
+ "periscope-machines",
180
+ ]
181
+
182
+ [[package]]
183
+ name = "pool_machines_native"
184
+ version = "0.1.7"
185
+ dependencies = [
186
+ "magnus",
187
+ "matryona-machines",
188
+ "pool-machines",
189
+ "rb-sys",
190
+ ]
191
+
192
+ [[package]]
193
+ name = "proc-macro2"
194
+ version = "1.0.107"
195
+ source = "registry+https://github.com/rust-lang/crates.io-index"
196
+ checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
197
+ dependencies = [
198
+ "unicode-ident",
199
+ ]
200
+
201
+ [[package]]
202
+ name = "quote"
203
+ version = "1.0.47"
204
+ source = "registry+https://github.com/rust-lang/crates.io-index"
205
+ checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
206
+ dependencies = [
207
+ "proc-macro2",
208
+ ]
209
+
210
+ [[package]]
211
+ name = "rb-sys"
212
+ version = "0.9.130"
213
+ source = "registry+https://github.com/rust-lang/crates.io-index"
214
+ checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
215
+ dependencies = [
216
+ "rb-sys-build",
217
+ ]
218
+
219
+ [[package]]
220
+ name = "rb-sys-build"
221
+ version = "0.9.130"
222
+ source = "registry+https://github.com/rust-lang/crates.io-index"
223
+ checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
224
+ dependencies = [
225
+ "bindgen",
226
+ "lazy_static",
227
+ "proc-macro2",
228
+ "quote",
229
+ "regex",
230
+ "shell-words",
231
+ "syn",
232
+ ]
233
+
234
+ [[package]]
235
+ name = "rb-sys-env"
236
+ version = "0.2.3"
237
+ source = "registry+https://github.com/rust-lang/crates.io-index"
238
+ checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
239
+
240
+ [[package]]
241
+ name = "regex"
242
+ version = "1.13.1"
243
+ source = "registry+https://github.com/rust-lang/crates.io-index"
244
+ checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
245
+ dependencies = [
246
+ "aho-corasick",
247
+ "memchr",
248
+ "regex-automata",
249
+ "regex-syntax",
250
+ ]
251
+
252
+ [[package]]
253
+ name = "regex-automata"
254
+ version = "0.4.18"
255
+ source = "registry+https://github.com/rust-lang/crates.io-index"
256
+ checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
257
+ dependencies = [
258
+ "aho-corasick",
259
+ "memchr",
260
+ "regex-syntax",
261
+ ]
262
+
263
+ [[package]]
264
+ name = "regex-syntax"
265
+ version = "0.8.11"
266
+ source = "registry+https://github.com/rust-lang/crates.io-index"
267
+ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
268
+
269
+ [[package]]
270
+ name = "rustc-hash"
271
+ version = "2.1.3"
272
+ source = "registry+https://github.com/rust-lang/crates.io-index"
273
+ checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
274
+
275
+ [[package]]
276
+ name = "seq-macro"
277
+ version = "0.3.6"
278
+ source = "registry+https://github.com/rust-lang/crates.io-index"
279
+ checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
280
+
281
+ [[package]]
282
+ name = "shell-words"
283
+ version = "1.1.1"
284
+ source = "registry+https://github.com/rust-lang/crates.io-index"
285
+ checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
286
+
287
+ [[package]]
288
+ name = "shlex"
289
+ version = "1.3.0"
290
+ source = "registry+https://github.com/rust-lang/crates.io-index"
291
+ checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
292
+
293
+ [[package]]
294
+ name = "syn"
295
+ version = "2.0.119"
296
+ source = "registry+https://github.com/rust-lang/crates.io-index"
297
+ checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
298
+ dependencies = [
299
+ "proc-macro2",
300
+ "quote",
301
+ "unicode-ident",
302
+ ]
303
+
304
+ [[package]]
305
+ name = "unicode-ident"
306
+ version = "1.0.27"
307
+ source = "registry+https://github.com/rust-lang/crates.io-index"
308
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
309
+
310
+ [[package]]
311
+ name = "windows-link"
312
+ version = "0.2.1"
313
+ source = "registry+https://github.com/rust-lang/crates.io-index"
314
+ checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
data/Cargo.toml CHANGED
@@ -8,12 +8,14 @@ rust-version = "1.99"
8
8
  license = "MIT"
9
9
  [workspace.dependencies]
10
10
  pool-machines = { path = "ext/pool_machines_native/core" }
11
+ matryona-machines = { version = ">=0.6", default-features = false }
11
12
  magnus = { version = "0.9.3", default-features = false }
12
13
  rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api-compiled-fallback"] }
13
- flow-machines = ">=0.2"
14
+ periscope-machines = ">=0.5"
14
15
  [workspace.lints.rust]
15
16
  unsafe_code = "deny"
16
17
  unused_must_use = "warn"
18
+ missing_docs = "warn"
17
19
  [workspace.lints.clippy]
18
20
  all = { level = "warn", priority = -1 }
19
21
  pedantic = { level = "warn", priority = -1 }
data/README.md CHANGED
@@ -16,20 +16,20 @@ now = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) }
16
16
 
17
17
  # You build the connection. The pool just learns that slot 0 is serviceable.
18
18
  connections[0] = PG.connect(db_url)
19
- pool.register(0, now.call) # => true
19
+ pool.register(0, now.call) # => :registered
20
20
 
21
21
  # Each request borrows a slot and gives it back.
22
- handle = pool.checkout(now.call) # => PoolMachines::Handle, or nil when none is free
22
+ handle = pool.checkout(now.call) # => PoolMachines::Handle, or nil when none is idle
23
23
  connections[handle.slot].exec(sql)
24
- pool.checkin(handle, now.call) # => "idle"
24
+ pool.checkin(handle, now.call) # => :idle
25
25
 
26
26
  # On a quiet night, tear down whatever has sat idle for five minutes.
27
- while (slot = pool.retire_idle(now.call, 5 * 60 * 1_000_000_000))
27
+ while (slot = pool.retire_idle(now.call, 5 * 60 * 1_000_000_000)).is_a?(Integer)
28
28
  connections.delete(slot).close
29
29
  end
30
30
  ```
31
31
 
32
- Times are nanoseconds from a monotonic clock. Slots are the integers 0 through 31.
32
+ Times are Integer nanoseconds from a monotonic clock, instants and spans alike. Slots are the integers 0 through 31. Every call answers with a value: what it did, or a symbol naming why it did nothing.
33
33
 
34
34
  ## A Message to the Resistance
35
35
 
@@ -71,10 +71,10 @@ stateDiagram-v2
71
71
  [*] --> vacant
72
72
  vacant --> idle: register(slot, now)
73
73
  idle --> busy: checkout(now) issues a handle
74
- busy --> idle: checkin(handle, now) returns "idle"
75
- busy --> vacant: checkin while draining returns "retire"
74
+ busy --> idle: checkin(handle, now) returns :idle
75
+ busy --> vacant: checkin while draining returns :retire
76
76
  idle --> vacant: retire_idle(now, idle_for) picks it
77
- vacant --> idle: register again, same slot, fresh generation
77
+ vacant --> idle: register again, same slot, next checkout gets a new handle
78
78
  ```
79
79
 
80
80
  And the deploy where the old pool was drained:
@@ -94,13 +94,13 @@ sequenceDiagram
94
94
  Note over App: SIGTERM, deploy starting
95
95
  App->>Pool: begin_drain
96
96
  App->>Pool: checkout(t2)
97
- Pool-->>App: nil, no new departures
97
+ Pool-->>App: :draining, no new departures
98
98
  App->>Pool: retire_idle(t2, any)
99
99
  Pool-->>App: 1
100
100
  App->>DB: close connection 1
101
101
 
102
102
  App->>Pool: checkin(handle, t3)
103
- Pool-->>App: "retire"
103
+ Pool-->>App: :retire
104
104
  App->>DB: close connection 0
105
105
  Note over Pool: checked_out is 0. Dock is empty.
106
106
  ```
@@ -113,37 +113,41 @@ sequenceDiagram
113
113
  pool = PoolMachines::Pool.new
114
114
  pool.checkout(0) # => nil, nothing registered yet
115
115
 
116
- pool.register(0, 1) # => true
117
- pool.register(0, 1) # => false, already on the roster
116
+ pool.register(0, 1) # => :registered
117
+ pool.register(0, 1) # => :already_idle, it's on the roster and nothing changed
118
118
 
119
119
  handle = pool.checkout(2)
120
120
  handle.slot # => 0
121
121
  pool.checked_out # => 1
122
+ pool.register(0, 3) # => :busy, that bay is out
123
+ pool.register(32, 3) # => :unknown_slot
122
124
  ```
123
125
 
124
- `checkout` returns `nil` when every registered slot is busy. It never blocks and never builds anything. If you want to grow the pool, build a resource and `register` a free slot number.
126
+ `checkout` returns `nil` when no registered slot is idle. It never blocks and never builds anything. If you want to grow the pool, build a resource and `register` a free slot number.
127
+
128
+ Registering a slot that already holds an idle resource is a repeat, not a mistake: the roster already says what you asked for, so the answer is `:already_idle` and nothing moves, not even the time it went idle.
125
129
 
126
130
  ### Check in, and the receipt that only works once
127
131
 
128
- A handle is good for exactly one `checkin`. Return it and the slot goes idle. Return it again and the pool raises, because the slot may already belong to a newer handle.
132
+ A handle is good for exactly one `checkin`. Return it and the slot goes idle. Return it again and the pool answers `:stale`, because the slot may already belong to a newer handle.
129
133
 
130
134
  ```ruby
131
135
  pool = PoolMachines::Pool.new
132
136
  pool.register(0, 1)
133
137
 
134
138
  first = pool.checkout(2)
135
- pool.checkin(first, 3) # => "idle"
139
+ pool.checkin(first, 3) # => :idle
136
140
 
137
141
  second = pool.checkout(4) # same slot 0, new receipt
138
- pool.checkin(first, 5) # raises ArgumentError, that receipt is spent
139
- pool.checkin(second, 5) # => "idle"
142
+ pool.checkin(first, 5) # => :stale, that receipt is spent
143
+ pool.checkin(second, 5) # => :idle
140
144
  ```
141
145
 
142
- That's the double-push bug from the cadet's code, caught at the second push instead of six hours later.
146
+ That's the double-push bug from the cadet's code, caught at the second push instead of six hours later. The second push is not honoured as a repeat: once a checkout is returned the pool keeps nothing about it, so it can't tell your retry from somebody's stale copy. Check the answer.
143
147
 
144
148
  ### Retire what's been sitting
145
149
 
146
- `retire_idle` hands you one slot per call: an idle slot that has been idle for at least `idle_for` nanoseconds. It returns `nil` when nothing qualifies. Loop until `nil`, closing as you go.
150
+ `retire_idle` hands you one slot per call: an idle slot that has been idle for at least `idle_for` nanoseconds. It returns `nil` when nothing qualifies. Loop while it answers an Integer, closing as you go.
147
151
 
148
152
  ```ruby
149
153
  pool = PoolMachines::Pool.new
@@ -155,14 +159,14 @@ pool.retire_idle(10, 5) # => 0
155
159
  pool.retire_idle(10, 5) # => 1
156
160
  pool.retire_idle(10, 5) # => nil
157
161
 
158
- pool.register(0, 11) # => true, the slot is vacant again
162
+ pool.register(0, 11) # => :registered, the slot is vacant again
159
163
  ```
160
164
 
161
165
  A busy slot is never retired. The pool will tell you to close it when it comes back.
162
166
 
163
167
  ### Drain
164
168
 
165
- `begin_drain` flips the pool into wind-down. No more registrations, no more checkouts. Idle slots retire regardless of how long they've been idle. Busy slots keep working, and when each one is checked in the answer is `"retire"` instead of `"idle"`, which is your cue to close it.
169
+ `begin_drain` flips the pool into wind-down. No more registrations, no more checkouts. Idle slots retire regardless of how long they've been idle. Busy slots keep working, and when each one is checked in the answer is `:retire` instead of `:idle`, which is your cue to close it.
166
170
 
167
171
  ```ruby
168
172
  pool = PoolMachines::Pool.new
@@ -170,11 +174,12 @@ pool.register(0, 0)
170
174
  pool.register(1, 0)
171
175
  handle = pool.checkout(1)
172
176
 
173
- pool.begin_drain
174
- pool.checkout(3) # => nil
175
- pool.register(2, 3) # => false
177
+ pool.begin_drain # => :begun
178
+ pool.begin_drain # => :already_draining
179
+ pool.checkout(3) # => :draining
180
+ pool.register(2, 3) # => :draining
176
181
  pool.retire_idle(3, 100) # => 1, idle_for is ignored while draining
177
- pool.checkin(handle, 4) # => "retire"
182
+ pool.checkin(handle, 4) # => :retire
178
183
  pool.checked_out # => 0
179
184
  ```
180
185
 
@@ -182,34 +187,82 @@ Drain never yanks a resource out from under a running query. It only refuses new
182
187
 
183
188
  ### The clock only moves forward
184
189
 
185
- You pass `now` on every call. The pool remembers the latest time it has seen and treats anything earlier as a non-event: `register` returns `false`, `checkout` returns `nil`, `checkin` raises.
190
+ You pass `now` on every call. The pool remembers the latest time an honoured call showed it and refuses anything earlier with `:time_regression`.
186
191
 
187
192
  ```ruby
188
193
  pool = PoolMachines::Pool.new
189
194
  pool.register(0, 5)
190
- pool.register(1, 3) # => false, time went backwards
195
+ pool.register(1, 3) # => :time_regression
196
+ pool.register(9_000, 999) # => :unknown_slot
197
+ pool.register(1, 5) # => :registered, the refusals above didn't touch the clock
198
+ ```
199
+
200
+ A refusal never moves the clock. An honoured call moves it exactly when its answer depends on `now`, and that includes the two that can come back empty-handed: `checkout` answering `nil` means "nothing was idle at `now`", and `retire_idle` answering `nil` means "nothing was old enough at `now`". Both are answers about that instant, so the pool holds you to it afterwards. The answers that hold whatever the time record nothing: `:already_idle`, `:retire` (closing a returned resource on a draining pool doesn't depend on when), and `begin_drain`, which takes no time at all.
201
+
202
+ ```ruby
203
+ pool = PoolMachines::Pool.new
204
+ pool.checkout(10) # => nil, honoured: nothing idle at 10
205
+ pool.register(0, 9) # => :time_regression
191
206
  ```
192
207
 
193
208
  Use a monotonic clock. Wall clocks jump.
194
209
 
210
+ ### Scopes
211
+
212
+ A handle is only meaningful to the pool that issued it. Run more than one pool and each needs its own scope, an Integer in `0..65535` that every handle it issues carries:
213
+
214
+ ```ruby
215
+ primary = PoolMachines::Pool.with_scope(1)
216
+ replica = PoolMachines::Pool.with_scope(2)
217
+ primary.register(0, 0)
218
+ replica.register(0, 0)
219
+
220
+ handle = primary.checkout(1)
221
+ handle.scope # => 1
222
+ replica.checkin(handle, 2) # => :stale, not one of mine
223
+ primary.checkin(handle, 2) # => :idle
224
+ ```
225
+
226
+ `Pool.new` is scope zero. The pool can't pick a scope for you: it reads no clock and rolls no dice. Leave two pools in the same scope and they issue the same handles, so one will happily accept the other's receipt.
227
+
228
+ A restarted pool counts from one again, so a handle that outlived the restart could name a new checkout. Resume from a saved count with `Pool.resumed(scope, pool.issued)`, or give each incarnation a new scope. `resumed` brings back the handle sequence and nothing else: every slot is vacant, earlier handles are `:stale`, and an `issued` above 2**48-1 raises `RangeError`.
229
+
230
+ ### What each call answers
231
+
232
+ | Call | Honoured | Records `now` | Refused, nothing changed |
233
+ | --- | --- | --- | --- |
234
+ | `register(slot, now)` | `:registered`, or `:already_idle` for a slot already holding an idle resource (nothing changed) | `:registered` only | `:draining`, `:time_regression`, `:unknown_slot`, `:busy` |
235
+ | `checkout(now)` | a `Handle`, or `nil` when nothing is idle | both | `:draining`, `:time_regression`, `:exhausted` |
236
+ | `checkin(handle, now)` | `:idle` (keep it) or `:retire` (close it) | `:idle` only | `:stale`, `:time_regression` |
237
+ | `begin_drain` | `:begun`, or `:already_draining` (nothing changed) | never | never refuses |
238
+ | `retire_idle(now, idle_for)` | the retired slot (Integer), or `nil` when nothing is old enough | both | `:time_regression` |
239
+ | `checked_out`, `capacity`, `scope`, `issued`, `draining?` | the value | never | queries, never refuse |
240
+
241
+ `register` checks in that order: a draining pool answers `:draining` whatever the slot. `:exhausted` means this pool 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.
242
+
195
243
  ## The Rules of the Tender
196
244
 
197
- - **32 slots, numbered 0 to 31.** Slot 32 or a negative slot raises `RangeError`.
198
- - **Every number is an Integer.** Slots, times, and durations. Floats, strings, and NaN raise `TypeError`. Values at or above `2**64` raise `RangeError`.
199
- - **Handles are opaque and single-use.** You can't construct one, `dup` one, or hand one to a different pool. A spent or foreign handle raises `ArgumentError` on `checkin`.
200
- - **Rejections are quiet, misuse is loud.** A duplicate `register`, a backwards clock, or an empty pool returns `false` or `nil`. A bad handle or a bad type raises.
201
- - **Frozen means frozen.** `freeze` the pool and every mutating call raises `FrozenError`. `checked_out` still answers.
245
+ - **32 slots, numbered 0 to 31.** `Pool::CAPACITY` and `pool.capacity` say so. Slot 32, or any other Integer that names no slot, is `:unknown_slot`.
246
+ - **Every number is an Integer.** Slots, times, and durations; times and durations are nanoseconds. Floats, strings, nil, and NaN raise `TypeError`. Negative values raise `RangeError`, and so do times and durations at or above `2**64` and slots a `usize` cannot hold (`2**64` on a 64-bit platform, `2**32` on a 32-bit one). A slot that fits but is past the last one is `:unknown_slot`.
247
+ - **Refusals don't raise, and don't change anything.** `:draining`, `:time_regression`, `:unknown_slot`, `:busy`, `:exhausted`, and `:stale` are answers. Not a slot, not a checkout, not an issued handle, not the clock moves on a refusal. Only malformed input raises.
248
+ - **Repeats.** `register` on a slot that is already idle is `:already_idle` and `begin_drain` on a draining pool is `:already_draining`: the pool can see the effect already holds. A second `checkin` is `:stale`: the pool keeps no history of a returned checkout, so it can't prove the repeat.
249
+ - **Handles are opaque and single-use.** You can't construct one, `dup` one or `Marshal` one. `Handle` is sealed (subclassing raises `TypeError`, `allocate` is gone), and `checkin` takes exactly a `PoolMachines::Handle`: anything else, a subclass included, raises `TypeError`. A spent handle, or one from a pool in another scope, is `:stale`.
250
+ - **Scopes.** Give each pool its own with `Pool.with_scope(scope)`; the core cannot pick one. Two pools in the same scope issue the same handles.
251
+ - **Restarts.** Resume from a saved count with `Pool.resumed(scope, issued)`, or give each incarnation a new scope. `resumed` restores the handle sequence only; registering the resources again is yours.
252
+ - **Wrong type is `TypeError`, wrong value is `RangeError`,** and the message names the argument (`slot must be an Integer`, `now must be in 0..=18446744073709551615`). `ArgumentError` is Ruby's own, for the wrong number of arguments.
253
+ - **The binding never loses work.** Arguments are converted before the core is called, and `checkout` decides on a copy of the pool that it keeps only once the `Handle` exists. The handle is wrapped natively, running no `new` or `initialize`, so a `checkout` that raises has checked nothing out and spent no handle. The `Handle` class is the one defined when the extension loads: reassigning the constant later changes nothing the pool builds or accepts.
254
+ - **Frozen means frozen.** `freeze` the pool and `register`, `checkout`, `checkin`, `begin_drain`, and `retire_idle` raise `FrozenError`. The queries still answer.
202
255
 
203
256
  ## What You Think You're Doing vs Reality
204
257
 
205
258
  ### You Think: "The ensure block guarantees the connection goes back."
206
259
  ### Reality: The ensure block guarantees it goes back at least once.
207
260
 
208
- `ensure` runs after `rescue`. If both return the connection, it's returned twice, and a plain array can't tell. A pool that issues receipts can, and refuses the second one on the spot.
261
+ `ensure` runs after `rescue`. If both return the connection, it's returned twice, and a plain array can't tell. A pool that issues receipts can, and answers `:stale` to the second one on the spot.
209
262
 
210
263
  ## What's Yours
211
264
 
212
- The pool holds slot numbers and timestamps, nothing else. You create the real resource before `register`, keep it somewhere indexed by slot, and close it when `retire_idle` or a `"retire"` check-in says so. Health checks, waiting for a free slot, and persistence across restarts are all outside the roster. Serialize calls to one pool; it doesn't lock for you.
265
+ The pool holds slot numbers and timestamps, nothing else. You create the real resource before `register`, keep it somewhere indexed by slot, and close it when `retire_idle` or a `:retire` check-in says so. Health checks, waiting for a free slot, and persistence across restarts are all outside the roster: the one thing worth saving is `issued`, so a restarted pool doesn't hand out an old receipt number again. Serialize calls to one pool; it doesn't lock for you.
213
266
 
214
267
  ## License
215
268