handoff_machines 0.8.3

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,437 @@
1
+ use core::{cmp::Ordering, num::NonZeroU64, time::Duration};
2
+
3
+ use lease_machines::FencingToken;
4
+ use offset_machines::{Ack, Commit, Tracker};
5
+
6
+ use crate::{Action, Phase, Recipient, Refusal, Status, Ticket};
7
+
8
+ /// What the transfer waits for next. Each step carries what its order
9
+ /// restates, so no step can stand without it.
10
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
11
+ pub enum Step {
12
+ Quiesce,
13
+ Drain {
14
+ until: u64,
15
+ },
16
+ Capture {
17
+ at: u64,
18
+ },
19
+ Install {
20
+ checkpoint: u64,
21
+ },
22
+ Fence,
23
+ Activate {
24
+ token: FencingToken,
25
+ },
26
+ Rollback {
27
+ resume: bool,
28
+ discard: bool,
29
+ token: Option<FencingToken>,
30
+ },
31
+ }
32
+
33
+ /// Result of an honoured acknowledgement.
34
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
35
+ pub enum Next {
36
+ /// Idempotent repeat; nothing was recorded and nothing changed.
37
+ Repeat,
38
+ /// Recorded; the transfer waits for the same thing.
39
+ Same,
40
+ /// The transfer waits for something new.
41
+ Moved,
42
+ /// The transfer ended; free its slot.
43
+ Done(Phase),
44
+ }
45
+
46
+ #[derive(Debug, Clone, PartialEq, Eq)]
47
+ pub struct Transfer<const WORDS: usize> {
48
+ pub ticket: Ticket,
49
+ pub source: u64,
50
+ pub target: u64,
51
+ pub deadline: Duration,
52
+ source_token: FencingToken,
53
+ step: Step,
54
+ until: Option<u64>,
55
+ checkpoint: Option<u64>,
56
+ token: Option<FencingToken>,
57
+ installed: bool,
58
+ tracker: Tracker<WORDS>,
59
+ }
60
+
61
+ /// Whether `token` may supersede `floor`, the newest token the transfer knows:
62
+ /// `StaleToken` unless it exceeds it.
63
+ ///
64
+ /// Both are of the transfer's one token scope: `token` passed
65
+ /// [`Transfer::homed`], and `floor` is the source token or the activation
66
+ /// token `fenced` admitted. The ranking is the token's own, which never orders
67
+ /// tokens across scopes: tokens of two scopes are `Unknown` here too, the
68
+ /// answer `homed` already gave, so no raw value is compared without its scope.
69
+ const fn supersedes(token: FencingToken, floor: FencingToken) -> Result<(), Refusal> {
70
+ match token.order(floor) {
71
+ Some(Ordering::Greater) => Ok(()),
72
+ Some(Ordering::Less | Ordering::Equal) => Err(Refusal::StaleToken),
73
+ None => Err(Refusal::Unknown),
74
+ }
75
+ }
76
+
77
+ /// The drain tracker's one generation. The tracker belongs to one transfer
78
+ /// and never meets another assignment: the ticket is checked before the
79
+ /// tracker is reached, so the tracker needs no generation of its own beyond
80
+ /// being assigned, and [`Tracker::assigned`] builds it so without a refusal.
81
+ const DRAIN: NonZeroU64 = NonZeroU64::MIN;
82
+
83
+ /// The answer for a drain-tracker refusal the transfer rules out: the tracker
84
+ /// is assigned at construction and only ever asked under its own current
85
+ /// generation, so `Stale` cannot come back; it is only asked to acknowledge
86
+ /// or confirm, so `Exhausted` cannot either, and `ack` never answers
87
+ /// `Unacked` nor `mark_committed` `OutOfWindow`. The tracker's one `Refusal`
88
+ /// type still names them. Refused as `OutOfPhase`, the most conservative
89
+ /// answer; the tracker refused, so nothing changed.
90
+ fn untracked() -> Refusal {
91
+ debug_assert!(
92
+ false,
93
+ "the drain tracker is asked only under its current generation"
94
+ );
95
+ Refusal::OutOfPhase
96
+ }
97
+
98
+ /// Answer to an acknowledgement the transfer already recorded: an idempotent
99
+ /// repeat when the same holder states the same payload, a refusal otherwise.
100
+ const fn replay(holder: bool, same: bool) -> Result<Next, Refusal> {
101
+ if !holder {
102
+ Err(Refusal::WrongReplica)
103
+ } else if same {
104
+ Ok(Next::Repeat)
105
+ } else {
106
+ Err(Refusal::Mismatch)
107
+ }
108
+ }
109
+
110
+ impl<const WORDS: usize> Transfer<WORDS> {
111
+ pub const fn new(
112
+ ticket: Ticket,
113
+ source: u64,
114
+ target: u64,
115
+ base: u64,
116
+ source_token: FencingToken,
117
+ deadline: Duration,
118
+ ) -> Self {
119
+ Self {
120
+ ticket,
121
+ source,
122
+ target,
123
+ deadline,
124
+ source_token,
125
+ step: Step::Quiesce,
126
+ until: None,
127
+ checkpoint: None,
128
+ token: None,
129
+ installed: false,
130
+ tracker: Tracker::assigned(DRAIN, base),
131
+ }
132
+ }
133
+
134
+ pub const fn involves(&self, replica: u64) -> bool {
135
+ self.source == replica || self.target == replica
136
+ }
137
+
138
+ pub const fn phase(&self) -> Phase {
139
+ match self.step {
140
+ Step::Quiesce => Phase::Quiesce,
141
+ Step::Drain { .. } => Phase::Drain,
142
+ Step::Capture { .. } | Step::Install { .. } => Phase::Checkpoint,
143
+ Step::Fence | Step::Activate { .. } => Phase::Activate,
144
+ Step::Rollback { .. } => Phase::Rollback,
145
+ }
146
+ }
147
+
148
+ pub const fn status(&self) -> Status {
149
+ Status {
150
+ ticket: self.ticket,
151
+ source: self.source,
152
+ target: self.target,
153
+ phase: self.phase(),
154
+ base: self.tracker.base(),
155
+ until: self.until,
156
+ checkpoint: self.checkpoint,
157
+ token: self.token,
158
+ deadline: self.deadline,
159
+ }
160
+ }
161
+
162
+ /// The order restated at `part` (0 or 1) of this transfer's slot.
163
+ pub const fn order(&self, part: usize) -> Option<(Recipient, Action)> {
164
+ let source = Recipient::Replica(self.source);
165
+ let target = Recipient::Replica(self.target);
166
+ let (first, second) = match self.step {
167
+ Step::Quiesce => (Some((source, Action::Quiesce)), None),
168
+ Step::Drain { until } => (Some((source, Action::Drain { until })), None),
169
+ Step::Capture { at } => (Some((source, Action::Capture { at })), None),
170
+ Step::Install { checkpoint } => (Some((target, Action::Install { checkpoint })), None),
171
+ Step::Fence => {
172
+ let above = self.source_token;
173
+ (Some((Recipient::Authority, Action::Fence { above })), None)
174
+ }
175
+ Step::Activate { token } => (Some((target, Action::Activate { token })), None),
176
+ Step::Rollback {
177
+ resume,
178
+ discard,
179
+ token,
180
+ } => (
181
+ if resume {
182
+ Some((source, Action::Resume { token }))
183
+ } else {
184
+ None
185
+ },
186
+ if discard {
187
+ Some((target, Action::Discard))
188
+ } else {
189
+ None
190
+ },
191
+ ),
192
+ };
193
+ match part {
194
+ 0 => first,
195
+ 1 => second,
196
+ _ => None,
197
+ }
198
+ }
199
+
200
+ /// Bounds of the still-unacknowledged drain: tracker and quiesce point.
201
+ pub const fn draining(&self) -> Option<(&Tracker<WORDS>, u64)> {
202
+ match self.step {
203
+ Step::Drain { until } => Some((&self.tracker, until)),
204
+ Step::Quiesce
205
+ | Step::Capture { .. }
206
+ | Step::Install { .. }
207
+ | Step::Fence
208
+ | Step::Activate { .. }
209
+ | Step::Rollback { .. } => None,
210
+ }
211
+ }
212
+
213
+ const fn draining_now(&self) -> bool {
214
+ self.draining().is_some()
215
+ }
216
+
217
+ /// A token of another scope than the source token's names nothing in
218
+ /// this transfer: `Unknown`, answered before the step or any recorded
219
+ /// token is read. Every token the transfer records has passed this, so
220
+ /// the source token's scope is the transfer's one token scope.
221
+ const fn homed(&self, token: FencingToken) -> Result<(), Refusal> {
222
+ if token.scope() == self.source_token.scope() {
223
+ Ok(())
224
+ } else {
225
+ Err(Refusal::Unknown)
226
+ }
227
+ }
228
+
229
+ /// `OutOfPhase` unless the transfer is `waiting` for this, then
230
+ /// `WrongReplica` unless `replica` is the `holder`.
231
+ const fn expect(waiting: bool, replica: u64, holder: u64) -> Result<(), Refusal> {
232
+ if !waiting {
233
+ Err(Refusal::OutOfPhase)
234
+ } else if replica != holder {
235
+ Err(Refusal::WrongReplica)
236
+ } else {
237
+ Ok(())
238
+ }
239
+ }
240
+
241
+ pub fn quiesced(&mut self, replica: u64, until: u64) -> Result<Next, Refusal> {
242
+ if let Some(recorded) = self.until {
243
+ return replay(replica == self.source, recorded == until);
244
+ }
245
+ Self::expect(matches!(self.step, Step::Quiesce), replica, self.source)?;
246
+ if until < self.tracker.base() {
247
+ return Err(Refusal::BehindBase);
248
+ }
249
+ self.until = Some(until);
250
+ self.step = if until == self.tracker.base() {
251
+ Step::Capture { at: until }
252
+ } else {
253
+ Step::Drain { until }
254
+ };
255
+ Ok(Next::Moved)
256
+ }
257
+
258
+ pub fn drained(&mut self, replica: u64, offset: u64) -> Result<Next, Refusal> {
259
+ let until = self.until.ok_or(Refusal::OutOfPhase)?;
260
+ if replica != self.source {
261
+ return Err(Refusal::WrongReplica);
262
+ }
263
+ if offset >= until {
264
+ return Err(Refusal::BeyondDrain);
265
+ }
266
+ if !self.draining_now() {
267
+ // The drain is over or was given up: only what it recorded repeats.
268
+ return if self.tracker.is_acked(offset) {
269
+ Ok(Next::Repeat)
270
+ } else {
271
+ Err(Refusal::OutOfPhase)
272
+ };
273
+ }
274
+ match self.tracker.ack(DRAIN.get(), offset) {
275
+ Ok(Ack::Duplicate) => return Ok(Next::Repeat),
276
+ Ok(Ack::Recorded) => {}
277
+ Err(offset_machines::Refusal::OutOfWindow) => return Err(Refusal::OutOfWindow),
278
+ Err(
279
+ offset_machines::Refusal::Stale
280
+ | offset_machines::Refusal::Unacked
281
+ | offset_machines::Refusal::Exhausted,
282
+ ) => return Err(untracked()),
283
+ }
284
+ let reached = self
285
+ .tracker
286
+ .commit_candidate()
287
+ .unwrap_or_else(|| self.tracker.base());
288
+ if reached < until {
289
+ return Ok(Next::Same);
290
+ }
291
+ self.step = Step::Capture { at: until };
292
+ Ok(Next::Moved)
293
+ }
294
+
295
+ pub fn committed(&mut self, replica: u64, offset: u64) -> Result<Next, Refusal> {
296
+ if self.until.is_none() {
297
+ return Err(Refusal::OutOfPhase);
298
+ }
299
+ if replica != self.source {
300
+ return Err(Refusal::WrongReplica);
301
+ }
302
+ if !self.draining_now() {
303
+ return if offset <= self.tracker.base() {
304
+ Ok(Next::Repeat)
305
+ } else {
306
+ Err(Refusal::OutOfPhase)
307
+ };
308
+ }
309
+ match self.tracker.mark_committed(DRAIN.get(), offset) {
310
+ Ok(Commit::Duplicate) => Ok(Next::Repeat),
311
+ Ok(Commit::Advanced) => Ok(Next::Same),
312
+ Err(offset_machines::Refusal::Unacked) => Err(Refusal::Unacked),
313
+ Err(
314
+ offset_machines::Refusal::Stale
315
+ | offset_machines::Refusal::OutOfWindow
316
+ | offset_machines::Refusal::Exhausted,
317
+ ) => Err(untracked()),
318
+ }
319
+ }
320
+
321
+ pub fn captured(&mut self, replica: u64, checkpoint: u64) -> Result<Next, Refusal> {
322
+ if let Some(recorded) = self.checkpoint {
323
+ return replay(replica == self.source, recorded == checkpoint);
324
+ }
325
+ let waiting = matches!(self.step, Step::Capture { .. });
326
+ Self::expect(waiting, replica, self.source)?;
327
+ self.checkpoint = Some(checkpoint);
328
+ self.step = Step::Install { checkpoint };
329
+ Ok(Next::Moved)
330
+ }
331
+
332
+ pub fn installed(&mut self, replica: u64, checkpoint: u64) -> Result<Next, Refusal> {
333
+ if self.installed {
334
+ let same = self.checkpoint == Some(checkpoint);
335
+ return replay(replica == self.target, same);
336
+ }
337
+ let waiting = matches!(self.step, Step::Install { .. });
338
+ Self::expect(waiting, replica, self.target)?;
339
+ if self.checkpoint != Some(checkpoint) {
340
+ return Err(Refusal::Mismatch);
341
+ }
342
+ self.installed = true;
343
+ self.step = Step::Fence;
344
+ Ok(Next::Moved)
345
+ }
346
+
347
+ pub fn fenced(&mut self, token: FencingToken) -> Result<Next, Refusal> {
348
+ self.homed(token)?;
349
+ if let Some(recorded) = self.token {
350
+ return replay(true, recorded == token);
351
+ }
352
+ if self.step != Step::Fence {
353
+ return Err(Refusal::OutOfPhase);
354
+ }
355
+ supersedes(token, self.source_token)?;
356
+ self.token = Some(token);
357
+ self.step = Step::Activate { token };
358
+ Ok(Next::Moved)
359
+ }
360
+
361
+ pub fn activated(&self, replica: u64, token: FencingToken) -> Result<Next, Refusal> {
362
+ self.homed(token)?;
363
+ let waiting = matches!(self.step, Step::Activate { .. });
364
+ Self::expect(waiting, replica, self.target)?;
365
+ if self.token != Some(token) {
366
+ return Err(Refusal::Mismatch);
367
+ }
368
+ Ok(Next::Done(Phase::Complete))
369
+ }
370
+
371
+ pub fn abort(&mut self, token: Option<FencingToken>) -> Result<Next, Refusal> {
372
+ if let Some(token) = token {
373
+ self.homed(token)?;
374
+ }
375
+ let discard = match self.step {
376
+ Step::Rollback {
377
+ token: recorded, ..
378
+ } => return replay(true, recorded == token),
379
+ Step::Quiesce | Step::Drain { .. } | Step::Capture { .. } => false,
380
+ Step::Install { .. } | Step::Fence | Step::Activate { .. } => true,
381
+ };
382
+ // The activation token is of the source token's scope: `fenced`
383
+ // admitted it. So the floor always names the transfer's one scope.
384
+ let floor = self.token.unwrap_or(self.source_token);
385
+ if let Some(token) = token {
386
+ supersedes(token, floor)?;
387
+ }
388
+ if token.is_none() && matches!(self.step, Step::Activate { .. }) {
389
+ return Err(Refusal::FenceRequired);
390
+ }
391
+ self.step = Step::Rollback {
392
+ resume: true,
393
+ discard,
394
+ token,
395
+ };
396
+ Ok(Next::Moved)
397
+ }
398
+
399
+ pub const fn resumed(&mut self, replica: u64) -> Result<Next, Refusal> {
400
+ self.undone(replica, self.source, true)
401
+ }
402
+
403
+ pub const fn discarded(&mut self, replica: u64) -> Result<Next, Refusal> {
404
+ self.undone(replica, self.target, false)
405
+ }
406
+
407
+ const fn undone(&mut self, replica: u64, holder: u64, source: bool) -> Result<Next, Refusal> {
408
+ let Step::Rollback {
409
+ resume,
410
+ discard,
411
+ token,
412
+ } = self.step
413
+ else {
414
+ return Err(Refusal::OutOfPhase);
415
+ };
416
+ if replica != holder {
417
+ return Err(Refusal::WrongReplica);
418
+ }
419
+ let (pending, resume, discard) = if source {
420
+ (resume, false, discard)
421
+ } else {
422
+ (discard, resume, false)
423
+ };
424
+ if !pending {
425
+ return Ok(Next::Repeat);
426
+ }
427
+ if !resume && !discard {
428
+ return Ok(Next::Done(Phase::Aborted));
429
+ }
430
+ self.step = Step::Rollback {
431
+ resume,
432
+ discard,
433
+ token,
434
+ };
435
+ Ok(Next::Same)
436
+ }
437
+ }