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,277 @@
1
+ //! Reader and checkpoint retention pins.
2
+ use offset_machines::Tracker;
3
+ use periscope_machines::scope_of;
4
+
5
+ use crate::{Journal, Refusal};
6
+
7
+ /// What a pin stands for.
8
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
9
+ pub enum PinKind {
10
+ /// A reader positioned at the pinned offset.
11
+ Reader,
12
+ /// Recovery replays from the pinned offset.
13
+ Checkpoint,
14
+ }
15
+
16
+ /// Handle to one pin acquisition. A released pin's handle never names a pin
17
+ /// again.
18
+ ///
19
+ /// A pin means something only to the journal that issued it. Its generation
20
+ /// carries that journal's scope, so a journal of another scope refuses it;
21
+ /// two journals left in the same scope cannot tell each other's pins apart.
22
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
23
+ pub struct Pin {
24
+ pub(crate) slot: usize,
25
+ pub(crate) generation: u64,
26
+ pub(crate) kind: PinKind,
27
+ }
28
+
29
+ impl Pin {
30
+ /// Reader or checkpoint.
31
+ #[must_use]
32
+ pub const fn kind(self) -> PinKind {
33
+ self.kind
34
+ }
35
+
36
+ /// Journal-issued acquisition generation, unique per journal and never
37
+ /// reissued: the journal's scope above a number of the one sequence its
38
+ /// segment ids and attempts are drawn from too.
39
+ #[must_use]
40
+ pub const fn generation(self) -> u64 {
41
+ self.generation
42
+ }
43
+
44
+ /// The scope of the journal that issued this pin, see
45
+ /// [`Journal::with_scope`].
46
+ #[must_use]
47
+ pub const fn scope(self) -> u16 {
48
+ scope_of(self.generation)
49
+ }
50
+ }
51
+
52
+ /// Honoured outcome of [`Journal::advance`].
53
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
54
+ pub enum Advanced {
55
+ /// The reader pin moved forward.
56
+ Moved,
57
+ /// Idempotent repeat: the pin already sits at that offset. Nothing changed.
58
+ Unchanged,
59
+ }
60
+
61
+ /// Honoured outcome of [`Journal::checkpoint`] and [`Journal::checkpoint_from`].
62
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
63
+ pub enum Checkpointed {
64
+ /// The same assignment generation moved the pin forward.
65
+ Advanced,
66
+ /// A newer assignment generation took over the checkpoint at its own offset.
67
+ Reassigned,
68
+ /// Idempotent repeat: the same assignment generation reported the offset
69
+ /// the pin already sits at. Nothing changed.
70
+ Unchanged,
71
+ }
72
+
73
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
74
+ pub struct PinSlot {
75
+ pub generation: u64,
76
+ pub kind: PinKind,
77
+ pub offset: u64,
78
+ pub assignment: u64,
79
+ }
80
+
81
+ impl<const SEGMENTS: usize, const PINS: usize> Journal<SEGMENTS, PINS> {
82
+ /// Retain every offset at or after `offset` for a reader.
83
+ ///
84
+ /// # Errors
85
+ /// [`Refusal::PinsFull`] or [`Refusal::Exhausted`]; nothing is pinned.
86
+ pub fn pin_reader(&mut self, offset: u64) -> Result<Pin, Refusal> {
87
+ self.acquire(PinKind::Reader, offset, 0)
88
+ }
89
+
90
+ /// Retain every offset at or after `offset` for recovery, on behalf of
91
+ /// the consumer assignment generation `assignment`.
92
+ ///
93
+ /// # Errors
94
+ /// [`Refusal::Unassigned`] for generation zero, otherwise as
95
+ /// [`Journal::pin_reader`].
96
+ pub fn pin_checkpoint(&mut self, assignment: u64, offset: u64) -> Result<Pin, Refusal> {
97
+ if assignment == 0 {
98
+ return Err(Refusal::Unassigned);
99
+ }
100
+ self.acquire(PinKind::Checkpoint, offset, assignment)
101
+ }
102
+
103
+ /// Pin a checkpoint at a tracker's confirmed-committed base, under its
104
+ /// assignment generation. Acknowledged but unconfirmed offsets stay retained.
105
+ ///
106
+ /// # Errors
107
+ /// As [`Journal::pin_checkpoint`]; an unassigned tracker is `Unassigned`.
108
+ pub fn pin_checkpoint_from<const WORDS: usize>(
109
+ &mut self,
110
+ tracker: &Tracker<WORDS>,
111
+ ) -> Result<Pin, Refusal> {
112
+ self.pin_checkpoint(tracker.generation(), tracker.base())
113
+ }
114
+
115
+ /// Move a reader pin forward. The offset the pin already sits at is an
116
+ /// idempotent repeat: [`Advanced::Unchanged`].
117
+ ///
118
+ /// # Errors
119
+ /// [`Refusal::Stale`] (a pin that is not held, or one of another scope),
120
+ /// [`Refusal::WrongKind`] or [`Refusal::Regressed`]; the pin stays where
121
+ /// it was.
122
+ pub fn advance(&mut self, pin: Pin, offset: u64) -> Result<Advanced, Refusal> {
123
+ let held = self.held_mut(pin).ok_or(Refusal::Stale)?;
124
+ if held.kind != PinKind::Reader {
125
+ return Err(Refusal::WrongKind);
126
+ }
127
+ if !forward(held.offset, offset)? {
128
+ return Ok(Advanced::Unchanged);
129
+ }
130
+ held.offset = offset;
131
+ Ok(Advanced::Moved)
132
+ }
133
+
134
+ /// Move a checkpoint pin to `offset` as confirmed under `assignment`.
135
+ ///
136
+ /// The same assignment generation only moves forward. A newer one takes
137
+ /// over at whatever offset it reports, even a lower one; an older one is
138
+ /// refused, so a fenced consumer cannot loosen retention. The same
139
+ /// generation at the offset the pin already sits at is an idempotent
140
+ /// repeat: [`Checkpointed::Unchanged`].
141
+ ///
142
+ /// # Errors
143
+ /// [`Refusal::Stale`], [`Refusal::WrongKind`], [`Refusal::Unassigned`],
144
+ /// [`Refusal::StaleAssignment`] or [`Refusal::Regressed`]; the pin stays
145
+ /// where it was.
146
+ pub fn checkpoint(
147
+ &mut self,
148
+ pin: Pin,
149
+ assignment: u64,
150
+ offset: u64,
151
+ ) -> Result<Checkpointed, Refusal> {
152
+ let held = self.held_mut(pin).ok_or(Refusal::Stale)?;
153
+ if held.kind != PinKind::Checkpoint {
154
+ return Err(Refusal::WrongKind);
155
+ }
156
+ if assignment == 0 {
157
+ return Err(Refusal::Unassigned);
158
+ }
159
+ if assignment < held.assignment {
160
+ return Err(Refusal::StaleAssignment);
161
+ }
162
+ if assignment > held.assignment {
163
+ held.assignment = assignment;
164
+ held.offset = offset;
165
+ return Ok(Checkpointed::Reassigned);
166
+ }
167
+ if !forward(held.offset, offset)? {
168
+ return Ok(Checkpointed::Unchanged);
169
+ }
170
+ held.offset = offset;
171
+ Ok(Checkpointed::Advanced)
172
+ }
173
+
174
+ /// Move a checkpoint pin to a tracker's confirmed-committed base.
175
+ ///
176
+ /// # Errors
177
+ /// As [`Journal::checkpoint`]; an unassigned tracker is `Unassigned`.
178
+ pub fn checkpoint_from<const WORDS: usize>(
179
+ &mut self,
180
+ pin: Pin,
181
+ tracker: &Tracker<WORDS>,
182
+ ) -> Result<Checkpointed, Refusal> {
183
+ self.checkpoint(pin, tracker.generation(), tracker.base())
184
+ }
185
+
186
+ /// Drop a pin. Only the handle of the current acquisition releases it.
187
+ ///
188
+ /// A second release is not an honoured repeat, because the journal cannot
189
+ /// prove it. Pin generations share one sequence with segment ids and
190
+ /// attempts, so "issued here and held in no slot" is as true of a segment
191
+ /// id as of a released pin, and the journal keeps no record of which
192
+ /// identities were pins or of the pins it released.
193
+ ///
194
+ /// # Errors
195
+ /// [`Refusal::Stale`] for a pin that is not held: released already, never
196
+ /// issued here (another scope, or a generation not reached), or held in
197
+ /// another slot than the one the handle names. Nothing was released, and
198
+ /// whoever holds the slot keeps it.
199
+ pub fn release(&mut self, pin: Pin) -> Result<(), Refusal> {
200
+ *self.held_entry(pin).ok_or(Refusal::Stale)? = None;
201
+ Ok(())
202
+ }
203
+
204
+ /// Offset a live pin retains from; `None` for a stale handle or one of
205
+ /// another scope.
206
+ #[must_use]
207
+ pub fn pin_offset(&self, pin: Pin) -> Option<u64> {
208
+ if !self.issuer.owns(pin.generation) {
209
+ return None;
210
+ }
211
+ self.pins
212
+ .get(pin.slot)
213
+ .copied()
214
+ .flatten()
215
+ .filter(|held| held.generation == pin.generation)
216
+ .map(|held| held.offset)
217
+ }
218
+
219
+ /// Lowest retained offset across all pins; `None` when nothing is pinned.
220
+ #[must_use]
221
+ pub fn low_pin(&self) -> Option<u64> {
222
+ self.pins.iter().flatten().map(|held| held.offset).min()
223
+ }
224
+
225
+ /// Number of pins currently held.
226
+ #[must_use]
227
+ pub fn pins(&self) -> usize {
228
+ self.pins.iter().flatten().count()
229
+ }
230
+
231
+ fn acquire(&mut self, kind: PinKind, offset: u64, assignment: u64) -> Result<Pin, Refusal> {
232
+ let (slot, entry) = self
233
+ .pins
234
+ .iter_mut()
235
+ .enumerate()
236
+ .find(|(_, entry)| entry.is_none())
237
+ .ok_or(Refusal::PinsFull)?;
238
+ let generation = self.issuer.issue()?;
239
+ *entry = Some(PinSlot {
240
+ generation,
241
+ kind,
242
+ offset,
243
+ assignment,
244
+ });
245
+ Ok(Pin {
246
+ slot,
247
+ generation,
248
+ kind,
249
+ })
250
+ }
251
+
252
+ /// The slot holding `pin`'s acquisition. A pin this journal never
253
+ /// issued, of another scope or not yet reached, names nothing here: no
254
+ /// slot is read.
255
+ fn held_entry(&mut self, pin: Pin) -> Option<&mut Option<PinSlot>> {
256
+ if !self.issuer.owns(pin.generation) {
257
+ return None;
258
+ }
259
+ self.pins
260
+ .get_mut(pin.slot)
261
+ .filter(|entry| entry.is_some_and(|held| held.generation == pin.generation))
262
+ }
263
+
264
+ fn held_mut(&mut self, pin: Pin) -> Option<&mut PinSlot> {
265
+ self.held_entry(pin)?.as_mut()
266
+ }
267
+ }
268
+
269
+ /// Whether moving a pin held at `held` to `offset` moves it forward; `false`
270
+ /// when it already sits there.
271
+ const fn forward(held: u64, offset: u64) -> Result<bool, Refusal> {
272
+ if offset < held {
273
+ Err(Refusal::Regressed)
274
+ } else {
275
+ Ok(offset > held)
276
+ }
277
+ }
@@ -0,0 +1,95 @@
1
+ //! Roll and compaction thresholds.
2
+ use core::{num::NonZeroU64, time::Duration};
3
+
4
+ /// The whole of a per-mille ratio: every stored record dead.
5
+ const PER_MILLE: u16 = 1000;
6
+
7
+ /// Why the active segment is due to roll. Checked in this order.
8
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
9
+ pub enum RollReason {
10
+ /// The observed byte size reached `max_bytes`.
11
+ Size,
12
+ /// The observed record count reached `max_records`.
13
+ Records,
14
+ /// The observed age reached `max_age`.
15
+ Age,
16
+ }
17
+
18
+ /// Roll thresholds and the dead-record ratio that makes a segment worth
19
+ /// compacting. A `None` threshold never triggers.
20
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
21
+ pub struct Policy {
22
+ max_bytes: Option<NonZeroU64>,
23
+ max_records: Option<NonZeroU64>,
24
+ max_age: Option<Duration>,
25
+ min_dead_per_mille: u16,
26
+ }
27
+
28
+ impl Policy {
29
+ /// Build a policy; `None` when `min_dead_per_mille` exceeds 1000 or
30
+ /// `max_age` is a zero span (disable a threshold with `None`, not zero).
31
+ ///
32
+ /// `max_age` is a span of the same monotonic clock that supplies `now`.
33
+ #[must_use]
34
+ pub const fn new(
35
+ max_bytes: Option<NonZeroU64>,
36
+ max_records: Option<NonZeroU64>,
37
+ max_age: Option<Duration>,
38
+ min_dead_per_mille: u16,
39
+ ) -> Option<Self> {
40
+ if min_dead_per_mille > PER_MILLE || matches!(max_age, Some(age) if age.is_zero()) {
41
+ return None;
42
+ }
43
+ Some(Self {
44
+ max_bytes,
45
+ max_records,
46
+ max_age,
47
+ min_dead_per_mille,
48
+ })
49
+ }
50
+
51
+ /// Byte size at which the active segment is due.
52
+ #[must_use]
53
+ pub const fn max_bytes(&self) -> Option<NonZeroU64> {
54
+ self.max_bytes
55
+ }
56
+
57
+ /// Record count at which the active segment is due.
58
+ #[must_use]
59
+ pub const fn max_records(&self) -> Option<NonZeroU64> {
60
+ self.max_records
61
+ }
62
+
63
+ /// Age at which a non-empty active segment is due.
64
+ #[must_use]
65
+ pub const fn max_age(&self) -> Option<Duration> {
66
+ self.max_age
67
+ }
68
+
69
+ /// Dead records per thousand stored records that make a compaction candidate.
70
+ #[must_use]
71
+ pub const fn min_dead_per_mille(&self) -> u16 {
72
+ self.min_dead_per_mille
73
+ }
74
+
75
+ pub(crate) fn due(&self, bytes: u64, records: u64, age: Duration) -> Option<RollReason> {
76
+ let reached = |limit: Option<NonZeroU64>, seen: u64| limit.is_some_and(|l| seen >= l.get());
77
+ if reached(self.max_bytes, bytes) {
78
+ Some(RollReason::Size)
79
+ } else if reached(self.max_records, records) {
80
+ Some(RollReason::Records)
81
+ } else if self.max_age.is_some_and(|limit| age >= limit) {
82
+ Some(RollReason::Age)
83
+ } else {
84
+ None
85
+ }
86
+ }
87
+
88
+ /// At least one dead record, and the dead share meets the threshold.
89
+ pub(crate) fn compactable(&self, stored: u64, live: u64) -> bool {
90
+ let dead = stored.saturating_sub(live);
91
+ dead > 0
92
+ && u128::from(dead) * u128::from(PER_MILLE)
93
+ >= u128::from(stored) * u128::from(self.min_dead_per_mille)
94
+ }
95
+ }
@@ -0,0 +1,105 @@
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 journal exactly as
5
+ /// it was; no operation reports "not honoured" any other way.
6
+ ///
7
+ /// An idempotent repeat the journal can prove is not a refusal: moving a
8
+ /// pin to where it already sits or confirming an attempt again with the same
9
+ /// payload is honoured as [`Advanced::Unchanged`](crate::Advanced),
10
+ /// [`Checkpointed::Unchanged`](crate::Checkpointed) or
11
+ /// [`Confirmed::AlreadyDurable`](crate::Confirmed). A repeat it cannot prove
12
+ /// is refused: a second `release`, `reclaim` or `abort` is
13
+ /// [`Refusal::Stale`], because the journal keeps neither the pins it released
14
+ /// nor how an attempt ended.
15
+ ///
16
+ /// Every identity the journal issues carries its scope and a number of its
17
+ /// one sequence. One it never issued, of another scope or not yet reached,
18
+ /// names nothing here and is refused before anything is looked up: a segment
19
+ /// id is [`Refusal::Unknown`], a pin or a replacement is [`Refusal::Stale`].
20
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
21
+ pub enum Refusal {
22
+ /// The journal has no active segment (zero segment capacity).
23
+ NoActive,
24
+ /// An empty active segment cannot be sealed.
25
+ Empty,
26
+ /// `now` is earlier than the active segment's opening time.
27
+ TimeRegression,
28
+ /// The offset range would pass `u64::MAX`.
29
+ Overflow,
30
+ /// Every segment slot is taken; reclaim before rolling.
31
+ SegmentsFull,
32
+ /// Every pin slot is held; release before pinning.
33
+ PinsFull,
34
+ /// The journal's identity sequence is spent: a scope holds 2^48 - 1
35
+ /// segment ids, pin generations and replacement attempts together.
36
+ Exhausted,
37
+ /// No such segment, which includes an identity of another scope.
38
+ Unknown,
39
+ /// The segment is the active one, still being written.
40
+ Active,
41
+ /// The segment already has a replacement in flight.
42
+ Busy,
43
+ /// More live records than the segment stores.
44
+ Exceeds,
45
+ /// The attempt is already confirmed durable with a different payload
46
+ /// than this call carries; the recorded confirmation stands.
47
+ Mismatch,
48
+ /// The handle is not current: a pin that is not held (a released one
49
+ /// included), a replacement that is not the segment's current attempt, or
50
+ /// a handle this journal never issued.
51
+ Stale,
52
+ /// A reader call on a checkpoint pin, or the reverse.
53
+ WrongKind,
54
+ /// Assignment generation zero is never a valid checkpoint source.
55
+ Unassigned,
56
+ /// The assignment generation is older than the one the checkpoint holds.
57
+ StaleAssignment,
58
+ /// The offset is behind the pin; pins never move back within a generation.
59
+ Regressed,
60
+ /// The replacement has not been confirmed durable.
61
+ NotDurable,
62
+ /// A pin still retains part of the segment.
63
+ Pinned {
64
+ /// Lowest pinned offset across all pins.
65
+ offset: u64,
66
+ },
67
+ }
68
+
69
+ impl fmt::Display for Refusal {
70
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
71
+ f.write_str(match self {
72
+ Self::NoActive => "the journal has no active segment",
73
+ Self::Empty => "an empty segment cannot be sealed",
74
+ Self::TimeRegression => "time is earlier than the active segment's opening",
75
+ Self::Overflow => "the offset range would overflow",
76
+ Self::SegmentsFull => "every segment slot is in use",
77
+ Self::PinsFull => "every pin slot is in use",
78
+ Self::Exhausted => "identity space exhausted",
79
+ Self::Unknown => "no such segment",
80
+ Self::Active => "the segment is still being written",
81
+ Self::Busy => "the segment already has a replacement in flight",
82
+ Self::Exceeds => "more live records than the segment stores",
83
+ Self::Mismatch => "the attempt is already durable with a different payload",
84
+ Self::Stale => "the handle is not current",
85
+ Self::WrongKind => "the pin is of the other kind",
86
+ Self::Unassigned => "assignment generation zero is not an assignment",
87
+ Self::StaleAssignment => "the assignment generation is older than the pin's",
88
+ Self::Regressed => "the offset is behind the pin",
89
+ Self::NotDurable => "the replacement is not confirmed durable",
90
+ Self::Pinned { .. } => "a pin still retains part of the segment",
91
+ })
92
+ }
93
+ }
94
+
95
+ impl core::error::Error for Refusal {}
96
+
97
+ /// The journal's identity sequence refused to issue: its one refusal is
98
+ /// [`Refusal::Exhausted`].
99
+ impl From<periscope_machines::Refusal> for Refusal {
100
+ fn from(refusal: periscope_machines::Refusal) -> Self {
101
+ match refusal {
102
+ periscope_machines::Refusal::Exhausted => Self::Exhausted,
103
+ }
104
+ }
105
+ }