window_machines 0.1.4 → 0.4.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.
@@ -1,31 +1,73 @@
1
- use crate::Watermark;
1
+ use crate::{Advancing, Refusal, Watermark};
2
2
  use core::num::NonZeroU64;
3
3
 
4
- /// Boundaries of a session; both endpoints are actual included event timestamps.
5
- #[derive(Debug, Clone, Copy, PartialEq, Eq)]
4
+ /// Boundaries of a session; both endpoints are actual included event
5
+ /// timestamps, so `first <= last`.
6
+ ///
7
+ /// The `Default` value is a placeholder, not a sentinel.
8
+ #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
6
9
  pub struct Session {
10
+ first: u64,
11
+ last: u64,
12
+ }
13
+ impl Session {
14
+ /// The session from `first` to `last`, or `None` unless `first <= last`.
15
+ #[must_use]
16
+ pub const fn new(first: u64, last: u64) -> Option<Self> {
17
+ if first <= last {
18
+ Some(Self { first, last })
19
+ } else {
20
+ None
21
+ }
22
+ }
23
+
7
24
  /// Earliest event.
8
- pub first: u64,
25
+ #[must_use]
26
+ pub const fn first(self) -> u64 {
27
+ self.first
28
+ }
29
+
9
30
  /// Latest event.
10
- pub last: u64,
31
+ #[must_use]
32
+ pub const fn last(self) -> u64 {
33
+ self.last
34
+ }
35
+
36
+ /// Whether the timestamp lies between the two endpoints, inclusive.
37
+ #[must_use]
38
+ pub const fn covers(self, timestamp: u64) -> bool {
39
+ self.first <= timestamp && timestamp <= self.last
40
+ }
11
41
  }
12
42
 
13
- /// Session event admission.
43
+ /// What an honoured [`Sessions::insert`] did, with the session the event is in.
14
44
  #[derive(Debug, Clone, Copy, PartialEq, Eq)]
