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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +73 -0
- data/Cargo.lock +307 -0
- data/Cargo.toml +27 -0
- data/LICENSE.txt +21 -0
- data/README.md +270 -0
- data/ext/offset_machines_native/core/CHANGELOG.md +52 -0
- data/ext/offset_machines_native/core/Cargo.toml +17 -0
- data/ext/offset_machines_native/core/README.md +81 -0
- data/ext/offset_machines_native/core/src/lib.rs +362 -0
- data/ext/offset_machines_native/core/src/refusal.rs +43 -0
- data/ext/offset_machines_native/core/src/status.rs +121 -0
- data/ext/offset_machines_native/extconf.rb +2 -0
- data/ext/offset_machines_native/ffi/Cargo.toml +21 -0
- data/ext/offset_machines_native/ffi/extconf.rb +14 -0
- data/ext/offset_machines_native/ffi/src/init.rs +32 -0
- data/ext/offset_machines_native/ffi/src/lib.rs +230 -0
- data/lib/offset_machines/version.rb +5 -0
- data/lib/offset_machines.rb +39 -0
- data/sig/offset_machines.rbs +52 -0
- metadata +85 -0
|
@@ -0,0 +1,362 @@
|
|
|
1
|
+
#![no_std]
|
|
2
|
+
#![cfg_attr(not(test), deny(clippy::indexing_slicing))]
|
|
3
|
+
#![doc = include_str!("../README.md")]
|
|
4
|
+
|
|
5
|
+
mod refusal;
|
|
6
|
+
mod status;
|
|
7
|
+
|
|
8
|
+
use core::num::NonZeroU64;
|
|
9
|
+
|
|
10
|
+
pub use refusal::Refusal;
|
|
11
|
+
pub use status::Status;
|
|
12
|
+
|
|
13
|
+
/// Offsets per bitmap word: one bit each in a `u64`.
|
|
14
|
+
const WORD_BITS: u64 = 64;
|
|
15
|
+
|
|
16
|
+
/// Honoured outcome of [`Tracker::ack`].
|
|
17
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
18
|
+
pub enum Ack {
|
|
19
|
+
/// The offset was recorded.
|
|
20
|
+
Recorded,
|
|
21
|
+
/// Idempotent repeat: the offset was already acknowledged or is already
|
|
22
|
+
/// below the window (committed). Nothing changed.
|
|
23
|
+
Duplicate,
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/// Honoured outcome of [`Tracker::mark_committed`].
|
|
27
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
28
|
+
pub enum Commit {
|
|
29
|
+
/// The window slid forward to the confirmed offset.
|
|
30
|
+
Advanced,
|
|
31
|
+
/// Idempotent repeat: the confirmed offset is not beyond the current
|
|
32
|
+
/// window base, so it is already committed. Nothing changed.
|
|
33
|
+
Duplicate,
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/// Per-partition acknowledgement window of `WORDS * 64` offsets.
|
|
37
|
+
///
|
|
38
|
+
/// The window covers `base .. base + CAPACITY`. Acknowledgements set bits;
|
|
39
|
+
/// the window only slides when the adapter confirms persistence through
|
|
40
|
+
/// [`Tracker::mark_committed`]. The tracker owns no execution, storage or
|
|
41
|
+
/// commit protocol: it never allocates and never decides on its own.
|
|
42
|
+
///
|
|
43
|
+
/// Offset `u64::MAX` is never acknowledgeable, so every commit candidate is
|
|
44
|
+
/// representable.
|
|
45
|
+
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
46
|
+
pub struct Tracker<const WORDS: usize> {
|
|
47
|
+
generation: u64,
|
|
48
|
+
base: u64,
|
|
49
|
+
bits: [u64; WORDS],
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
impl<const WORDS: usize> Default for Tracker<WORDS> {
|
|
53
|
+
fn default() -> Self {
|
|
54
|
+
Self::new()
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
impl<const WORDS: usize> Tracker<WORDS> {
|
|
59
|
+
/// Number of offsets in the window.
|
|
60
|
+
pub const CAPACITY: u64 = WORDS as u64 * WORD_BITS;
|
|
61
|
+
|
|
62
|
+
/// Start unassigned: generation zero, so every acknowledgement and
|
|
63
|
+
/// confirmation is refused as [`Refusal::Stale`].
|
|
64
|
+
#[must_use]
|
|
65
|
+
pub const fn new() -> Self {
|
|
66
|
+
Self {
|
|
67
|
+
generation: 0,
|
|
68
|
+
base: 0,
|
|
69
|
+
bits: [0; WORDS],
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/// Start already assigned: `generation` is current and the window starts
|
|
74
|
+
/// at `base_offset`, nothing acknowledged.
|
|
75
|
+
///
|
|
76
|
+
/// The tracker [`Tracker::assign`] would make of a fresh one, without the
|
|
77
|
+
/// refusal: a fresh tracker is at generation zero, so `assign` refuses
|
|
78
|
+
/// only zero, and a [`NonZeroU64`] is never zero. Equal to
|
|
79
|
+
/// `Tracker::new()` followed by an honoured `assign(generation.get(),
|
|
80
|
+
/// base_offset)`.
|
|
81
|
+
#[must_use]
|
|
82
|
+
pub const fn assigned(generation: NonZeroU64, base_offset: u64) -> Self {
|
|
83
|
+
Self {
|
|
84
|
+
generation: generation.get(),
|
|
85
|
+
base: base_offset,
|
|
86
|
+
bits: [0; WORDS],
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/// Current assignment generation; zero while unassigned.
|
|
91
|
+
#[must_use]
|
|
92
|
+
pub const fn generation(&self) -> u64 {
|
|
93
|
+
self.generation
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/// Lowest offset not yet confirmed committed; the window starts here.
|
|
97
|
+
#[must_use]
|
|
98
|
+
pub const fn base(&self) -> u64 {
|
|
99
|
+
self.base
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/// Install a newer assignment generation and restart the window at
|
|
103
|
+
/// `base_offset`, discarding acknowledgements of the previous generation.
|
|
104
|
+
///
|
|
105
|
+
/// # Errors
|
|
106
|
+
///
|
|
107
|
+
/// [`Refusal::Stale`] when `generation` is not newer than the current one
|
|
108
|
+
/// (zero is never newer).
|
|
109
|
+
pub const fn assign(&mut self, generation: u64, base_offset: u64) -> Result<(), Refusal> {
|
|
110
|
+
if generation <= self.generation {
|
|
111
|
+
return Err(Refusal::Stale);
|
|
112
|
+
}
|
|
113
|
+
self.install(generation, base_offset);
|
|
114
|
+
Ok(())
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/// Start the window of a generation already known to be newer.
|
|
118
|
+
const fn install(&mut self, generation: u64, base_offset: u64) {
|
|
119
|
+
self.generation = generation;
|
|
120
|
+
self.base = base_offset;
|
|
121
|
+
self.bits = [0; WORDS];
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/// Assign the next generation at `base_offset` and return it.
|
|
125
|
+
///
|
|
126
|
+
/// # Errors
|
|
127
|
+
///
|
|
128
|
+
/// [`Refusal::Exhausted`] when the current generation is `u64::MAX`.
|
|
129
|
+
pub fn reassign(&mut self, base_offset: u64) -> Result<u64, Refusal> {
|
|
130
|
+
let generation = self.generation.checked_add(1).ok_or(Refusal::Exhausted)?;
|
|
131
|
+
// One past the current generation is newer by construction: no
|
|
132
|
+
// `Stale` arm to carry.
|
|
133
|
+
self.install(generation, base_offset);
|
|
134
|
+
Ok(generation)
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/// Record that `offset` finished processing under `generation`.
|
|
138
|
+
///
|
|
139
|
+
/// An offset already acknowledged, or already below the window, is an
|
|
140
|
+
/// idempotent repeat: [`Ack::Duplicate`].
|
|
141
|
+
///
|
|
142
|
+
/// # Errors
|
|
143
|
+
///
|
|
144
|
+
/// [`Refusal::Stale`] when `generation` is not the current assignment
|
|
145
|
+
/// generation (always, while unassigned); [`Refusal::OutOfWindow`] when
|
|
146
|
+
/// `offset` is beyond the window or is `u64::MAX`.
|
|
147
|
+
pub fn ack(&mut self, generation: u64, offset: u64) -> Result<Ack, Refusal> {
|
|
148
|
+
self.check_current(generation)?;
|
|
149
|
+
let Some(index) = offset.checked_sub(self.base) else {
|
|
150
|
+
return Ok(Ack::Duplicate);
|
|
151
|
+
};
|
|
152
|
+
if offset == u64::MAX {
|
|
153
|
+
return Err(Refusal::OutOfWindow);
|
|
154
|
+
}
|
|
155
|
+
// The window is exactly the words there are: no word, no window.
|
|
156
|
+
let (word, mask) = Self::slot(index);
|
|
157
|
+
let word = word
|
|
158
|
+
.and_then(|word| self.bits.get_mut(word))
|
|
159
|
+
.ok_or(Refusal::OutOfWindow)?;
|
|
160
|
+
if *word & mask != 0 {
|
|
161
|
+
return Ok(Ack::Duplicate);
|
|
162
|
+
}
|
|
163
|
+
*word |= mask;
|
|
164
|
+
Ok(Ack::Recorded)
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/// [`Refusal::Stale`] unless `generation` is the current, assigned one.
|
|
168
|
+
const fn check_current(&self, generation: u64) -> Result<(), Refusal> {
|
|
169
|
+
if generation != self.generation || generation == 0 {
|
|
170
|
+
Err(Refusal::Stale)
|
|
171
|
+
} else {
|
|
172
|
+
Ok(())
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/// Word index (if it fits a `usize`) and bit mask of the slot `index`
|
|
177
|
+
/// offsets above `base`; the caller checks the word exists.
|
|
178
|
+
fn slot(index: u64) -> (Option<usize>, u64) {
|
|
179
|
+
(
|
|
180
|
+
usize::try_from(index / WORD_BITS).ok(),
|
|
181
|
+
1 << (index % WORD_BITS),
|
|
182
|
+
)
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/// Length of the contiguous acknowledged prefix from `base`.
|
|
186
|
+
fn prefix(&self) -> u64 {
|
|
187
|
+
let mut run = 0_u64;
|
|
188
|
+
for word in &self.bits {
|
|
189
|
+
run += u64::from(word.trailing_ones());
|
|
190
|
+
if *word != u64::MAX {
|
|
191
|
+
break;
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
run
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/// The next offset to commit: one past the contiguous acknowledged prefix.
|
|
198
|
+
/// `None` when `base` itself is not acknowledged.
|
|
199
|
+
#[must_use]
|
|
200
|
+
pub fn commit_candidate(&self) -> Option<u64> {
|
|
201
|
+
let run = self.prefix();
|
|
202
|
+
// `base + run` is one past an acknowledged offset, and `ack` refuses
|
|
203
|
+
// `u64::MAX`, so the sum is at most `u64::MAX`.
|
|
204
|
+
(run > 0).then(|| self.base + run)
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/// One past the highest acknowledged offset, or `None` when nothing is
|
|
208
|
+
/// acknowledged. Offsets below it that are not acknowledged are gaps.
|
|
209
|
+
#[must_use]
|
|
210
|
+
pub fn frontier(&self) -> Option<u64> {
|
|
211
|
+
let (index, word) = self
|
|
212
|
+
.bits
|
|
213
|
+
.iter()
|
|
214
|
+
.enumerate()
|
|
215
|
+
.rev()
|
|
216
|
+
.find(|(_, word)| **word != 0)?;
|
|
217
|
+
let top = WORD_BITS - u64::from(word.leading_zeros());
|
|
218
|
+
// One past an acknowledged offset; `ack` refuses `u64::MAX`, so this
|
|
219
|
+
// fits (see `commit_candidate`).
|
|
220
|
+
Some(self.base + index as u64 * WORD_BITS + top)
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/// Number of acknowledged offsets in the window.
|
|
224
|
+
#[must_use]
|
|
225
|
+
pub fn acked(&self) -> u64 {
|
|
226
|
+
self.bits
|
|
227
|
+
.iter()
|
|
228
|
+
.map(|word| u64::from(word.count_ones()))
|
|
229
|
+
.sum()
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/// Whether `offset` is already acknowledged under the current generation:
|
|
233
|
+
/// it is below `base` (covered by the committed base) or recorded in the
|
|
234
|
+
/// window. Exactly the offsets for which [`Tracker::ack`] with the current
|
|
235
|
+
/// generation answers [`Ack::Duplicate`].
|
|
236
|
+
///
|
|
237
|
+
/// `false` for an offset in the window that is not recorded, for any
|
|
238
|
+
/// offset beyond the window, for `u64::MAX`, and for every offset while
|
|
239
|
+
/// unassigned (the base is zero and the window empty). A pure query: it
|
|
240
|
+
/// takes no generation because it reads only the current one, and a newer
|
|
241
|
+
/// [`Tracker::assign`] forgets what the previous generation acknowledged.
|
|
242
|
+
#[must_use]
|
|
243
|
+
pub fn is_acked(&self, offset: u64) -> bool {
|
|
244
|
+
let Some(index) = offset.checked_sub(self.base) else {
|
|
245
|
+
return true;
|
|
246
|
+
};
|
|
247
|
+
let (word, mask) = Self::slot(index);
|
|
248
|
+
word.and_then(|word| self.bits.get(word))
|
|
249
|
+
.is_some_and(|word| word & mask != 0)
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/// Unacknowledged offsets below the frontier, ascending, starting at
|
|
253
|
+
/// `from` (clamped up to `base`). Resume by passing last yielded + 1.
|
|
254
|
+
#[must_use]
|
|
255
|
+
pub fn gaps(&self, from: u64) -> Gaps<'_, WORDS> {
|
|
256
|
+
Gaps {
|
|
257
|
+
tracker: self,
|
|
258
|
+
next: from.max(self.base),
|
|
259
|
+
end: self.frontier().unwrap_or(self.base),
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/// Adapter confirms offsets below `offset` are durably committed under
|
|
264
|
+
/// `generation`; the window slides to `offset`. Partial confirmation up
|
|
265
|
+
/// to the commit candidate is allowed.
|
|
266
|
+
///
|
|
267
|
+
/// An offset not beyond the window base is already committed: an
|
|
268
|
+
/// idempotent repeat, [`Commit::Duplicate`].
|
|
269
|
+
///
|
|
270
|
+
/// # Errors
|
|
271
|
+
///
|
|
272
|
+
/// [`Refusal::Stale`] when `generation` is not the current assignment
|
|
273
|
+
/// generation (always, while unassigned); [`Refusal::Unacked`] when
|
|
274
|
+
/// `offset` is beyond the contiguous acknowledged prefix.
|
|
275
|
+
pub fn mark_committed(&mut self, generation: u64, offset: u64) -> Result<Commit, Refusal> {
|
|
276
|
+
self.check_current(generation)?;
|
|
277
|
+
if offset <= self.base {
|
|
278
|
+
return Ok(Commit::Duplicate);
|
|
279
|
+
}
|
|
280
|
+
if self
|
|
281
|
+
.commit_candidate()
|
|
282
|
+
.is_none_or(|candidate| offset > candidate)
|
|
283
|
+
{
|
|
284
|
+
return Err(Refusal::Unacked);
|
|
285
|
+
}
|
|
286
|
+
self.slide(offset - self.base);
|
|
287
|
+
self.base = offset;
|
|
288
|
+
Ok(Commit::Advanced)
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
fn slide(&mut self, shift: u64) {
|
|
292
|
+
let old = self.bits;
|
|
293
|
+
let (Ok(words), bits) = (usize::try_from(shift / WORD_BITS), shift % WORD_BITS) else {
|
|
294
|
+
self.bits = [0; WORDS];
|
|
295
|
+
return;
|
|
296
|
+
};
|
|
297
|
+
// A word past the old window reads as nothing acknowledged.
|
|
298
|
+
let old_word = |i: usize, ahead: usize| {
|
|
299
|
+
i.checked_add(ahead)
|
|
300
|
+
.and_then(|j| old.get(j))
|
|
301
|
+
.copied()
|
|
302
|
+
.unwrap_or(0)
|
|
303
|
+
};
|
|
304
|
+
for (i, slot) in self.bits.iter_mut().enumerate() {
|
|
305
|
+
let low = old_word(i, words);
|
|
306
|
+
*slot = if bits == 0 {
|
|
307
|
+
low
|
|
308
|
+
} else {
|
|
309
|
+
(low >> bits) | (old_word(i, words.saturating_add(1)) << (WORD_BITS - bits))
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/// Resumable iterator over unacknowledged offsets below the frontier.
|
|
316
|
+
#[derive(Debug, Clone)]
|
|
317
|
+
pub struct Gaps<'a, const WORDS: usize> {
|
|
318
|
+
tracker: &'a Tracker<WORDS>,
|
|
319
|
+
next: u64,
|
|
320
|
+
end: u64,
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
impl<const WORDS: usize> Iterator for Gaps<'_, WORDS> {
|
|
324
|
+
type Item = u64;
|
|
325
|
+
|
|
326
|
+
/// Word at a time: a fully acknowledged rest of a word is skipped in one
|
|
327
|
+
/// step, and the next gap inside a word is its lowest clear bit.
|
|
328
|
+
fn next(&mut self) -> Option<u64> {
|
|
329
|
+
let tracker = self.tracker;
|
|
330
|
+
while self.next < self.end {
|
|
331
|
+
// `next` starts at or above `base`, and `end` (the frontier) is at
|
|
332
|
+
// most `base + CAPACITY`: every offset in between has a word.
|
|
333
|
+
let (word, _) = Tracker::<WORDS>::slot(self.next - tracker.base);
|
|
334
|
+
let Some(word) = word.and_then(|word| tracker.bits.get(word)) else {
|
|
335
|
+
debug_assert!(false, "an offset below the frontier lies in the window");
|
|
336
|
+
self.next = self.end;
|
|
337
|
+
return None;
|
|
338
|
+
};
|
|
339
|
+
let bit = (self.next - tracker.base) % WORD_BITS;
|
|
340
|
+
let open = !word >> bit;
|
|
341
|
+
if open == 0 {
|
|
342
|
+
self.next = self.next.saturating_add(WORD_BITS - bit).min(self.end);
|
|
343
|
+
continue;
|
|
344
|
+
}
|
|
345
|
+
// The lowest clear bit at or above `next`: `u64::MAX` is never
|
|
346
|
+
// acknowledged, so it lies at or below `u64::MAX` and cannot wrap.
|
|
347
|
+
let offset = self.next + u64::from(open.trailing_zeros());
|
|
348
|
+
if offset >= self.end {
|
|
349
|
+
self.next = self.end;
|
|
350
|
+
return None;
|
|
351
|
+
}
|
|
352
|
+
self.next = offset + 1;
|
|
353
|
+
return Some(offset);
|
|
354
|
+
}
|
|
355
|
+
None
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
#[cfg(test)]
|
|
360
|
+
extern crate std;
|
|
361
|
+
#[cfg(test)]
|
|
362
|
+
mod tests;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
//! The one answer for every call that changed nothing.
|
|
2
|
+
use core::fmt;
|
|
3
|
+
|
|
4
|
+
/// Why a call was not honoured. Every refusal leaves the tracker exactly as
|
|
5
|
+
/// it was; no operation reports "nothing happened" any other way.
|
|
6
|
+
///
|
|
7
|
+
/// An idempotent repeat is not a refusal: acknowledging an offset twice or
|
|
8
|
+
/// confirming a commit twice is honoured as [`Ack::Duplicate`](crate::Ack) or
|
|
9
|
+
/// [`Commit::Duplicate`](crate::Commit).
|
|
10
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
11
|
+
pub enum Refusal {
|
|
12
|
+
/// The generation is not acceptable: for [`Tracker::assign`] it is not
|
|
13
|
+
/// newer than the current one (zero is never newer); for [`Tracker::ack`]
|
|
14
|
+
/// and [`Tracker::mark_committed`] it is not the current assignment
|
|
15
|
+
/// generation, or the tracker is unassigned.
|
|
16
|
+
///
|
|
17
|
+
/// [`Tracker::assign`]: crate::Tracker::assign
|
|
18
|
+
/// [`Tracker::ack`]: crate::Tracker::ack
|
|
19
|
+
/// [`Tracker::mark_committed`]: crate::Tracker::mark_committed
|
|
20
|
+
Stale,
|
|
21
|
+
/// The offset is beyond the window, or is `u64::MAX`.
|
|
22
|
+
OutOfWindow,
|
|
23
|
+
/// The confirmed offset is beyond the contiguous acknowledged prefix.
|
|
24
|
+
Unacked,
|
|
25
|
+
/// The generation space is spent; [`Tracker::reassign`] has no next
|
|
26
|
+
/// generation to issue.
|
|
27
|
+
///
|
|
28
|
+
/// [`Tracker::reassign`]: crate::Tracker::reassign
|
|
29
|
+
Exhausted,
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
impl fmt::Display for Refusal {
|
|
33
|
+
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
34
|
+
f.write_str(match self {
|
|
35
|
+
Self::Stale => "the generation is not current",
|
|
36
|
+
Self::OutOfWindow => "the offset is beyond the window",
|
|
37
|
+
Self::Unacked => "the offset is beyond the acknowledged prefix",
|
|
38
|
+
Self::Exhausted => "generation space exhausted",
|
|
39
|
+
})
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
impl core::error::Error for Refusal {}
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
//! Point-in-time view of a tracker, valid by construction.
|
|
2
|
+
use crate::Tracker;
|
|
3
|
+
|
|
4
|
+
/// What a [`Tracker`] reports about itself at one instant: the answers of its
|
|
5
|
+
/// five readers together.
|
|
6
|
+
///
|
|
7
|
+
/// A `Status` exists only when some tracker could report it. [`Tracker::status`]
|
|
8
|
+
/// builds one from a live tracker; [`Status::new`] checks five loose numbers
|
|
9
|
+
/// against a window and answers `None` for a combination no tracker reaches.
|
|
10
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
11
|
+
pub struct Status {
|
|
12
|
+
generation: u64,
|
|
13
|
+
base: u64,
|
|
14
|
+
commit_candidate: Option<u64>,
|
|
15
|
+
frontier: Option<u64>,
|
|
16
|
+
acked: u64,
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
impl Status {
|
|
20
|
+
/// A view a `Tracker<WORDS>` could report, or `None`.
|
|
21
|
+
///
|
|
22
|
+
/// The rules, with `run = commit_candidate - base` and
|
|
23
|
+
/// `span = frontier - base` (zero when absent):
|
|
24
|
+
///
|
|
25
|
+
/// - unassigned (`generation == 0`): `base` is zero and nothing is
|
|
26
|
+
/// acknowledged;
|
|
27
|
+
/// - `acked == 0` exactly when there is no frontier, and then there is no
|
|
28
|
+
/// commit candidate either;
|
|
29
|
+
/// - a frontier lies in `base + 1 ..= base + CAPACITY`, a commit candidate
|
|
30
|
+
/// in `base + 1 ..= frontier`;
|
|
31
|
+
/// - `run == span` means no gaps, so `acked == span`; otherwise the offset
|
|
32
|
+
/// at `base + run` is a gap and the one below the frontier is
|
|
33
|
+
/// acknowledged, so `span >= run + 2` and `run < acked < span`.
|
|
34
|
+
#[must_use]
|
|
35
|
+
pub const fn new<const WORDS: usize>(
|
|
36
|
+
generation: u64,
|
|
37
|
+
base: u64,
|
|
38
|
+
commit_candidate: Option<u64>,
|
|
39
|
+
frontier: Option<u64>,
|
|
40
|
+
acked: u64,
|
|
41
|
+
) -> Option<Self> {
|
|
42
|
+
let status = Self {
|
|
43
|
+
generation,
|
|
44
|
+
base,
|
|
45
|
+
commit_candidate,
|
|
46
|
+
frontier,
|
|
47
|
+
acked,
|
|
48
|
+
};
|
|
49
|
+
let Some(span) = distance(base, frontier) else {
|
|
50
|
+
return None;
|
|
51
|
+
};
|
|
52
|
+
let Some(run) = distance(base, commit_candidate) else {
|
|
53
|
+
return None;
|
|
54
|
+
};
|
|
55
|
+
let assigned = generation != 0 || (base == 0 && acked == 0);
|
|
56
|
+
let counted = if run == span {
|
|
57
|
+
acked == span
|
|
58
|
+
} else {
|
|
59
|
+
run < acked && acked < span
|
|
60
|
+
};
|
|
61
|
+
if assigned && span <= Tracker::<WORDS>::CAPACITY && run <= span && counted {
|
|
62
|
+
Some(status)
|
|
63
|
+
} else {
|
|
64
|
+
None
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/// Assignment generation; zero while unassigned.
|
|
69
|
+
#[must_use]
|
|
70
|
+
pub const fn generation(&self) -> u64 {
|
|
71
|
+
self.generation
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/// Lowest offset not yet confirmed committed.
|
|
75
|
+
#[must_use]
|
|
76
|
+
pub const fn base(&self) -> u64 {
|
|
77
|
+
self.base
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/// One past the contiguous acknowledged prefix, if `base` is acknowledged.
|
|
81
|
+
#[must_use]
|
|
82
|
+
pub const fn commit_candidate(&self) -> Option<u64> {
|
|
83
|
+
self.commit_candidate
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/// One past the highest acknowledged offset, if any is acknowledged.
|
|
87
|
+
#[must_use]
|
|
88
|
+
pub const fn frontier(&self) -> Option<u64> {
|
|
89
|
+
self.frontier
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/// Number of acknowledged offsets in the window.
|
|
93
|
+
#[must_use]
|
|
94
|
+
pub const fn acked(&self) -> u64 {
|
|
95
|
+
self.acked
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/// How far a mark sits above `base`: zero when absent, `None` when it is
|
|
100
|
+
/// present but not above `base` (a mark is always one past an offset).
|
|
101
|
+
const fn distance(base: u64, mark: Option<u64>) -> Option<u64> {
|
|
102
|
+
match mark {
|
|
103
|
+
None => Some(0),
|
|
104
|
+
Some(mark) if mark > base => Some(mark - base),
|
|
105
|
+
Some(_) => None,
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
impl<const WORDS: usize> Tracker<WORDS> {
|
|
110
|
+
/// The tracker's five readers as one value.
|
|
111
|
+
#[must_use]
|
|
112
|
+
pub fn status(&self) -> Status {
|
|
113
|
+
Status {
|
|
114
|
+
generation: self.generation(),
|
|
115
|
+
base: self.base(),
|
|
116
|
+
commit_candidate: self.commit_candidate(),
|
|
117
|
+
frontier: self.frontier(),
|
|
118
|
+
acked: self.acked(),
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
[package]
|
|
2
|
+
name = "offset_machines_native"
|
|
3
|
+
version = "0.1.5"
|
|
4
|
+
edition.workspace = true
|
|
5
|
+
rust-version.workspace = true
|
|
6
|
+
license.workspace = true
|
|
7
|
+
publish = false
|
|
8
|
+
|
|
9
|
+
[lib]
|
|
10
|
+
crate-type = ["cdylib"]
|
|
11
|
+
test = false
|
|
12
|
+
doctest = false
|
|
13
|
+
|
|
14
|
+
[dependencies]
|
|
15
|
+
offset-machines.workspace = true
|
|
16
|
+
magnus.workspace = true
|
|
17
|
+
rb-sys.workspace = true
|
|
18
|
+
matryona-machines = { workspace = true, features = ["ruby"] }
|
|
19
|
+
|
|
20
|
+
[lints]
|
|
21
|
+
workspace = true
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
require 'mkmf'
|
|
3
|
+
require 'pathname'
|
|
4
|
+
require 'rb_sys/mkmf'
|
|
5
|
+
|
|
6
|
+
create_rust_makefile('offset_machines_native/offset_machines_native') do |e|
|
|
7
|
+
e.ext_dir = Pathname(__dir__).relative_path_from(Pathname(Dir.pwd)).to_s
|
|
8
|
+
e.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
|
|
9
|
+
end
|
|
10
|
+
makefile = File.join(Dir.pwd, 'Makefile')
|
|
11
|
+
File.write(makefile, File.read(makefile).gsub(
|
|
12
|
+
/^RB_SYS_CARGO_MANIFEST_DIR \?=.*$/,
|
|
13
|
+
"RB_SYS_CARGO_MANIFEST_DIR ?= #{File.expand_path(__dir__)}"
|
|
14
|
+
))
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
//! Private native entry point.
|
|
2
|
+
use crate::{CAPACITY, STATUS, Tracker, status};
|
|
3
|
+
use magnus::{Error, Ruby, function, method, prelude::*};
|
|
4
|
+
use matryona_machines::ruby::Class;
|
|
5
|
+
|
|
6
|
+
#[magnus::init]
|
|
7
|
+
fn init(ruby: &Ruby) -> Result<(), Error> {
|
|
8
|
+
let module = ruby.define_module("OffsetMachines")?;
|
|
9
|
+
module.const_set("CAPACITY", CAPACITY)?;
|
|
10
|
+
STATUS.set(ruby, Class::resolve(ruby, module, "Status")?)?;
|
|
11
|
+
module.define_singleton_method("__status", function!(status, 5))?;
|
|
12
|
+
let class = module.define_class("Tracker", ruby.class_object())?;
|
|
13
|
+
class.undef_default_alloc_func();
|
|
14
|
+
class.define_singleton_method("new", function!(Tracker::new, 0))?;
|
|
15
|
+
class.define_singleton_method("assigned", function!(Tracker::assigned, 2))?;
|
|
16
|
+
class.define_method("assign", method!(Tracker::assign, 2))?;
|
|
17
|
+
class.define_method("reassign", method!(Tracker::reassign, 1))?;
|
|
18
|
+
class.define_method("ack", method!(Tracker::ack, 2))?;
|
|
19
|
+
class.define_method("mark_committed", method!(Tracker::mark_committed, 2))?;
|
|
20
|
+
class.define_method("acked?", method!(Tracker::is_acked, 1))?;
|
|
21
|
+
class.define_method("commit_candidate", method!(Tracker::commit_candidate, 0))?;
|
|
22
|
+
class.define_method("frontier", method!(Tracker::frontier, 0))?;
|
|
23
|
+
class.define_method("gaps", method!(Tracker::gaps, 2))?;
|
|
24
|
+
class.define_method("generation", method!(Tracker::generation, 0))?;
|
|
25
|
+
class.define_method("base", method!(Tracker::base, 0))?;
|
|
26
|
+
class.define_method("acked", method!(Tracker::acked, 0))?;
|
|
27
|
+
class.define_method("status", method!(Tracker::status, 0))?;
|
|
28
|
+
class.define_method("capacity", function!(Tracker::capacity, 0))?;
|
|
29
|
+
// `new` and `assigned` answer a Tracker: its class is fixed now, so no
|
|
30
|
+
// conversion runs `Object.const_get` later.
|
|
31
|
+
Class::pin_wrapped::<Tracker>(ruby, class).map(drop)
|
|
32
|
+
}
|