batch_machines 0.1.4 → 0.5.4

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: 920b2df3c09c3302a734456202cc18bac028ef244bbc6430d45f9381be8baa50
4
- data.tar.gz: 464f1086a6717a9802eed02c8bfa3bf2b5e3c24f9e4e87c9170b19c549b048c7
3
+ metadata.gz: 8fe776e77c7b9bb284dd1ad3d20083490f0bba41328c8611eac67e346c8d1bf4
4
+ data.tar.gz: 32a011e1b87b86caaa1c10009dcfcf9a164a2b776e0b119102952036cd1ee52e
5
5
  SHA512:
6
- metadata.gz: dad356cd56970262d1807c0f6aaa9bcdec5ec3b18b3cde986739ddaa9098f557230b7fef48192c1e0c4d19b8fdaeaa3acbc653d7bbc9ef2ad3fd4fa7c359a154
7
- data.tar.gz: 6702ff431f499e8ea9c87676551a093fad72f17773a61f8f08b58ed50c64102dd26821a782f9416088e5f7ddaaec209a6016de6b7f9f54952347fb3ad3ddb555
6
+ metadata.gz: f0f81215fd33d15453ce75ddcbfc217af0720d03618214eea6a1147156a2908c89c1e59ed451c6822bfdbbab62dcdaae2daf8524dd364799eda89f005ff4a6c8
7
+ data.tar.gz: b41c2d9ee23236d46c68e26973a23bf63b766c42fff146236ba8aebeb7212392e4a289b84684701cc524398277fbedecdeb6a653640ee7d6967bea8e32715b9d
data/CHANGELOG.md CHANGED
@@ -1,5 +1,77 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.5.4](https://github.com/seuros/batch_machines/compare/batch_machines/v0.5.3...batch_machines/v0.5.4) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * accept every instant the gem returns ([728dbb6](https://github.com/seuros/batch_machines/commit/728dbb647498703a429da7c82de4533d27225ccf))
9
+
10
+ ## [0.5.3](https://github.com/seuros/batch_machines/compare/batch_machines/v0.5.2...batch_machines/v0.5.3) (2026-11-16)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * fix wrapped classes at load so building a value runs no Ruby ([9030929](https://github.com/seuros/batch_machines/commit/9030929996bfe215a71b316254408db433b3a8f6))
16
+
17
+ ## [0.5.2](https://github.com/seuros/batch_machines/compare/batch_machines/v0.5.1...batch_machines/v0.5.2) (2026-11-16)
18
+
19
+
20
+ ### Features
21
+
22
+ * accept an Integer controller output in Batch#adapt ([676da13](https://github.com/seuros/batch_machines/commit/676da134787cb86aa12156445eaec2fbce346cc5))
23
+
24
+ ## [0.5.1](https://github.com/seuros/batch_machines/compare/batch_machines/v0.5.0...batch_machines/v0.5.1) (2026-11-14)
25
+
26
+
27
+ ### Bug Fixes
28
+
29
+ * **deps:** require matryona-machines >= 0.4 ([8737aa0](https://github.com/seuros/batch_machines/commit/8737aa0f16af8ed9362876300d02a7ed5c99251e))
30
+
31
+ ## [0.5.0](https://github.com/seuros/batch_machines/compare/batch_machines/v0.4.0...batch_machines/v0.5.0) (2026-11-14)
32
+
33
+
34
+ ### ⚠ BREAKING CHANGES
35
+
36
+ * read retarget/adapt reals exactly with matryona 0.3
37
+
38
+ ### Features
39
+
40
+ * read retarget/adapt reals exactly with matryona 0.3 ([cb5eee4](https://github.com/seuros/batch_machines/commit/cb5eee456ac5a5455d6fe9a3ccac3e0dc5445cbb))
41
+
42
+ ## [0.4.0](https://github.com/seuros/batch_machines/compare/batch_machines/v0.3.0...batch_machines/v0.4.0) (2026-11-14)
43
+
44
+
45
+ ### ⚠ BREAKING CHANGES
46
+
47
+ * adopt matryona-machines 0.2 (symbols!, frozen-first)
48
+
49
+ ### Features
50
+
51
+ * adopt matryona-machines 0.2 (symbols!, frozen-first) ([8c964b4](https://github.com/seuros/batch_machines/commit/8c964b4fbc9c0a051da4e4e187378a6dcd718fe7))
52
+
53
+ ## [0.3.0](https://github.com/seuros/batch_machines/compare/batch_machines/v0.2.0...batch_machines/v0.3.0) (2026-11-14)
54
+
55
+
56
+ ### ⚠ BREAKING CHANGES
57
+
58
+ * seal Flush, resolve it at load, re-check frozen before keeping
59
+
60
+ ### Features
61
+
62
+ * seal Flush, resolve it at load, re-check frozen before keeping ([3cde5ab](https://github.com/seuros/batch_machines/commit/3cde5ab2b43cdd2d30dc10729570f53a705e7d8c))
63
+
64
+ ## [0.2.0](https://github.com/seuros/batch_machines/compare/batch_machines/v0.1.4...batch_machines/v0.2.0) (2026-11-13)
65
+
66
+
67
+ ### ⚠ BREAKING CHANGES
68
+
69
+ * 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 and feedback-machines >= 0.3. configure_pid is gone; Ruby answers symbols and a Flush value.
70
+
71
+ ### Features
72
+
73
+ * answer Result<_, Refusal>, stop refused pushes recording the clock, adapt a caller-owned controller ([a3746a5](https://github.com/seuros/batch_machines/commit/a3746a5c91bf437e38389cb5aee5022b3b760797))
74
+
3
75
  ## [0.1.4](https://github.com/seuros/batch_machines/compare/batch_machines/v0.1.3...batch_machines/v0.1.4) (2026-11-06)
4
76
 
5
77
 
data/Cargo.lock ADDED
@@ -0,0 +1,322 @@
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 = "batch-machines"
16
+ version = "0.7.0"
17
+ dependencies = [
18
+ "feedback-machines",
19
+ "flow-machines",
20
+ "matryona-machines",
21
+ ]
22
+
23
+ [[package]]
24
+ name = "batch_machines_native"
25
+ version = "0.1.8"
26
+ dependencies = [
27
+ "batch-machines",
28
+ "feedback-machines",
29
+ "magnus",
30
+ "matryona-machines",
31
+ "rb-sys",
32
+ ]
33
+
34
+ [[package]]
35
+ name = "bindgen"
36
+ version = "0.72.1"
37
+ source = "registry+https://github.com/rust-lang/crates.io-index"
38
+ checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
39
+ dependencies = [
40
+ "bitflags",
41
+ "cexpr",
42
+ "clang-sys",
43
+ "itertools",
44
+ "proc-macro2",
45
+ "quote",
46
+ "regex",
47
+ "rustc-hash",
48
+ "shlex",
49
+ "syn",
50
+ ]
51
+
52
+ [[package]]
53
+ name = "bitflags"
54
+ version = "2.13.2"
55
+ source = "registry+https://github.com/rust-lang/crates.io-index"
56
+ checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
57
+
58
+ [[package]]
59
+ name = "bytes"
60
+ version = "1.12.1"
61
+ source = "registry+https://github.com/rust-lang/crates.io-index"
62
+ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
63
+
64
+ [[package]]
65
+ name = "cexpr"
66
+ version = "0.6.0"
67
+ source = "registry+https://github.com/rust-lang/crates.io-index"
68
+ checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
69
+ dependencies = [
70
+ "nom",
71
+ ]
72
+
73
+ [[package]]
74
+ name = "cfg-if"
75
+ version = "1.0.5"
76
+ source = "registry+https://github.com/rust-lang/crates.io-index"
77
+ checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
78
+
79
+ [[package]]
80
+ name = "clang-sys"
81
+ version = "1.9.1"
82
+ source = "registry+https://github.com/rust-lang/crates.io-index"
83
+ checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
84
+ dependencies = [
85
+ "glob",
86
+ "libc",
87
+ "libloading",
88
+ ]
89
+
90
+ [[package]]
91
+ name = "either"
92
+ version = "1.19.0"
93
+ source = "registry+https://github.com/rust-lang/crates.io-index"
94
+ checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
95
+
96
+ [[package]]
97
+ name = "feedback-machines"
98
+ version = "0.6.0"
99
+ source = "registry+https://github.com/rust-lang/crates.io-index"
100
+ checksum = "27b8299a2c2c2f595a1d18ccb9a856b56e15b25759d794e8961bf63ae1b212da"
101
+
102
+ [[package]]
103
+ name = "flow-machines"
104
+ version = "0.4.1"
105
+ source = "registry+https://github.com/rust-lang/crates.io-index"
106
+ checksum = "762c59df44265a4181afd1ee4bd1f4a0b87b954b71cbd1bb128f3cbcaaccfac4"
107
+
108
+ [[package]]
109
+ name = "glob"
110
+ version = "0.3.4"
111
+ source = "registry+https://github.com/rust-lang/crates.io-index"
112
+ checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
113
+
114
+ [[package]]
115
+ name = "itertools"
116
+ version = "0.13.0"
117
+ source = "registry+https://github.com/rust-lang/crates.io-index"
118
+ checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
119
+ dependencies = [
120
+ "either",
121
+ ]
122
+
123
+ [[package]]
124
+ name = "lazy_static"
125
+ version = "1.5.1"
126
+ source = "registry+https://github.com/rust-lang/crates.io-index"
127
+ checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
128
+
129
+ [[package]]
130
+ name = "libc"
131
+ version = "0.2.191"
132
+ source = "registry+https://github.com/rust-lang/crates.io-index"
133
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
134
+
135
+ [[package]]
136
+ name = "libloading"
137
+ version = "0.8.9"
138
+ source = "registry+https://github.com/rust-lang/crates.io-index"
139
+ checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
140
+ dependencies = [
141
+ "cfg-if",
142
+ "windows-link",
143
+ ]
144
+
145
+ [[package]]
146
+ name = "magnus"
147
+ version = "0.9.3"
148
+ source = "registry+https://github.com/rust-lang/crates.io-index"
149
+ checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
150
+ dependencies = [
151
+ "bytes",
152
+ "magnus-macros",
153
+ "rb-sys",
154
+ "rb-sys-env",
155
+ "seq-macro",
156
+ ]
157
+
158
+ [[package]]
159
+ name = "magnus-macros"
160
+ version = "0.9.1"
161
+ source = "registry+https://github.com/rust-lang/crates.io-index"
162
+ checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
163
+ dependencies = [
164
+ "proc-macro2",
165
+ "quote",
166
+ "syn",
167
+ ]
168
+
169
+ [[package]]
170
+ name = "matryona-machines"
171
+ version = "0.6.0"
172
+ source = "registry+https://github.com/rust-lang/crates.io-index"
173
+ checksum = "cf8a06ab02efd767270815a1f515a40bbf3bfc77038e9360676ebe8d47833b07"
174
+ dependencies = [
175
+ "magnus",
176
+ ]
177
+
178
+ [[package]]
179
+ name = "memchr"
180
+ version = "2.8.3"
181
+ source = "registry+https://github.com/rust-lang/crates.io-index"
182
+ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
183
+
184
+ [[package]]
185
+ name = "minimal-lexical"
186
+ version = "0.2.1"
187
+ source = "registry+https://github.com/rust-lang/crates.io-index"
188
+ checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
189
+
190
+ [[package]]
191
+ name = "nom"
192
+ version = "7.1.3"
193
+ source = "registry+https://github.com/rust-lang/crates.io-index"
194
+ checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
195
+ dependencies = [
196
+ "memchr",
197
+ "minimal-lexical",
198
+ ]
199
+
200
+ [[package]]
201
+ name = "proc-macro2"
202
+ version = "1.0.107"
203
+ source = "registry+https://github.com/rust-lang/crates.io-index"
204
+ checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
205
+ dependencies = [
206
+ "unicode-ident",
207
+ ]
208
+
209
+ [[package]]
210
+ name = "quote"
211
+ version = "1.0.47"
212
+ source = "registry+https://github.com/rust-lang/crates.io-index"
213
+ checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
214
+ dependencies = [
215
+ "proc-macro2",
216
+ ]
217
+
218
+ [[package]]
219
+ name = "rb-sys"
220
+ version = "0.9.130"
221
+ source = "registry+https://github.com/rust-lang/crates.io-index"
222
+ checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
223
+ dependencies = [
224
+ "rb-sys-build",
225
+ ]
226
+
227
+ [[package]]
228
+ name = "rb-sys-build"
229
+ version = "0.9.130"
230
+ source = "registry+https://github.com/rust-lang/crates.io-index"
231
+ checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
232
+ dependencies = [
233
+ "bindgen",
234
+ "lazy_static",
235
+ "proc-macro2",
236
+ "quote",
237
+ "regex",
238
+ "shell-words",
239
+ "syn",
240
+ ]
241
+
242
+ [[package]]
243
+ name = "rb-sys-env"
244
+ version = "0.2.3"
245
+ source = "registry+https://github.com/rust-lang/crates.io-index"
246
+ checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
247
+
248
+ [[package]]
249
+ name = "regex"
250
+ version = "1.13.1"
251
+ source = "registry+https://github.com/rust-lang/crates.io-index"
252
+ checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
253
+ dependencies = [
254
+ "aho-corasick",
255
+ "memchr",
256
+ "regex-automata",
257
+ "regex-syntax",
258
+ ]
259
+
260
+ [[package]]
261
+ name = "regex-automata"
262
+ version = "0.4.18"
263
+ source = "registry+https://github.com/rust-lang/crates.io-index"
264
+ checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
265
+ dependencies = [
266
+ "aho-corasick",
267
+ "memchr",
268
+ "regex-syntax",
269
+ ]
270
+
271
+ [[package]]
272
+ name = "regex-syntax"
273
+ version = "0.8.11"
274
+ source = "registry+https://github.com/rust-lang/crates.io-index"
275
+ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
276
+
277
+ [[package]]
278
+ name = "rustc-hash"
279
+ version = "2.1.3"
280
+ source = "registry+https://github.com/rust-lang/crates.io-index"
281
+ checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
282
+
283
+ [[package]]
284
+ name = "seq-macro"
285
+ version = "0.3.6"
286
+ source = "registry+https://github.com/rust-lang/crates.io-index"
287
+ checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
288
+
289
+ [[package]]
290
+ name = "shell-words"
291
+ version = "1.1.1"
292
+ source = "registry+https://github.com/rust-lang/crates.io-index"
293
+ checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
294
+
295
+ [[package]]
296
+ name = "shlex"
297
+ version = "1.3.0"
298
+ source = "registry+https://github.com/rust-lang/crates.io-index"
299
+ checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
300
+
301
+ [[package]]
302
+ name = "syn"
303
+ version = "2.0.119"
304
+ source = "registry+https://github.com/rust-lang/crates.io-index"
305
+ checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
306
+ dependencies = [
307
+ "proc-macro2",
308
+ "quote",
309
+ "unicode-ident",
310
+ ]
311
+
312
+ [[package]]
313
+ name = "unicode-ident"
314
+ version = "1.0.27"
315
+ source = "registry+https://github.com/rust-lang/crates.io-index"
316
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
317
+
318
+ [[package]]
319
+ name = "windows-link"
320
+ version = "0.2.1"
321
+ source = "registry+https://github.com/rust-lang/crates.io-index"
322
+ checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
data/Cargo.toml CHANGED
@@ -8,13 +8,15 @@ rust-version = "1.99"
8
8
  license = "MIT"
9
9
  [workspace.dependencies]
10
10
  batch-machines = { path = "ext/batch_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
- feedback-machines = ">=0.2"
14
+ flow-machines = ">=0.4.1"
15
+ feedback-machines = ">=0.6"
15
16
  [workspace.lints.rust]
16
17
  unsafe_code = "deny"
17
18
  unused_must_use = "warn"
19
+ missing_docs = "warn"
18
20
  [workspace.lints.clippy]
19
21
  all = { level = "warn", priority = -1 }
20
22
  pedantic = { level = "warn", priority = -1 }
data/README.md CHANGED
@@ -18,12 +18,17 @@ rows = []
18
18
  def ingest(batch, rows, row)
19
19
  rows << row
20
20
  case batch.push(now_ns)
21
- when 'size', 'deadline' then insert_all(batch, rows)
21
+ in :buffered then nil # counted, keep going
22
+ in BatchMachines::Flush then insert_all(batch, rows) # counted, and it's time
23
+ in :full | :time_regression then rows.pop # NOT counted
22
24
  end
23
25
  end
24
26
 
25
27
  def tick(batch, rows)
26
- insert_all(batch, rows) if batch.poll(now_ns)
28
+ case batch.poll(now_ns)
29
+ in :size | :deadline then insert_all(batch, rows)
30
+ in nil | :time_regression then nil
31
+ end
27
32
  end
28
33
 
29
34
  def insert_all(batch, rows)
@@ -88,15 +93,15 @@ sequenceDiagram
88
93
  participant DB
89
94
 
90
95
  App->>Batch: push(t=0ms)
91
- Batch-->>App: buffered
96
+ Batch-->>App: :buffered
92
97
  App->>Batch: push(t=20ms)
93
- Batch-->>App: buffered
98
+ Batch-->>App: :buffered
94
99
  App->>Batch: push(t=45ms)
95
- Batch-->>App: buffered
100
+ Batch-->>App: :buffered
96
101
  Note over Batch: oldest arrived at 0ms, max wait 50ms
97
102
 
98
103
  App->>Batch: poll(t=50ms)
99
- Batch-->>App: deadline
104
+ Batch-->>App: :deadline
100
105
  App->>DB: INSERT 3 rows
101
106
  App->>Batch: flush(t=51ms)
102
107
  Batch-->>App: 3
@@ -107,18 +112,31 @@ sequenceDiagram
107
112
 
108
113
  ### Push
109
114
 
110
- Every arrival is a `push` with the current time. The return value is a String telling you what to do.
115
+ Every arrival is a `push` with the current time. The answer tells you what happened and what to do.
111
116
 
112
117
  ```ruby
113
118
  batch = BatchMachines::Batch.new(2, 10)
114
119
 
115
- batch.push(1) # => "buffered" room left, no reason to send
116
- batch.push(2) # => "size" target reached, send now
117
- batch.push(3) # => "full" capacity reached, this one was NOT accepted
120
+ batch.push(1) # => :buffered room left, no reason to send
121
+ batch.push(2) # => #<data Flush reason=:size> target reached, send now
122
+ batch.push(3) # => :full capacity reached, this one was NOT counted
118
123
  batch.pending # => 2
119
124
  ```
120
125
 
121
- `"buffered"`, `"size"`, and `"deadline"` all mean the item was counted. `"full"` means it wasn't, and you need to flush before it can be. Keep your own list of payloads alongside, and only append when the push was accepted.
126
+ `:buffered` and a `Flush` both mean the item was counted; `Flush#reason` is `:size` or `:deadline`. `:full` and `:time_regression` are refusals: the item wasn't counted and nothing changed, not even the batch's idea of what time it is. After `:full` you need to flush before it can be. Keep your own list of payloads alongside, and only keep the payload when the push was honoured.
127
+
128
+ Both honoured answers and refusals are truthy. Don't write `if batch.push(now)`; match on the answer.
129
+
130
+ Items aren't always the same size. `push_weighted(now, cost)` spends `cost` units of capacity instead of one, so a byte budget flushes at a byte target. `pending` counts items, `pending_cost` counts what they spent.
131
+
132
+ ```ruby
133
+ batch = BatchMachines::Batch.new(1_000, 50_000_000) # 1000 bytes per flush
134
+ batch.push_weighted(0, 400) # => :buffered
135
+ batch.push_weighted(1, 700) # => :full only 600 left
136
+ batch.push_weighted(1, 600) # => #<data Flush reason=:size>
137
+ batch.pending # => 2
138
+ batch.pending_cost # => 1000
139
+ ```
122
140
 
123
141
  ### Poll
124
142
 
@@ -129,11 +147,12 @@ batch = BatchMachines::Batch.new(100, 50_000_000)
129
147
  batch.push(1_000)
130
148
  batch.push(40_000_000)
131
149
 
132
- batch.poll(50_000_999) # => nil oldest has waited 49.999999ms
133
- batch.poll(50_001_000) # => "deadline" oldest has waited 50ms
150
+ batch.poll(50_000_999) # => nil oldest has waited 49.999999ms
151
+ batch.deadline # => 50_001_000 sleep until then instead of guessing
152
+ batch.poll(50_001_000) # => :deadline oldest has waited 50ms
134
153
  ```
135
154
 
136
- The deadline belongs to the oldest item and never moves. A new arrival doesn't push it back, and neither does changing the target.
155
+ The deadline belongs to the oldest item and never moves. A new arrival doesn't push it back, and neither does changing the target. `deadline` is the instant `poll` first says `:deadline`, and `nil` while the hold is empty.
137
156
 
138
157
  ### Flush
139
158
 
@@ -153,53 +172,81 @@ When an arrival both fills the target and lands at the deadline, you hear about
153
172
 
154
173
  ```ruby
155
174
  batch = BatchMachines::Batch.new(2, 10)
156
- batch.push(0) # => "buffered"
157
- batch.push(10) # => "deadline"
175
+ batch.push(0) # => :buffered
176
+ batch.push(10) # => #<data Flush reason=:deadline>
158
177
  ```
159
178
 
160
179
  ### Adapting the target
161
180
 
162
- The target size starts at capacity. If you'd rather it follow conditions downstream, such as insert latency, feed `adapt` an error signal and it moves the target for you, clamped to `1..capacity`. Out of the box it's a proportional controller with gain 1, so the target simply follows the number you give it. The second argument is how much time passed since the last call, in nanoseconds.
181
+ The target size starts at capacity. If you'd rather it follow conditions downstream, such as insert latency, `retarget` moves it: hand it a number and the target becomes that number, truncated and clamped to `1..capacity`.
163
182
 
164
183
  ```ruby
165
184
  batch = BatchMachines::Batch.new(100, 50_000_000)
166
- batch.target # => 100
185
+ batch.target # => 100
167
186
 
168
- batch.adapt(10, 1_000_000_000) # => 10
169
- batch.adapt(-3, 1_000_000_000) # => 1 never below one
170
- batch.adapt(1000, 1_000_000_000) # => 100 never above capacity
187
+ batch.retarget(10) # => 10
188
+ batch.retarget(-3) # => 1 never below one
189
+ batch.retarget(1000) # => 100 never above capacity
171
190
  ```
172
191
 
173
- Need memory? `configure_pid(p, i, d)` sets the gains. With only an integral gain the target climbs a little more each call:
192
+ Need memory? Bring a controller. `adapt(pid, error, elapsed)` steps your PID once and retargets to its output. The controller is yours: a `FeedbackMachines::Pid` from [feedback_machines](https://github.com/seuros/feedback_machines), or any object whose `step(error, elapsed)` answers the same way. This gem doesn't depend on that one. It only calls `step`. `elapsed` is the time since the last sample, in nanoseconds.
174
193
 
175
194
  ```ruby
195
+ require 'feedback_machines'
196
+
197
+ pid = FeedbackMachines::Pid.new(
198
+ FeedbackMachines::Gains.new(0, 1.0, 0), # integral only
199
+ FeedbackMachines::Limits.new(0, 100)
200
+ )
176
201
  batch = BatchMachines::Batch.new(100, 10)
177
- batch.configure_pid(0, 1.0, 0)
178
202
 
179
- batch.adapt(5.0, 1_000_000_000) # => 5
180
- batch.adapt(5.0, 1_000_000_000) # => 10
181
- batch.adapt(5.0, 1_000_000_000) # => 15
203
+ batch.adapt(pid, 5.0, 1_000_000_000) # => 5
204
+ batch.adapt(pid, 5.0, 1_000_000_000) # => 10
205
+ batch.adapt(pid, 5.0, 1_000_000_000) # => 15
206
+ batch.adapt(pid, 5.0, 0) # => :invalid_duration nothing stepped, target still 15
182
207
  ```
183
208
 
184
- Lowering the target doesn't drop anything already in the hold. Items past the target still count, and the next push or poll says `"size"` until you flush.
209
+ Lowering the target doesn't drop anything already in the hold. Items past the target still count, and the next push or poll says size until you flush.
185
210
 
186
211
  ```ruby
187
212
  batch = BatchMachines::Batch.new(5, 10)
188
213
  batch.push(0)
189
- batch.adapt(2.0, 1_000_000_000) # => 2
190
- batch.push(1) # => "size"
191
- batch.push(2) # => "size" accepted, still under capacity 5
192
- batch.pending # => 3
214
+ batch.retarget(2) # => 2
215
+ batch.push(1) # => #<data Flush reason=:size>
216
+ batch.push(2) # => #<data Flush reason=:size> counted, still under capacity 5
217
+ batch.pending # => 3
193
218
  ```
194
219
 
195
220
  ## The Rules of the Consolidator
196
221
 
197
- - **Capacity is an Integer** in `1...2**32`, and `max_wait_ns` is a positive Integer. Zero for either raises `ArgumentError`.
198
- - **Time is unsigned 64-bit Integer nanoseconds.** Floats and strings raise `TypeError`, negative or overflow raises `RangeError`.
199
- - **Time only moves forward.** A `push` with an earlier clock than the last one returns `"rejected"` and counts nothing. `poll` and `flush` with an earlier clock return `nil` and change nothing.
200
- - **Gains are finite and non-negative.** Infinite, NaN, or negative gains raise `ArgumentError`. An error of infinity or NaN raises too, and `adapt` with zero elapsed raises.
201
- - **A blown-up controller returns `nil`** and leaves the target where it was, rather than handing you a nonsense size.
202
- - **Frozen means frozen.** `freeze` the batch and `push`, `poll`, `flush`, `adapt`, and `configure_pid` all raise `FrozenError`.
222
+ - **Ruby mirrors the Rust core.** `Batch.new(capacity, max_wait)` and every method take their arguments positionally, in the core's order. `Admission::Buffered` is `:buffered`, `Admission::Flush(reason)` is a `BatchMachines::Flush` `Data` with a `reason`, and `FlushReason` is `:size` or `:deadline`.
223
+ - **Every answer, by method.**
224
+
225
+ | Method | Honoured | Records the clock | Refused |
226
+ | --- | --- | --- | --- |
227
+ | `Flush.new(reason)` | a `Flush` | no clock | none; a symbol that is not `:size` or `:deadline` raises `RangeError`, a non-Symbol `TypeError` |
228
+ | `Batch.new(capacity, max_wait)` | a `Batch` | no clock | none; a zero `max_wait` raises `RangeError` |
229
+ | `push(now)` | `:buffered` or a `Flush`; the item is counted either way | yes, every honoured answer | `:time_regression`, `:full`, `:overflow` |
230
+ | `push_weighted(now, cost)` | `:buffered` or a `Flush`; the item is counted either way | yes, every honoured answer | `:time_regression`, `:full`, `:overflow` |
231
+ | `poll(now)` | `:size` or `:deadline`, `nil` when nothing is due at this instant | yes, every honoured answer, `nil` included | `:time_regression` |
232
+ | `flush(now)` | the items that were pending (Integer), `0` for an empty hold | yes when items left; `0` records nothing | `:time_regression` |
233
+ | `adapt(pid, error, elapsed)` | the new target (Integer) | no, `elapsed` is a span | `:not_finite`, `:invalid_duration`, `:overflow` |
234
+ | `retarget(output)` | the new target (Integer) | no clock | `:not_finite` |
235
+ | `capacity`, `max_wait`, `pending`, `pending_cost`, `target` | Integer | no, a query | never refuse |
236
+ | `deadline` | Integer nanoseconds, `nil` when nothing is pending | no, a query | never refuses |
237
+
238
+ Every refusal has its own symbol; there is no catch-all. `nil` only ever means "nothing due" or "nothing pending".
239
+ - **A `Flush` is valid or does not exist.** `Flush.new(:nope)` raises `RangeError` and `Flush.new('size')` raises `TypeError`, exactly as if the batch had tried to answer it. Build one by hand to compare against and it is held to the same rule. `Flush` is sealed: `Flush.allocate` is gone and subclassing raises `TypeError` (a named `class X < Flush` still binds its constant first; Ruby does that before `inherited` runs). The batch never reads a `Flush` back, so a forged one cannot reach it.
240
+ - **The binding never loses work.** Everything that can raise, a bad argument, a frozen batch, a controller that raises, happens before the batch counts or retargets anything. The `Flush` class is resolved once when the gem loads; swapping the constant later changes nothing the batch builds. A push answers with a `Flush` built by Ruby code, so it is counted on a copy and the batch moves only once that answer exists. If a call raised, the batch is where it was. If a redefined `Flush.new` froze the batch while the answer was being built, the push raises `FrozenError`; if it changed the batch, `RuntimeError` and that change stands. Either way the push is not applied.
241
+ - **A refusal never raises and changes nothing.** No item counted, no cost held, the target where it was. The clock a refused call carried is not remembered either, so a refused push can't turn your next call into a `:time_regression`.
242
+ - **Time only moves forward.** `push`, `poll` and `flush` with a clock earlier than the last recorded one answer `:time_regression`. An answer records the clock when it depends on the clock: every honoured `push`, every honoured `poll` (a `nil` is "nothing due at this instant") and a `flush` that emptied the hold.
243
+ - **Flushing an empty hold is honoured** and answers `0`. Do it twice, get `0` twice. That answer is true whatever the time, so it records nothing: an empty flush at a late clock does not turn an earlier push into a `:time_regression`.
244
+ - **Capacity and cost are Integers** in `1...2**32`. Anything else is `TypeError`, zero or out of range is `RangeError`.
245
+ - **Time is Integer nanoseconds.** Spans (`max_wait`, `elapsed`) are in `0...2**64`. Instants (`now`) run over the whole Rust `Duration` range, `0..Duration::MAX` nanoseconds (about `1.8e28`), so every `deadline` the batch answers, `now + max_wait` past `2**64` included, reads back as `now`. Floats and strings raise `TypeError`, negative or too large raises `RangeError`. A zero `max_wait` raises `RangeError`: the first item would be late on arrival.
246
+ - **The controller is duck-typed.** `adapt` calls `pid.step(error, elapsed)` and expects a Float or one of `:not_finite`, `:invalid_duration`, `:overflow`, which it hands straight back to you. An Integer output is taken too, as its nearest Float (one past `Float::MAX` is infinite, so `:not_finite`); no `to_f` is called. Any other Symbol from `step` is a `RangeError`, anything that is neither a Float, an Integer nor a Symbol (a Rational included) a `TypeError` naming its class; an object without `step` is a `NoMethodError`. The error must be a number and `elapsed` an Integer in range, checked before the controller is touched. A refusing controller has not been stepped, so nothing changed on either side.
247
+ - **`:overflow` from a push** means the item would start a batch at a clock so late that `now + max_wait` doesn't fit a `Duration`. Nothing was counted.
248
+ - **Frozen means frozen.** `freeze` the batch and `push`, `push_weighted`, `poll`, `flush`, `adapt`, and `retarget` all raise `FrozenError`, before any controller is stepped. A controller whose `step` freezes the batch has been stepped (the binding cannot undo your object); `adapt` then raises `FrozenError` and the target is where it was.
249
+ - **No ids, nothing to restore.** The batch hands out no handles. After a restart, build a new one; it starts empty.
203
250
 
204
251
  ## What You Think You're Doing vs Reality
205
252