batch_machines 0.1.4 → 0.5.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,123 +1,260 @@
1
- use std::{cell::RefCell, num::NonZeroU32};
1
+ use std::cell::RefCell;
2
2
 
3
- use batch_machines::{Admission, Batch, FlushReason};
4
- use feedback_machines::{Gains, Limits, Pid};
5
- use magnus::{Error, RModule, Ruby, function, method, prelude::*, typed_data::Obj};
3
+ use batch_machines::{Admission, Batch, FlushReason, Refusal};
4
+ use magnus::{Error, RModule, Ruby, Symbol, Value, function, method, prelude::*, typed_data::Obj};
5
+ use matryona_machines::ruby::{
6
+ Class, Named, Refused, Registry, SymbolNames, SymbolOrReal, Symbols, class_name, duration,
7
+ instant, keep, nanoseconds, positive, real, symbol_or_real_why,
8
+ };
6
9
 
7
- use crate::Count;
10
+ matryona_machines::symbols! {
11
+ /// The core's refusals, each the snake case of its variant.
12
+ Refusals for Refusal as "a refusal" {
13
+ TimeRegression => "time_regression",
14
+ Overflow => "overflow",
15
+ Full => "full",
16
+ NotFinite => "not_finite",
17
+ InvalidDuration => "invalid_duration",
18
+ }
19
+ }
8
20
 
