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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +91 -0
- data/Cargo.lock +314 -0
- data/Cargo.toml +24 -0
- data/LICENSE.txt +21 -0
- data/README.md +278 -0
- data/ext/join_machines_native/core/CHANGELOG.md +66 -0
- data/ext/join_machines_native/core/Cargo.toml +17 -0
- data/ext/join_machines_native/core/README.md +176 -0
- data/ext/join_machines_native/core/src/lib.rs +550 -0
- data/ext/join_machines_native/core/src/refusal.rs +41 -0
- data/ext/join_machines_native/extconf.rb +2 -0
- data/ext/join_machines_native/ffi/Cargo.toml +21 -0
- data/ext/join_machines_native/ffi/extconf.rb +14 -0
- data/ext/join_machines_native/ffi/src/classes.rs +57 -0
- data/ext/join_machines_native/ffi/src/init.rs +54 -0
- data/ext/join_machines_native/ffi/src/lib.rs +391 -0
- data/lib/join_machines/version.rb +4 -0
- data/lib/join_machines.rb +65 -0
- data/sig/join_machines.rbs +140 -0
- metadata +86 -0
|
@@ -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,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
|