offset_machines 0.5.1

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,230 @@
1
+ //! Thin binding to the bounded acknowledgement tracker.
2
+ mod init;
3
+
4
+ use std::{cell::RefCell, num::NonZeroU64};
5
+
6
+ use magnus::{Error, RArray, RClass, Ruby, Symbol, Value, prelude::*, typed_data::Obj};
7
+ use matryona_machines::ruby::{Class, Registry, Symbols, integer, optional, symbol};
8
+ use offset_machines::{Ack, Commit, Refusal, Status};
9
+
10
+ /// Words in the compiled window (`WORDS * 64` offsets).
11
+ const WORDS: usize = 4;
12
+ /// Offsets in the compiled window.
13
+ const CAPACITY: u64 = Core::CAPACITY;
14
+ /// The window as a gap count: at most this many gaps exist.
15
+ const WINDOW: usize = WORDS * 64;
16
+
17
+ matryona_machines::symbols! {
18
+ /// The core's refusals as Symbols: the snake case of each variant.
19
+ Refusals for Refusal as "a refusal" {
20
+ Stale => "stale",
21
+ OutOfWindow => "out_of_window",
22
+ Unacked => "unacked",
23
+ Exhausted => "exhausted",
24
+ }
25
+ }
26
+
27
+ matryona_machines::symbols! {
28
+ /// The honoured answers of `ack` as Symbols.
29
+ Acks for Ack as "an ack" {
30
+ Recorded => "recorded",
31
+ Duplicate => "duplicate",
32
+ }
33
+ }
34
+
35
+ matryona_machines::symbols! {
36
+ /// The honoured answers of `mark_committed` as Symbols.
37
+ Commits for Commit as "a commit" {
38
+ Advanced => "advanced",
39
+ Duplicate => "duplicate",
40
+ }
41
+ }
42
+
43
+ /// `OffsetMachines::Status`, defined in Ruby before the extension loads,
44
+ /// resolved once at init and pinned.
45
+ static STATUS: Registry<Class> = Registry::new("offset_machines");
46
+
47
+ fn status_class(ruby: &Ruby) -> Result<RClass, Error> {
48
+ STATUS.get(ruby).map(|class| class.get(ruby))
49
+ }
50
+
51
+ /// What `Status.new` checks its five fields with: the core's `Status::new`
52
+ /// for the compiled window. `TypeError` for a non-Integer (`nil` is allowed
53
+ /// for the two optional marks), `RangeError` for a value outside
54
+ /// `0..2**64-1` or a combination no tracker reports.
55
+ fn status(
56
+ ruby: &Ruby,
57
+ generation: Value,
58
+ base: Value,
59
+ commit_candidate: Value,
60
+ frontier: Value,
61
+ acked: Value,
62
+ ) -> Result<(), Error> {
63
+ Status::new::<WORDS>(
64
+ integer(generation, "generation")?,
65
+ integer(base, "base")?,
66
+ optional(commit_candidate, "commit_candidate")?,
67
+ optional(frontier, "frontier")?,
68
+ integer(acked, "acked")?,
69
+ )
70
+ .map(|_| ())
71
+ .ok_or_else(|| {
72
+ Error::new(
73
+ ruby.exception_range_error(),
74
+ "no tracker reports this status",
75
+ )
76
+ })
77
+ }
78
+
79
+ /// The symbol for an outcome: the honoured value's from table `S`, or the
80
+ /// refusal's.
81
+ fn answer<S: Symbols>(ruby: &Ruby, outcome: Result<S::Variant, Refusal>) -> Symbol {
82
+ match outcome {
83
+ Ok(honoured) => S::symbol(ruby, honoured),
84
+ Err(refusal) => Refusals::symbol(ruby, refusal),
85
+ }
86
+ }
87
+
88
+ type Core = offset_machines::Tracker<WORDS>;
89
+
90
+ #[magnus::wrap(class = "OffsetMachines::Tracker", free_immediately, size)]
91
+ struct Tracker {
92
+ core: RefCell<Core>,
93
+ }
94
+
95
+ impl Tracker {
96
+ const fn new() -> Self {
97
+ Self {
98
+ core: RefCell::new(Core::new()),
99
+ }
100
+ }
101
+
102
+ /// The core's `Tracker::assigned`: generation zero is the one value the
103
+ /// core's `NonZeroU64` rules out, so it raises `RangeError` here.
104
+ fn assigned(ruby: &Ruby, generation: Value, base: Value) -> Result<Self, Error> {
105
+ let (generation, base) = (integer(generation, "generation")?, integer(base, "base")?);
106
+ let generation = NonZeroU64::new(generation).ok_or_else(|| {
107
+ Error::new(
108
+ ruby.exception_range_error(),
109
+ "generation 0 is unassigned, never assigned",
110
+ )
111
+ })?;
112
+ Ok(Self {
113
+ core: RefCell::new(Core::assigned(generation, base)),
114
+ })
115
+ }
116
+
117
+ fn assign(
118
+ ruby: &Ruby,
119
+ this: Obj<Self>,
120
+ generation: Value,
121
+ base: Value,
122
+ ) -> Result<Symbol, Error> {
123
+ this.check_frozen()?;
124
+ let (generation, base) = (integer(generation, "generation")?, integer(base, "base")?);
125
+ let outcome = this.core.borrow_mut().assign(generation, base);
126
+ Ok(match outcome {
127
+ Ok(()) => symbol(ruby, "assigned"),
128
+ Err(refusal) => Refusals::symbol(ruby, refusal),
129
+ })
130
+ }
131
+
132
+ /// The new generation, or a refusal symbol.
133
+ fn reassign(ruby: &Ruby, this: Obj<Self>, base: Value) -> Result<Value, Error> {
134
+ this.check_frozen()?;
135
+ let base = integer(base, "base")?;
136
+ let outcome = this.core.borrow_mut().reassign(base);
137
+ Ok(match outcome {
138
+ Ok(generation) => ruby.integer_from_u64(generation).as_value(),
139
+ Err(refusal) => Refusals::symbol(ruby, refusal).as_value(),
140
+ })
141
+ }
142
+
143
+ fn ack(
144
+ ruby: &Ruby,
145
+ this: Obj<Self>,
146
+ generation: Value,
147
+ offset: Value,
148
+ ) -> Result<Symbol, Error> {
149
+ this.check_frozen()?;
150
+ let (generation, offset) = (
151
+ integer(generation, "generation")?,
152
+ integer(offset, "offset")?,
153
+ );
154
+ let outcome = this.core.borrow_mut().ack(generation, offset);
155
+ Ok(answer::<Acks>(ruby, outcome))
156
+ }
157
+
158
+ fn mark_committed(
159
+ ruby: &Ruby,
160
+ this: Obj<Self>,
161
+ generation: Value,
162
+ offset: Value,
163
+ ) -> Result<Symbol, Error> {
164
+ this.check_frozen()?;
165
+ let (generation, offset) = (
166
+ integer(generation, "generation")?,
167
+ integer(offset, "offset")?,
168
+ );
169
+ let outcome = this.core.borrow_mut().mark_committed(generation, offset);
170
+ Ok(answer::<Commits>(ruby, outcome))
171
+ }
172
+
173
+ fn is_acked(&self, offset: Value) -> Result<bool, Error> {
174
+ Ok(self.core.borrow().is_acked(integer(offset, "offset")?))
175
+ }
176
+
177
+ fn commit_candidate(&self) -> Option<u64> {
178
+ self.core.borrow().commit_candidate()
179
+ }
180
+
181
+ fn frontier(&self) -> Option<u64> {
182
+ self.core.borrow().frontier()
183
+ }
184
+
185
+ /// At most `limit` gaps (clamped to the window) at or after `from`.
186
+ fn gaps(ruby: &Ruby, this: &Self, from: Value, limit: Value) -> Result<RArray, Error> {
187
+ let (from, limit): (u64, u64) = (integer(from, "from")?, integer(limit, "limit")?);
188
+ // The window bounds the answer whatever the limit.
189
+ let take = usize::try_from(limit).map_or(WINDOW, |limit| limit.min(WINDOW));
190
+ let array = ruby.ary_new_capa(take);
191
+ for offset in this.core.borrow().gaps(from).take(take) {
192
+ array.push(offset)?;
193
+ }
194
+ Ok(array)
195
+ }
196
+
197
+ /// The core's `Tracker::status`: the five readers taken in one borrow,
198
+ /// built into a `Status` through its validating `new`. No reader of this
199
+ /// tracker is dispatched, so redefining one changes nothing here.
200
+ fn status(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
201
+ let class = status_class(ruby)?;
202
+ let status = this.core.borrow().status();
203
+ class.funcall(
204
+ "new",
205
+ (
206
+ status.generation(),
207
+ status.base(),
208
+ status.commit_candidate(),
209
+ status.frontier(),
210
+ status.acked(),
211
+ ),
212
+ )
213
+ }
214
+
215
+ fn generation(&self) -> u64 {
216
+ self.core.borrow().generation()
217
+ }
218
+
219
+ fn base(&self) -> u64 {
220
+ self.core.borrow().base()
221
+ }
222
+
223
+ fn acked(&self) -> u64 {
224
+ self.core.borrow().acked()
225
+ }
226
+
227
+ const fn capacity() -> u64 {
228
+ CAPACITY
229
+ }
230
+ }
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OffsetMachines
4
+ VERSION = '0.5.1'
5
+ end
@@ -0,0 +1,39 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'offset_machines/version'
4
+
5
+ module OffsetMachines
6
+ # The core's `Status`: an immutable point-in-time view of a tracker, the
7
+ # answers of its five readers together. Like `Status::new`, it holds only
8
+ # what a tracker of this window could report: anything else raises
9
+ # RangeError (TypeError for a non-Integer; the two marks may be nil).
10
+ Status = Data.define(:generation, :base, :commit_candidate, :frontier, :acked) do
11
+ def initialize(generation:, base:, commit_candidate:, frontier:, acked:)
12
+ OffsetMachines.__send__(:__status, generation, base, commit_candidate, frontier, acked)
13
+ super
14
+ end
15
+ end
16
+ end
17
+
18
+ # Native is required: no algorithm fallback. It validates the Data value above
19
+ # and builds `Tracker#status` from the core's `Tracker::status`, the five
20
+ # readers taken at once rather than dispatched one by one.
21
+ require 'offset_machines_native/offset_machines_native'
22
+
23
+ module OffsetMachines
24
+ private_class_method :__status
25
+
26
+ # The value is final. `initialize` is where it validates, and a subclass
27
+ # could override it, or `allocate` build an instance that never ran it:
28
+ # subclassing raises TypeError and `allocate` is gone. This stops accidents,
29
+ # not reflection (Marshal, `Data#initialize` bound by hand); no method of
30
+ # this gem reads a Status back, so a forged one never reaches the core.
31
+ #
32
+ # `Tracker` wraps native data and is sealed the same way: a subclass could
33
+ # override what callers rely on, and `allocate` would build a shell with no
34
+ # core behind it.
35
+ [Status, Tracker].each do |klass|
36
+ klass.singleton_class.undef_method(:allocate)
37
+ klass.define_singleton_method(:inherited) { |_| raise TypeError, "#{klass} cannot be subclassed" }
38
+ end
39
+ end
@@ -0,0 +1,52 @@
1
+ module OffsetMachines
2
+ VERSION: String
3
+ CAPACITY: Integer
4
+ # Refusals: the call was not honoured and changed nothing. One symbol per
5
+ # core `Refusal` variant; there is no catch-all.
6
+ type refusal = :stale | :out_of_window | :unacked | :exhausted
7
+ # Honoured: :assigned. Refused: :stale.
8
+ type assign_result = :assigned | :stale
9
+ # Honoured: the new generation. Refused: :exhausted.
10
+ type reassign_result = Integer | :exhausted
11
+ # Honoured: :recorded, :duplicate (idempotent repeat). Refused: :stale, :out_of_window.
12
+ type ack_result = :recorded | :duplicate | :stale | :out_of_window
13
+ # Honoured: :advanced, :duplicate (idempotent repeat). Refused: :stale, :unacked.
14
+ type commit_result = :advanced | :duplicate | :stale | :unacked
15
+ # Native check behind `Status.new`: nil when a tracker of this window could
16
+ # report the five values together, raises (TypeError/RangeError) otherwise.
17
+ private def self.__status: (Integer generation, Integer base, Integer? commit_candidate, Integer? frontier, Integer acked) -> nil
18
+ # The core's `Status`. `new` mirrors `Status::new`: it raises RangeError
19
+ # unless a tracker of this window could report the five values together,
20
+ # TypeError for a non-Integer (the two marks may be nil).
21
+ class Status < Data
22
+ attr_reader generation: Integer
23
+ attr_reader base: Integer
24
+ attr_reader commit_candidate: Integer?
25
+ attr_reader frontier: Integer?
26
+ attr_reader acked: Integer
27
+ def self.new: (Integer generation, Integer base, Integer? commit_candidate, Integer? frontier, Integer acked) -> Status
28
+ | (generation: Integer, base: Integer, commit_candidate: Integer?, frontier: Integer?, acked: Integer) -> Status
29
+ end
30
+ class Tracker
31
+ def self.new: () -> Tracker
32
+ # Already assigned: what an honoured `assign` makes of a new tracker.
33
+ # Generation 0 raises RangeError, the one value `assign` refuses there.
34
+ def self.assigned: (Integer generation, Integer base_offset) -> Tracker
35
+ def capacity: () -> Integer
36
+ def generation: () -> Integer
37
+ def base: () -> Integer
38
+ def acked: () -> Integer
39
+ def assign: (Integer generation, Integer base_offset) -> assign_result
40
+ def reassign: (Integer base_offset) -> reassign_result
41
+ def ack: (Integer generation, Integer offset) -> ack_result
42
+ def mark_committed: (Integer generation, Integer offset) -> commit_result
43
+ # Already acknowledged under the current generation: below `base`, or
44
+ # recorded in the window. Exactly when `ack(generation, offset)` would
45
+ # answer :duplicate. Always false while unassigned.
46
+ def acked?: (Integer offset) -> bool
47
+ def commit_candidate: () -> Integer?
48
+ def frontier: () -> Integer?
49
+ def gaps: (Integer from, Integer limit) -> Array[Integer]
50
+ def status: () -> Status
51
+ end
52
+ end
metadata ADDED
@@ -0,0 +1,85 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: offset_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.5.1
5
+ platform: ruby
6
+ authors:
7
+ - Abdelkader Boudih
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: rb_sys
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - "~>"
17
+ - !ruby/object:Gem::Version
18
+ version: '0.9'
19
+ - - ">="
20
+ - !ruby/object:Gem::Version
21
+ version: 0.9.130
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: !ruby/object:Gem::Requirement
25
+ requirements:
26
+ - - "~>"
27
+ - !ruby/object:Gem::Version
28
+ version: '0.9'
29
+ - - ">="
30
+ - !ruby/object:Gem::Version
31
+ version: 0.9.130
32
+ description: 'Offset acknowledgement tracker: contiguous commit candidate, gaps, generation
33
+ checks. Not a commit log or runtime.'
34
+ email:
35
+ - oss@seuros.com
36
+ executables: []
37
+ extensions:
38
+ - ext/offset_machines_native/extconf.rb
39
+ extra_rdoc_files: []
40
+ files:
41
+ - CHANGELOG.md
42
+ - Cargo.lock
43
+ - Cargo.toml
44
+ - LICENSE.txt
45
+ - README.md
46
+ - ext/offset_machines_native/core/CHANGELOG.md
47
+ - ext/offset_machines_native/core/Cargo.toml
48
+ - ext/offset_machines_native/core/README.md
49
+ - ext/offset_machines_native/core/src/lib.rs
50
+ - ext/offset_machines_native/core/src/refusal.rs
51
+ - ext/offset_machines_native/core/src/status.rs
52
+ - ext/offset_machines_native/extconf.rb
53
+ - ext/offset_machines_native/ffi/Cargo.toml
54
+ - ext/offset_machines_native/ffi/extconf.rb
55
+ - ext/offset_machines_native/ffi/src/init.rs
56
+ - ext/offset_machines_native/ffi/src/lib.rs
57
+ - lib/offset_machines.rb
58
+ - lib/offset_machines/version.rb
59
+ - sig/offset_machines.rbs
60
+ homepage: https://github.com/seuros/offset_machines
61
+ licenses:
62
+ - MIT
63
+ metadata:
64
+ source_code_uri: https://github.com/seuros/offset_machines
65
+ rubygems_mfa_required: 'true'
66
+ cargo_crate_name: offset_machines_native
67
+ cargo_manifest_path: ext/offset_machines_native/ffi/Cargo.toml
68
+ rdoc_options: []
69
+ require_paths:
70
+ - lib
71
+ required_ruby_version: !ruby/object:Gem::Requirement
72
+ requirements:
73
+ - - ">="
74
+ - !ruby/object:Gem::Version
75
+ version: 4.0.0
76
+ required_rubygems_version: !ruby/object:Gem::Requirement
77
+ requirements:
78
+ - - ">="
79
+ - !ruby/object:Gem::Version
80
+ version: '0'
81
+ requirements: []
82
+ rubygems_version: 4.0.20
83
+ specification_version: 4
84
+ summary: Bounded per-partition acknowledgement bitmap with a native Rust core
85
+ test_files: []