9
- struct State {
10
- batch: Batch,
11
- pid: Pid,
21
+ /// Ruby symbol of a refusal.
22
+ fn refusal(ruby: &Ruby, refused: Refusal) -> Value {
23
+ Refusals::symbol(ruby, refused).as_value()
12
24
  }
13
25
 
14
- #[magnus::wrap(class = "BatchMachines::Batch", free_immediately, size)]
15
- struct Wrapper {
16
- state: RefCell<State>,
17
- capacity: u32,
26
+ matryona_machines::symbols! {
27
+ /// Why a batch flushed, as `Flush#reason` holds it.
28
+ Reasons for FlushReason as "reason" {
29
+ Size => "size",
30
+ Deadline => "deadline",
31
+ }
32
+ }
33
+
34
+ matryona_machines::symbols! {
35
+ /// The refusals a `feedback_machines` controller's `step` answers.
36
+ ControllerRefusals for feedback_machines::Refusal as "step's refusal" {
37
+ NotFinite => "not_finite",
38
+ InvalidDuration => "invalid_duration",
39
+ Overflow => "overflow",
40
+ }
41
+ }
42
+
43
+ matryona_machines::symbols! {
44
+ /// What a push answers: `:buffered`, or a `Flush`.
45
+ Admissions for Admission as "an admission" => names_only {
46
+ Buffered => "buffered",
47
+ Flush(..) => "flush",
48
+ }
49
+ }
50
+
51
+ fn reason(ruby: &Ruby, reason: FlushReason) -> Symbol {
52
+ Reasons::symbol(ruby, reason)
18
53
  }
19
54
 
55
+ /// The controller's refusal as the core's `adapt` carries it.
56
+ const fn controller_refusal(refused: feedback_machines::Refusal) -> Refusal {
57
+ match refused {
58
+ feedback_machines::Refusal::NotFinite => Refusal::NotFinite,
59
+ feedback_machines::Refusal::InvalidDuration => Refusal::InvalidDuration,
60
+ feedback_machines::Refusal::Overflow => Refusal::Overflow,
61
+ }
62
+ }
63
+
64
+ /// A count, or the refusal symbol.
65
+ fn counted(ruby: &Ruby, answer: Result<u32, Refusal>) -> Value {
66
+ match answer {
67
+ Ok(count) => ruby.integer_from_u64(u64::from(count)).as_value(),
68
+ Err(refused) => refusal(ruby, refused),
69
+ }
70
+ }
71
+
72
+ /// What `Flush.new` stores: the core's `FlushReason`, as its symbol.
73
+ /// `TypeError` for a non-Symbol, `RangeError` for a symbol that names no
74
+ /// `FlushReason`.
75
+ fn checked_flush(ruby: &Ruby, value: Value) -> Result<Symbol, Error> {
76
+ let due = Reasons::parse(ruby, value)?;
77
+ Ok(reason(ruby, due))
78
+ }
79
+
80
+ /// `BatchMachines::Flush`, resolved once at init: swapping the constant later
81
+ /// changes nothing the batch builds.
82
+ struct Classes {
83
+ flush: Class,
84
+ }
85
+
86
+ static CLASSES: Registry<Classes> = Registry::new("batch_machines");
87
+
88
+ #[magnus::wrap(class = "BatchMachines::Batch", free_immediately, size)]
89
+ struct Wrapper(RefCell<Batch>);
90
+
20
91
  impl Wrapper {
21
- fn new(ruby: &Ruby, capacity: Count, wait: Count) -> Result<Self, Error> {
22
- let capacity = u32::try_from(capacity.0)
23
- .ok()
24
- .and_then(NonZeroU32::new)
25
- .ok_or_else(|| {
26
- Error::new(ruby.exception_arg_error(), "capacity must be in 1..2**32")
27
- })?;
28
- let batch = Batch::new(capacity, wait.duration())
29
- .ok_or_else(|| Error::new(ruby.exception_arg_error(), "max wait must be positive"))?;
30
- let pid = Self::pid(ruby, capacity.get(), 1.0, 0.0, 0.0)?;
31
- Ok(Self {
32
- state: RefCell::new(State { batch, pid }),
33
- capacity: capacity.get(),
92
+ /// Raises `RangeError` for a zero `max_wait` (the core answers `None`).
93
+ fn new(ruby: &Ruby, capacity: Value, max_wait: Value) -> Result<Self, Error> {
94
+ let capacity = positive(capacity, "capacity")?;
95
+ Batch::new(capacity, duration(max_wait, "max_wait")?)
96
+ .map(|batch| Self(RefCell::new(batch)))
97
+ .ok_or_else(|| Error::new(ruby.exception_range_error(), "max_wait must be positive"))
98
+ }
99
+
100
+ /// A push answers with a `Flush` built by Ruby code, so it is counted on
101
+ /// a copy and the batch moves only once the answer exists: a raise while
102
+ /// building it counts nothing. A build that froze the batch meanwhile
103
+ /// raises `FrozenError`, one that changed it (a redefined `Flush.new`
104
+ /// calling back in) `RuntimeError`; neither applies the copy.
105
+ fn admit(
106
+ ruby: &Ruby,
107
+ this: Obj<Self>,
108
+ act: impl FnOnce(&mut Batch) -> Result<Admission, Refusal>,
109
+ ) -> Result<Value, Error> {
110
+ this.check_frozen()?;
111
+ let flush = CLASSES.get(ruby)?.flush.get(ruby);
112
+ keep(ruby, this, &this.0, act, |admitted| match admitted {
113
+ Ok(Admission::Buffered) => {
114
+ Ok(Admissions::symbol_of(ruby, Admission::Buffered).as_value())
115
+ }
116
+ Ok(Admission::Flush(due)) => flush.funcall("new", (reason(ruby, due),)),
117
+ Err(refused) => Ok(refusal(ruby, refused)),
34
118
  })
35
119
  }
36
120
 
37
- fn pid(ruby: &Ruby, capacity: u32, p: f64, i: f64, d: f64) -> Result<Pid, Error> {
38
- let gains = Gains::new(p, i, d).ok_or_else(|| {
39
- Error::new(
40
- ruby.exception_arg_error(),
41
- "gains must be finite and nonnegative",
42
- )
43
- })?;
44
- let limits = Limits::new(0.0, f64::from(capacity))
45
- .ok_or_else(|| Error::new(ruby.exception_arg_error(), "invalid PID output limits"))?;
46
- Ok(Pid::new(gains, limits))
121
+ fn push(ruby: &Ruby, this: Obj<Self>, now: Value) -> Result<Value, Error> {
122
+ this.check_frozen()?;
123
+ let now = instant(now, "now")?;
124
+ Self::admit(ruby, this, |batch| batch.push(now))
47
125
  }
48
126
 
49
- fn configure_pid(ruby: &Ruby, this: Obj<Self>, p: f64, i: f64, d: f64) -> Result<(), Error> {
127
+ fn push_weighted(
128
+ ruby: &Ruby,
129
+ this: Obj<Self>,
130
+ now: Value,
131
+ cost: Value,
132
+ ) -> Result<Value, Error> {
50
133
  this.check_frozen()?;
51
- let pid = Self::pid(ruby, this.capacity, p, i, d)?;
52
- this.state.borrow_mut().pid = pid;
53
- Ok(())
134
+ let (now, cost) = (instant(now, "now")?, positive(cost, "cost")?);
135
+ Self::admit(ruby, this, |batch| batch.push_weighted(now, cost))
54
136
  }
55
137
 
56
- fn push(this: Obj<Self>, now: Count) -> Result<&'static str, Error> {
138
+ fn poll(ruby: &Ruby, this: Obj<Self>, now: Value) -> Result<Option<Value>, Error> {
57
139
  this.check_frozen()?;
58
- let result = this.state.borrow_mut().batch.push(now.duration());
59
- Ok(match result {
60
- Admission::Buffered => "buffered",
61
- Admission::Flush(FlushReason::Size) => "size",
62
- Admission::Flush(_) => "deadline",
63
- Admission::Full => "full",
64
- _ => "rejected",
140
+ let now = instant(now, "now")?;
141
+ let answer = this.0.borrow_mut().poll(now);
142
+ Ok(match answer {
143
+ Ok(due) => due.map(|due| reason(ruby, due).as_value()),
144
+ Err(refused) => Some(refusal(ruby, refused)),
65
145
  })
66
146
  }
67
147
 
68
- fn poll(this: Obj<Self>, now: Count) -> Result<Option<&'static str>, Error> {
148
+ /// A mutating call that answers a count: nothing can raise once the
149
+ /// core has acted.
150
+ fn count(
151
+ ruby: &Ruby,
152
+ this: Obj<Self>,
153
+ act: impl FnOnce(&mut Batch) -> Result<u32, Refusal>,
154
+ ) -> Result<Value, Error> {
69
155
  this.check_frozen()?;
70
- let reason = this.state.borrow_mut().batch.poll(now.duration());
71
- Ok(reason.map(|reason| match reason {
72
- FlushReason::Size => "size",
73
- _ => "deadline",
74
- }))
156
+ let answer = act(&mut this.0.borrow_mut());
157
+ Ok(counted(ruby, answer))
75
158
  }
76
159
 
77
- fn flush(this: Obj<Self>, now: Count) -> Result<Option<u32>, Error> {
160
+ fn flush(ruby: &Ruby, this: Obj<Self>, now: Value) -> Result<Value, Error> {
78
161
  this.check_frozen()?;
79
- let count = this.state.borrow_mut().batch.flush(now.duration());
80
- Ok(count)
162
+ let now = instant(now, "now")?;
163
+ Self::count(ruby, this, |batch| batch.flush(now))
81
164
  }
82
165
 
166
+ /// The core's `adapt`, across two native extensions: the controller is
167
+ /// the caller's object, stepped through its own `step`, and its answer is
168
+ /// handed to the core's `retarget`. `adapt` is exactly that pair. `step`
169
+ /// answers a refusal Symbol, or a Float or an Integer (read as `real`
170
+ /// reads one: its nearest Float, no `to_f` run); a NaN or infinite
171
+ /// output is the core's `:not_finite`. The
172
+ /// batch is checked for frozen before the controller is touched; a
173
+ /// `step` that freezes it has stepped the caller's controller, which the
174
+ /// binding cannot undo, and `retarget` then raises `FrozenError` with the
175
+ /// batch unchanged.
83
176
  fn adapt(
84
177
  ruby: &Ruby,
85
178
  this: Obj<Self>,
86
- error: f64,
87
- elapsed: Count,
88
- ) -> Result<Option<u32>, Error> {
179
+ pid: Value,
180
+ error: Value,
181
+ elapsed: Value,
182
+ ) -> Result<Value, Error> {
89
183
  this.check_frozen()?;
90
- if !error.is_finite() || elapsed.0 == 0 {
91
- return Err(Error::new(
92
- ruby.exception_arg_error(),
93
- "finite error and positive elapsed required",
94
- ));
184
+ real(error, "error")?;
185
+ duration(elapsed, "elapsed")?;
186
+ let stepped: Value = pid.funcall("step", (error, elapsed))?;
187
+ // The controller's refusals, by name: a `feedback_machines::Refusal`.
188
+ let read = symbol_or_real_why(ruby, stepped, ControllerRefusals, |why| match why {
189
+ Refused::UnknownSymbol(_) => format!(
190
+ "step's refusal must be one of :{}",
191
+ ControllerRefusals::EVERY_NAME.join(", :")
192
+ ),
193
+ _ => format!(
194
+ "step must answer a Float, an Integer or a refusal Symbol, not {}",
195
+ class_name(stepped)
196
+ ),
197
+ })?;
198
+ match read {
199
+ SymbolOrReal::Symbol(refused) => Ok(refusal(ruby, controller_refusal(refused))),
200
+ SymbolOrReal::Real(output) => Self::count(ruby, this, |batch| batch.retarget(output)),
95
201
  }
96
- let result = {
97
- let mut state = this.state.borrow_mut();
98
- let State { batch, pid } = &mut *state;
99
- batch.adapt(pid, error, elapsed.duration())
100
- };
101
- Ok(result)
202
+ }
203
+
204
+ /// Frozen is checked before `output` is converted.
205
+ fn retarget(ruby: &Ruby, this: Obj<Self>, output: Value) -> Result<Value, Error> {
206
+ this.check_frozen()?;
207
+ let output = real(output, "output")?;
208
+ Self::count(ruby, this, |batch| batch.retarget(output))
209
+ }
210
+
211
+ fn capacity(&self) -> u32 {
212
+ self.0.borrow().capacity()
213
+ }
214
+
215
+ fn max_wait(ruby: &Ruby, this: &Self) -> Value {
216
+ nanoseconds(ruby, this.0.borrow().max_wait()).as_value()
102
217
  }
103
218
 
104
219
  fn pending(&self) -> u32 {
105
- self.state.borrow().batch.pending()
220
+ self.0.borrow().pending()
221
+ }
222
+
223
+ fn pending_cost(&self) -> u32 {
224
+ self.0.borrow().pending_cost()
106
225
  }
107
226
 
108
227
  fn target(&self) -> u32 {
109
- self.state.borrow().batch.target()
228
+ self.0.borrow().target()
229
+ }
230
+
231
+ fn deadline(ruby: &Ruby, this: &Self) -> Option<Value> {
232
+ let deadline = this.0.borrow().deadline();
233
+ deadline.map(|deadline| nanoseconds(ruby, deadline).as_value())
110
234
  }
111
235
  }
112
236
 
113
237
  pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
238
+ // `Flush` is defined in Ruby before the extension loads: a missing one
239
+ // is `NameError`.
240
+ let flush = Class::resolve(ruby, module, "Flush")?;
241
+ CLASSES.set(ruby, Classes { flush })?;
242
+ module.define_singleton_method("__flush", function!(checked_flush, 1))?;
114
243
  let class = module.define_class("Batch", ruby.class_object())?;
244
+ class.undef_default_alloc_func();
115
245
  class.define_singleton_method("new", function!(Wrapper::new, 2))?;
116
- class.define_method("configure_pid", method!(Wrapper::configure_pid, 3))?;
117
246
  class.define_method("push", method!(Wrapper::push, 1))?;
247
+ class.define_method("push_weighted", method!(Wrapper::push_weighted, 2))?;
118
248
  class.define_method("poll", method!(Wrapper::poll, 1))?;
119
249
  class.define_method("flush", method!(Wrapper::flush, 1))?;
120
- class.define_method("adapt", method!(Wrapper::adapt, 2))?;
250
+ class.define_method("adapt", method!(Wrapper::adapt, 3))?;
251
+ class.define_method("retarget", method!(Wrapper::retarget, 1))?;
252
+ class.define_method("capacity", method!(Wrapper::capacity, 0))?;
253
+ class.define_method("max_wait", method!(Wrapper::max_wait, 0))?;
121
254
  class.define_method("pending", method!(Wrapper::pending, 0))?;
122
- class.define_method("target", method!(Wrapper::target, 0))
255
+ class.define_method("pending_cost", method!(Wrapper::pending_cost, 0))?;
256
+ class.define_method("target", method!(Wrapper::target, 0))?;
257
+ class.define_method("deadline", method!(Wrapper::deadline, 0))?;
258
+ // `new` answers a Wrapper: fix its class now, so building one runs no Ruby.
259
+ Class::pin_wrapped::<Wrapper>(ruby, class).map(drop)
123
260
  }
@@ -1,28 +1,3 @@
1
1
  //! Thin native batch policy with caller-owned payload storage and clock.
2
2
  mod batch;
3
3
  mod init;
4
-
5
- use std::time::Duration;
6
-
7
- use magnus::{Error, Integer, Ruby, TryConvert, Value};
8
-
9
- #[derive(Clone, Copy)]
10
- struct Count(u64);
11
-
12
- impl TryConvert for Count {
13
- fn try_convert(value: Value) -> Result<Self, Error> {
14
- if Integer::from_value(value).is_none() {
15
- return Err(Error::new(
16
- Ruby::get_with(value).exception_type_error(),
17
- "count/time must be an unsigned 64-bit Integer (time in nanoseconds)",
18
- ));
19
- }
20
- u64::try_convert(value).map(Self)
21
- }
22
- }
23
-
24
- impl Count {
25
- const fn duration(self) -> Duration {
26
- Duration::from_nanos(self.0)
27
- }
28
- }
@@ -1,4 +1,4 @@
1
1
  # frozen_string_literal: true
2
2
  module BatchMachines
3
- VERSION = '0.1.4'
3
+ VERSION = '0.5.4'
4
4
  end
@@ -1,3 +1,33 @@
1
1
  # frozen_string_literal: true
2
+
2
3
  require_relative 'batch_machines/version'
4
+
5
+ module BatchMachines
6
+ # The core's `Admission::Flush(FlushReason)`: the item was counted and a
7
+ # flush is due. `reason` is :size or :deadline. The other honoured push
8
+ # answer, `Admission::Buffered`, is the symbol :buffered. A Flush holds
9
+ # only a `FlushReason`: any other symbol raises RangeError, a non-Symbol
10
+ # TypeError, whether the gem built it or you did.
11
+ Flush = Data.define(:reason) do
12
+ def initialize(reason:)
13
+ reason = BatchMachines.__send__(:__flush, reason)
14
+ super
15
+ end
16
+ end
17
+ end
18
+
19
+ # Native is required: there is no pure-Ruby fallback. It validates and builds
20
+ # Flush values and resolves the class once at load, so the Data class above
21
+ # must exist first.
3
22
  require 'batch_machines_native/batch_machines_native'
23
+
24
+ module BatchMachines
25
+ private_class_method :__flush
26
+
27
+ # Sealed: no subclass can skip the check by overriding `initialize`, and no
28
+ # bare `allocate` builds a value that never ran it. Sealing stops
29
+ # accidents, not reflection; the batch never reads a Flush back, so a
30
+ # forged one cannot reach the core.
31
+ Flush.singleton_class.undef_method(:allocate)
32
+ Flush.define_singleton_method(:inherited) { |_| raise TypeError, "#{Flush} cannot be subclassed" }
33
+ end
@@ -1,13 +1,112 @@
1
+ # Time is Integer nanoseconds on a monotonic clock: TypeError for a
2
+ # non-Integer. Spans (max_wait, elapsed) raise RangeError outside
3
+ # 0..2**64-1; instants (`now`) are read over the whole `Duration` range,
4
+ # 0..Duration::MAX nanoseconds, so every `deadline` the batch answers reads
5
+ # back as `now`, and raise RangeError outside it. Capacity and
6
+ # cost are Integers in 1..2**32-1: TypeError for anything else, RangeError
7
+ # outside the range. A frozen batch raises FrozenError on every mutating
8
+ # call. Refusals are symbols, one per core `Refusal` variant; they never
9
+ # raise, and a refused call changes nothing, not even the observed clock.
1
10
  module BatchMachines
2
11
  VERSION: String
12
+
13
+ # The core's `Refusal`.
14
+ # :time_regression, `now` is earlier than the latest observed instant.
15
+ # :overflow, `now + max_wait` does not fit a Duration (push), or a term of
16
+ # the controller's calculation is not finite (adapt).
17
+ # :full, the item costs more than the capacity still unspent.
18
+ # :not_finite, the error or output is NaN or infinite.
19
+ # :invalid_duration, the elapsed time is zero.
20
+ type refusal = :time_regression | :overflow | :full | :not_finite | :invalid_duration
21
+
22
+ # The core's `FlushReason`.
23
+ type flush_reason = :size | :deadline
24
+
25
+ # The core's `Admission::Flush(FlushReason)`: counted, and a flush is due.
26
+ # `new` holds a hand-built value to the same rule as one the gem returned:
27
+ # RangeError for a symbol that is not a `FlushReason`, TypeError for a
28
+ # non-Symbol. Sealed: no `allocate`, subclassing raises TypeError.
29
+ class Flush < Data
30
+ attr_reader reason: flush_reason
31
+ def self.new: (flush_reason reason) -> Flush
32
+ | (reason: flush_reason) -> Flush
33
+ end
34
+
35
+ # The core's `Admission`: `Buffered` is :buffered, `Flush(reason)` a Flush.
36
+ type admission = :buffered | Flush
37
+
38
+ # A FeedbackMachines::Pid, or anything whose `step` answers as it does: a
39
+ # Float (or Integer) output, or :not_finite, :invalid_duration or :overflow.
40
+ interface _Controller
41
+ def step: (Numeric error, Integer elapsed) -> (Float | Integer | :not_finite | :invalid_duration | :overflow)
42
+ end
43
+
44
+ # The core's `Batch`.
3
45
  class Batch
4
- def self.new: (Integer capacity, Integer max_wait_ns) -> instance
5
- def configure_pid: (Float | Integer p, Float | Integer i, Float | Integer d) -> nil
6
- def push: (Integer now_ns) -> String
7
- def poll: (Integer now_ns) -> String?
8
- def flush: (Integer now_ns) -> Integer?
9
- def adapt: (Float | Integer error, Integer elapsed_ns) -> Integer?
46
+ # The core's `Batch::new(capacity, max_wait)`; the target starts at
47
+ # capacity. Raises RangeError for a zero max_wait (the core's `None`).
48
+ def self.new: (Integer capacity, Integer max_wait) -> Batch
49
+
50
+ # The core's `push(now)`: `push_weighted(now, 1)`.
51
+ # Honoured: :buffered or a Flush; the item is counted either way.
52
+ # An honoured push observes `now`. Counted on a copy, applied once the
53
+ # answer is built: a raise while building it counts nothing; FrozenError
54
+ # if building it froze the batch, RuntimeError if it changed the batch,
55
+ # nothing applied in either case.
56
+ # Refused: :time_regression, :full, :overflow (the item would start a
57
+ # batch and `now + max_wait` does not fit a Duration).
58
+ def push: (Integer now) -> (admission | :time_regression | :full | :overflow)
59
+
60
+ # The core's `push_weighted(now, cost)`.
61
+ # Honoured: :buffered or a Flush; the item is counted either way.
62
+ # Refused: :time_regression, :full, :overflow, as for `push`.
63
+ def push_weighted: (Integer now, Integer cost) -> (admission | :time_regression | :full | :overflow)
64
+
65
+ # The core's `poll(now)`. Honoured: :size or :deadline when a flush is
66
+ # due, nil when nothing is due at this instant. Every honoured poll
67
+ # observes `now`, nil included. Refused: :time_regression.
68
+ def poll: (Integer now) -> (flush_reason | nil | :time_regression)
69
+
70
+ # The core's `flush(now)`. Honoured: the items that were pending, and
71
+ # `now` is observed; 0 for an empty batch, an honoured repeat that holds
72
+ # whatever the time and observes nothing. Refused: :time_regression.
73
+ # Never nil.
74
+ def flush: (Integer now) -> (Integer | :time_regression)
75
+
76
+ # The core's `adapt(pid, error, elapsed)`: steps the caller's controller
77
+ # once (`pid.step(error, elapsed)`) and retargets to its output.
78
+ # Honoured: the new target. Refused: :not_finite, :invalid_duration,
79
+ # :overflow, as the controller answered them; nothing changed. Never nil.
80
+ # Reads and observes no clock: `elapsed` is a span.
81
+ # An Integer output is read as its nearest Float; one past Float::MAX is
82
+ # infinite and answers :not_finite.
83
+ # Raises TypeError for a non-number error, a non-Integer elapsed, or a
84
+ # `step` that answers neither a Float, an Integer nor a Symbol; RangeError
85
+ # for an elapsed outside 0..2**64-1 or a `step` that answers any other
86
+ # Symbol;
87
+ # NoMethodError for an object without `step`. FrozenError for a frozen
88
+ # batch before stepping; a `step` that freezes the batch has stepped the
89
+ # controller, and FrozenError follows with the target unchanged.
90
+ def adapt: (_Controller pid, Numeric error, Integer elapsed) -> (Integer | :not_finite | :invalid_duration | :overflow)
91
+
92
+ # The core's `retarget(output)`: the target becomes `output` truncated
93
+ # and clamped to 1..capacity. Honoured: the new target. Refused:
94
+ # :not_finite. Never nil. Reads no clock. Raises TypeError for a
95
+ # non-number.
96
+ def retarget: (Numeric output) -> (Integer | :not_finite)
97
+
98
+ def capacity: () -> Integer
99
+ def max_wait: () -> Integer
10
100
  def pending: () -> Integer
101
+ def pending_cost: () -> Integer
11
102
  def target: () -> Integer
103
+
104
+ # The instant `poll` first answers :deadline; nil while nothing is pending.
105
+ def deadline: () -> Integer?
12
106
  end
107
+
108
+ # Native check behind `Flush#initialize`: the reason back when it is a
109
+ # `FlushReason`, RangeError for any other Symbol, TypeError for a
110
+ # non-Symbol.
111
+ private def self.__flush: (flush_reason reason) -> flush_reason
13
112
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: batch_machines
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.5.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 native batch policy model. Caller owns payloads and execution.
33
- Local sibling Rust checkouts required.
32
+ description: 'Ruby adapter to the no_std batch-machines Rust core: bounded size/deadline
33
+ batch decisions with a controller-adapted target. Caller owns payloads, clock and
34
+ 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,6 +48,7 @@ files:
46
48
  - ext/batch_machines_native/core/Cargo.toml
47
49
  - ext/batch_machines_native/core/README.md
48
50
  - ext/batch_machines_native/core/src/lib.rs
51
+ - ext/batch_machines_native/core/src/refusal.rs
49
52
  - ext/batch_machines_native/extconf.rb
50
53
  - ext/batch_machines_native/ffi/Cargo.toml
51
54
  - ext/batch_machines_native/ffi/extconf.rb