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,440 @@
1
+ use core::time::Duration;
2
+
3
+ use lease_machines::FencingToken;
4
+ use periscope_machines::{SEQUENCE_MAX, scope_of, sequence_of};
5
+
6
+ /// Identity of one transfer: the partition and the generation it was issued under.
7
+ ///
8
+ /// Every acknowledgement carries the ticket. A ticket whose generation is not
9
+ /// the partition's current transfer generation is refused, and so is one
10
+ /// whose generation another coordinator's scope issued.
11
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
12
+ pub struct Ticket {
13
+ pub(crate) partition: u64,
14
+ pub(crate) generation: u64,
15
+ }
16
+
17
+ impl Ticket {
18
+ /// A ticket from its two fields, as one that travelled to a replica and
19
+ /// back is rebuilt. `None` when `generation` carries a zero sequence: no
20
+ /// coordinator issues it, whatever its scope.
21
+ #[must_use]
22
+ pub const fn new(partition: u64, generation: u64) -> Option<Self> {
23
+ if sequence_of(generation) == 0 {
24
+ return None;
25
+ }
26
+ Some(Self {
27
+ partition,
28
+ generation,
29
+ })
30
+ }
31
+
32
+ /// Caller-owned partition identity.
33
+ #[must_use]
34
+ pub const fn partition(&self) -> u64 {
35
+ self.partition
36
+ }
37
+
38
+ /// Coordinator-issued transfer generation; never zero, never reused. It
39
+ /// carries the coordinator's scope above a sequence counted from one, so
40
+ /// scope zero issues 1, 2, 3.
41
+ #[must_use]
42
+ pub const fn generation(&self) -> u64 {
43
+ self.generation
44
+ }
45
+
46
+ /// The scope of the coordinator that issued this ticket, see
47
+ /// [`Handoff::with_scope`](crate::Handoff::with_scope).
48
+ #[must_use]
49
+ pub const fn scope(&self) -> u16 {
50
+ scope_of(self.generation)
51
+ }
52
+ }
53
+
54
+ /// Where a transfer stands. `Complete` and `Aborted` are only ever returned
55
+ /// from the call that ended the transfer; the slot is free afterwards.
56
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
57
+ pub enum Phase {
58
+ /// Waiting for the source to stop admitting new work.
59
+ Quiesce,
60
+ /// Waiting for in-flight offsets below the quiesce point.
61
+ Drain,
62
+ /// Waiting for the source to capture, then the target to install.
63
+ Checkpoint,
64
+ /// Waiting for a fencing token, then the target's activation.
65
+ Activate,
66
+ /// Aborted; waiting for the replicas to undo what they were told.
67
+ Rollback,
68
+ /// The target owns the partition under the activation token.
69
+ Complete,
70
+ /// Every rollback acknowledgement arrived; the source owns the partition.
71
+ Aborted,
72
+ }
73
+
74
+ impl Phase {
75
+ /// Whether the transfer is over: `Complete` or `Aborted`. No live transfer
76
+ /// stands at a final phase.
77
+ #[must_use]
78
+ pub const fn is_final(self) -> bool {
79
+ match self {
80
+ Self::Quiesce | Self::Drain | Self::Checkpoint | Self::Activate | Self::Rollback => {
81
+ false
82
+ }
83
+ Self::Complete | Self::Aborted => true,
84
+ }
85
+ }
86
+ }
87
+
88
+ /// Honoured outcome of every acknowledgement. Each may be delivered more than
89
+ /// once; the transfer answers a repeat from what it recorded.
90
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
91
+ pub enum Acked {
92
+ /// Recorded for the first time; the transfer now stands at this phase.
93
+ Recorded(Phase),
94
+ /// Idempotent repeat: the transfer already recorded this acknowledgement
95
+ /// with the same payload (quiesce point, offset, checkpoint, token), or
96
+ /// the rollback never owed it. Nothing changed, not even the observed
97
+ /// clock; the transfer still stands at this phase, which may be a later
98
+ /// one than the acknowledgement first led to.
99
+ Duplicate(Phase),
100
+ }
101
+
102
+ impl Acked {
103
+ /// `Recorded(phase)`, or `None` for `Quiesce`: a transfer starts there, so
104
+ /// no acknowledgement ever leads to it.
105
+ #[must_use]
106
+ pub const fn recorded(phase: Phase) -> Option<Self> {
107
+ match phase {
108
+ Phase::Quiesce => None,
109
+ Phase::Drain
110
+ | Phase::Checkpoint
111
+ | Phase::Activate
112
+ | Phase::Rollback
113
+ | Phase::Complete
114
+ | Phase::Aborted => Some(Self::Recorded(phase)),
115
+ }
116
+ }
117
+
118
+ /// `Duplicate(phase)`, or `None` for `Quiesce` (nothing is recorded yet,
119
+ /// so nothing repeats) and for a final phase (the slot is free, and a
120
+ /// repeat on a finished ticket is `Stale`).
121
+ #[must_use]
122
+ pub const fn duplicate(phase: Phase) -> Option<Self> {
123
+ match phase {
124
+ Phase::Quiesce | Phase::Complete | Phase::Aborted => None,
125
+ Phase::Drain | Phase::Checkpoint | Phase::Activate | Phase::Rollback => {
126
+ Some(Self::Duplicate(phase))
127
+ }
128
+ }
129
+ }
130
+
131
+ /// Where the transfer stands after the call.
132
+ #[must_use]
133
+ pub const fn phase(self) -> Phase {
134
+ match self {
135
+ Self::Recorded(phase) | Self::Duplicate(phase) => phase,
136
+ }
137
+ }
138
+
139
+ /// Whether the call was an idempotent repeat that changed nothing.
140
+ #[must_use]
141
+ pub const fn is_duplicate(self) -> bool {
142
+ match self {
143
+ Self::Recorded(_) => false,
144
+ Self::Duplicate(_) => true,
145
+ }
146
+ }
147
+ }
148
+
149
+ /// Who an order is addressed to.
150
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
151
+ pub enum Recipient {
152
+ /// A replica, by its caller-owned durable identity.
153
+ Replica(u64),
154
+ /// The serialized lease authority that issues fencing tokens.
155
+ Authority,
156
+ }
157
+
158
+ /// What the recipient is asked to do. Orders are restated until acknowledged.
159
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
160
+ pub enum Action {
161
+ /// Source: stop admitting new work and report the quiesce point.
162
+ Quiesce,
163
+ /// Source: finish in-flight offsets below `until` and acknowledge each.
164
+ Drain {
165
+ /// One past the last admitted offset.
166
+ until: u64,
167
+ },
168
+ /// Source: capture a checkpoint at exactly `at` and report its identity.
169
+ Capture {
170
+ /// The drained quiesce point.
171
+ at: u64,
172
+ },
173
+ /// Target: install the named checkpoint and acknowledge it.
174
+ Install {
175
+ /// Checkpoint identity reported by the source.
176
+ checkpoint: u64,
177
+ },
178
+ /// Authority: issue the target a token strictly greater than `above`.
179
+ Fence {
180
+ /// The source's token; the activation token must exceed it.
181
+ above: FencingToken,
182
+ },
183
+ /// Target: start serving under `token` and acknowledge it.
184
+ Activate {
185
+ /// The activation token.
186
+ token: FencingToken,
187
+ },
188
+ /// Source: resume serving; under `token` when the rollback was fenced.
189
+ Resume {
190
+ /// The rollback token, when one was supplied to `abort`.
191
+ token: Option<FencingToken>,
192
+ },
193
+ /// Target: stop serving if it started, and drop the installed checkpoint.
194
+ Discard,
195
+ }
196
+
197
+ /// One outstanding instruction.
198
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
199
+ pub struct Order {
200
+ pub(crate) ticket: Ticket,
201
+ pub(crate) to: Recipient,
202
+ pub(crate) action: Action,
203
+ }
204
+
205
+ impl Order {
206
+ /// An order from its three fields. `None` when the recipient cannot be
207
+ /// asked for the action: only the authority fences, and it does nothing
208
+ /// else. Also `None` for a ticket no coordinator issues.
209
+ #[must_use]
210
+ pub const fn new(ticket: Ticket, to: Recipient, action: Action) -> Option<Self> {
211
+ if Ticket::new(ticket.partition, ticket.generation).is_none() {
212
+ return None;
213
+ }
214
+ let authority = match to {
215
+ Recipient::Authority => true,
216
+ Recipient::Replica(_) => false,
217
+ };
218
+ let fence = match action {
219
+ Action::Fence { .. } => true,
220
+ Action::Quiesce
221
+ | Action::Drain { .. }
222
+ | Action::Capture { .. }
223
+ | Action::Install { .. }
224
+ | Action::Activate { .. }
225
+ | Action::Resume { .. }
226
+ | Action::Discard => false,
227
+ };
228
+ let fits = authority == fence;
229
+ if fits {
230
+ Some(Self { ticket, to, action })
231
+ } else {
232
+ None
233
+ }
234
+ }
235
+
236
+ /// The transfer this order belongs to; echo it in the acknowledgement.
237
+ #[must_use]
238
+ pub const fn ticket(&self) -> Ticket {
239
+ self.ticket
240
+ }
241
+
242
+ /// Who must act.
243
+ #[must_use]
244
+ pub const fn to(&self) -> Recipient {
245
+ self.to
246
+ }
247
+
248
+ /// What they must do.
249
+ #[must_use]
250
+ pub const fn action(&self) -> Action {
251
+ self.action
252
+ }
253
+ }
254
+
255
+ /// A read-only view of one active transfer.
256
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
257
+ pub struct Status {
258
+ pub(crate) ticket: Ticket,
259
+ pub(crate) source: u64,
260
+ pub(crate) target: u64,
261
+ pub(crate) phase: Phase,
262
+ pub(crate) base: u64,
263
+ pub(crate) until: Option<u64>,
264
+ pub(crate) checkpoint: Option<u64>,
265
+ pub(crate) token: Option<FencingToken>,
266
+ pub(crate) deadline: Duration,
267
+ }
268
+
269
+ impl Status {
270
+ /// A view from its fields, as one that was stored or sent is rebuilt;
271
+ /// `None` when no coordinator could have answered it.
272
+ ///
273
+ /// A live transfer has a ticket some coordinator issues, two different
274
+ /// replicas and a phase that is not final. What it has recorded follows
275
+ /// its phase: no quiesce point while it waits for one, one above `base`
276
+ /// during the drain and one at or above it afterwards; a checkpoint only after a quiesce point, none
277
+ /// before the drain is over and one once activation is under way; an
278
+ /// activation token only with a checkpoint, and only while activating or
279
+ /// rolling back. A rollback keeps whatever was recorded when it began.
280
+ /// An activation token exceeds a source token of its scope, so its
281
+ /// sequence is at least two; one a rollback keeps was superseded by a
282
+ /// newer token of that scope, so its sequence is below the last.
283
+ #[must_use]
284
+ #[allow(clippy::too_many_arguments)] // One per field, in field order.
285
+ pub const fn new(
286
+ ticket: Ticket,
287
+ source: u64,
288
+ target: u64,
289
+ phase: Phase,
290
+ base: u64,
291
+ until: Option<u64>,
292
+ checkpoint: Option<u64>,
293
+ token: Option<FencingToken>,
294
+ deadline: Duration,
295
+ ) -> Option<Self> {
296
+ Self {
297
+ ticket,
298
+ source,
299
+ target,
300
+ phase,
301
+ base,
302
+ until,
303
+ checkpoint,
304
+ token,
305
+ deadline,
306
+ }
307
+ .checked()
308
+ }
309
+
310
+ /// This view, when a coordinator could have answered it.
311
+ pub(crate) const fn checked(self) -> Option<Self> {
312
+ let (until, checkpoint, token) = (
313
+ self.until.is_some(),
314
+ self.checkpoint.is_some(),
315
+ self.token.is_some(),
316
+ );
317
+ let recorded = match self.phase {
318
+ Phase::Quiesce => !until && !checkpoint && !token,
319
+ Phase::Drain => until && !checkpoint && !token,
320
+ Phase::Checkpoint => until && !token,
321
+ Phase::Activate => until && checkpoint,
322
+ Phase::Rollback => (until || !checkpoint) && (checkpoint || !token),
323
+ Phase::Complete | Phase::Aborted => false,
324
+ };
325
+ // A drain lasts only while the base is below the quiesce point: both
326
+ // `quiesced` at the base and `drained` up to it move to the capture.
327
+ let based = match (self.phase, self.until) {
328
+ (Phase::Drain, Some(until)) => self.base < until,
329
+ (_, Some(until)) => self.base <= until,
330
+ (_, None) => true,
331
+ };
332
+ // `fenced` admits only a token above the source token, whose sequence
333
+ // is at least one; a rollback keeps one only when `abort` was given a
334
+ // newer token of the same scope, so it is below the last sequence.
335
+ let fenced = match (self.phase, self.token) {
336
+ (Phase::Activate, Some(token)) => sequence_of(token.raw()) > 1,
337
+ (Phase::Rollback, Some(token)) => {
338
+ let sequence = sequence_of(token.raw());
339
+ sequence > 1 && sequence < SEQUENCE_MAX
340
+ }
341
+ _ => true,
342
+ };
343
+ let issued = Ticket::new(self.ticket.partition, self.ticket.generation).is_some();
344
+ if recorded && based && fenced && issued && self.source != self.target {
345
+ Some(self)
346
+ } else {
347
+ None
348
+ }
349
+ }
350
+
351
+ /// The transfer's identity.
352
+ #[must_use]
353
+ pub const fn ticket(&self) -> Ticket {
354
+ self.ticket
355
+ }
356
+
357
+ /// Replica giving the partition up.
358
+ #[must_use]
359
+ pub const fn source(&self) -> u64 {
360
+ self.source
361
+ }
362
+
363
+ /// Replica taking the partition over.
364
+ #[must_use]
365
+ pub const fn target(&self) -> u64 {
366
+ self.target
367
+ }
368
+
369
+ /// Current phase; never `Complete` or `Aborted`.
370
+ #[must_use]
371
+ pub const fn phase(&self) -> Phase {
372
+ self.phase
373
+ }
374
+
375
+ /// Lowest offset not yet confirmed committed.
376
+ #[must_use]
377
+ pub const fn base(&self) -> u64 {
378
+ self.base
379
+ }
380
+
381
+ /// The quiesce point, once the source reported it.
382
+ #[must_use]
383
+ pub const fn until(&self) -> Option<u64> {
384
+ self.until
385
+ }
386
+
387
+ /// The checkpoint identity, once the source reported it.
388
+ #[must_use]
389
+ pub const fn checkpoint(&self) -> Option<u64> {
390
+ self.checkpoint
391
+ }
392
+
393
+ /// The activation token, once the authority issued it.
394
+ #[must_use]
395
+ pub const fn token(&self) -> Option<FencingToken> {
396
+ self.token
397
+ }
398
+
399
+ /// When the current phase becomes overdue.
400
+ #[must_use]
401
+ pub const fn deadline(&self) -> Duration {
402
+ self.deadline
403
+ }
404
+ }
405
+
406
+ /// Admission and timing limits for a coordinator.
407
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
408
+ pub struct Limits {
409
+ pub(crate) phase_budget: Duration,
410
+ pub(crate) per_replica: usize,
411
+ }
412
+
413
+ impl Limits {
414
+ /// Limits a coordinator can admit a transfer under. `None` when
415
+ /// `per_replica` is zero: no replica could take part in any transfer, so
416
+ /// every [`Handoff::start`](crate::Handoff::start) would be refused. Any
417
+ /// `phase_budget` is accepted; zero makes every phase overdue at once.
418
+ #[must_use]
419
+ pub const fn new(phase_budget: Duration, per_replica: usize) -> Option<Self> {
420
+ if per_replica == 0 {
421
+ return None;
422
+ }
423
+ Some(Self {
424
+ phase_budget,
425
+ per_replica,
426
+ })
427
+ }
428
+
429
+ /// How long one phase may last before `overdue` reports the transfer.
430
+ #[must_use]
431
+ pub const fn phase_budget(&self) -> Duration {
432
+ self.phase_budget
433
+ }
434
+
435
+ /// How many concurrent transfers one replica may take part in.
436
+ #[must_use]
437
+ pub const fn per_replica(&self) -> usize {
438
+ self.per_replica
439
+ }
440
+ }
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'
@@ -0,0 +1,21 @@
1
+ [package]
2
+ name = "handoff_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
+ handoff-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('handoff_machines_native/handoff_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,50 @@
1
+ //! The `Data` classes, resolved once at load and pinned. The exact-class
2
+ //! check, the own-or-sibling read (see `values`) and clone-then-keep are
3
+ //! `matryona_machines::ruby`'s.
4
+ use magnus::{Error, RModule, Ruby};
5
+ use matryona_machines::ruby::Class;
6
+
7
+ /// Every `Data` class the binding checks or builds.
8
+ pub struct Classes {
9
+ pub token: Class,
10
+ pub limits: Class,
11
+ pub ticket: Class,
12
+ pub recorded: Class,
13
+ pub duplicate: Class,
14
+ pub replica: Class,
15
+ /// The action classes, in [`ACTIONS`] order.
16
+ pub actions: [Class; 6],
17
+ }
18
+
19
+ /// The action names whose classes [`Classes::actions`] holds, in order.
20
+ pub const ACTIONS: [&str; 6] = ["Drain", "Capture", "Install", "Fence", "Activate", "Resume"];
21
+
22
+ matryona_machines::registry! {
23
+ static CLASSES: Classes = "handoff_machines";
24
+ /// The classes resolved at load.
25
+ pub fn classes;
26
+ }
27
+
28
+ /// Resolve the classes `handoff_machines.rb` defined before requiring the
29
+ /// extension. Called once, from init; never by name again.
30
+ pub fn resolve(ruby: &Ruby, module: RModule) -> Result<(), Error> {
31
+ let class = |name| Class::resolve(ruby, module, name);
32
+ let [drain, capture, install, fence, activate, resume] = ACTIONS;
33
+ let classes = Classes {
34
+ token: class("FencingToken")?,
35
+ limits: class("Limits")?,
36
+ ticket: class("Ticket")?,
37
+ recorded: class("Recorded")?,
38
+ duplicate: class("Duplicate")?,
39
+ replica: class("Replica")?,
40
+ actions: [
41
+ class(drain)?,
42
+ class(capture)?,
43
+ class(install)?,
44
+ class(fence)?,
45
+ class(activate)?,
46
+ class(resume)?,
47
+ ],
48
+ };
49
+ CLASSES.set(ruby, classes).map(drop)
50
+ }