journal_machines 0.7.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,258 @@
1
+ //! Replacement lifecycle: proposed, durable-confirmed, reclaimed.
2
+ use periscope_machines::scope_of;
3
+
4
+ use crate::{Journal, Phase, Refusal, SegmentId, Slot, locate};
5
+
6
+ /// Handle to one replacement attempt for one sealed segment.
7
+ ///
8
+ /// A handle means something only to the journal that issued it. Its segment
9
+ /// id and its attempt number both carry that journal's scope, so a journal of
10
+ /// another scope refuses it; two journals left in the same scope cannot tell
11
+ /// each other's handles apart.
12
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
13
+ pub struct Replacement {
14
+ pub(crate) segment: SegmentId,
15
+ pub(crate) attempt: u64,
16
+ }
17
+
18
+ impl Replacement {
19
+ /// The segment being replaced.
20
+ #[must_use]
21
+ pub const fn segment(self) -> SegmentId {
22
+ self.segment
23
+ }
24
+
25
+ /// Journal-unique attempt number, never reissued: the journal's scope
26
+ /// above a number of the one sequence its segment ids and pin generations
27
+ /// are drawn from too. A rewrite becomes this revision.
28
+ #[must_use]
29
+ pub const fn attempt(self) -> u64 {
30
+ self.attempt
31
+ }
32
+
33
+ /// The scope of the journal that issued this attempt, see
34
+ /// [`Journal::with_scope`].
35
+ #[must_use]
36
+ pub const fn scope(self) -> u16 {
37
+ scope_of(self.attempt)
38
+ }
39
+ }
40
+
41
+ /// What the caller made durable in place of the original segment.
42
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
43
+ pub enum Durable {
44
+ /// A compacted copy of the same offset range holding only live records.
45
+ Rewritten {
46
+ /// Byte size of the compacted copy.
47
+ bytes: u64,
48
+ /// Records the copy holds.
49
+ live_records: u64,
50
+ },
51
+ /// Something outside the journal (a snapshot, an archive, or nothing for
52
+ /// an all-dead segment) supersedes the range; the segment leaves the journal.
53
+ Superseded,
54
+ }
55
+
56
+ /// Honoured outcome of [`Journal::confirm_durable`].
57
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
58
+ pub enum Confirmed {
59
+ /// The confirmation was recorded; the replacement is now durable.
60
+ Recorded,
61
+ /// Idempotent repeat: this attempt was confirmed before with exactly
62
+ /// this [`Durable`]. Nothing changed.
63
+ AlreadyDurable,
64
+ }
65
+
66
+ /// Permission to delete one original segment file; build one with
67
+ /// [`Reclaimed::new`].
68
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
69
+ pub struct Reclaimed {
70
+ pub(crate) segment: SegmentId,
71
+ pub(crate) revision: u64,
72
+ pub(crate) bytes: u64,
73
+ pub(crate) replaced_by: Option<u64>,
74
+ }
75
+
76
+ impl Reclaimed {
77
+ /// The segment whose original may now be deleted.
78
+ #[must_use]
79
+ pub const fn segment(&self) -> SegmentId {
80
+ self.segment
81
+ }
82
+
83
+ /// Revision of the original to delete.
84
+ #[must_use]
85
+ pub const fn revision(&self) -> u64 {
86
+ self.revision
87
+ }
88
+
89
+ /// Bytes the original occupied.
90
+ #[must_use]
91
+ pub const fn bytes(&self) -> u64 {
92
+ self.bytes
93
+ }
94
+
95
+ /// Revision now serving the range, or `None` when the segment left the journal.
96
+ #[must_use]
97
+ pub const fn replaced_by(&self) -> Option<u64> {
98
+ self.replaced_by
99
+ }
100
+ }
101
+
102
+ impl<const SEGMENTS: usize, const PINS: usize> Journal<SEGMENTS, PINS> {
103
+ /// Open a replacement attempt for a sealed segment.
104
+ ///
105
+ /// # Errors
106
+ /// [`Refusal::Unknown`] (which includes an identity of another scope),
107
+ /// [`Refusal::Active`], [`Refusal::Busy`] or [`Refusal::Exhausted`]; a
108
+ /// refusal changes nothing.
109
+ pub fn propose(&mut self, id: SegmentId) -> Result<Replacement, Refusal> {
110
+ let (_, slot) =
111
+ locate(&self.issuer, &mut self.slots, self.len, id).ok_or(Refusal::Unknown)?;
112
+ match slot.phase {
113
+ Phase::Active => return Err(Refusal::Active),
114
+ Phase::Proposed(_) | Phase::Durable(..) => return Err(Refusal::Busy),
115
+ Phase::Sealed => {}
116
+ }
117
+ let attempt = self.issuer.issue()?;
118
+ slot.phase = Phase::Proposed(attempt);
119
+ Ok(Replacement {
120
+ segment: id,
121
+ attempt,
122
+ })
123
+ }
124
+
125
+ /// Record the caller's confirmation that the replacement is durable.
126
+ /// The journal cannot verify durability; it only refuses to reclaim without it.
127
+ ///
128
+ /// Confirming an attempt that is already durable with the `durable` it
129
+ /// was confirmed with is an idempotent repeat,
130
+ /// [`Confirmed::AlreadyDurable`]. Any other `durable` was never recorded
131
+ /// and is refused: the first confirmation stands.
132
+ ///
133
+ /// # Errors
134
+ /// [`Refusal::Stale`] (not the segment's current attempt, or a handle of
135
+ /// another scope), [`Refusal::Mismatch`] for an attempt already
136
+ /// durable with a different `durable`, or, for a rewrite holding more
137
+ /// records than the original stored, [`Refusal::Exceeds`]; a refusal
138
+ /// changes nothing.
139
+ pub fn confirm_durable(
140
+ &mut self,
141
+ replacement: Replacement,
142
+ durable: Durable,
143
+ ) -> Result<Confirmed, Refusal> {
144
+ let (_, slot) = self.replaced(replacement)?;
145
+ match slot.phase {
146
+ Phase::Proposed(attempt) if attempt == replacement.attempt => {}
147
+ Phase::Durable(attempt, recorded) if attempt == replacement.attempt => {
148
+ return if recorded == durable {
149
+ Ok(Confirmed::AlreadyDurable)
150
+ } else {
151
+ Err(Refusal::Mismatch)
152
+ };
153
+ }
154
+ Phase::Active | Phase::Sealed | Phase::Proposed(_) | Phase::Durable(..) => {
155
+ return Err(Refusal::Stale);
156
+ }
157
+ }
158
+ match durable {
159
+ Durable::Rewritten { live_records, .. } if live_records > slot.stored => {
160
+ return Err(Refusal::Exceeds);
161
+ }
162
+ Durable::Rewritten { .. } | Durable::Superseded => {}
163
+ }
164
+ slot.phase = Phase::Durable(replacement.attempt, durable);
165
+ Ok(Confirmed::Recorded)
166
+ }
167
+
168
+ /// Release the original once its replacement is durable and no pin
169
+ /// retains any of its offsets. Delete the original only after `Ok`.
170
+ ///
171
+ /// # Errors
172
+ /// [`Refusal::Stale`], [`Refusal::NotDurable`] or [`Refusal::Pinned`];
173
+ /// a refusal changes nothing.
174
+ pub fn reclaim(&mut self, replacement: Replacement) -> Result<Reclaimed, Refusal> {
175
+ let low_pin = self.low_pin();
176
+ let (index, slot) = self.replaced(replacement)?;
177
+ let durable = match slot.phase {
178
+ Phase::Durable(attempt, durable) if attempt == replacement.attempt => durable,
179
+ Phase::Proposed(attempt) if attempt == replacement.attempt => {
180
+ return Err(Refusal::NotDurable);
181
+ }
182
+ Phase::Active | Phase::Sealed | Phase::Proposed(_) | Phase::Durable(..) => {
183
+ return Err(Refusal::Stale);
184
+ }
185
+ };
186
+ if let Some(offset) = low_pin
187
+ && offset < slot.end()
188
+ {
189
+ return Err(Refusal::Pinned { offset });
190
+ }
191
+ let mut reclaimed = Reclaimed {
192
+ segment: replacement.segment,
193
+ revision: slot.revision,
194
+ bytes: slot.bytes,
195
+ replaced_by: None,
196
+ };
197
+ match durable {
198
+ Durable::Rewritten {
199
+ bytes,
200
+ live_records,
201
+ } => {
202
+ slot.revision = replacement.attempt;
203
+ slot.bytes = bytes;
204
+ slot.stored = live_records;
205
+ slot.live = slot.live.min(live_records);
206
+ slot.phase = Phase::Sealed;
207
+ reclaimed.replaced_by = Some(replacement.attempt);
208
+ }
209
+ Durable::Superseded => self.remove(index),
210
+ }
211
+ Ok(reclaimed)
212
+ }
213
+
214
+ /// Abandon a proposed or durable replacement; the original stays.
215
+ ///
216
+ /// # Errors
217
+ /// [`Refusal::Stale`]; nothing was abandoned.
218
+ pub fn abort(&mut self, replacement: Replacement) -> Result<(), Refusal> {
219
+ let (_, slot) = self.replaced(replacement)?;
220
+ match slot.phase {
221
+ Phase::Proposed(attempt) | Phase::Durable(attempt, _)
222
+ if attempt == replacement.attempt =>
223
+ {
224
+ slot.phase = Phase::Sealed;
225
+ Ok(())
226
+ }
227
+ Phase::Active | Phase::Sealed | Phase::Proposed(_) | Phase::Durable(..) => {
228
+ Err(Refusal::Stale)
229
+ }
230
+ }
231
+ }
232
+
233
+ /// Slot index and the segment a handle names. A handle whose attempt or
234
+ /// segment this journal never issued, of another scope or not yet
235
+ /// reached, names nothing here: no slot is read.
236
+ fn replaced(&mut self, replacement: Replacement) -> Result<(usize, &mut Slot), Refusal> {
237
+ if !self.issuer.owns(replacement.attempt) {
238
+ return Err(Refusal::Stale);
239
+ }
240
+ self.find_mut(replacement.segment).ok_or(Refusal::Stale)
241
+ }
242
+
243
+ /// Drop the tracked segment at `index`, shifting the later ones down so
244
+ /// the tracked slots stay a prefix.
245
+ /// `index` comes from `locate`, which only answers indices below `len`,
246
+ /// so `len` is at least one and the decrement cannot wrap.
247
+ fn remove(&mut self, index: usize) {
248
+ let mut hole: Option<&mut Option<Slot>> = None;
249
+ for entry in self.slots.iter_mut().take(self.len).skip(index) {
250
+ let moved = entry.take();
251
+ if let Some(previous) = hole {
252
+ *previous = moved;
253
+ }
254
+ hole = Some(entry);
255
+ }
256
+ self.len -= 1;
257
+ }
258
+ }
@@ -0,0 +1,160 @@
1
+ //! The answers about segments: views, roll decisions and recorded rolls.
2
+ use core::time::Duration;
3
+
4
+ use crate::{Replacement, RollReason, SegmentId};
5
+
6
+ /// Where a segment stands.
7
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
8
+ pub enum SegmentState {
9
+ /// The tail segment still being written.
10
+ Active,
11
+ /// Closed, with no replacement in flight.
12
+ Sealed,
13
+ /// A replacement is being built.
14
+ Proposed,
15
+ /// The replacement is confirmed durable, but a pin still retains the original.
16
+ Durable,
17
+ /// The replacement is durable and no pin retains the original.
18
+ Reclaimable,
19
+ }
20
+
21
+ /// Whether any pin retains part of a segment's range.
22
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
23
+ pub enum Retention {
24
+ /// No pin sits below the segment's end; always so while active.
25
+ Unpinned,
26
+ /// A pin sits below the segment's end and retains part of its range.
27
+ Pinned,
28
+ }
29
+
30
+ /// Point-in-time view of one segment's metadata.
31
+ ///
32
+ /// A value exists only when some journal could have answered it: build one
33
+ /// with [`Segment::new`], read it with the accessors.
34
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
35
+ pub struct Segment {
36
+ pub(crate) id: SegmentId,
37
+ pub(crate) revision: u64,
38
+ pub(crate) base_offset: u64,
39
+ pub(crate) records: u64,
40
+ pub(crate) stored_records: u64,
41
+ pub(crate) live_records: u64,
42
+ pub(crate) bytes: u64,
43
+ pub(crate) opened_at: Duration,
44
+ pub(crate) state: SegmentState,
45
+ pub(crate) retention: Retention,
46
+ pub(crate) replacement: Option<Replacement>,
47
+ }
48
+
49
+ impl Segment {
50
+ /// Segment identity.
51
+ #[must_use]
52
+ pub const fn id(&self) -> SegmentId {
53
+ self.id
54
+ }
55
+
56
+ /// Zero for the original file, otherwise the attempt that rewrote it.
57
+ #[must_use]
58
+ pub const fn revision(&self) -> u64 {
59
+ self.revision
60
+ }
61
+
62
+ /// First offset of the range.
63
+ #[must_use]
64
+ pub const fn base_offset(&self) -> u64 {
65
+ self.base_offset
66
+ }
67
+
68
+ /// Offsets in the range; zero while active.
69
+ #[must_use]
70
+ pub const fn records(&self) -> u64 {
71
+ self.records
72
+ }
73
+
74
+ /// Records physically held by the current revision.
75
+ #[must_use]
76
+ pub const fn stored_records(&self) -> u64 {
77
+ self.stored_records
78
+ }
79
+
80
+ /// Records the caller last reported as still live.
81
+ #[must_use]
82
+ pub const fn live_records(&self) -> u64 {
83
+ self.live_records
84
+ }
85
+
86
+ /// Byte size of the current revision; zero while active.
87
+ #[must_use]
88
+ pub const fn bytes(&self) -> u64 {
89
+ self.bytes
90
+ }
91
+
92
+ /// When the segment was opened, on the caller's monotonic clock.
93
+ #[must_use]
94
+ pub const fn opened_at(&self) -> Duration {
95
+ self.opened_at
96
+ }
97
+
98
+ /// Lifecycle state.
99
+ #[must_use]
100
+ pub const fn state(&self) -> SegmentState {
101
+ self.state
102
+ }
103
+
104
+ /// Whether any pin retains part of the range; always
105
+ /// [`Retention::Unpinned`] while active.
106
+ #[must_use]
107
+ pub const fn retention(&self) -> Retention {
108
+ self.retention
109
+ }
110
+
111
+ /// The replacement attempt in flight, if any.
112
+ #[must_use]
113
+ pub const fn replacement(&self) -> Option<Replacement> {
114
+ self.replacement
115
+ }
116
+
117
+ /// One past the last offset of the range.
118
+ #[must_use]
119
+ pub const fn end_offset(&self) -> u64 {
120
+ // Copied from a slot whose `base + span` was checked when it sealed.
121
+ self.base_offset + self.records
122
+ }
123
+ }
124
+
125
+ /// Answer of [`Journal::roll_decision`]./// Answer of [`Journal::roll_decision`].
126
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
127
+ pub enum Roll {
128
+ /// Keep writing to the active segment.
129
+ Keep,
130
+ /// A threshold was reached.
131
+ Due(RollReason),
132
+ }
133
+
134
+ /// A recorded roll; build one with [`Rolled::new`].
135
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
136
+ pub struct Rolled {
137
+ pub(crate) sealed: SegmentId,
138
+ pub(crate) opened: SegmentId,
139
+ pub(crate) next_offset: u64,
140
+ }
141
+
142
+ impl Rolled {
143
+ /// The segment that was sealed.
144
+ #[must_use]
145
+ pub const fn sealed(&self) -> SegmentId {
146
+ self.sealed
147
+ }
148
+
149
+ /// The new active segment.
150
+ #[must_use]
151
+ pub const fn opened(&self) -> SegmentId {
152
+ self.opened
153
+ }
154
+
155
+ /// First offset of the new active segment.
156
+ #[must_use]
157
+ pub const fn next_offset(&self) -> u64 {
158
+ self.next_offset
159
+ }
160
+ }
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'
@@ -0,0 +1,21 @@
1
+ [package]
2
+ name = "journal_machines_native"
3
+ version = "0.1.8"
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
+ journal-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('journal_machines_native/journal_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,98 @@
1
+ //! The binding's answers as the gem's own `Data` values, built from what the
2
+ //! core returned with the classes resolved at init.
3
+ use journal_machines::{
4
+ Reclaimed, Refusal, Retention, Roll, RollReason, Rolled, Segment, SegmentState,
5
+ };
6
+ use magnus::{Error, IntoValue, RClass, Ruby, Value, prelude::*};
7
+ use matryona_machines::ruby::{SymbolNames, Symbols, nanoseconds};
8
+
9
+ use crate::{ReplacementHandle, convert::Refusals};
10
+
11
+ /// The refusal's symbol, or what `build` makes of the honoured answer.
12
+ pub fn reply<T>(
13
+ ruby: &Ruby,
14
+ outcome: Result<T, Refusal>,
15
+ build: impl FnOnce(T) -> Result<Value, Error>,
16
+ ) -> Result<Value, Error> {
17
+ outcome.map_or_else(
18
+ |refusal| Ok(Refusals::symbol(ruby, &refusal).as_value()),
19
+ build,
20
+ )
21
+ }
22
+
23
+ matryona_machines::symbols! {
24
+ /// The core's roll reasons as Symbols, in the order they are checked.
25
+ pub Reasons for RollReason as "reason" {
26
+ Size => "size",
27
+ Records => "records",
28
+ Age => "age",
29
+ }
30
+ }
31
+
32
+ matryona_machines::symbols! {
33
+ /// The core's segment states as Symbols.
34
+ pub States for SegmentState as "state" {
35
+ Active => "active",
36
+ Sealed => "sealed",
37
+ Proposed => "proposed",
38
+ Durable => "durable",
39
+ Reclaimable => "reclaimable",
40
+ }
41
+ }
42
+
43
+ matryona_machines::symbols! {
44
+ /// The core's retentions as Symbols.
45
+ pub Retentions for Retention as "retention" {
46
+ Unpinned => "unpinned",
47
+ Pinned => "pinned",
48
+ }
49
+ }
50
+
51
+ matryona_machines::symbols! {
52
+ /// The core's roll decisions by name: `Keep` answers its Symbol, `Due`
53
+ /// answers a `Due` value instead and its name is never sent.
54
+ pub Rolls for Roll as "roll decision" => names_only {
55
+ Keep => "keep",
56
+ Due(..) => "due",
57
+ }
58
+ }
59
+
60
+ pub fn rolled(class: RClass, rolled: Rolled) -> Result<Value, Error> {
61
+ let fields = (
62
+ rolled.sealed().raw(),
63
+ rolled.opened().raw(),
64
+ rolled.next_offset(),
65
+ );
66
+ class.funcall("new", fields)
67
+ }
68
+
69
+ pub fn reclaimed(class: RClass, reclaimed: Reclaimed) -> Result<Value, Error> {
70
+ let fields = (
71
+ reclaimed.segment().raw(),
72
+ reclaimed.revision(),
73
+ reclaimed.bytes(),
74
+ reclaimed.replaced_by(),
75
+ );
76
+ class.funcall("new", fields)
77
+ }
78
+
79
+ pub fn segment(ruby: &Ruby, class: RClass, segment: Segment) -> Result<Value, Error> {
80
+ let replacement = segment
81
+ .replacement()
82
+ .map(|replacement| ReplacementHandle { replacement });
83
+ let state = States::symbol(ruby, segment.state());
84
+ let fields: [Value; 11] = [
85
+ segment.id().raw().into_value_with(ruby),
86
+ segment.revision().into_value_with(ruby),
87
+ segment.base_offset().into_value_with(ruby),
88
+ segment.records().into_value_with(ruby),
89
+ segment.stored_records().into_value_with(ruby),
90
+ segment.live_records().into_value_with(ruby),
91
+ segment.bytes().into_value_with(ruby),
92
+ nanoseconds(ruby, segment.opened_at()).as_value(),
93
+ state.as_value(),
94
+ Retentions::symbol(ruby, segment.retention()).as_value(),
95
+ replacement.into_value_with(ruby),
96
+ ];
97
+ class.funcall("new", fields)
98
+ }
@@ -0,0 +1,46 @@
1
+ //! The value classes, resolved once at init and pinned. The exact-class
2
+ //! reads and clone-then-keep are `matryona_machines::ruby`'s.
3
+ use magnus::{Error, RClass, RModule, Ruby};
4
+ use matryona_machines::ruby::Class;
5
+
6
+ use crate::{PinHandle, ReplacementHandle};
7
+
8
+ /// The `Data` classes the binding builds and reads.
9
+ pub struct Classes {
10
+ pub policy: Class,
11
+ pub segment: Class,
12
+ pub due: Class,
13
+ pub rolled: Class,
14
+ pub reclaimed: Class,
15
+ pub pin: Class,
16
+ pub replacement: Class,
17
+ }
18
+
19
+ matryona_machines::registry! {
20
+ static CLASSES: Classes = "journal_machines";
21
+ /// The classes resolved at init.
22
+ pub fn classes;
23
+ }
24
+
25
+ /// Resolves the classes `lib/journal_machines.rb` defined before it loaded the
26
+ /// extension and pins the two handle classes init defined, fixing magnus's
27
+ /// class for each handle type to them: no handle conversion runs
28
+ /// `Object.const_get` later. Called once, from init; never by name again.
29
+ pub fn resolve(
30
+ ruby: &Ruby,
31
+ module: RModule,
32
+ pin: RClass,
33
+ replacement: RClass,
34
+ ) -> Result<(), Error> {
35
+ let class = |name| Class::resolve(ruby, module, name);
36
+ let classes = Classes {
37
+ policy: class("Policy")?,
38
+ segment: class("Segment")?,
39
+ due: class("Due")?,
40
+ rolled: class("Rolled")?,
41
+ reclaimed: class("Reclaimed")?,
42
+ pin: Class::pin_wrapped::<PinHandle>(ruby, pin)?,
43
+ replacement: Class::pin_wrapped::<ReplacementHandle>(ruby, replacement)?,
44
+ };
45
+ CLASSES.set(ruby, classes).map(drop)
46
+ }
@@ -0,0 +1,80 @@
1
+ //! Ruby value conversion and refusal names.
2
+ use std::num::NonZeroU64;
3
+
4
+ use journal_machines::{Policy, Refusal};
5
+ use magnus::{Error, Ruby, Symbol, Value};
6
+ use matryona_machines::ruby::{SymbolNames, exact_fields, integer_in, optional_positive, symbol};
7
+
8
+ use crate::classes::classes;
9
+
10
+ /// The core policy for the four `Policy` fields as Ruby passes them. Each is
11
+ /// converted first, in order: a threshold is `nil` or a positive Integer,
12
+ /// the ratio an Integer in `0..=1000`. The core's `Policy::new` then checks
13
+ /// them again (`RangeError` where it answers `None`).
14
+ pub fn policy(
15
+ ruby: &Ruby,
16
+ max_bytes: Value,
17
+ max_records: Value,
18
+ max_age: Value,
19
+ min_dead_per_mille: Value,
20
+ ) -> Result<Policy, Error> {
21
+ let max_bytes = optional_positive::<NonZeroU64>(max_bytes, "max_bytes")?;
22
+ let max_records = optional_positive::<NonZeroU64>(max_records, "max_records")?;
23
+ let max_age = optional_positive::<NonZeroU64>(max_age, "max_age")?
24
+ .map(|age| std::time::Duration::from_nanos(age.get()));
25
+ let per_mille = integer_in(min_dead_per_mille, "min_dead_per_mille", 0..=1000)?;
26
+ Policy::new(max_bytes, max_records, max_age, per_mille).ok_or_else(|| {
27
+ Error::new(
28
+ ruby.exception_range_error(),
29
+ "no journal answers this policy",
30
+ )
31
+ })
32
+ }
33
+
34
+ /// A `Policy` the journal is opened with: exactly a `JournalMachines::Policy`
35
+ /// (`TypeError` otherwise, a subclass included), its four fields read
36
+ /// from the struct and checked again by the core's `Policy::new`
37
+ /// (`RangeError`), so a forged one never reaches the core.
38
+ pub fn policy_from(ruby: &Ruby, value: Value) -> Result<Policy, Error> {
39
+ let class = classes(ruby)?.policy.get(ruby);
40
+ let [max_bytes, max_records, max_age, per_mille] =
41
+ exact_fields::<4>(ruby, value, class, "expected a JournalMachines::Policy")?;
42
+ policy(ruby, max_bytes, max_records, max_age, per_mille)
43
+ }
44
+
45
+ matryona_machines::symbols! {
46
+ /// The core's refusals as Symbols: the snake case of each variant.
47
+ pub Refusals for Refusal as "a refusal" => names_only {
48
+ NoActive => "no_active",
49
+ Empty => "empty",
50
+ TimeRegression => "time_regression",
51
+ Overflow => "overflow",
52
+ SegmentsFull => "segments_full",
53
+ PinsFull => "pins_full",
54
+ Exhausted => "exhausted",
55
+ Unknown => "unknown",
56
+ Active => "active",
57
+ Busy => "busy",
58
+ Exceeds => "exceeds",
59
+ Mismatch => "mismatch",
60
+ Stale => "stale",
61
+ WrongKind => "wrong_kind",
62
+ Unassigned => "unassigned",
63
+ StaleAssignment => "stale_assignment",
64
+ Regressed => "regressed",
65
+ NotDurable => "not_durable",
66
+ Pinned { .. } => "pinned",
67
+ }
68
+ }
69
+
70
+ /// The Ruby symbol for a refusal, or the one `name` gives the honoured answer.
71
+ pub fn answer<T>(
72
+ ruby: &Ruby,
73
+ outcome: Result<T, Refusal>,
74
+ name: impl FnOnce(T) -> &'static str,
75
+ ) -> Symbol {
76
+ symbol(
77
+ ruby,
78
+ outcome.map_or_else(|refusal| Refusals::name(&refusal), name),
79
+ )
80
+ }