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,55 +1,93 @@
1
1
  use std::cell::RefCell;
2
2
 
3
- use magnus::{Error, RArray, RModule, Ruby, function, method, prelude::*, typed_data::Obj};
4
- use window_machines::{Insert, Sessions};
3
+ use magnus::{Error, RModule, Ruby, Symbol, Value, function, method, prelude::*, typed_data::Obj};
4
+ use matryona_machines::ruby::{Class, integer, keep, positive};
5
+ use window_machines::{Inserting, Sessions};
5
6
 
6
- use crate::{Tick, positive};
7
+ use crate::{CAPACITY, advancing, classes, refusal, session, watermark};
7
8
 
8
9
  #[magnus::wrap(class = "WindowMachines::Sessions", free_immediately, size)]
9
- struct Wrapper(RefCell<Sessions<32>>);
10
+ struct Wrapper(RefCell<Sessions<CAPACITY>>);
10
11
 
11
12
  impl Wrapper {
12
- fn new(ruby: &Ruby, gap: Tick) -> Result<Self, Error> {
13
- Ok(Self(RefCell::new(Sessions::new(positive(ruby, gap)?))))
13
+ fn new(gap: Value) -> Result<Self, Error> {
14
+ Ok(Self(RefCell::new(Sessions::new(positive(gap, "gap")?))))
14
15
  }
15
16
 
16
- fn insert(ruby: &Ruby, this: Obj<Self>, time: Tick) -> Result<RArray, Error> {
17
- this.check_frozen()?;
18
- let result = this.0.borrow_mut().insert(time.0);
19
- // No Ruby allocation while a RefCell guard is alive.
20
- match result {
21
- Insert::Accepted(session) => Ok(ruby.ary_from_iter([session.first, session.last])),
22
- Insert::Late => Err(Error::new(
23
- ruby.exception_arg_error(),
24
- "event at/below watermark",
25
- )),
26
- Insert::Full => Err(Error::new(
27
- ruby.exception_range_error(),
28
- "32 session capacity reached",
29
- )),
30
- _ => Err(Error::new(
31
- ruby.exception_range_error(),
32
- "session endpoint overflow",
33
- )),
34
- }
35
- }
36
-
37
- fn advance(this: Obj<Self>, time: Tick) -> Result<bool, Error> {
17
+ fn gap(&self) -> u64 {
18
+ self.0.borrow().gap().get()
19
+ }
20
+
21
+ fn capacity(&self) -> usize {
22
+ self.0.borrow().capacity()
23
+ }
24
+
25
+ fn size(&self) -> usize {
26
+ self.0.borrow().len()
27
+ }
28
+
29
+ fn empty(&self) -> bool {
30
+ self.0.borrow().is_empty()
31
+ }
32
+
33
+ /// A copy, as the core answers it: advancing it does not move the tracker.
34
+ fn watermark(&self) -> watermark::Wrapper {
35
+ watermark::Wrapper::holding(self.0.borrow().watermark())
36
+ }
37
+
38
+ /// Answers through [`keep`]: a raise while building the answer changes
39
+ /// nothing, a freeze meanwhile raises `FrozenError`, a re-entrant change
40
+ /// `RuntimeError`.
41
+ fn insert(ruby: &Ruby, this: Obj<Self>, timestamp: Value) -> Result<Value, Error> {
38
42
  this.check_frozen()?;
39
- Ok(this.0.borrow_mut().advance_watermark(time.0))
43
+ let timestamp = integer(timestamp, "timestamp")?;
44
+ let known = classes::classes(ruby)?;
45
+ keep(
46
+ ruby,
47
+ this,
48
+ &this.0,
49
+ |next| next.insert(timestamp),
50
+ |inserted| {
51
+ let (class, held) = match inserted {
52
+ Ok(Inserting::Opened(held)) => (known.opened, held),
53
+ Ok(Inserting::Extended(held)) => (known.extended, held),
54
+ Ok(Inserting::Covered(held)) => (known.covered, held),
55
+ Err(refused) => return Ok(refusal(ruby, refused)),
56
+ };
57
+ classes::build(ruby, class, (session(ruby, held)?,))
58
+ },
59
+ )
40
60
  }
41
61
 
42
- fn take_closed(this: Obj<Self>) -> Result<Option<(u64, u64)>, Error> {
62
+ fn advance_watermark(ruby: &Ruby, this: Obj<Self>, value: Value) -> Result<Symbol, Error> {
43
63
  this.check_frozen()?;
44
- let session = this.0.borrow_mut().take_closed();
45
- Ok(session.map(|s| (s.first, s.last)))
64
+ let value = integer(value, "value")?;
65
+ let outcome = this.0.borrow_mut().advance_watermark(value);
66
+ Ok(advancing(ruby, outcome))
67
+ }
68
+
69
+ /// Answers through [`keep`]: a raise while building the session leaves
70
+ /// it held, to be taken again; a freeze meanwhile raises `FrozenError`, a
71
+ /// re-entrant change `RuntimeError`.
72
+ fn take_closed(ruby: &Ruby, this: Obj<Self>) -> Result<Option<Value>, Error> {
73
+ classes::classes(ruby)?;
74
+ keep(ruby, this, &this.0, Sessions::take_closed, |closed| {
75
+ closed.map(|closed| session(ruby, closed)).transpose()
76
+ })
46
77
  }
47
78
  }
48
79
 
49
80
  pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
50
81
  let class = module.define_class("Sessions", ruby.class_object())?;
82
+ class.undef_default_alloc_func();
51
83
  class.define_singleton_method("new", function!(Wrapper::new, 1))?;
84
+ class.define_method("gap", method!(Wrapper::gap, 0))?;
85
+ class.define_method("capacity", method!(Wrapper::capacity, 0))?;
86
+ class.define_method("size", method!(Wrapper::size, 0))?;
87
+ class.define_method("empty?", method!(Wrapper::empty, 0))?;
88
+ class.define_method("watermark", method!(Wrapper::watermark, 0))?;
52
89
  class.define_method("insert", method!(Wrapper::insert, 1))?;
53
- class.define_method("advance_watermark", method!(Wrapper::advance, 1))?;
54
- class.define_method("take_closed", method!(Wrapper::take_closed, 0))
90
+ class.define_method("advance_watermark", method!(Wrapper::advance_watermark, 1))?;
91
+ class.define_method("take_closed", method!(Wrapper::take_closed, 0))?;
92
+ Class::pin_wrapped::<Wrapper>(ruby, class).map(drop)
55
93
  }
@@ -1,21 +1,32 @@
1
1
  use std::cell::RefCell;
2
2
 
3
- use magnus::{Error, RModule, Ruby, function, method, prelude::*, typed_data::Obj};
4
- use window_machines::{Watermark, Window};
3
+ use magnus::{Error, RModule, Ruby, Symbol, Value, function, method, prelude::*, typed_data::Obj};
4
+ use matryona_machines::ruby::{Class, integer};
5
+ use window_machines::Watermark;
5
6
 
6
- use crate::Tick;
7
+ use crate::{advancing, interval};
7
8
 
8
9
  #[magnus::wrap(class = "WindowMachines::Watermark", free_immediately, size)]
9
- struct Wrapper(RefCell<Watermark>);
10
+ pub struct Wrapper(RefCell<Watermark>);
10
11
 
11
12
  impl Wrapper {
13
+ pub const fn holding(watermark: Watermark) -> Self {
14
+ Self(RefCell::new(watermark))
15
+ }
16
+
12
17
  fn new() -> Self {
13
- Self(RefCell::new(Watermark::default()))
18
+ Self::holding(Watermark::default())
19
+ }
20
+
21
+ fn at(value: Value) -> Result<Self, Error> {
22
+ Ok(Self::holding(Watermark::at(integer(value, "value")?)))
14
23
  }
15
24
 
16
- fn advance(this: Obj<Self>, time: Tick) -> Result<bool, Error> {
25
+ fn advance(ruby: &Ruby, this: Obj<Self>, value: Value) -> Result<Symbol, Error> {
17
26
  this.check_frozen()?;
18
- Ok(this.0.borrow_mut().advance(time.0))
27
+ let value = integer(value, "value")?;
28
+ let outcome = this.0.borrow_mut().advance(value);
29
+ Ok(advancing(ruby, outcome))
19
30
  }
20
31
 
21
32
  fn value(&self) -> Option<u64> {
@@ -25,30 +36,22 @@ impl Wrapper {
25
36
  fn closes(
26
37
  ruby: &Ruby,
27
38
  this: &Self,
28
- start: Tick,
29
- end: Tick,
30
- lateness: Tick,
39
+ window: Value,
40
+ allowed_lateness: Value,
31
41
  ) -> Result<bool, Error> {
32
- if start.0 >= end.0 || end.0.checked_add(lateness.0).is_none() {
33
- return Err(Error::new(
34
- ruby.exception_arg_error(),
35
- "invalid interval/lateness",
36
- ));
37
- }
38
- Ok(this.0.borrow().closes(
39
- Window {
40
- start: start.0,
41
- end: end.0,
42
- },
43
- lateness.0,
44
- ))
42
+ let window = interval(ruby, window)?;
43
+ let lateness = integer(allowed_lateness, "allowed_lateness")?;
44
+ Ok(this.0.borrow().closes(window, lateness))
45
45
  }
46
46
  }
47
47
 
48
48
  pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
49
49
  let class = module.define_class("Watermark", ruby.class_object())?;
50
+ class.undef_default_alloc_func();
50
51
  class.define_singleton_method("new", function!(Wrapper::new, 0))?;
52
+ class.define_singleton_method("at", function!(Wrapper::at, 1))?;
51
53
  class.define_method("advance", method!(Wrapper::advance, 1))?;
52
54
  class.define_method("value", method!(Wrapper::value, 0))?;
53
- class.define_method("closes?", method!(Wrapper::closes, 3))
55
+ class.define_method("closes?", method!(Wrapper::closes, 2))?;
56
+ Class::pin_wrapped::<Wrapper>(ruby, class).map(drop)
54
57
  }
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module WindowMachines
4
- VERSION = '0.1.4'
4
+ VERSION = '0.4.4'
5
5
  end
@@ -1,4 +1,64 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative 'window_machines/version'
4
+
5
+ module WindowMachines
6
+ # Half-open event-time interval: `start` is inside, `end` is not. Like the
7
+ # core's `Window::new` it holds only Integers in 0..2**64-1 with
8
+ # `start < end`: TypeError for another type, RangeError for another value.
9
+ Window = Data.define(:start, :end) do
10
+ def initialize(**)
11
+ super
12
+ WindowMachines.__send__(:__window, start, self.end)
13
+ end
14
+ end
15
+
16
+ # Boundaries of a session; both endpoints are timestamps of real events.
17
+ # Like the core's `Session::new` it holds only Integers in 0..2**64-1 with
18
+ # `first <= last`: TypeError for another type, RangeError for another value.
19
+ # `covers?(timestamp)` is native (the core's `covers`).
20
+ Session = Data.define(:first, :last) do
21
+ def initialize(**)
22
+ super
23
+ WindowMachines.__send__(:__session, first, last)
24
+ end
25
+ end
26
+
27
+ # What Opened, Extended and Covered share: they hold a Session and nothing
28
+ # else (TypeError).
29
+ module Inserting
30
+ def initialize(**)
31
+ super
32
+ WindowMachines.__send__(:__inserting, session)
33
+ end
34
+ end
35
+
36
+ # The core's `Inserting`, what an honoured `Sessions#insert` did. Each
37
+ # carries the session the event is in.
38
+ #
39
+ # Opened: the event joined no held session, a new one took a slot.
40
+ Opened = Data.define(:session) { include Inserting }
41
+ # Extended: the event grew one held session or bridged several into this one.
42
+ Extended = Data.define(:session) { include Inserting }
43
+ # Covered: a held session already covered the timestamp, nothing changed.
44
+ Covered = Data.define(:session) { include Inserting }
45
+ end
46
+
47
+ # Native is required: no algorithm fallback. It validates and builds the Data
48
+ # values above, resolves their classes once at load and adds
49
+ # `Session#covers?`, so they must exist first.
4
50
  require 'window_machines_native/window_machines_native'
51
+
52
+ module WindowMachines
53
+ private_class_method :__window, :__session, :__inserting
54
+ private_constant :Inserting
55
+
56
+ # Sealed: no subclass can skip the check by overriding `initialize`, and no
57
+ # bare `allocate` builds a value that never ran it. Sealing stops
58
+ # accidents, not reflection, so the native side reads only instances of
59
+ # exactly these classes and re-validates their members through the core.
60
+ [Window, Session, Opened, Extended, Covered].each do |value|
61
+ value.singleton_class.undef_method(:allocate)
62
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
63
+ end
64
+ end
@@ -1,17 +1,113 @@
1
1
  module WindowMachines
2
2
  VERSION: String
3
- def self.tumbling: (Integer timestamp, Integer width) -> [Integer, Integer]
4
- def self.sliding: (Integer timestamp, Integer width, Integer slide) -> Array[[Integer, Integer]]
3
+ # Sessions one tracker holds, and windows one `sliding` call can answer.
4
+ CAPACITY: Integer
5
+
6
+ # Refusals: the call was not honoured and changed nothing. Every reason has
7
+ # its own symbol; there is no catch-all.
8
+ type refusal = :overflow | :undersized | :regressed | :late | :full
9
+
10
+ # The core's `Advancing`: what an honoured watermark call did.
11
+ type advancing = :advanced | :repeated
12
+
13
+ # The core's `Inserting`: what an honoured insert did.
14
+ type inserting = Opened | Extended | Covered
15
+
16
+ # Honoured: the Window holding `timestamp`. Refused: :overflow.
17
+ def self.tumbling: (Integer timestamp, Integer width) -> (Window | :overflow)
18
+ # Honoured: the Windows holding `timestamp`, newest first, [] in a hole.
19
+ # Refused: :overflow, and :undersized past CAPACITY windows.
20
+ def self.sliding: (Integer timestamp, Integer size, Integer slide) -> (Array[Window] | :overflow | :undersized)
21
+
22
+ # Private native checks behind `Window.new`, `Session.new` and the
23
+ # Inserting values: nil when the core has the value, TypeError/RangeError
24
+ # otherwise. `__inserting` takes exactly a Session.
25
+ private def self.__window: (Integer start, Integer end) -> nil
26
+ private def self.__session: (Integer first, Integer last) -> nil
27
+ private def self.__inserting: (Session session) -> nil
28
+
29
+ # Every value class is sealed: no `allocate`, subclassing raises TypeError.
30
+ # The native side accepts only instances of exactly these classes and
31
+ # re-validates their members through the core.
32
+
33
+ # Mirrors the core's `Window`, validated by `Window::new`: TypeError unless
34
+ # both are Integers, RangeError outside 0..2**64-1 or unless start < end.
35
+ class Window < Data
36
+ attr_reader start: Integer
37
+ attr_reader end: Integer
38
+ def self.new: (Integer start, Integer end) -> Window
39
+ | (start: Integer, end: Integer) -> Window
40
+ end
41
+
42
+ # Mirrors the core's `Session`, validated by `Session::new`: TypeError unless
43
+ # both are Integers, RangeError outside 0..2**64-1 or unless first <= last.
44
+ class Session < Data
45
+ attr_reader first: Integer
46
+ attr_reader last: Integer
47
+ def self.new: (Integer first, Integer last) -> Session
48
+ | (first: Integer, last: Integer) -> Session
49
+ # The core's `covers`. TypeError for a receiver that is not exactly a
50
+ # Session, RangeError for one whose members the core refuses.
51
+ def covers?: (Integer timestamp) -> bool
52
+ end
53
+
54
+ # `Inserting::Opened`. Opened, Extended and Covered raise TypeError unless
55
+ # `session` is exactly a Session, RangeError for one the core refuses.
56
+ class Opened < Data
57
+ attr_reader session: Session
58
+ def self.new: (Session session) -> Opened
59
+ | (session: Session) -> Opened
60
+ end
61
+
62
+ # `Inserting::Extended`.
63
+ class Extended < Data
64
+ attr_reader session: Session
65
+ def self.new: (Session session) -> Extended
66
+ | (session: Session) -> Extended
67
+ end
68
+
69
+ # `Inserting::Covered`.
70
+ class Covered < Data
71
+ attr_reader session: Session
72
+ def self.new: (Session session) -> Covered
73
+ | (session: Session) -> Covered
74
+ end
75
+
5
76
  class Watermark
6
- def self.new: () -> instance
7
- def advance: (Integer value) -> bool
77
+ # Nothing observed yet (the core's `Default`).
78
+ def self.new: () -> Watermark
79
+ # Already standing at `value`.
80
+ def self.at: (Integer value) -> Watermark
81
+ # Honoured: :advanced, and :repeated when it already held exactly `value`
82
+ # (nothing changes). Refused: :regressed.
83
+ def advance: (Integer value) -> (advancing | :regressed)
84
+ # nil before the first observation.
8
85
  def value: () -> Integer?
9
- def closes?: (Integer start, Integer end, Integer lateness) -> bool
86
+ # A pure query: never refuses. TypeError unless `window` is exactly a
87
+ # Window, RangeError for one whose members the core refuses.
88
+ def closes?: (Window window, Integer allowed_lateness) -> bool
10
89
  end
90
+
11
91
  class Sessions
12
- def self.new: (Integer gap) -> instance
13
- def insert: (Integer timestamp) -> [Integer, Integer]
14
- def advance_watermark: (Integer value) -> bool
15
- def take_closed: () -> [Integer, Integer]?
92
+ def self.new: (Integer gap) -> Sessions
93
+ def gap: () -> Integer
94
+ def capacity: () -> Integer
95
+ # Sessions held (the core's `len`).
96
+ def size: () -> Integer
97
+ def empty?: () -> bool
98
+ # A copy of the tracker's progress, never nil itself.
99
+ def watermark: () -> Watermark
100
+ # Honoured: Opened, Extended, and Covered when a held session already
101
+ # covers `timestamp` (nothing changes). Refused: :late, :overflow, :full.
102
+ # FrozenError if building the answer froze the tracker, RuntimeError if it
103
+ # changed it; nothing applied either way.
104
+ def insert: (Integer timestamp) -> (inserting | :late | :overflow | :full)
105
+ # Honoured: :advanced, and :repeated when it already held exactly `value`
106
+ # (nothing changes). Refused: :regressed.
107
+ def advance_watermark: (Integer value) -> (advancing | :regressed)
108
+ # The earliest closed session, nil when none is closed. Never refuses.
109
+ # FrozenError if building the session froze the tracker, RuntimeError if
110
+ # it changed it; nothing taken either way.
111
+ def take_closed: () -> Session?
16
112
  end
17
113
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: window_machines
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.4.4
5
5
  platform: ruby
6
6
  authors:
7
7
  - Abdelkader Boudih
@@ -29,8 +29,9 @@ dependencies:
29
29
  - - ">="
30
30
  - !ruby/object:Gem::Version
31
31
  version: 0.9.130
32
- description: Initial allocation-free window policy core and thin native Ruby binding.
33
- Caller owns payloads, clocks, and execution.
32
+ description: Assigns events to tumbling or sliding windows by their own timestamp,
33
+ closes windows behind a watermark, and tracks gap-split sessions that merge when
34
+ a late event bridges them. The caller owns payloads, clocks and execution.
34
35
  email:
35
36
  - oss@seuros.com
36
37
  executables: []
@@ -39,6 +40,7 @@ extensions:
39
40
  extra_rdoc_files: []
40
41
  files:
41
42
  - CHANGELOG.md
43
+ - Cargo.lock
42
44
  - Cargo.toml
43
45
  - LICENSE.txt
44
46
  - README.md
@@ -46,10 +48,12 @@ files:
46
48
  - ext/window_machines_native/core/Cargo.toml
47
49
  - ext/window_machines_native/core/README.md
48
50
  - ext/window_machines_native/core/src/lib.rs
51
+ - ext/window_machines_native/core/src/refusal.rs
49
52
  - ext/window_machines_native/core/src/sessions.rs
50
53
  - ext/window_machines_native/extconf.rb
51
54
  - ext/window_machines_native/ffi/Cargo.toml
52
55
  - ext/window_machines_native/ffi/extconf.rb
56
+ - ext/window_machines_native/ffi/src/classes.rs
53
57
  - ext/window_machines_native/ffi/src/init.rs
54
58
  - ext/window_machines_native/ffi/src/lib.rs
55
59
  - ext/window_machines_native/ffi/src/sessions.rs
@@ -81,5 +85,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
81
85
  requirements: []
82
86
  rubygems_version: 4.0.20
83
87
  specification_version: 4
84
- summary: Native event-time window boundaries for Ruby
88
+ summary: Event-time windows, watermarks and sessions over a native Rust core
85
89
  test_files: []