15
- #[non_exhaustive]
16
- pub enum Insert {
17
- /// New or merged boundaries; adapters must merge overlapping payloads too.
18
- Accepted(Session),
19
- /// Event is at/below the current watermark.
20
- Late,
21
- /// No free slot and no existing session could absorb the event.
22
- Full,
23
- /// Inactivity endpoint overflowed.
24
- Overflow,
45
+ pub enum Inserting {
46
+ /// The event joined no held session: a new one-event session took a slot.
47
+ Opened(Session),
48
+ /// The event moved boundaries: it grew one held session, or bridged
49
+ /// several into the one returned. Adapters must merge every payload whose
50
+ /// old session lies inside the returned boundaries.
51
+ Extended(Session),
52
+ /// A held session already covered the timestamp: nothing changed.
53
+ ///
54
+ /// The core keeps boundaries, not events, so this proves the timestamp
55
+ /// is inside the session and not that the same event was seen before;
56
+ /// telling a replay from a second event at that time is the caller's job.
57
+ Covered(Session),
58
+ }
59
+ impl Inserting {
60
+ /// The session the event belongs to, whichever way it got there.
61
+ #[must_use]
62
+ pub const fn session(self) -> Session {
63
+ match self {
64
+ Self::Opened(session) | Self::Extended(session) | Self::Covered(session) => session,
65
+ }
66
+ }
25
67
  }
26
68
 
27
69
  /// Bounded sessions for one logical event key.
28
- #[derive(Debug)]
70
+ #[derive(Debug, Clone, PartialEq, Eq)]
29
71
  pub struct Sessions<const N: usize> {
30
72
  entries: [Option<Session>; N],
31
73
  gap: NonZeroU64,
@@ -33,27 +75,79 @@ pub struct Sessions<const N: usize> {
33
75
  }
34
76
  impl<const N: usize> Sessions<N> {
35
77
  /// Construct an empty one-key session tracker.
78
+ ///
79
+ /// `gap` is the longest silence, in event-time units, two neighbouring
80
+ /// events of one session may have between them.
36
81
  #[must_use]
37
- pub fn new(gap: NonZeroU64) -> Self {
82
+ pub const fn new(gap: NonZeroU64) -> Self {
38
83
  Self {
39
84
  entries: [None; N],
40
85
  gap,
41
- watermark: Watermark::default(),
86
+ watermark: Watermark { value: None },
42
87
  }
43
88
  }
44
89
 
45
- /// Merge an event atomically, including bridges across multiple sessions.
90
+ /// The inactivity gap fixed at construction.
91
+ #[must_use]
92
+ pub const fn gap(&self) -> NonZeroU64 {
93
+ self.gap
94
+ }
95
+
96
+ /// Sessions that can be held at once.
97
+ #[must_use]
98
+ pub const fn capacity(&self) -> usize {
99
+ N
100
+ }
101
+
102
+ /// Sessions currently held, closed-but-undrained ones included.
46
103
  #[must_use]
47
- pub fn insert(&mut self, timestamp: u64) -> Insert {
104
+ pub fn len(&self) -> usize {
105
+ self.entries.iter().flatten().count()
106
+ }
107
+
108
+ /// Whether no session is held.
109
+ #[must_use]
110
+ pub fn is_empty(&self) -> bool {
111
+ self.len() == 0
112
+ }
113
+
114
+ /// Event-time progress of this tracker, a copy.
115
+ #[must_use]
116
+ pub const fn watermark(&self) -> Watermark {
117
+ self.watermark
118
+ }
119
+
120
+ /// Merge an event atomically, including bridges across multiple sessions.
121
+ ///
122
+ /// A timestamp a held session already covers is the effect asked for
123
+ /// already holding: [`Inserting::Covered`], whatever the watermark says,
124
+ /// and nothing changes. That holds only while the session is held: once
125
+ /// [`take_closed`](Self::take_closed) drained it no history remains and
126
+ /// the same timestamp is [`Refusal::Late`].
127
+ ///
128
+ /// # Errors
129
+ /// [`Refusal::Late`] at or below the watermark with no held session
130
+ /// covering the timestamp, [`Refusal::Overflow`] when `timestamp + gap`
131
+ /// would pass `u64::MAX`, [`Refusal::Full`] without a free slot or a
132
+ /// session to join. Nothing changes.
133
+ pub fn insert(&mut self, timestamp: u64) -> Result<Inserting, Refusal> {
134
+ if let Some(session) = self
135
+ .entries
136
+ .iter()
137
+ .flatten()
138
+ .find(|session| session.covers(timestamp))
139
+ {
140
+ return Ok(Inserting::Covered(*session));
141
+ }
48
142
  if self
49
143
  .watermark
50
144
  .value()
51
145
  .is_some_and(|value| timestamp <= value)
52
146
  {
53
- return Insert::Late;
147
+ return Err(Refusal::Late);
54
148
  }
55
149
  if timestamp.checked_add(self.gap.get()).is_none() {
56
- return Insert::Overflow;
150
+ return Err(Refusal::Overflow);
57
151
  }
58
152
  let mut candidate = Session {
59
153
  first: timestamp,
@@ -63,17 +157,18 @@ impl<const N: usize> Sessions<N> {
63
157
  // Fixed point handles any slot order and transitive bridges.
64
158
  for _ in 0..N {
65
159
  let mut changed = false;
66
- for (index, session) in self.entries.iter().enumerate() {
160
+ for (session, merged) in self.entries.iter().zip(merged.iter_mut()) {
67
161
  let Some(session) = session else {
68
162
  continue;
69
163
  };
70
- if !merged[index]
164
+ // Both sums widen two `u64`s into `u128`: they cannot overflow.
165
+ if !*merged
71
166
  && u128::from(candidate.first)
72
167
  <= u128::from(session.last) + u128::from(self.gap.get())
73
168
  && u128::from(session.first)
74
169
  <= u128::from(candidate.last) + u128::from(self.gap.get())
75
170
  {
76
- merged[index] = true;
171
+ *merged = true;
77
172
  candidate.first = candidate.first.min(session.first);
78
173
  candidate.last = candidate.last.max(session.last);
79
174
  changed = true;
@@ -83,47 +178,56 @@ impl<const N: usize> Sessions<N> {
83
178
  break;
84
179
  }
85
180
  }
86
- let Some(slot) = merged
87
- .iter()
88
- .position(|merged| *merged)
89
- .or_else(|| self.entries.iter().position(Option::is_none))
90
- else {
91
- return Insert::Full;
181
+ let joined = merged.iter().position(|merged| *merged);
182
+ let Some(slot) = joined.or_else(|| self.entries.iter().position(Option::is_none)) else {
183
+ return Err(Refusal::Full);
92
184
  };
93
- for (index, merged) in merged.into_iter().enumerate() {
94
- if merged {
95
- self.entries[index] = None;
185
+ // `slot` came from a position over these same `N` entries, so this
186
+ // pass always meets it; a merged slot other than `slot` is freed.
187
+ for (index, (entry, merged)) in self.entries.iter_mut().zip(merged).enumerate() {
188
+ if index == slot {
189
+ *entry = Some(candidate);
190
+ } else if merged {
191
+ *entry = None;
96
192
  }
97
193
  }
98
- self.entries[slot] = Some(candidate);
99
- Insert::Accepted(candidate)
194
+ Ok(if joined.is_some() {
195
+ Inserting::Extended(candidate)
196
+ } else {
197
+ Inserting::Opened(candidate)
198
+ })
100
199
  }
101
200
 
102
- /// Advance event-time progress, without silently deleting closed sessions.
103
- #[must_use]
104
- pub fn advance_watermark(&mut self, value: u64) -> bool {
201
+ /// Advance or repeat event-time progress, as [`Watermark::advance`] does.
202
+ ///
203
+ /// Advancing never removes sessions; drain them with
204
+ /// [`take_closed`](Self::take_closed).
205
+ ///
206
+ /// # Errors
207
+ /// [`Refusal::Regressed`] when `value` is behind the watermark. Nothing
208
+ /// changes.
209
+ pub const fn advance_watermark(&mut self, value: u64) -> Result<Advancing, Refusal> {
105
210
  self.watermark.advance(value)
106
211
  }
107
212
 
108
213
  /// Drain the earliest closed session; payload emission remains the caller's job.
214
+ ///
215
+ /// A session is closed once the watermark has reached `last + gap`.
216
+ /// `None` means nothing is closed yet, not a refusal.
109
217
  pub fn take_closed(&mut self) -> Option<Session> {
110
218
  let value = self.watermark.value()?;
111
- let index = self
112
- .entries
113
- .iter()
114
- .enumerate()
115
- .filter_map(|(index, session)| {
116
- session
117
- .filter(|session| {
118
- session
119
- .last
120
- .checked_add(self.gap.get())
121
- .is_some_and(|end| value >= end)
122
- })
123
- .map(|session| (index, session.first))
219
+ let gap = self.gap.get();
220
+ self.entries
221
+ .iter_mut()
222
+ .filter(|entry| {
223
+ entry.is_some_and(|session| {
224
+ session
225
+ .last
226
+ .checked_add(gap)
227
+ .is_some_and(|end| value >= end)
228
+ })
124
229
  })
125
- .min_by_key(|&(_, first)| first)
126
- .map(|(index, _)| index)?;
127
- self.entries[index].take()
230
+ .min_by_key(|entry| entry.map(|session| session.first))?
231
+ .take()
128
232
  }
129
233
  }
@@ -1,6 +1,6 @@
1
1
  [package]
2
2
  name = "window_machines_native"
3
- version = "0.1.3"
3
+ version = "0.1.7"
4
4
  edition.workspace = true
5
5
  rust-version.workspace = true
6
6
  license.workspace = true
@@ -15,6 +15,7 @@ doctest = false
15
15
  window-machines.workspace = true
16
16
  magnus.workspace = true
17
17
  rb-sys.workspace = true
18
+ matryona-machines = { workspace = true, features = ["ruby"] }
18
19
 
19
20
  [lints]
20
21
  workspace = true
@@ -0,0 +1,55 @@
1
+ //! The gem's `Data` classes, resolved once when the extension loads.
2
+ //!
3
+ //! Sealing in Ruby stops accidents, not reflection: a subclass constant is
4
+ //! bound before `inherited` raises, `Data#initialize` can be bound directly
5
+ //! and `Marshal.load` skips `initialize`. So the binding is the authority: a
6
+ //! value it reads must be an instance of exactly the sealed class, its members
7
+ //! are read natively (no method is dispatched) and the caller re-validates
8
+ //! them through the core constructor.
9
+ use magnus::{Error, RModule, Ruby, Value, prelude::*};
10
+ use matryona_machines::ruby::{Class, exact_fields};
11
+
12
+ /// `WindowMachines::Window`, `Session`, `Opened`, `Extended` and `Covered`.
13
+ pub struct Classes {
14
+ pub window: Class,
15
+ pub session: Class,
16
+ pub opened: Class,
17
+ pub extended: Class,
18
+ pub covered: Class,
19
+ }
20
+
21
+ matryona_machines::registry! {
22
+ static CLASSES: Classes = "window_machines";
23
+ /// The classes resolved at init.
24
+ pub fn classes;
25
+ }
26
+
27
+ /// Resolve and pin the classes Ruby defined before loading the extension.
28
+ pub fn resolve(ruby: &Ruby, module: RModule) -> Result<(), Error> {
29
+ let class = |name| Class::resolve(ruby, module, name);
30
+ let classes = Classes {
31
+ window: class("Window")?,
32
+ session: class("Session")?,
33
+ opened: class("Opened")?,
34
+ extended: class("Extended")?,
35
+ covered: class("Covered")?,
36
+ };
37
+ CLASSES.set(ruby, classes).map(drop)
38
+ }
39
+
40
+ /// A new value of `class`, through its own `new` (so through its check).
41
+ pub fn build<A: magnus::ArgList>(ruby: &Ruby, class: Class, args: A) -> Result<Value, Error> {
42
+ class.get(ruby).funcall("new", args)
43
+ }
44
+
45
+ /// The two members of `value`, read from the struct (no reader runs), when
46
+ /// `value` is an instance of exactly `class` (`instance_of?`, not `is_a?`);
47
+ /// `TypeError` with `message` otherwise.
48
+ pub fn pair(
49
+ ruby: &Ruby,
50
+ value: Value,
51
+ class: Class,
52
+ message: &'static str,
53
+ ) -> Result<[Value; 2], Error> {
54
+ exact_fields::<2>(ruby, value, class.get(ruby), message)
55
+ }
@@ -1,10 +1,18 @@
1
- use magnus::{Error, Ruby, function, prelude::*};
1
+ use magnus::{Error, Ruby, function, method, prelude::*};
2
2
 
3
3
  #[magnus::init]
4
4
  fn init(ruby: &Ruby) -> Result<(), Error> {
5
5
  let module = ruby.define_module("WindowMachines")?;
6
+ module.const_set("CAPACITY", crate::CAPACITY)?;
7
+ crate::classes::resolve(ruby, module)?;
6
8
  module.define_singleton_method("tumbling", function!(crate::tumbling, 2))?;
7
9
  module.define_singleton_method("sliding", function!(crate::sliding, 3))?;
10
+ // The Data classes are defined in Ruby; the core validates them here.
11
+ module.define_singleton_method("__window", function!(crate::validate_window, 2))?;
12
+ module.define_singleton_method("__session", function!(crate::validate_session, 2))?;
13
+ module.define_singleton_method("__inserting", function!(crate::validate_inserting, 1))?;
14
+ let session = crate::classes::classes(ruby)?.session.get(ruby);
15
+ session.define_method("covers?", method!(crate::session_covers, 1))?;
8
16
  crate::watermark::define(ruby, module)?;
9
17
  crate::sessions::define(ruby, module)
10
18
  }
@@ -1,46 +1,133 @@
1
1
  //! Thin event-time boundary adapters; no Ruby payloads are retained.
2
+ mod classes;
2
3
  mod init;
3
4
  mod sessions;
4
5
  mod watermark;
5
6
 
6
- use std::num::NonZeroU64;
7
+ use classes::classes;
8
+ use magnus::{Error, Ruby, Symbol, Value, value::ReprValue};
9
+ use matryona_machines::ruby::{Symbols, integer, positive, symbol};
10
+ use window_machines::{Advancing, Refusal, Session, Window};
7
11
 
8
- use magnus::{Error, Integer, RArray, Ruby, TryConvert, Value};
12
+ /// Sessions one tracker holds, and windows one `sliding` call can answer.
13
+ const CAPACITY: usize = 32;
9
14
 
10
- #[derive(Clone, Copy)]
11
- struct Tick(u64);
15
+ /// A `WindowMachines::Window` (exactly), its members read natively and
16
+ /// re-validated through the core: a forged value raises.
17
+ fn interval(ruby: &Ruby, value: Value) -> Result<Window, Error> {
18
+ let window = classes(ruby)?.window;
19
+ let [start, end] = classes::pair(ruby, value, window, "expected a WindowMachines::Window")?;
20
+ checked_window(ruby, start, end)
21
+ }
22
+
23
+ /// The core's `Window::new`: what `Window.new` is held to.
24
+ fn checked_window(ruby: &Ruby, start: Value, end: Value) -> Result<Window, Error> {
25
+ let (start, end) = (integer(start, "start")?, integer(end, "end")?);
26
+ Window::new(start, end).ok_or_else(|| {
27
+ Error::new(
28
+ ruby.exception_range_error(),
29
+ "a window's start must be below its end",
30
+ )
31
+ })
32
+ }
33
+
34
+ /// The core's `Session::new`: what `Session.new` is held to.
35
+ fn checked_session(ruby: &Ruby, first: Value, last: Value) -> Result<Session, Error> {
36
+ let (first, last) = (integer(first, "first")?, integer(last, "last")?);
37
+ Session::new(first, last).ok_or_else(|| {
38
+ Error::new(
39
+ ruby.exception_range_error(),
40
+ "a session's first must not be above its last",
41
+ )
42
+ })
43
+ }
44
+
45
+ /// A `WindowMachines::Session` (exactly), its members read natively and
46
+ /// re-validated through the core; `TypeError` for anything else.
47
+ fn session_from(ruby: &Ruby, value: Value) -> Result<Session, Error> {
48
+ let session = classes(ruby)?.session;
49
+ let [first, last] = classes::pair(ruby, value, session, "expected a WindowMachines::Session")?;
50
+ checked_session(ruby, first, last)
51
+ }
52
+
53
+ /// Private hook behind `Window.new`.
54
+ fn validate_window(ruby: &Ruby, start: Value, end: Value) -> Result<(), Error> {
55
+ checked_window(ruby, start, end).map(|_| ())
56
+ }
57
+
58
+ /// Private hook behind `Session.new`.
59
+ fn validate_session(ruby: &Ruby, first: Value, last: Value) -> Result<(), Error> {
60
+ checked_session(ruby, first, last).map(|_| ())
61
+ }
62
+
63
+ /// Private hook behind `Opened.new`, `Extended.new` and `Covered.new`.
64
+ fn validate_inserting(ruby: &Ruby, session: Value) -> Result<(), Error> {
65
+ session_from(ruby, session).map(|_| ())
66
+ }
12
67
 
13
- impl TryConvert for Tick {
14
- fn try_convert(value: Value) -> Result<Self, Error> {
15
- if Integer::from_value(value).is_none() {
16
- return Err(Error::new(
17
- Ruby::get_with(value).exception_type_error(),
18
- "time must be an Integer in 0..2**64",
19
- ));
20
- }
21
- u64::try_convert(value).map(Self)
68
+ /// `Session#covers?`: the core's `Session::covers`.
69
+ fn session_covers(ruby: &Ruby, this: Value, timestamp: Value) -> Result<bool, Error> {
70
+ let timestamp = integer(timestamp, "timestamp")?;
71
+ session_from(ruby, this).map(|session| session.covers(timestamp))
72
+ }
73
+
74
+ matryona_machines::symbols! {
75
+ /// The core's refusals, each the snake case of its variant.
76
+ Refusals for Refusal as "a refusal" {
77
+ Overflow => "overflow",
78
+ Undersized => "undersized",
79
+ Regressed => "regressed",
80
+ Late => "late",
81
+ Full => "full",
22
82
  }
23
83
  }
24
84
 
25
- fn positive(ruby: &Ruby, value: Tick) -> Result<NonZeroU64, Error> {
26
- NonZeroU64::new(value.0)
27
- .ok_or_else(|| Error::new(ruby.exception_arg_error(), "width/gap must be positive"))
85
+ matryona_machines::symbols! {
86
+ /// An honoured watermark advance.
87
+ Advancings for Advancing as "an advance" {
88
+ Advanced => "advanced",
89
+ Repeated => "repeated",
90
+ }
91
+ }
92
+
93
+ fn advancing(ruby: &Ruby, outcome: Result<Advancing, Refusal>) -> Symbol {
94
+ symbol(ruby, outcome.map_or_else(Refusals::name, Advancings::name))
95
+ }
96
+
97
+ /// The refusal symbol, as an answer.
98
+ fn refusal(ruby: &Ruby, refused: Refusal) -> Value {
99
+ Refusals::symbol(ruby, refused).as_value()
28
100
  }
29
101
 
30
- fn tumbling(ruby: &Ruby, time: Tick, width: Tick) -> Result<(u64, u64), Error> {
31
- let window = window_machines::tumbling(time.0, positive(ruby, width)?)
32
- .ok_or_else(|| Error::new(ruby.exception_range_error(), "window endpoint overflow"))?;
33
- Ok((window.start, window.end))
102
+ fn window(ruby: &Ruby, window: Window) -> Result<Value, Error> {
103
+ let class = classes(ruby)?.window;
104
+ classes::build(ruby, class, (window.start(), window.end()))
34
105
  }
35
106
 
36
- fn sliding(ruby: &Ruby, time: Tick, width: Tick, slide: Tick) -> Result<RArray, Error> {
37
- let windows =
38
- window_machines::sliding::<32>(time.0, positive(ruby, width)?, positive(ruby, slide)?)
39
- .ok_or_else(|| {
40
- Error::new(
41
- ruby.exception_range_error(),
42
- "endpoint overflow or more than 32 sliding windows",
43
- )
44
- })?;
45
- Ok(ruby.ary_from_iter(windows.into_iter().flatten().map(|w| (w.start, w.end))))
107
+ fn session(ruby: &Ruby, session: Session) -> Result<Value, Error> {
108
+ let class = classes(ruby)?.session;
109
+ classes::build(ruby, class, (session.first(), session.last()))
110
+ }
111
+
112
+ fn tumbling(ruby: &Ruby, timestamp: Value, width: Value) -> Result<Value, Error> {
113
+ let (timestamp, width) = (integer(timestamp, "timestamp")?, positive(width, "width")?);
114
+ match window_machines::tumbling(timestamp, width) {
115
+ Ok(found) => window(ruby, found),
116
+ Err(refused) => Ok(refusal(ruby, refused)),
117
+ }
118
+ }
119
+
120
+ fn sliding(ruby: &Ruby, timestamp: Value, size: Value, slide: Value) -> Result<Value, Error> {
121
+ let timestamp = integer(timestamp, "timestamp")?;
122
+ let (size, slide) = (positive(size, "size")?, positive(slide, "slide")?);
123
+ let mut out = [Window::default(); CAPACITY];
124
+ let written = match window_machines::sliding(timestamp, size, slide, &mut out) {
125
+ Ok(written) => written,
126
+ Err(refused) => return Ok(refusal(ruby, refused)),
127
+ };
128
+ let result = ruby.ary_new_capa(written);
129
+ for found in out.into_iter().take(written) {
130
+ result.push(window(ruby, found)?)?;
131
+ }
132
+ Ok(result.as_value())
46
133
  }