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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +72 -0
- data/Cargo.lock +322 -0
- data/Cargo.toml +4 -2
- data/README.md +84 -37
- data/ext/batch_machines_native/core/CHANGELOG.md +40 -0
- data/ext/batch_machines_native/core/Cargo.toml +4 -2
- data/ext/batch_machines_native/core/README.md +53 -0
- data/ext/batch_machines_native/core/src/lib.rs +151 -63
- data/ext/batch_machines_native/core/src/refusal.rs +34 -0
- data/ext/batch_machines_native/ffi/Cargo.toml +2 -1
- data/ext/batch_machines_native/ffi/src/batch.rs +212 -75
- data/ext/batch_machines_native/ffi/src/lib.rs +0 -25
- data/lib/batch_machines/version.rb +1 -1
- data/lib/batch_machines.rb +30 -0
- data/sig/batch_machines.rbs +105 -6
- metadata +6 -3
|
@@ -1,123 +1,260 @@
|
|
|
1
|
-
use std::
|
|
1
|
+
use std::cell::RefCell;
|
|
2
2
|
|
|
3
|
-
use batch_machines::{Admission, Batch, FlushReason};
|
|
4
|
-
use
|
|
5
|
-
use
|
|
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
|
-
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
.
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
|
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
|
|
52
|
-
this.
|
|
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
|
|
138
|
+
fn poll(ruby: &Ruby, this: Obj<Self>, now: Value) -> Result<Option<Value>, Error> {
|
|
57
139
|
this.check_frozen()?;
|
|
58
|
-
let
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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
|
-
|
|
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
|
|
71
|
-
Ok(
|
|
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:
|
|
160
|
+
fn flush(ruby: &Ruby, this: Obj<Self>, now: Value) -> Result<Value, Error> {
|
|
78
161
|
this.check_frozen()?;
|
|
79
|
-
let
|
|
80
|
-
|
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
179
|
+
pid: Value,
|
|
180
|
+
error: Value,
|
|
181
|
+
elapsed: Value,
|
|
182
|
+
) -> Result<Value, Error> {
|
|
89
183
|
this.check_frozen()?;
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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.
|
|
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.
|
|
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,
|
|
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("
|
|
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
|
-
}
|
data/lib/batch_machines.rb
CHANGED
|
@@ -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
|
data/sig/batch_machines.rbs
CHANGED
|
@@ -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
|
-
|
|
5
|
-
|
|
6
|
-
def
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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.
|
|
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:
|
|
33
|
-
|
|
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
|