join_machines 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,54 @@
1
+ //! Private native entry point.
2
+ use crate::{
3
+ CAPACITY, Wrapper, bounds_reach, other, reach_contains, validate_bounds, validate_pair,
4
+ validate_reach, validate_record, validate_retired, validate_watermark,
5
+ };
6
+ use magnus::{Error, Ruby, function, method, prelude::*};
7
+ use matryona_machines::ruby::Class;
8
+
9
+ #[magnus::init]
10
+ fn init(ruby: &Ruby) -> Result<(), Error> {
11
+ let module = ruby.define_module("JoinMachines")?;
12
+ module.const_set("CAPACITY", CAPACITY)?;
13
+ crate::classes::resolve(ruby, module)?;
14
+ module.define_singleton_method("other", function!(other, 1))?;
15
+ // Bounds is a Data class defined in Ruby; its arithmetic lives here.
16
+ let known = crate::classes::classes(ruby)?;
17
+ let bounds = known.bounds.get(ruby);
18
+ bounds.define_method("reach", method!(bounds_reach, 2))?;
19
+ let reach = known.reach.get(ruby);
20
+ reach.define_method("include?", method!(reach_contains, 1))?;
21
+ // The Data classes are defined in Ruby; the core validates them here. Each
22
+ // hook takes the value just built, reads it natively, and answers nil or
23
+ // raises.
24
+ module.define_singleton_method("__reach", function!(validate_reach, 1))?;
25
+ module.define_singleton_method("__bounds", function!(validate_bounds, 1))?;
26
+ module.define_singleton_method("__pair", function!(validate_pair, 1))?;
27
+ module.define_singleton_method("__record", function!(validate_record, 1))?;
28
+ module.define_singleton_method("__retired", function!(validate_retired, 1))?;
29
+ module.define_singleton_method("__watermark", function!(validate_watermark, 1))?;
30
+ let class = module.define_class("Join", ruby.class_object())?;
31
+ class.undef_default_alloc_func();
32
+ class.define_singleton_method("new", function!(Wrapper::new, 1))?;
33
+ class.define_method("bounds", method!(Wrapper::bounds, 0))?;
34
+ class.define_method("capacity", method!(Wrapper::capacity, 1))?;
35
+ class.define_method("size", method!(Wrapper::size, 1))?;
36
+ class.define_method("empty?", method!(Wrapper::empty, 0))?;
37
+ class.define_method("include?", method!(Wrapper::include, 2))?;
38
+ class.define_method("watermark", method!(Wrapper::watermark, 1))?;
39
+ class.define_method("side_watermark", method!(Wrapper::side_watermark, 1))?;
40
+ class.define_method("insert", method!(Wrapper::insert, 2))?;
41
+ class.define_method("pending?", method!(Wrapper::pending, 0))?;
42
+ class.define_method("pending_pairs", method!(Wrapper::pending_pairs, 0))?;
43
+ class.define_method("drain", method!(Wrapper::drain, 1))?;
44
+ class.define_method("advance_watermark", method!(Wrapper::advance_watermark, 2))?;
45
+ class.define_method(
46
+ "advance_watermark_from",
47
+ method!(Wrapper::advance_watermark_from, 2),
48
+ )?;
49
+ class.define_method("retirable", method!(Wrapper::retirable, 0))?;
50
+ class.define_method("retire", method!(Wrapper::retire, 1))?;
51
+ // `new` answers a Join: its class is fixed now, so building one never
52
+ // runs `Object.const_get`.
53
+ Class::pin_wrapped::<Wrapper>(ruby, class).map(drop)
54
+ }
@@ -0,0 +1,391 @@
1
+ //! Thin binding to the bounded two-input interval join.
2
+ mod classes;
3
+ mod init;
4
+
5
+ use std::cell::RefCell;
6
+
7
+ use classes::{build, classes, members};
8
+ use join_machines::{
9
+ Advancing, Bounds, Inserting, Join, Pair, Reach, Record, Refusal, Retired, Side, Watermark,
10
+ };
11
+ use magnus::{Error, RArray, Ruby, Symbol, Value, typed_data::Obj, value::ReprValue};
12
+ use matryona_machines::ruby::{
13
+ Class, Refused, Symbols, integer, keep, optional, own_or_sibling_why, symbol,
14
+ };
15
+
16
+ /// Live records held per input.
17
+ const CAPACITY: usize = 64;
18
+
19
+ /// A Rust buffer for at most `max` entries, of which `ready` exist.
20
+ fn buffer<T: Clone + Default>(max: u64, ready: usize) -> Vec<T> {
21
+ let room = usize::try_from(max).unwrap_or(usize::MAX);
22
+ vec![T::default(); room.min(ready)]
23
+ }
24
+
25
+ matryona_machines::symbols! {
26
+ /// The sibling's `Side` as `:left` and `:right`.
27
+ Sides for Side as "side" {
28
+ Left => "left",
29
+ Right => "right",
30
+ }
31
+ }
32
+
33
+ /// `:left` or `:right`: `TypeError` for a non-Symbol, `RangeError` for
34
+ /// another Symbol.
35
+ fn side(value: Value) -> Result<Side, Error> {
36
+ Sides::parse(&Ruby::get_with(value), value)
37
+ }
38
+
39
+ /// The members of a gem value (exactly its class, read natively), each
40
+ /// converted to a `u64` under its member's name: a forged value raises, it
41
+ /// never reaches the core.
42
+ fn numbers<const N: usize>(
43
+ value: Value,
44
+ class: impl FnOnce(&classes::Classes) -> Class,
45
+ message: &'static str,
46
+ names: [&str; N],
47
+ ) -> Result<[u64; N], Error> {
48
+ let ruby = Ruby::get_with(value);
49
+ let read = members::<N>(&ruby, value, class(classes(&ruby)?), message)?;
50
+ let mut out = [0; N];
51
+ for ((slot, member), name) in out.iter_mut().zip(read).zip(names) {
52
+ *slot = integer(member, name)?;
53
+ }
54
+ Ok(out)
55
+ }
56
+
57
+ /// A `JoinMachines::Bounds`, re-validated through the core's `Bounds::new`.
58
+ fn limits(value: Value) -> Result<Bounds, Error> {
59
+ let [before, after] = numbers(
60
+ value,
61
+ |known| known.bounds,
62
+ "expected a JoinMachines::Bounds",
63
+ ["before", "after"],
64
+ )?;
65
+ Ok(Bounds::new(before, after))
66
+ }
67
+
68
+ /// A `JoinMachines::Record`: every field an Integer in `0..2**64`.
69
+ fn entry(value: Value) -> Result<Record, Error> {
70
+ let names = ["id", "key", "timestamp"];
71
+ let [id, key, timestamp] = numbers(
72
+ value,
73
+ |known| known.record,
74
+ "expected a JoinMachines::Record",
75
+ names,
76
+ )?;
77
+ Ok(Record { id, key, timestamp })
78
+ }
79
+
80
+ /// The core's `Reach::new`: what `Reach.new` is held to.
81
+ fn checked_reach(ruby: &Ruby, first: u64, last: u64) -> Result<Reach, Error> {
82
+ Reach::new(first, last).ok_or_else(|| {
83
+ Error::new(
84
+ ruby.exception_range_error(),
85
+ "a reach's first must not be above its last",
86
+ )
87
+ })
88
+ }
89
+
90
+ // Private hooks behind every value's `initialize`, called with the value
91
+ // itself once `Data#initialize` stored it: its members are read from the
92
+ // struct, never through `deconstruct` or a reader, and only from an instance
93
+ // of exactly its class.
94
+
95
+ /// The `N` members of the value being built, `this`, read natively.
96
+ fn own<const N: usize>(
97
+ ruby: &Ruby,
98
+ this: Value,
99
+ class: impl FnOnce(&classes::Classes) -> Class,
100
+ message: &'static str,
101
+ ) -> Result<[Value; N], Error> {
102
+ members::<N>(ruby, this, class(classes(ruby)?), message)
103
+ }
104
+
105
+ /// `Reach.new`: the core's `Reach::new`.
106
+ fn validate_reach(ruby: &Ruby, this: Value) -> Result<(), Error> {
107
+ let message = "expected a JoinMachines::Reach";
108
+ let [first, last] = own(ruby, this, |known| known.reach, message)?;
109
+ let (first, last) = (integer(first, "first")?, integer(last, "last")?);
110
+ checked_reach(ruby, first, last).map(|_| ())
111
+ }
112
+
113
+ // `Bounds.new`, `Pair.new`, `Record.new`, `Retired.new` and `Watermark.new`.
114
+ // The core's `Bounds::new` and its public-field `Pair`, `Record` and
115
+ // `Retired` accept every value of their field types, so converting each
116
+ // member to that type (an Integer in `0..2**64`, a side, a
117
+ // `JoinMachines::Record`, `nil` or an Integer) is the whole check.
118
+
119
+ fn validate_bounds(ruby: &Ruby, this: Value) -> Result<(), Error> {
120
+ let message = "expected a JoinMachines::Bounds";
121
+ let [before, after] = own(ruby, this, |known| known.bounds, message)?;
122
+ integer::<u64>(before, "before")?;
123
+ integer::<u64>(after, "after").map(drop)
124
+ }
125
+
126
+ fn validate_pair(ruby: &Ruby, this: Value) -> Result<(), Error> {
127
+ let message = "expected a JoinMachines::Pair";
128
+ let [key, left, right] = own(ruby, this, |known| known.pair, message)?;
129
+ integer::<u64>(key, "key")?;
130
+ integer::<u64>(left, "left")?;
131
+ integer::<u64>(right, "right").map(drop)
132
+ }
133
+
134
+ fn validate_record(ruby: &Ruby, this: Value) -> Result<(), Error> {
135
+ let message = "expected a JoinMachines::Record";
136
+ let [id, key, timestamp] = own(ruby, this, |known| known.record, message)?;
137
+ integer::<u64>(id, "id")?;
138
+ integer::<u64>(key, "key")?;
139
+ integer::<u64>(timestamp, "timestamp").map(drop)
140
+ }
141
+
142
+ fn validate_retired(ruby: &Ruby, this: Value) -> Result<(), Error> {
143
+ let message = "expected a JoinMachines::Retired";
144
+ let [input, record] = own(ruby, this, |known| known.retired, message)?;
145
+ side(input)?;
146
+ entry(record).map(drop)
147
+ }
148
+
149
+ fn validate_watermark(ruby: &Ruby, this: Value) -> Result<(), Error> {
150
+ let message = "expected a JoinMachines::Watermark";
151
+ let [value] = own(ruby, this, |known| known.watermark, message)?;
152
+ optional::<u64>(value, "value").map(drop)
153
+ }
154
+
155
+ /// `nil` or an Integer in `0..2**64`, as the sibling's `Watermark`.
156
+ fn watermark_of(value: Option<u64>) -> Watermark {
157
+ value.map_or_else(Watermark::default, Watermark::at)
158
+ }
159
+
160
+ /// `Reach#include?`: the core's `Reach::contains`.
161
+ fn reach_contains(ruby: &Ruby, this: Value, timestamp: Value) -> Result<bool, Error> {
162
+ let timestamp = integer(timestamp, "timestamp")?;
163
+ let [first, last] = numbers(
164
+ this,
165
+ |known| known.reach,
166
+ "expected a JoinMachines::Reach",
167
+ ["first", "last"],
168
+ )?;
169
+ Ok(checked_reach(ruby, first, last)?.contains(timestamp))
170
+ }
171
+
172
+ matryona_machines::symbols! {
173
+ /// The core's refusals, each the snake case of its variant.
174
+ Refusals for Refusal as "a refusal" {
175
+ Mismatch => "mismatch",
176
+ Pending => "pending",
177
+ Late => "late",
178
+ Full => "full",
179
+ WatermarkRegressed => "watermark_regressed",
180
+ }
181
+ }
182
+
183
+ matryona_machines::symbols! {
184
+ /// An honoured watermark advance.
185
+ Advancings for Advancing as "an advance" {
186
+ Advanced => "advanced",
187
+ Repeated => "repeated",
188
+ }
189
+ }
190
+
191
+ matryona_machines::symbols! {
192
+ /// An honoured insert.
193
+ Insertings for Inserting as "an insert" {
194
+ Accepted => "accepted",
195
+ Duplicate => "duplicate",
196
+ }
197
+ }
198
+
199
+ fn advancing(ruby: &Ruby, outcome: Result<Advancing, Refusal>) -> Symbol {
200
+ symbol(ruby, outcome.map_or_else(Refusals::name, Advancings::name))
201
+ }
202
+
203
+ /// `Bounds#reach(side, timestamp)`: the core's `Reach`, as a `Reach`.
204
+ fn bounds_reach(ruby: &Ruby, this: Value, input: Value, timestamp: Value) -> Result<Value, Error> {
205
+ let (input, timestamp) = (side(input)?, integer(timestamp, "timestamp")?);
206
+ let reach = limits(this)?.reach(input, timestamp);
207
+ build(ruby, classes(ruby)?.reach, (reach.first(), reach.last()))
208
+ }
209
+
210
+ /// `Side::other` for the Symbol that stands for a side.
211
+ fn other(ruby: &Ruby, input: Value) -> Result<Symbol, Error> {
212
+ Ok(Sides::symbol(ruby, side(input)?.other()))
213
+ }
214
+
215
+ #[magnus::wrap(class = "JoinMachines::Join", free_immediately, size)]
216
+ struct Wrapper {
217
+ core: RefCell<Join<CAPACITY, CAPACITY>>,
218
+ }
219
+
220
+ impl Wrapper {
221
+ fn new(bounds: Value) -> Result<Self, Error> {
222
+ Ok(Self {
223
+ core: RefCell::new(Join::new(limits(bounds)?)),
224
+ })
225
+ }
226
+
227
+ fn bounds(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
228
+ let bounds = this.core.borrow().bounds();
229
+ build(
230
+ ruby,
231
+ classes(ruby)?.bounds,
232
+ (bounds.before(), bounds.after()),
233
+ )
234
+ }
235
+
236
+ fn insert(ruby: &Ruby, this: Obj<Self>, input: Value, record: Value) -> Result<Symbol, Error> {
237
+ this.check_frozen()?;
238
+ let (input, record) = (side(input)?, entry(record)?);
239
+ let outcome = this.core.borrow_mut().insert(input, record);
240
+ Ok(symbol(
241
+ ruby,
242
+ outcome.map_or_else(Refusals::name, Insertings::name),
243
+ ))
244
+ }
245
+
246
+ fn pending(&self) -> bool {
247
+ self.core.borrow().pending()
248
+ }
249
+
250
+ fn pending_pairs(&self) -> usize {
251
+ self.core.borrow().pending_pairs()
252
+ }
253
+
254
+ /// Drains into a Rust buffer and builds every `Pair` through [`keep`]: a
255
+ /// raise while building leaves every pair owed, a freeze meanwhile
256
+ /// raises `FrozenError`, a re-entrant change `RuntimeError`.
257
+ fn drain(ruby: &Ruby, this: Obj<Self>, max: Value) -> Result<RArray, Error> {
258
+ this.check_frozen()?;
259
+ let max = integer(max, "max")?;
260
+ let class = classes(ruby)?.pair;
261
+ keep(
262
+ ruby,
263
+ this,
264
+ &this.core,
265
+ |next| {
266
+ let mut buffer = buffer::<Pair>(max, next.pending_pairs());
267
+ let written = next.drain(&mut buffer);
268
+ buffer.truncate(written);
269
+ buffer
270
+ },
271
+ |drained| {
272
+ let result = ruby.ary_new_capa(drained.len());
273
+ for pair in drained {
274
+ result.push(build(ruby, class, (pair.key, pair.left, pair.right))?)?;
275
+ }
276
+ Ok(result)
277
+ },
278
+ )
279
+ }
280
+
281
+ fn advance_watermark(
282
+ ruby: &Ruby,
283
+ this: Obj<Self>,
284
+ input: Value,
285
+ value: Value,
286
+ ) -> Result<Symbol, Error> {
287
+ this.check_frozen()?;
288
+ let (input, value) = (side(input)?, integer(value, "value")?);
289
+ let outcome = this.core.borrow_mut().advance_watermark(input, value);
290
+ Ok(advancing(ruby, outcome))
291
+ }
292
+
293
+ /// Reads the watermark's value (an Integer, or nil for "nothing observed
294
+ /// yet") into the sibling type the core takes: natively from this gem's
295
+ /// own `Watermark`, through `#value` from a sibling's. A `#value` that
296
+ /// froze the join raises `FrozenError` before the core is called.
297
+ fn advance_watermark_from(
298
+ ruby: &Ruby,
299
+ this: Obj<Self>,
300
+ input: Value,
301
+ watermark: Value,
302
+ ) -> Result<Symbol, Error> {
303
+ this.check_frozen()?;
304
+ let input = side(input)?;
305
+ let source = watermark_of(Self::watermark_value(ruby, watermark)?);
306
+ this.check_frozen()?;
307
+ let outcome = this
308
+ .core
309
+ .borrow_mut()
310
+ .advance_watermark_from(input, &source);
311
+ Ok(advancing(ruby, outcome))
312
+ }
313
+
314
+ /// `watermark`'s value: this gem's `Watermark` exactly (read natively),
315
+ /// `TypeError` for a subclass of it, else a sibling's read by `#value`.
316
+ fn watermark_value(ruby: &Ruby, watermark: Value) -> Result<Option<u64>, Error> {
317
+ let own = classes(ruby)?.watermark.get(ruby);
318
+ let [value] = own_or_sibling_why(ruby, watermark, own, ["value"], |why| match why {
319
+ Refused::Subclass => {
320
+ "JoinMachines::Watermark is sealed: a subclass of it is not a Watermark"
321
+ }
322
+ _ => "watermark must be a JoinMachines::Watermark or respond to #value",
323
+ })?;
324
+ optional(value, "value")
325
+ }
326
+
327
+ fn watermark(&self, input: Value) -> Result<Option<u64>, Error> {
328
+ Ok(self.core.borrow().watermark(side(input)?))
329
+ }
330
+
331
+ fn side_watermark(ruby: &Ruby, this: &Self, input: Value) -> Result<Value, Error> {
332
+ let watermark = this.core.borrow().side_watermark(side(input)?);
333
+ build(ruby, classes(ruby)?.watermark, (watermark.value(),))
334
+ }
335
+
336
+ fn retirable(&self) -> usize {
337
+ self.core.borrow().retirable()
338
+ }
339
+
340
+ /// Retires into a Rust buffer and builds every `Retired` through
341
+ /// [`keep`]: a raise while building leaves every record held, a freeze
342
+ /// meanwhile raises `FrozenError`, a re-entrant change `RuntimeError`.
343
+ fn retire(ruby: &Ruby, this: Obj<Self>, max: Value) -> Result<Value, Error> {
344
+ this.check_frozen()?;
345
+ let max = integer(max, "max")?;
346
+ let known = classes(ruby)?;
347
+ keep(
348
+ ruby,
349
+ this,
350
+ &this.core,
351
+ |next| {
352
+ let mut buffer = buffer::<Retired>(max, next.retirable());
353
+ next.retire(&mut buffer).map(|written| {
354
+ buffer.truncate(written);
355
+ buffer
356
+ })
357
+ },
358
+ |retired| {
359
+ let retired = match retired {
360
+ Ok(retired) => retired,
361
+ Err(refused) => return Ok(Refusals::symbol(ruby, refused).as_value()),
362
+ };
363
+ let result = ruby.ary_new_capa(retired.len());
364
+ for gone in retired {
365
+ let held = gone.record;
366
+ let record = build(ruby, known.record, (held.id, held.key, held.timestamp))?;
367
+ let input = Sides::symbol(ruby, gone.side);
368
+ result.push(build(ruby, known.retired, (input, record))?)?;
369
+ }
370
+ Ok(result.as_value())
371
+ },
372
+ )
373
+ }
374
+
375
+ fn size(&self, input: Value) -> Result<usize, Error> {
376
+ Ok(self.core.borrow().len(side(input)?))
377
+ }
378
+
379
+ fn include(&self, input: Value, id: Value) -> Result<bool, Error> {
380
+ let (input, id) = (side(input)?, integer(id, "id")?);
381
+ Ok(self.core.borrow().contains(input, id))
382
+ }
383
+
384
+ fn empty(&self) -> bool {
385
+ self.core.borrow().is_empty()
386
+ }
387
+
388
+ fn capacity(&self, input: Value) -> Result<usize, Error> {
389
+ Ok(self.core.borrow().capacity(side(input)?))
390
+ }
391
+ }
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+ module JoinMachines
3
+ VERSION = '0.6.2'
4
+ end
@@ -0,0 +1,65 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'join_machines/version'
4
+
5
+ module JoinMachines
6
+ # Every value below is checked by the core when it is built, by hand or by
7
+ # the gem, `with` included: TypeError for a wrong type, RangeError for a
8
+ # value the core rejects. `hook` names the private native check, handed the
9
+ # value itself once stored: it reads the members from the struct, never
10
+ # through `deconstruct` or a reader, so neither can lie to it.
11
+ module Checked
12
+ def self.by(hook)
13
+ Module.new do
14
+ define_method(:initialize) do |**fields|
15
+ super(**fields)
16
+ JoinMachines.__send__(hook, self)
17
+ end
18
+ end
19
+ end
20
+ end
21
+
22
+ # Inclusive range of opposite-side event times a record can match. Like the
23
+ # core's `Reach::new` it holds Integers in 0..2**64-1 with `first <= last`.
24
+ # `include?(timestamp)` is native (the core's `contains`).
25
+ Reach = Data.define(:first, :last) { include Checked.by(:__reach) }
26
+
27
+ # Interval bounds: a pair matches when `left - before <= right <= left + after`
28
+ # in event time. Both are Integers in 0..2**64-1. `reach(side, timestamp)` is
29
+ # native: the opposite-side timestamps reachable from a record on `side`, a
30
+ # Reach saturating at the edges of 0..2**64-1.
31
+ Bounds = Data.define(:before, :after) { include Checked.by(:__bounds) }
32
+
33
+ # A matched pair of record ids sharing a join key; Integers in 0..2**64-1.
34
+ Pair = Data.define(:key, :left, :right) { include Checked.by(:__pair) }
35
+ # Join metadata for one externally stored record; Integers in 0..2**64-1.
36
+ Record = Data.define(:id, :key, :timestamp) { include Checked.by(:__record) }
37
+ # A record the join dropped; its payload can be released. `side` is :left or
38
+ # :right, `record` a Record.
39
+ Retired = Data.define(:side, :record) { include Checked.by(:__retired) }
40
+
41
+ # One input's event-time progress, as `Join#side_watermark` answers it: a
42
+ # frozen copy whose `value` is an Integer in 0..2**64-1, or nil before the
43
+ # first watermark. It reads the way `Join#advance_watermark_from` expects, so
44
+ # it can be handed to another join; it does not advance.
45
+ Watermark = Data.define(:value) { include Checked.by(:__watermark) }
46
+ end
47
+
48
+ # Native is required: no algorithm fallback. It validates and builds the Data
49
+ # values above, resolves their classes once at load and adds `Bounds#reach`
50
+ # and `Reach#include?`, so they must exist first.
51
+ require 'join_machines_native/join_machines_native'
52
+
53
+ module JoinMachines
54
+ private_class_method :__reach, :__bounds, :__pair, :__record, :__retired, :__watermark
55
+ private_constant :Checked
56
+
57
+ # Sealed: no subclass can skip the check by overriding `initialize`, and no
58
+ # bare `allocate` builds a value that never ran it. Sealing stops
59
+ # accidents, not reflection, so the native side reads only instances of
60
+ # exactly these classes and re-validates their members through the core.
61
+ [Reach, Bounds, Pair, Record, Retired, Watermark].each do |value|
62
+ value.singleton_class.undef_method(:allocate)
63
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
64
+ end
65
+ end
@@ -0,0 +1,140 @@
1
+ module JoinMachines
2
+ VERSION: String
3
+ # Live records each input holds.
4
+ CAPACITY: Integer
5
+
6
+ type side = :left | :right
7
+
8
+ # Refusals: the call was not honoured and changed nothing. Every reason has
9
+ # its own symbol; there is no catch-all.
10
+ type refusal = :mismatch | :pending | :late | :full | :watermark_regressed
11
+
12
+ # The core's `Advancing`: what an accepted watermark did.
13
+ type advancing = :advanced | :repeated
14
+
15
+ # The core's `Side::other`: the opposite input.
16
+ def self.other: (side) -> side
17
+
18
+ # Every Data value is checked by the core when built, `with` included:
19
+ # TypeError for a wrong type, RangeError for a value the core rejects
20
+ # (an Integer outside 0..2**64-1, a side other than :left or :right).
21
+ # Every value class is sealed: no `allocate`, subclassing raises TypeError.
22
+ # Where the binding reads one back it takes only an instance of exactly the
23
+ # class (TypeError otherwise) and re-validates its members (RangeError).
24
+
25
+ # Mirrors the core's `Reach`, validated by `Reach::new`: RangeError unless
26
+ # first <= last.
27
+ class Reach < Data
28
+ attr_reader first: Integer
29
+ attr_reader last: Integer
30
+ def self.new: (Integer first, Integer last) -> Reach
31
+ | (first: Integer, last: Integer) -> Reach
32
+ # The core's `contains`.
33
+ def include?: (Integer timestamp) -> bool
34
+ end
35
+
36
+ # Mirrors the core's `Bounds`: any two Integers in 0..2**64-1.
37
+ class Bounds < Data
38
+ attr_reader before: Integer
39
+ attr_reader after: Integer
40
+ def self.new: (Integer before, Integer after) -> Bounds
41
+ | (before: Integer, after: Integer) -> Bounds
42
+ def reach: (side, Integer timestamp) -> Reach
43
+ end
44
+
45
+ # Mirrors the core's `Pair`: any three Integers in 0..2**64-1.
46
+ class Pair < Data
47
+ attr_reader key: Integer
48
+ attr_reader left: Integer
49
+ attr_reader right: Integer
50
+ def self.new: (Integer key, Integer left, Integer right) -> Pair
51
+ | (key: Integer, left: Integer, right: Integer) -> Pair
52
+ end
53
+
54
+ # Mirrors the core's `Record`: any three Integers in 0..2**64-1.
55
+ class Record < Data
56
+ attr_reader id: Integer
57
+ attr_reader key: Integer
58
+ attr_reader timestamp: Integer
59
+ def self.new: (Integer id, Integer key, Integer timestamp) -> Record
60
+ | (id: Integer, key: Integer, timestamp: Integer) -> Record
61
+ end
62
+
63
+ # Mirrors the core's `Retired`: TypeError unless `record` is a Record.
64
+ class Retired < Data
65
+ attr_reader side: side
66
+ attr_reader record: Record
67
+ def self.new: (side side, Record record) -> Retired
68
+ | (side: side, record: Record) -> Retired
69
+ end
70
+
71
+ # Anything that reads like WindowMachines::Watermark.
72
+ interface _Watermark
73
+ def value: () -> Integer?
74
+ end
75
+
76
+ # What `Join#side_watermark` answers: a frozen copy of one input's progress.
77
+ # `value` is nil before the first watermark, else an Integer in
78
+ # 0..2**64-1. It satisfies `_Watermark`.
79
+ class Watermark < Data
80
+ attr_reader value: Integer?
81
+ def self.new: (Integer? value) -> Watermark
82
+ | (value: Integer?) -> Watermark
83
+ end
84
+
85
+ class Join
86
+ def self.new: (Bounds bounds) -> Join
87
+ def bounds: () -> Bounds
88
+ def capacity: (side) -> Integer
89
+ # Live records held for one input (the core's `len`).
90
+ def size: (side) -> Integer
91
+ def empty?: () -> bool
92
+ # The core's `contains`.
93
+ def include?: (side, Integer id) -> bool
94
+ # Honoured: :accepted, or :duplicate (the core's `Inserting`) when exactly
95
+ # this record is already held on that side: nothing changes and no pair is
96
+ # owed twice. Refused: :mismatch (the id is held with another key or
97
+ # timestamp), :pending, :late (at or below its own side's watermark; the
98
+ # other side's watermark never makes a record late), :full. A held id is
99
+ # answered first.
100
+ def insert: (side, Record record) -> (:accepted | :duplicate | :mismatch | :pending | :late | :full)
101
+ def pending?: () -> bool
102
+ def pending_pairs: () -> Integer
103
+ # At most `max` owed pairs, [] when none is owed. Never refuses. A raise
104
+ # while building the answer drains nothing; FrozenError if building it
105
+ # froze the join, RuntimeError if it changed it; nothing drained.
106
+ def drain: (Integer max) -> Array[Pair]
107
+ # Honoured: :advanced, and :repeated when the side already held exactly
108
+ # `value` (nothing changes). Refused: :watermark_regressed.
109
+ def advance_watermark: (side, Integer value) -> (advancing | :watermark_regressed)
110
+ # Reads this gem's Watermark natively (TypeError for a subclass of it),
111
+ # any other object through `value`; FrozenError, nothing advanced, if
112
+ # `value` froze the join. Honoured: :advanced, and :repeated when the side
113
+ # already equals it, a nil value against a side with no watermark
114
+ # included. Refused: :watermark_regressed, a nil value against a side that
115
+ # holds one included.
116
+ def advance_watermark_from: (side, _Watermark watermark) -> (advancing | :watermark_regressed)
117
+ # The side's watermark as an Integer, nil before the first.
118
+ def watermark: (side) -> Integer?
119
+ # The same state as a Watermark value, never nil itself.
120
+ def side_watermark: (side) -> Watermark
121
+ # Held records both watermarks have finished: the other side's is at or
122
+ # past the end of the record's reach, and its own is at or past its
123
+ # timestamp (so a replay of it is :late).
124
+ def retirable: () -> Integer
125
+ # Honoured: the retired records, [] when none is retirable. Refused: :pending.
126
+ # A raise while building the answer retires nothing; FrozenError if
127
+ # building it froze the join, RuntimeError if it changed it; nothing
128
+ # retired.
129
+ def retire: (Integer max) -> (Array[Retired] | :pending)
130
+ end
131
+
132
+ # Private native hooks each Data value's `initialize` runs on the built
133
+ # value: nil, or TypeError/RangeError for one the core rejects.
134
+ private def self.__reach: (Reach value) -> nil
135
+ private def self.__bounds: (Bounds value) -> nil
136
+ private def self.__pair: (Pair value) -> nil
137
+ private def self.__record: (Record value) -> nil
138
+ private def self.__retired: (Retired value) -> nil
139
+ private def self.__watermark: (Watermark value) -> nil
140
+ end