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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +113 -0
- data/Cargo.lock +331 -0
- data/Cargo.toml +30 -0
- data/LICENSE.txt +21 -0
- data/README.md +383 -0
- data/ext/handoff_machines_native/core/CHANGELOG.md +81 -0
- data/ext/handoff_machines_native/core/Cargo.toml +22 -0
- data/ext/handoff_machines_native/core/README.md +215 -0
- data/ext/handoff_machines_native/core/src/iter.rs +130 -0
- data/ext/handoff_machines_native/core/src/lib.rs +498 -0
- data/ext/handoff_machines_native/core/src/refusal.rs +83 -0
- data/ext/handoff_machines_native/core/src/transfer.rs +437 -0
- data/ext/handoff_machines_native/core/src/types.rs +440 -0
- data/ext/handoff_machines_native/extconf.rb +2 -0
- data/ext/handoff_machines_native/ffi/Cargo.toml +21 -0
- data/ext/handoff_machines_native/ffi/extconf.rb +14 -0
- data/ext/handoff_machines_native/ffi/src/classes.rs +50 -0
- data/ext/handoff_machines_native/ffi/src/handoff.rs +375 -0
- data/ext/handoff_machines_native/ffi/src/init.rs +62 -0
- data/ext/handoff_machines_native/ffi/src/lib.rs +36 -0
- data/ext/handoff_machines_native/ffi/src/names.rs +86 -0
- data/ext/handoff_machines_native/ffi/src/values.rs +211 -0
- data/lib/handoff_machines/version.rb +4 -0
- data/lib/handoff_machines.rb +263 -0
- data/sig/handoff_machines.rbs +291 -0
- metadata +93 -0
|
@@ -0,0 +1,498 @@
|
|
|
1
|
+
#![no_std]
|
|
2
|
+
#![cfg_attr(not(test), deny(clippy::indexing_slicing))]
|
|
3
|
+
#![doc = include_str!("../README.md")]
|
|
4
|
+
|
|
5
|
+
mod iter;
|
|
6
|
+
mod refusal;
|
|
7
|
+
mod transfer;
|
|
8
|
+
mod types;
|
|
9
|
+
|
|
10
|
+
use core::time::Duration;
|
|
11
|
+
|
|
12
|
+
pub use iter::{Orders, Outstanding, Overdue};
|
|
13
|
+
pub use lease_machines::FencingToken;
|
|
14
|
+
use periscope_machines::Issuer;
|
|
15
|
+
pub use refusal::Refusal;
|
|
16
|
+
use transfer::{Next, Transfer};
|
|
17
|
+
pub use types::{Acked, Action, Limits, Order, Phase, Recipient, Status, Ticket};
|
|
18
|
+
|
|
19
|
+
/// Coordinator for at most `N` concurrent partition transfers, each with a
|
|
20
|
+
/// drain window of `WORDS * 64` offsets.
|
|
21
|
+
///
|
|
22
|
+
/// The coordinator decides what is owed next and who owes it. It sends
|
|
23
|
+
/// nothing, stores nothing and issues no fencing tokens: the caller delivers
|
|
24
|
+
/// orders, reports acknowledgements and brings tokens from its authority.
|
|
25
|
+
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
26
|
+
pub struct Handoff<const N: usize, const WORDS: usize> {
|
|
27
|
+
slots: [Option<Transfer<WORDS>>; N],
|
|
28
|
+
/// Issues the ticket generations; it also holds the coordinator's scope.
|
|
29
|
+
generations: Issuer,
|
|
30
|
+
observed: Duration,
|
|
31
|
+
limits: Limits,
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
impl<const N: usize, const WORDS: usize> Handoff<N, WORDS> {
|
|
35
|
+
/// Concurrent transfers this coordinator can hold.
|
|
36
|
+
pub const CAPACITY: usize = N;
|
|
37
|
+
/// Offsets one transfer's drain window covers before it must slide.
|
|
38
|
+
pub const WINDOW: u64 = WORDS as u64 * 64;
|
|
39
|
+
|
|
40
|
+
/// Start with no transfers in a fresh generation namespace, in scope zero.
|
|
41
|
+
#[must_use]
|
|
42
|
+
pub const fn new(limits: Limits) -> Self {
|
|
43
|
+
Self::with_scope(limits, 0)
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/// Start with no transfers in a fresh generation namespace whose
|
|
47
|
+
/// generations carry `scope`.
|
|
48
|
+
///
|
|
49
|
+
/// A generation is a plain integer counted from one, so two coordinators
|
|
50
|
+
/// in the same scope issue the same tickets for the same partition, and
|
|
51
|
+
/// an acknowledgement sent to the wrong one is recorded there. Give every
|
|
52
|
+
/// coordinator whose tickets could meet its own scope: a ticket of
|
|
53
|
+
/// another scope is then always [`Refusal::Unknown`]. The coordinator
|
|
54
|
+
/// cannot pick a scope itself; keeping them distinct is the caller's job.
|
|
55
|
+
#[must_use]
|
|
56
|
+
pub const fn with_scope(limits: Limits, scope: u16) -> Self {
|
|
57
|
+
Self::resuming(limits, Issuer::new(scope))
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/// Start with no transfers in `scope`, issuing generations above
|
|
61
|
+
/// `last_generation`: what [`Handoff::generation`] answered on the
|
|
62
|
+
/// previous coordinator of this namespace, `None` when it had issued
|
|
63
|
+
/// nothing (an equal coordinator to [`Handoff::with_scope`]).
|
|
64
|
+
///
|
|
65
|
+
/// The scope is the caller's, never read out of the saved value, and the
|
|
66
|
+
/// saved value must be a generation of it: `None` when `last_generation`
|
|
67
|
+
/// is of another scope or carries a zero sequence. So a value that lost
|
|
68
|
+
/// its top bits, or the `0` a store answers for a row that is not there,
|
|
69
|
+
/// cannot put a coordinator of a non-zero scope into scope zero, and `0`
|
|
70
|
+
/// is no generation in scope zero either. Those are the only refusals:
|
|
71
|
+
/// [`Issuer::restored`] answers exactly them, and `None` is its answer
|
|
72
|
+
/// carried whole.
|
|
73
|
+
#[must_use]
|
|
74
|
+
pub const fn restored(
|
|
75
|
+
limits: Limits,
|
|
76
|
+
scope: u16,
|
|
77
|
+
last_generation: Option<u64>,
|
|
78
|
+
) -> Option<Self> {
|
|
79
|
+
match Issuer::restored(scope, last_generation) {
|
|
80
|
+
Some(generations) => Some(Self::resuming(limits, generations)),
|
|
81
|
+
None => None,
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
const fn resuming(limits: Limits, generations: Issuer) -> Self {
|
|
86
|
+
Self {
|
|
87
|
+
slots: [const { None }; N],
|
|
88
|
+
generations,
|
|
89
|
+
observed: Duration::ZERO,
|
|
90
|
+
limits,
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/// The scope carried by every generation this coordinator issues.
|
|
95
|
+
#[must_use]
|
|
96
|
+
pub const fn scope(&self) -> u16 {
|
|
97
|
+
self.generations.scope()
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/// Highest generation issued so far, `None` before the first; persist it
|
|
101
|
+
/// before exposing a ticket.
|
|
102
|
+
///
|
|
103
|
+
/// The whole generation, scope included. Persist it beside
|
|
104
|
+
/// [`Handoff::scope`] (a nullable column: `None` is "nothing issued
|
|
105
|
+
/// yet"): [`Handoff::restored`] takes both and refuses a value that is
|
|
106
|
+
/// not a generation of that scope.
|
|
107
|
+
#[must_use]
|
|
108
|
+
pub const fn generation(&self) -> Option<u64> {
|
|
109
|
+
self.generations.last()
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/// Number of transfers in progress.
|
|
113
|
+
#[must_use]
|
|
114
|
+
pub fn active(&self) -> usize {
|
|
115
|
+
self.slots.iter().flatten().count()
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/// The limits this coordinator was built with.
|
|
119
|
+
#[must_use]
|
|
120
|
+
pub const fn limits(&self) -> Limits {
|
|
121
|
+
self.limits
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/// Begin moving `partition` from `source` to `target`.
|
|
125
|
+
///
|
|
126
|
+
/// `base` is the lowest offset not yet durably committed under the source,
|
|
127
|
+
/// and `source_token` the fencing token the source currently serves under.
|
|
128
|
+
/// Its scope is the transfer's token scope: every later token is ranked
|
|
129
|
+
/// against it, and one of another scope is [`Refusal::Unknown`].
|
|
130
|
+
///
|
|
131
|
+
/// An honoured start records `now`: the first phase's deadline is
|
|
132
|
+
/// counted from it.
|
|
133
|
+
///
|
|
134
|
+
/// # Errors
|
|
135
|
+
/// `ClockRegressed`, `SameReplica`, `Busy`, `Full`, `ReplicaBusy` or `Exhausted`.
|
|
136
|
+
pub fn start(
|
|
137
|
+
&mut self,
|
|
138
|
+
partition: u64,
|
|
139
|
+
source: u64,
|
|
140
|
+
target: u64,
|
|
141
|
+
base: u64,
|
|
142
|
+
source_token: FencingToken,
|
|
143
|
+
now: Duration,
|
|
144
|
+
) -> Result<Ticket, Refusal> {
|
|
145
|
+
self.clock(now)?;
|
|
146
|
+
if source == target {
|
|
147
|
+
return Err(Refusal::SameReplica);
|
|
148
|
+
}
|
|
149
|
+
if self.find(partition).is_some() {
|
|
150
|
+
return Err(Refusal::Busy);
|
|
151
|
+
}
|
|
152
|
+
let crowded = self.load(source) >= self.limits.per_replica
|
|
153
|
+
|| self.load(target) >= self.limits.per_replica;
|
|
154
|
+
let deadline = self.deadline(now);
|
|
155
|
+
let Some(slot) = self.slots.iter_mut().find(|slot| slot.is_none()) else {
|
|
156
|
+
return Err(Refusal::Full);
|
|
157
|
+
};
|
|
158
|
+
if crowded {
|
|
159
|
+
return Err(Refusal::ReplicaBusy);
|
|
160
|
+
}
|
|
161
|
+
// Issued on a copy, kept only once the transfer exists: a refused
|
|
162
|
+
// start consumes no generation.
|
|
163
|
+
let mut generations = self.generations;
|
|
164
|
+
let generation = match generations.issue() {
|
|
165
|
+
Ok(generation) => generation,
|
|
166
|
+
Err(periscope_machines::Refusal::Exhausted) => return Err(Refusal::Exhausted),
|
|
167
|
+
};
|
|
168
|
+
let ticket = Ticket {
|
|
169
|
+
partition,
|
|
170
|
+
generation,
|
|
171
|
+
};
|
|
172
|
+
*slot = Some(Transfer::new(
|
|
173
|
+
ticket,
|
|
174
|
+
source,
|
|
175
|
+
target,
|
|
176
|
+
base,
|
|
177
|
+
source_token,
|
|
178
|
+
deadline,
|
|
179
|
+
));
|
|
180
|
+
self.generations = generations;
|
|
181
|
+
self.observed = now;
|
|
182
|
+
Ok(ticket)
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/// The source stopped admitting work; `until` is one past the last
|
|
186
|
+
/// admitted offset. Moves to `Drain`, or straight to `Checkpoint` when
|
|
187
|
+
/// nothing is in flight.
|
|
188
|
+
///
|
|
189
|
+
/// Repeated with the recorded `until`, for as long as the transfer lives,
|
|
190
|
+
/// it is an idempotent repeat: [`Acked::Duplicate`].
|
|
191
|
+
///
|
|
192
|
+
/// # Errors
|
|
193
|
+
/// A ticket refusal, `OutOfPhase` (the transfer was given up before the
|
|
194
|
+
/// source quiesced), `WrongReplica`, `BehindBase`, or `Mismatch` when a
|
|
195
|
+
/// different quiesce point is already recorded.
|
|
196
|
+
pub fn quiesced(
|
|
197
|
+
&mut self,
|
|
198
|
+
ticket: Ticket,
|
|
199
|
+
replica: u64,
|
|
200
|
+
until: u64,
|
|
201
|
+
now: Duration,
|
|
202
|
+
) -> Result<Acked, Refusal> {
|
|
203
|
+
self.acked(ticket, now, |transfer| transfer.quiesced(replica, until))
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/// The source finished one in-flight `offset`. Moves to `Checkpoint` once
|
|
207
|
+
/// every offset below the quiesce point is acknowledged.
|
|
208
|
+
///
|
|
209
|
+
/// An offset already acknowledged or already committed is an idempotent
|
|
210
|
+
/// repeat, during the drain and after it: [`Acked::Duplicate`].
|
|
211
|
+
///
|
|
212
|
+
/// # Errors
|
|
213
|
+
/// A ticket refusal, `OutOfPhase` (before the quiesce point is known, or
|
|
214
|
+
/// an unacknowledged offset once the drain was given up), `WrongReplica`,
|
|
215
|
+
/// `BeyondDrain` or `OutOfWindow`.
|
|
216
|
+
pub fn drained(
|
|
217
|
+
&mut self,
|
|
218
|
+
ticket: Ticket,
|
|
219
|
+
replica: u64,
|
|
220
|
+
offset: u64,
|
|
221
|
+
now: Duration,
|
|
222
|
+
) -> Result<Acked, Refusal> {
|
|
223
|
+
self.acked(ticket, now, |transfer| transfer.drained(replica, offset))
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/// The source durably committed every offset below `offset`; the drain
|
|
227
|
+
/// window slides there. Needed only when the drain is wider than `WINDOW`.
|
|
228
|
+
///
|
|
229
|
+
/// An offset not beyond the window base is already committed, an
|
|
230
|
+
/// idempotent repeat during the drain and after it: [`Acked::Duplicate`].
|
|
231
|
+
///
|
|
232
|
+
/// # Errors
|
|
233
|
+
/// A ticket refusal, `OutOfPhase` (before the quiesce point is known, or
|
|
234
|
+
/// a new offset once the drain is over), `WrongReplica` or `Unacked`.
|
|
235
|
+
pub fn committed(
|
|
236
|
+
&mut self,
|
|
237
|
+
ticket: Ticket,
|
|
238
|
+
replica: u64,
|
|
239
|
+
offset: u64,
|
|
240
|
+
now: Duration,
|
|
241
|
+
) -> Result<Acked, Refusal> {
|
|
242
|
+
self.acked(ticket, now, |transfer| transfer.committed(replica, offset))
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/// The source captured `checkpoint` at the quiesce point.
|
|
246
|
+
///
|
|
247
|
+
/// Repeated with the recorded checkpoint it is an idempotent repeat:
|
|
248
|
+
/// [`Acked::Duplicate`].
|
|
249
|
+
///
|
|
250
|
+
/// # Errors
|
|
251
|
+
/// A ticket refusal, `OutOfPhase` (the drain is not over), `WrongReplica`,
|
|
252
|
+
/// or `Mismatch` when a different checkpoint is already recorded.
|
|
253
|
+
pub fn captured(
|
|
254
|
+
&mut self,
|
|
255
|
+
ticket: Ticket,
|
|
256
|
+
replica: u64,
|
|
257
|
+
checkpoint: u64,
|
|
258
|
+
now: Duration,
|
|
259
|
+
) -> Result<Acked, Refusal> {
|
|
260
|
+
self.acked(ticket, now, |transfer| {
|
|
261
|
+
transfer.captured(replica, checkpoint)
|
|
262
|
+
})
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/// The target installed `checkpoint`. Moves to `Activate`.
|
|
266
|
+
///
|
|
267
|
+
/// Repeated once recorded it is an idempotent repeat: [`Acked::Duplicate`].
|
|
268
|
+
///
|
|
269
|
+
/// # Errors
|
|
270
|
+
/// A ticket refusal, `OutOfPhase` (no checkpoint was captured, or the
|
|
271
|
+
/// transfer was given up before the install), `WrongReplica`, or
|
|
272
|
+
/// `Mismatch` when `checkpoint` is not the captured one.
|
|
273
|
+
pub fn installed(
|
|
274
|
+
&mut self,
|
|
275
|
+
ticket: Ticket,
|
|
276
|
+
replica: u64,
|
|
277
|
+
checkpoint: u64,
|
|
278
|
+
now: Duration,
|
|
279
|
+
) -> Result<Acked, Refusal> {
|
|
280
|
+
self.acked(ticket, now, |transfer| {
|
|
281
|
+
transfer.installed(replica, checkpoint)
|
|
282
|
+
})
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/// The authority issued the target `token`, which must be of the source
|
|
286
|
+
/// token's scope and exceed it. From here on, aborting needs a newer
|
|
287
|
+
/// token still.
|
|
288
|
+
///
|
|
289
|
+
/// Repeated with the recorded token it is an idempotent repeat:
|
|
290
|
+
/// [`Acked::Duplicate`].
|
|
291
|
+
///
|
|
292
|
+
/// # Errors
|
|
293
|
+
/// In this order: a ticket refusal; `Unknown` (a token of another scope
|
|
294
|
+
/// than the source token's, whatever the transfer waits for or has
|
|
295
|
+
/// recorded); `Mismatch` when a different token is already recorded;
|
|
296
|
+
/// `OutOfPhase` (no token is awaited yet, or the transfer was given up
|
|
297
|
+
/// before one arrived); `StaleToken` (not above the source token).
|
|
298
|
+
pub fn fenced(
|
|
299
|
+
&mut self,
|
|
300
|
+
ticket: Ticket,
|
|
301
|
+
token: FencingToken,
|
|
302
|
+
now: Duration,
|
|
303
|
+
) -> Result<Acked, Refusal> {
|
|
304
|
+
self.acked(ticket, now, |transfer| transfer.fenced(token))
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/// The target is serving under `token`. Ends the transfer as `Complete`.
|
|
308
|
+
///
|
|
309
|
+
/// It frees the slot, so a repeat cannot be told from any other finished
|
|
310
|
+
/// ticket and is refused as `Stale`; this call never answers a duplicate.
|
|
311
|
+
///
|
|
312
|
+
/// # Errors
|
|
313
|
+
/// In this order: a ticket refusal; `Unknown` (a token of another scope
|
|
314
|
+
/// than the source token's); `OutOfPhase` (activation is not ordered, or
|
|
315
|
+
/// the transfer was given up); `WrongReplica`; `Mismatch` (not the token
|
|
316
|
+
/// recorded by `fenced`).
|
|
317
|
+
pub fn activated(
|
|
318
|
+
&mut self,
|
|
319
|
+
ticket: Ticket,
|
|
320
|
+
replica: u64,
|
|
321
|
+
token: FencingToken,
|
|
322
|
+
now: Duration,
|
|
323
|
+
) -> Result<Acked, Refusal> {
|
|
324
|
+
self.acked(ticket, now, |transfer| transfer.activated(replica, token))
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
/// Give the transfer up from any phase and move to `Rollback`.
|
|
328
|
+
///
|
|
329
|
+
/// A `token` fences the rollback: it must be of the source token's scope
|
|
330
|
+
/// and exceed every token the transfer knows, and the source resumes
|
|
331
|
+
/// under it. It is required once activation was ordered, because the
|
|
332
|
+
/// target may already be serving.
|
|
333
|
+
///
|
|
334
|
+
/// During the rollback, repeated with the same `token` (or the same
|
|
335
|
+
/// absence of one), it is an idempotent repeat: [`Acked::Duplicate`].
|
|
336
|
+
///
|
|
337
|
+
/// # Errors
|
|
338
|
+
/// In this order: a ticket refusal; `Unknown` (a token of another scope
|
|
339
|
+
/// than the source token's); `Mismatch` when the rollback is already
|
|
340
|
+
/// under way with a different token; `StaleToken`; `FenceRequired`.
|
|
341
|
+
pub fn abort(
|
|
342
|
+
&mut self,
|
|
343
|
+
ticket: Ticket,
|
|
344
|
+
token: Option<FencingToken>,
|
|
345
|
+
now: Duration,
|
|
346
|
+
) -> Result<Acked, Refusal> {
|
|
347
|
+
self.acked(ticket, now, |transfer| transfer.abort(token))
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/// The source is serving again. Ends the rollback as `Aborted` once no
|
|
351
|
+
/// other rollback acknowledgement is owed.
|
|
352
|
+
///
|
|
353
|
+
/// While the rollback still waits for the target, a second `resumed` is
|
|
354
|
+
/// an idempotent repeat: [`Acked::Duplicate`].
|
|
355
|
+
///
|
|
356
|
+
/// # Errors
|
|
357
|
+
/// A ticket refusal, `OutOfPhase` (no rollback was ordered) or
|
|
358
|
+
/// `WrongReplica`.
|
|
359
|
+
pub fn resumed(
|
|
360
|
+
&mut self,
|
|
361
|
+
ticket: Ticket,
|
|
362
|
+
replica: u64,
|
|
363
|
+
now: Duration,
|
|
364
|
+
) -> Result<Acked, Refusal> {
|
|
365
|
+
self.acked(ticket, now, |transfer| transfer.resumed(replica))
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/// The target dropped what it installed. Ends the rollback as `Aborted`
|
|
369
|
+
/// once no other rollback acknowledgement is owed.
|
|
370
|
+
///
|
|
371
|
+
/// A `discarded` the rollback does not wait for (already recorded, or
|
|
372
|
+
/// never owed because the target was never asked to install) is an
|
|
373
|
+
/// idempotent repeat: [`Acked::Duplicate`].
|
|
374
|
+
///
|
|
375
|
+
/// # Errors
|
|
376
|
+
/// A ticket refusal, `OutOfPhase` (no rollback was ordered) or
|
|
377
|
+
/// `WrongReplica`.
|
|
378
|
+
pub fn discarded(
|
|
379
|
+
&mut self,
|
|
380
|
+
ticket: Ticket,
|
|
381
|
+
replica: u64,
|
|
382
|
+
now: Duration,
|
|
383
|
+
) -> Result<Acked, Refusal> {
|
|
384
|
+
self.acked(ticket, now, |transfer| transfer.discarded(replica))
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
/// The transfer currently moving `partition`, if any.
|
|
388
|
+
#[must_use]
|
|
389
|
+
pub fn status(&self, partition: u64) -> Option<Status> {
|
|
390
|
+
self.find(partition).map(Transfer::status)
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
/// Outstanding orders from position `from` (zero to begin). At most two
|
|
394
|
+
/// per transfer, so a full pass yields at most `2 * N`. Stop any time and
|
|
395
|
+
/// resume from [`Orders::position`].
|
|
396
|
+
#[must_use]
|
|
397
|
+
pub const fn orders(&self, from: usize) -> Orders<'_, WORDS> {
|
|
398
|
+
Orders::new(&self.slots, from)
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
/// Offsets the drain still waits for, ascending from `from`. Resume by
|
|
402
|
+
/// passing the last yielded offset plus one.
|
|
403
|
+
///
|
|
404
|
+
/// # Errors
|
|
405
|
+
/// `Stale` or `Unknown` for the ticket, `OutOfPhase` outside `Drain`.
|
|
406
|
+
pub fn outstanding(
|
|
407
|
+
&self,
|
|
408
|
+
ticket: Ticket,
|
|
409
|
+
from: u64,
|
|
410
|
+
) -> Result<Outstanding<'_, WORDS>, Refusal> {
|
|
411
|
+
let (tracker, until) = self.locate(ticket)?.draining().ok_or(Refusal::OutOfPhase)?;
|
|
412
|
+
Ok(Outstanding::new(tracker, from, until))
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
/// Transfers whose current phase reached its deadline at `now`, from slot
|
|
416
|
+
/// `from` (zero to begin). Resume from [`Overdue::position`]. Advisory:
|
|
417
|
+
/// the coordinator never aborts on its own.
|
|
418
|
+
#[must_use]
|
|
419
|
+
pub const fn overdue(&self, now: Duration, from: usize) -> Overdue<'_, WORDS> {
|
|
420
|
+
Overdue::new(&self.slots, now, from)
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
const fn clock(&self, now: Duration) -> Result<(), Refusal> {
|
|
424
|
+
if now.as_nanos() < self.observed.as_nanos() {
|
|
425
|
+
Err(Refusal::ClockRegressed)
|
|
426
|
+
} else {
|
|
427
|
+
Ok(())
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
const fn deadline(&self, now: Duration) -> Duration {
|
|
432
|
+
now.saturating_add(self.limits.phase_budget)
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
fn find(&self, partition: u64) -> Option<&Transfer<WORDS>> {
|
|
436
|
+
let mut live = self.slots.iter().flatten();
|
|
437
|
+
live.find(|transfer| transfer.ticket.partition == partition)
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
fn load(&self, replica: u64) -> usize {
|
|
441
|
+
let busy = self.slots.iter().flatten();
|
|
442
|
+
busy.filter(|transfer| transfer.involves(replica)).count()
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
/// A generation this coordinator did not issue (another scope, or a
|
|
446
|
+
/// sequence it has not reached) is unknown: no slot is read. One it did
|
|
447
|
+
/// issue and holds in no slot is stale.
|
|
448
|
+
fn locate(&self, ticket: Ticket) -> Result<&Transfer<WORDS>, Refusal> {
|
|
449
|
+
if !self.generations.owns(ticket.generation) {
|
|
450
|
+
return Err(Refusal::Unknown);
|
|
451
|
+
}
|
|
452
|
+
let mut live = self.slots.iter().flatten();
|
|
453
|
+
live.find(|transfer| transfer.ticket == ticket)
|
|
454
|
+
.ok_or(Refusal::Stale)
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
/// Answer one acknowledgement. Only an acknowledgement that moves the
|
|
458
|
+
/// transfer to a new wait records `now`: the new phase's deadline is
|
|
459
|
+
/// counted from it. A repeat, a step within the same wait and the end of
|
|
460
|
+
/// the transfer answer the same whatever the time, and record nothing.
|
|
461
|
+
fn acked(
|
|
462
|
+
&mut self,
|
|
463
|
+
ticket: Ticket,
|
|
464
|
+
now: Duration,
|
|
465
|
+
ack: impl FnOnce(&mut Transfer<WORDS>) -> Result<Next, Refusal>,
|
|
466
|
+
) -> Result<Acked, Refusal> {
|
|
467
|
+
self.clock(now)?;
|
|
468
|
+
if !self.generations.owns(ticket.generation) {
|
|
469
|
+
return Err(Refusal::Unknown);
|
|
470
|
+
}
|
|
471
|
+
let deadline = self.deadline(now);
|
|
472
|
+
for slot in &mut self.slots {
|
|
473
|
+
let Some(transfer) = slot else { continue };
|
|
474
|
+
if transfer.ticket != ticket {
|
|
475
|
+
continue;
|
|
476
|
+
}
|
|
477
|
+
return Ok(match ack(transfer)? {
|
|
478
|
+
Next::Repeat => Acked::Duplicate(transfer.phase()),
|
|
479
|
+
Next::Same => Acked::Recorded(transfer.phase()),
|
|
480
|
+
Next::Moved => {
|
|
481
|
+
transfer.deadline = deadline;
|
|
482
|
+
self.observed = now;
|
|
483
|
+
Acked::Recorded(transfer.phase())
|
|
484
|
+
}
|
|
485
|
+
Next::Done(phase) => {
|
|
486
|
+
*slot = None;
|
|
487
|
+
Acked::Recorded(phase)
|
|
488
|
+
}
|
|
489
|
+
});
|
|
490
|
+
}
|
|
491
|
+
Err(Refusal::Stale)
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
#[cfg(test)]
|
|
496
|
+
extern crate std;
|
|
497
|
+
#[cfg(test)]
|
|
498
|
+
mod tests;
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
//! The one answer for every call that was not honoured.
|
|
2
|
+
use core::fmt;
|
|
3
|
+
|
|
4
|
+
/// Why a call was not honoured. Every refusal leaves the coordinator exactly
|
|
5
|
+
/// as it was. An idempotent repeat is not a refusal: see [`Acked::Duplicate`](crate::Acked).
|
|
6
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
7
|
+
pub enum Refusal {
|
|
8
|
+
/// Every transfer slot is in use.
|
|
9
|
+
Full,
|
|
10
|
+
/// The partition already has a transfer in progress.
|
|
11
|
+
Busy,
|
|
12
|
+
/// The source or the target is already in its per-replica limit of transfers.
|
|
13
|
+
ReplicaBusy,
|
|
14
|
+
/// Source and target are the same replica.
|
|
15
|
+
SameReplica,
|
|
16
|
+
/// The scope's generation space (2^48 - 1) is exhausted; generations
|
|
17
|
+
/// never wrap.
|
|
18
|
+
Exhausted,
|
|
19
|
+
/// `now` is earlier than the latest accepted observation.
|
|
20
|
+
ClockRegressed,
|
|
21
|
+
/// The ticket's generation was issued but is not the partition's current transfer.
|
|
22
|
+
Stale,
|
|
23
|
+
/// An id that is not of the namespace the call ranks it in. The ticket
|
|
24
|
+
/// was never issued by this coordinator: its generation is zero, beyond
|
|
25
|
+
/// the last one issued, or of another scope. Or the fencing token offered
|
|
26
|
+
/// to `fenced`, `activated` or `abort` is of another scope than the
|
|
27
|
+
/// transfer's source token: it names nothing in this transfer, and is
|
|
28
|
+
/// answered before the transfer's phase or recorded token is read.
|
|
29
|
+
Unknown,
|
|
30
|
+
/// The transfer is not waiting for this acknowledgement and never
|
|
31
|
+
/// recorded it: it came too early, or the transfer left the path that
|
|
32
|
+
/// wanted it. Never a repeat of something recorded.
|
|
33
|
+
OutOfPhase,
|
|
34
|
+
/// The acknowledgement came from a replica that does not hold that role.
|
|
35
|
+
WrongReplica,
|
|
36
|
+
/// The quiesce point is below the transfer's base offset.
|
|
37
|
+
BehindBase,
|
|
38
|
+
/// The offset is at or beyond the quiesce point.
|
|
39
|
+
BeyondDrain,
|
|
40
|
+
/// The offset is beyond the drain window; confirm commits to slide it.
|
|
41
|
+
OutOfWindow,
|
|
42
|
+
/// The confirmed offset is beyond the contiguous acknowledged prefix.
|
|
43
|
+
Unacked,
|
|
44
|
+
/// The quiesce point, checkpoint or token is not the one this transfer
|
|
45
|
+
/// recorded: a first report that contradicts it, or a repeat that differs.
|
|
46
|
+
Mismatch,
|
|
47
|
+
/// The token is of the transfer's token scope and does not exceed every
|
|
48
|
+
/// token this transfer already knows. A token of another scope is
|
|
49
|
+
/// `Unknown`, never this.
|
|
50
|
+
StaleToken,
|
|
51
|
+
/// Activation was ordered; aborting needs a newer fencing token.
|
|
52
|
+
FenceRequired,
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
impl fmt::Display for Refusal {
|
|
56
|
+
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
57
|
+
f.write_str(match self {
|
|
58
|
+
Self::Full => "every transfer slot is in use",
|
|
59
|
+
Self::Busy => "the partition already has a transfer in progress",
|
|
60
|
+
Self::ReplicaBusy => "a replica is at its limit of concurrent transfers",
|
|
61
|
+
Self::SameReplica => "source and target are the same replica",
|
|
62
|
+
Self::Exhausted => "generation space exhausted",
|
|
63
|
+
Self::ClockRegressed => "time is earlier than the latest accepted observation",
|
|
64
|
+
Self::Stale => "the ticket is not the partition's current transfer",
|
|
65
|
+
Self::Unknown => {
|
|
66
|
+
"the ticket was never issued by this coordinator, or the token is of another scope"
|
|
67
|
+
}
|
|
68
|
+
Self::OutOfPhase => {
|
|
69
|
+
"the transfer neither waits for this acknowledgement nor recorded it"
|
|
70
|
+
}
|
|
71
|
+
Self::WrongReplica => "the replica does not hold that role",
|
|
72
|
+
Self::BehindBase => "the quiesce point is below the base offset",
|
|
73
|
+
Self::BeyondDrain => "the offset is at or beyond the quiesce point",
|
|
74
|
+
Self::OutOfWindow => "the offset is beyond the drain window",
|
|
75
|
+
Self::Unacked => "the offset is beyond the acknowledged prefix",
|
|
76
|
+
Self::Mismatch => "the quiesce point, checkpoint or token is not the one recorded",
|
|
77
|
+
Self::StaleToken => "the token does not exceed every known token",
|
|
78
|
+
Self::FenceRequired => "aborting after activation was ordered needs a newer token",
|
|
79
|
+
})
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
impl core::error::Error for Refusal {}
|