handoff_machines 0.8.3-aarch64-linux
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/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/README.md +215 -0
- data/ext/handoff_machines_native/extconf.rb +2 -0
- data/lib/handoff_machines/version.rb +4 -0
- data/lib/handoff_machines.rb +263 -0
- data/lib/handoff_machines_native/handoff_machines_native.so +0 -0
- data/sig/handoff_machines.rbs +291 -0
- metadata +63 -0
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# handoff-machines
|
|
2
|
+
|
|
3
|
+
> **AMS DeCandia**, NCC-4234, *DeCandia*-class transfer tender.
|
|
4
|
+
|
|
5
|
+
Engine-room flight manual: move a partition between replicas one acknowledged phase at a time.
|
|
6
|
+
|
|
7
|
+
Allocation-free `no_std` coordinator policy for partition
|
|
8
|
+
ownership transfer: quiesce the source, drain what is in flight, checkpoint,
|
|
9
|
+
then activate the target under a newer fencing token. `Handoff<N, WORDS>` holds
|
|
10
|
+
at most `N` concurrent transfers, each with a drain window of `WORDS * 64`
|
|
11
|
+
offsets, and refuses rather than grows.
|
|
12
|
+
|
|
13
|
+
It coordinates ownership migration. It does not rank placement, replicate data,
|
|
14
|
+
issue fencing tokens, send messages or persist anything.
|
|
15
|
+
|
|
16
|
+
- `start` issues a `Ticket` (`partition()`, `generation()`). Generations are strictly
|
|
17
|
+
increasing and never reused. Every acknowledgement carries its ticket: an
|
|
18
|
+
issued generation that is no longer the partition's transfer is `Stale`, one
|
|
19
|
+
never issued is `Unknown`.
|
|
20
|
+
- **Scopes.** A ticket means something only to the coordinator that issued
|
|
21
|
+
it. A generation is a `u64` in the
|
|
22
|
+
[`periscope-machines`](https://crates.io/crates/periscope-machines) layout:
|
|
23
|
+
the coordinator's scope in the top 16 bits, a sequence counted from 1 in
|
|
24
|
+
the low 48. Two coordinators count the same sequence, so without scopes a
|
|
25
|
+
ticket for the same partition given to the wrong one is acknowledged there.
|
|
26
|
+
`Handoff::new(limits)` is scope zero and issues 1, 2, 3;
|
|
27
|
+
`Handoff::with_scope(limits, scope)` issues the same sequence under `scope`;
|
|
28
|
+
`Handoff::scope()` and `Ticket::scope()` read it back. A ticket of another
|
|
29
|
+
scope was never issued here: every acknowledgement and `outstanding` answer
|
|
30
|
+
`Unknown` before any transfer is looked up, and nothing changes. The
|
|
31
|
+
coordinator reads no clock and no random source, so it cannot pick a scope;
|
|
32
|
+
two coordinators left in the same scope still alias. A scope holds 2^48 - 1
|
|
33
|
+
generations, then `start` answers `Exhausted`.
|
|
34
|
+
- **Restarts.** A fresh coordinator counts from 1 again, so a ticket that
|
|
35
|
+
outlived a restart could name a new transfer. Either resume the sequence,
|
|
36
|
+
or give each incarnation a scope no earlier one used.
|
|
37
|
+
`Handoff::restored(limits, scope, last_generation)` resumes: it takes the
|
|
38
|
+
scope and what `generation()` answered, an `Option<u64>`, and is `None`
|
|
39
|
+
when a saved value is not a generation of `scope`. The scope is never read
|
|
40
|
+
out of the saved value, so one that lost its top bits, or the `0` a store
|
|
41
|
+
answers for a missing row, cannot land a coordinator in scope zero (`0` is
|
|
42
|
+
no generation there either). "Nothing issued yet" is spelled one way,
|
|
43
|
+
`None`, which is what `generation()` answers then and restores an equal
|
|
44
|
+
fresh coordinator.
|
|
45
|
+
- An idempotent repeat (`Acked::Duplicate`) is answered only from a live
|
|
46
|
+
transfer whose ticket matches, scope included. A ticket whose transfer
|
|
47
|
+
ended is `Stale` even though the coordinator can tell it issued it: it does
|
|
48
|
+
not keep how the transfer ended.
|
|
49
|
+
- Each phase advances only on an explicit acknowledgement from the replica that
|
|
50
|
+
holds the role: `quiesced` (source, with the quiesce point), `drained` (source,
|
|
51
|
+
one in-flight offset at a time), `captured` (source, checkpoint identity),
|
|
52
|
+
`installed` (target, the same identity), `fenced` (the authority's token,
|
|
53
|
+
strictly above the source's), `activated` (target, the same token).
|
|
54
|
+
- Fencing tokens are `lease-machines` `FencingToken`s, re-exported here, and
|
|
55
|
+
they carry their authority's scope. Tokens of two scopes have no order, so a
|
|
56
|
+
transfer reads tokens only inside its source token's scope. `fenced`,
|
|
57
|
+
`activated` and `abort` answer `Unknown` to a token of any other scope,
|
|
58
|
+
whatever its number, and they answer it first: after the clock and the
|
|
59
|
+
ticket, before the transfer's phase, the replica or any recorded token is
|
|
60
|
+
looked at. `Unknown` is the name every crate gives an id that is not of
|
|
61
|
+
the namespace the call reads it in; a foreign token is never folded into
|
|
62
|
+
"older" (`StaleToken`), "not the one recorded" (`Mismatch`) or "not now"
|
|
63
|
+
(`OutOfPhase`). Those three are only ever said of a token of the
|
|
64
|
+
transfer's scope: `StaleToken` when it does not exceed the ones the
|
|
65
|
+
transfer knows, `Mismatch` when a different one is recorded. `start` has
|
|
66
|
+
nothing to compare its source token with: that token names the scope.
|
|
67
|
+
One transfer therefore lives under one authority scope: if
|
|
68
|
+
the authority came back under a new scope before `fenced`, give the
|
|
69
|
+
transfer up with an unfenced `abort` and start it again under a source
|
|
70
|
+
token of the new scope.
|
|
71
|
+
- Drain readiness is an `offset-machines` `Tracker` per transfer, built
|
|
72
|
+
already assigned (`Tracker::assigned`) at the transfer's base: the ticket
|
|
73
|
+
is checked before the tracker is reached, so the tracker keeps one
|
|
74
|
+
generation of its own and never meets another. The phase ends when the contiguous acknowledged prefix
|
|
75
|
+
reaches the quiesce point. `committed` slides the window for drains wider
|
|
76
|
+
than it; `outstanding` lists what is still missing, resumably.
|
|
77
|
+
- `abort` works from every phase and moves to `Rollback`: the source owes
|
|
78
|
+
`resumed`, and the target owes `discarded` once it was asked to install. After
|
|
79
|
+
`fenced`, activation has been ordered and the target may be serving, so `abort`
|
|
80
|
+
demands a token above the activation token and the source resumes under it.
|
|
81
|
+
- `orders(from)` restates what is owed, at most two orders per transfer. Orders
|
|
82
|
+
are derived from state, not queued: nothing overflows, and a pass can stop
|
|
83
|
+
anywhere and resume from `Orders::position()`.
|
|
84
|
+
- Every mutating call takes `now`. An earlier `now` than the last recorded one is
|
|
85
|
+
`ClockRegressed`. Each phase gets `Limits::phase_budget`; `overdue` lists
|
|
86
|
+
transfers past it. That is advice: the coordinator never aborts by itself.
|
|
87
|
+
- **Which answers record the clock.** An honoured call records `now` exactly
|
|
88
|
+
when its answer depends on it: `start`, and every acknowledgement that moves
|
|
89
|
+
the transfer to a new wait (`quiesced`, a `drained` that ends the drain,
|
|
90
|
+
`captured`, `installed`, `fenced`, `abort`), because the new phase's
|
|
91
|
+
deadline is `now + phase_budget`. A `Duplicate`, a `drained` or
|
|
92
|
+
`committed` within the drain, a `resumed` or `discarded` while the rollback
|
|
93
|
+
still waits for the other, and the acknowledgement that ends the transfer
|
|
94
|
+
(`activated`, the last of the rollback) hold whatever the time and record
|
|
95
|
+
nothing. `overdue(now, ..)` is a query.
|
|
96
|
+
- **Values valid by construction.** `Limits::new` (`None` for `per_replica`
|
|
97
|
+
zero), `Ticket::new` (`None` for a zero sequence), `Acked::recorded` and
|
|
98
|
+
`Acked::duplicate` (`None` for a phase no acknowledgement answers),
|
|
99
|
+
`Order::new` (`None` unless only the authority is asked to fence, and it
|
|
100
|
+
is asked nothing else) and `Status::new` (`None` for a view no live
|
|
101
|
+
transfer reports) are what the Ruby binding builds every value through.
|
|
102
|
+
Their fields are private: a `Ticket`, `Order`, `Status` or `Limits` exists
|
|
103
|
+
only as its constructor or the coordinator built it, and is read through
|
|
104
|
+
accessors named after the fields.
|
|
105
|
+
`Phase::is_final` says whether a phase ends a transfer.
|
|
106
|
+
- **No unreachable arms.** Each step carries what its order restates, so an
|
|
107
|
+
order is never missing a field. A transfer is built without a refusal:
|
|
108
|
+
`Tracker::assigned` takes a generation that is never zero, so `start` has
|
|
109
|
+
no arm for a fresh drain tracker refusing. `restored` carries
|
|
110
|
+
`periscope-machines`' `Issuer::restored` whole, whose only refusals are the
|
|
111
|
+
two **Restarts** names (another scope, a zero sequence), so no sequence
|
|
112
|
+
can fall out of reach. Tokens are ranked with
|
|
113
|
+
`FencingToken::order`, which has no answer across scopes: `supersedes`
|
|
114
|
+
answers `Unknown` there, the answer `homed` already gave, and never
|
|
115
|
+
compares raw values of two scopes. One arm remains that the types demand
|
|
116
|
+
and the invariants rule out, a `debug_assert!` with the most conservative
|
|
117
|
+
refusal and nothing changed: the drain tracker refusing an `ack` or a
|
|
118
|
+
`mark_committed` for a reason the transfer rules out (`OutOfPhase`).
|
|
119
|
+
The tracker is asked only under its own current generation, so `Stale`
|
|
120
|
+
cannot come back, but its one `Refusal` type still names it, `Exhausted`,
|
|
121
|
+
and the variant the other call answers.
|
|
122
|
+
Nothing in the crate panics.
|
|
123
|
+
- Every call that can refuse returns `Result<T, Refusal>`. `Refusal` is the one
|
|
124
|
+
enum for "not honoured", and a refused call changes nothing. No public enum
|
|
125
|
+
is `#[non_exhaustive]`: a new variant is a breaking change every caller
|
|
126
|
+
matches on.
|
|
127
|
+
- A network may deliver any acknowledgement twice, so every acknowledgement
|
|
128
|
+
method (`quiesced`, `drained`, `committed`, `captured`, `installed`, `fenced`,
|
|
129
|
+
`activated`, `abort`, `resumed`, `discarded`) returns `Result<Acked, Refusal>`:
|
|
130
|
+
`Acked::Recorded(phase)` the first time, `Acked::Duplicate(phase)` for an
|
|
131
|
+
idempotent repeat. A repeat is honoured, not refused, and changes nothing,
|
|
132
|
+
not even the observed clock.
|
|
133
|
+
- A repeat is answered from what the transfer recorded, for as long as the
|
|
134
|
+
transfer lives, rollback included: `quiesced` with the recorded quiesce
|
|
135
|
+
point, `drained` of an acknowledged or committed offset, `committed` at or
|
|
136
|
+
below the window base, `captured` and `installed` with the recorded
|
|
137
|
+
checkpoint, `fenced` with the recorded token, `abort` during the rollback
|
|
138
|
+
with the same token (or the same absence of one), and a `resumed` or
|
|
139
|
+
`discarded` already recorded or never owed.
|
|
140
|
+
- A replay whose payload differs from the record is not a repeat: a different
|
|
141
|
+
quiesce point, checkpoint, activation token or rollback token is `Mismatch`.
|
|
142
|
+
From the wrong replica it is `WrongReplica`.
|
|
143
|
+
- `OutOfPhase` is what is left: the transfer is not waiting for the
|
|
144
|
+
acknowledgement and never recorded it, because it came too early or because
|
|
145
|
+
the transfer was given up first. `activated` and the acknowledgement that
|
|
146
|
+
ends a rollback free the slot, so their repeats are `Stale` like any other
|
|
147
|
+
finished ticket's.
|
|
148
|
+
- Checks run in one order, and the first that fails is the answer. Every
|
|
149
|
+
acknowledgement: `ClockRegressed`, then the ticket (`Unknown`, `Stale`).
|
|
150
|
+
Then, for the three that take a fencing token:
|
|
151
|
+
|
|
152
|
+
| Call | After the clock and the ticket |
|
|
153
|
+
| --- | --- |
|
|
154
|
+
| `fenced` | `Unknown` (token scope), then `Duplicate` or `Mismatch` against a recorded token, `OutOfPhase`, `StaleToken` |
|
|
155
|
+
| `activated` | `Unknown` (token scope), `OutOfPhase`, `WrongReplica`, `Mismatch` |
|
|
156
|
+
| `abort` | `Unknown` (token scope, when a token is given), then `Duplicate` or `Mismatch` during a rollback, `StaleToken`, `FenceRequired` |
|
|
157
|
+
|
|
158
|
+
```rust
|
|
159
|
+
use core::time::Duration;
|
|
160
|
+
use handoff_machines::{Acked, Action, FencingToken, Handoff, Limits, Phase, Recipient, Refusal};
|
|
161
|
+
|
|
162
|
+
# fn example() -> Option<()> {
|
|
163
|
+
let limits = Limits::new(Duration::from_secs(30), 2)?;
|
|
164
|
+
let mut handoff = Handoff::<8, 4>::new(limits); // 8 transfers, 256-offset drains
|
|
165
|
+
let now = Duration::ZERO;
|
|
166
|
+
let held = FencingToken::from_raw(7)?; // scope zero, sequence 7
|
|
167
|
+
// Partition 42 from replica 1 to replica 2; offsets below 100 are committed.
|
|
168
|
+
let ticket = handoff.start(42, 1, 2, 100, held, now).ok()?;
|
|
169
|
+
let order = handoff.orders(0).next()?;
|
|
170
|
+
assert_eq!((order.to(), order.action()), (Recipient::Replica(1), Action::Quiesce));
|
|
171
|
+
|
|
172
|
+
let acked = |phase| Ok(Acked::Recorded(phase));
|
|
173
|
+
assert_eq!(handoff.quiesced(ticket, 1, 102, now), acked(Phase::Drain));
|
|
174
|
+
assert_eq!(handoff.quiesced(ticket, 1, 102, now), Ok(Acked::Duplicate(Phase::Drain)));
|
|
175
|
+
assert_eq!(handoff.drained(ticket, 1, 101, now), acked(Phase::Drain));
|
|
176
|
+
assert_eq!(handoff.drained(ticket, 1, 101, now), Ok(Acked::Duplicate(Phase::Drain)));
|
|
177
|
+
assert_eq!(handoff.outstanding(ticket, 0).ok()?.next(), Some(100));
|
|
178
|
+
assert_eq!(handoff.drained(ticket, 1, 100, now), acked(Phase::Checkpoint));
|
|
179
|
+
assert_eq!(handoff.captured(ticket, 1, 9, now), acked(Phase::Checkpoint));
|
|
180
|
+
assert_eq!(handoff.installed(ticket, 2, 9, now), acked(Phase::Activate));
|
|
181
|
+
let granted = FencingToken::from_raw(8)?; // from your lease authority
|
|
182
|
+
// A token of another authority's scope has no order against the source's.
|
|
183
|
+
let foreign = FencingToken::from_raw((3 << 48) | 8)?;
|
|
184
|
+
assert_eq!(handoff.fenced(ticket, foreign, now), Err(Refusal::Unknown));
|
|
185
|
+
assert_eq!(handoff.fenced(ticket, held, now), Err(Refusal::StaleToken));
|
|
186
|
+
assert_eq!(handoff.fenced(ticket, granted, now), acked(Phase::Activate));
|
|
187
|
+
assert_eq!(handoff.activated(ticket, 2, granted, now), acked(Phase::Complete));
|
|
188
|
+
assert_eq!(handoff.active(), 0);
|
|
189
|
+
# Some(())
|
|
190
|
+
# }
|
|
191
|
+
# assert_eq!(example(), Some(()));
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## What stays outside
|
|
195
|
+
|
|
196
|
+
1. **Durable replica identities.** Replicas are `u64`s the caller vouches for.
|
|
197
|
+
The coordinator compares them; it cannot tell a restarted replica from an
|
|
198
|
+
impostor, and an acknowledgement is believed if its ticket and role match.
|
|
199
|
+
2. **Serialized fenced activation.** The token passed to `fenced` must come from
|
|
200
|
+
one serialized authority (`lease-machines` models its decisions), and the
|
|
201
|
+
resource must reject lower tokens atomically with each write. The coordinator
|
|
202
|
+
only checks that the token is of the source token's scope and above it. Without resource-side
|
|
203
|
+
fencing, a source that missed `Quiesce` keeps writing.
|
|
204
|
+
3. **Transfer replay protection.** Generations refuse stale acknowledgements
|
|
205
|
+
inside one coordinator lifetime. Across restarts, persist `generation()` before
|
|
206
|
+
exposing a ticket and rebuild with `Handoff::restored`, or build every
|
|
207
|
+
incarnation with a scope of its own. In-flight transfers
|
|
208
|
+
are not restored: start them again under a new generation, and let the
|
|
209
|
+
authority's highest token say who owns a partition that was mid-activation.
|
|
210
|
+
4. **Delivery and timing.** Orders are restated until acknowledged; delivery,
|
|
211
|
+
retries and deduplication at the replicas are the adapter's. Checkpoint bytes,
|
|
212
|
+
their integrity and the source's retirement after `Complete` are too.
|
|
213
|
+
5. **An abort without a token before `fenced` assumes no grant exists.** If the
|
|
214
|
+
authority may already have issued the target a token, report it with `fenced`
|
|
215
|
+
first, then abort with a newer one.
|
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative 'handoff_machines/version'
|
|
4
|
+
|
|
5
|
+
# Every value mirrors the core type of the same name, field for field. Every
|
|
6
|
+
# instant and span (`now`, `phase_budget`, `deadline`) is Integer nanoseconds.
|
|
7
|
+
#
|
|
8
|
+
# The native side is the authority on every value it reads: one of this gem's
|
|
9
|
+
# classes must be exactly that class (a subclass is a TypeError, whatever it
|
|
10
|
+
# holds), and every field is validated again through the core constructor, so
|
|
11
|
+
# a value forged past `initialize` (`Marshal.load`, a bound
|
|
12
|
+
# `Data#initialize`) raises TypeError or RangeError and never reaches the core.
|
|
13
|
+
module HandoffMachines
|
|
14
|
+
|
|
15
|
+
# A fencing token, the lease core's `FencingToken` which the handoff core
|
|
16
|
+
# re-exports: the issuing authority's scope in the top 16 bits of `raw`
|
|
17
|
+
# above a sequence number counted from 1. The coordinator issues none: bring
|
|
18
|
+
# them from your authority. Every method that takes a token reads its `raw`,
|
|
19
|
+
# so the `lease_machines` gem's FencingToken fits as it is, and this gem does
|
|
20
|
+
# not depend on that one; a value that keeps a token (Fence, Activate,
|
|
21
|
+
# Resume, Status) converts it to this class. A bare Integer is not a token:
|
|
22
|
+
# TypeError.
|
|
23
|
+
#
|
|
24
|
+
# Tokens of one scope are ordered; tokens of two scopes are not, so there is
|
|
25
|
+
# no `<` or `<=>`. Compare with `order` and `newer_than?`.
|
|
26
|
+
FencingToken = Data.define(:raw) do
|
|
27
|
+
# The core's `FencingToken::from_raw`. RangeError when the sequence number
|
|
28
|
+
# is zero, which no authority issues.
|
|
29
|
+
def self.from_raw(raw) = new(raw)
|
|
30
|
+
|
|
31
|
+
def initialize(raw:)
|
|
32
|
+
HandoffMachines.__send__(:native_raw, raw)
|
|
33
|
+
super
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# The scope of the authority that issued this token.
|
|
37
|
+
def scope = HandoffMachines.__send__(:native_token_scope, self)
|
|
38
|
+
|
|
39
|
+
# -1, 0 or 1 against a token of the same scope; nil across scopes.
|
|
40
|
+
def order(other) = HandoffMachines.__send__(:native_token_order, self, other)
|
|
41
|
+
|
|
42
|
+
# Whether this token is of `other`'s scope and strictly newer. False across
|
|
43
|
+
# scopes, so its negation does not mean "older or equal".
|
|
44
|
+
def newer_than?(other) = HandoffMachines.__send__(:native_token_newer, self, other)
|
|
45
|
+
end
|
|
46
|
+
# Every value below is valid or does not exist: it is checked at
|
|
47
|
+
# construction through the core constructor of the type it mirrors.
|
|
48
|
+
# TypeError for a value of the wrong type, RangeError for one the core would
|
|
49
|
+
# not build. A value built by hand is held to the same rule as one returned.
|
|
50
|
+
|
|
51
|
+
# Admission and timing limits: how long one phase may last before `overdue`
|
|
52
|
+
# reports the transfer, and how many transfers one replica may take part in.
|
|
53
|
+
# The core's `Limits::new`: `per_replica` is at least 1.
|
|
54
|
+
Limits = Data.define(:phase_budget, :per_replica) do
|
|
55
|
+
def initialize(phase_budget:, per_replica:)
|
|
56
|
+
HandoffMachines.__send__(:__limits, phase_budget, per_replica)
|
|
57
|
+
super
|
|
58
|
+
end
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
# One transfer: the partition and the generation it was issued under.
|
|
62
|
+
# Plain data, so it can travel to a replica and come back in its reply. The
|
|
63
|
+
# generation carries the scope of the coordinator that issued it; a
|
|
64
|
+
# coordinator of another scope answers :unknown to the ticket. The core's
|
|
65
|
+
# `Ticket::new`: a generation with a zero sequence, which no coordinator
|
|
66
|
+
# issues, raises RangeError.
|
|
67
|
+
Ticket = Data.define(:partition, :generation) do
|
|
68
|
+
def initialize(partition:, generation:)
|
|
69
|
+
HandoffMachines.__send__(:__ticket, partition, generation)
|
|
70
|
+
super
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
# The scope of the coordinator that issued this ticket.
|
|
74
|
+
def scope = Handoff.__send__(:native_scope_of, self)
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
# Honoured acknowledgement, recorded for the first time; the transfer now
|
|
78
|
+
# stands at `phase`. The core's `Acked::recorded`: never :quiesce.
|
|
79
|
+
Recorded = Data.define(:phase) do
|
|
80
|
+
def initialize(phase:)
|
|
81
|
+
HandoffMachines.__send__(:__recorded, phase)
|
|
82
|
+
super
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
def duplicate? = false
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
# Honoured idempotent repeat: nothing changed, and the transfer still stands
|
|
89
|
+
# at `phase`, which may be later than the one the acknowledgement first led
|
|
90
|
+
# to. The core's `Acked::duplicate`: never :quiesce, :complete or :aborted.
|
|
91
|
+
Duplicate = Data.define(:phase) do
|
|
92
|
+
def initialize(phase:)
|
|
93
|
+
HandoffMachines.__send__(:__duplicate, phase)
|
|
94
|
+
super
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
def duplicate? = true
|
|
98
|
+
end
|
|
99
|
+
|
|
100
|
+
# Order#to for a replica, by its caller-owned id. The lease authority is
|
|
101
|
+
# the symbol :authority.
|
|
102
|
+
Replica = Data.define(:id) do
|
|
103
|
+
def initialize(id:)
|
|
104
|
+
HandoffMachines.__send__(:__replica, id)
|
|
105
|
+
super
|
|
106
|
+
end
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
# Order#action, one Data per core `Action` variant that carries a field.
|
|
110
|
+
# The two that carry none are the symbols :quiesce and :discard, and only
|
|
111
|
+
# those two are Symbols: a bare :resume is not `Resume.new(nil)`. Offsets
|
|
112
|
+
# and checkpoint ids are Integers in 0...2**64; tokens are converted to
|
|
113
|
+
# this gem's FencingToken.
|
|
114
|
+
Drain = Data.define(:until) do
|
|
115
|
+
def initialize(**field)
|
|
116
|
+
HandoffMachines.__send__(:__drain, field[:until]) if field.key?(:until)
|
|
117
|
+
super
|
|
118
|
+
end
|
|
119
|
+
end
|
|
120
|
+
Capture = Data.define(:at) do
|
|
121
|
+
def initialize(at:)
|
|
122
|
+
HandoffMachines.__send__(:__capture, at)
|
|
123
|
+
super
|
|
124
|
+
end
|
|
125
|
+
end
|
|
126
|
+
Install = Data.define(:checkpoint) do
|
|
127
|
+
def initialize(checkpoint:)
|
|
128
|
+
HandoffMachines.__send__(:__install, checkpoint)
|
|
129
|
+
super
|
|
130
|
+
end
|
|
131
|
+
end
|
|
132
|
+
Fence = Data.define(:above) do
|
|
133
|
+
def initialize(above:) = super(above: HandoffMachines.__send__(:__token, above))
|
|
134
|
+
end
|
|
135
|
+
Activate = Data.define(:token) do
|
|
136
|
+
def initialize(token:) = super(token: HandoffMachines.__send__(:__token, token))
|
|
137
|
+
end
|
|
138
|
+
# `token` is nil when the rollback was not fenced; anything else is checked
|
|
139
|
+
# as a token, so `false` is a TypeError.
|
|
140
|
+
Resume = Data.define(:token) do
|
|
141
|
+
def initialize(token:) = super(token: token.nil? ? nil : HandoffMachines.__send__(:__token, token))
|
|
142
|
+
end
|
|
143
|
+
|
|
144
|
+
# One outstanding instruction: who must act (`to`, a Replica or
|
|
145
|
+
# :authority) and what they must do. The core's `Order::new`: only the
|
|
146
|
+
# authority is asked to fence, and it is asked nothing else.
|
|
147
|
+
Order = Data.define(:ticket, :to, :action) do
|
|
148
|
+
def initialize(ticket:, to:, action:)
|
|
149
|
+
HandoffMachines.__send__(:__order, ticket, to, action)
|
|
150
|
+
super
|
|
151
|
+
end
|
|
152
|
+
end
|
|
153
|
+
|
|
154
|
+
# A read-only view of one active transfer. The core's `Status::checked`:
|
|
155
|
+
# a ticket some coordinator issues, two different replicas, a phase that is
|
|
156
|
+
# not final, and only what that phase has recorded.
|
|
157
|
+
Status = Data.define(
|
|
158
|
+
:ticket, :source, :target, :phase, :base, :until, :checkpoint, :token, :deadline
|
|
159
|
+
) do
|
|
160
|
+
# `until` is a keyword, so the fields arrive as a Hash. A missing or
|
|
161
|
+
# unknown one is Data's own ArgumentError.
|
|
162
|
+
def initialize(**fields)
|
|
163
|
+
return super unless fields.keys.sort == members.sort
|
|
164
|
+
|
|
165
|
+
super(**fields.merge(token: HandoffMachines.__send__(:__status, *fields.values_at(*members))))
|
|
166
|
+
end
|
|
167
|
+
end
|
|
168
|
+
|
|
169
|
+
# Sealed: no subclass can skip the checks above by overriding `initialize`,
|
|
170
|
+
# and no bare `allocate` builds a value that never ran them. Ruby still
|
|
171
|
+
# binds a subclass constant before `inherited` raises; the native side
|
|
172
|
+
# refuses its instances.
|
|
173
|
+
[FencingToken, Limits, Ticket, Recorded, Duplicate, Replica, Drain, Capture, Install, Fence, Activate, Resume,
|
|
174
|
+
Order, Status].each do |value|
|
|
175
|
+
value.singleton_class.undef_method(:allocate)
|
|
176
|
+
value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
|
|
177
|
+
end
|
|
178
|
+
|
|
179
|
+
# The action Data a native row names, by the action's name.
|
|
180
|
+
ACTIONS = { drain: Drain, capture: Capture, install: Install, fence: Fence, activate: Activate,
|
|
181
|
+
resume: Resume }.freeze
|
|
182
|
+
# The actions whose field is a fencing token.
|
|
183
|
+
TOKENED = %i[fence activate resume].freeze
|
|
184
|
+
private_constant :ACTIONS, :TOKENED
|
|
185
|
+
end
|
|
186
|
+
|
|
187
|
+
# Native is required: no algorithm fallback. It resolves the classes above
|
|
188
|
+
# once, here.
|
|
189
|
+
require 'handoff_machines_native/handoff_machines_native'
|
|
190
|
+
|
|
191
|
+
module HandoffMachines
|
|
192
|
+
class << self
|
|
193
|
+
private :native_raw, :native_token_scope, :native_token_order, :native_token_newer,
|
|
194
|
+
:__limits, :__ticket, :__recorded, :__duplicate, :__replica, :__drain, :__capture, :__install,
|
|
195
|
+
:__token, :__order, :__status
|
|
196
|
+
end
|
|
197
|
+
|
|
198
|
+
# The core's `Handoff`. Every mutating call (start and each
|
|
199
|
+
# acknowledgement) reads its arguments before the core is asked, decides on
|
|
200
|
+
# a copy, builds the answer (a Ticket, a Recorded or Duplicate: their `new`
|
|
201
|
+
# runs), then keeps the copy only if this coordinator is still unfrozen
|
|
202
|
+
# (FrozenError) and unchanged (RuntimeError: a re-entrant call changed it).
|
|
203
|
+
# Either way, a raise means nothing was applied. A refusal is a Symbol.
|
|
204
|
+
class Handoff
|
|
205
|
+
class << self
|
|
206
|
+
# A fresh generation namespace in scope zero.
|
|
207
|
+
def new(limits) = with_scope(limits, 0)
|
|
208
|
+
|
|
209
|
+
# A fresh generation namespace whose generations carry `scope`, an
|
|
210
|
+
# Integer in 0..65_535. Give each coordinator its own.
|
|
211
|
+
def with_scope(limits, scope) = native_with_scope(limits, scope)
|
|
212
|
+
|
|
213
|
+
# Generations of `scope` above `last_generation`: what #generation
|
|
214
|
+
# answered on the previous coordinator of this namespace, nil when it had
|
|
215
|
+
# issued nothing. RangeError when `last_generation` is not a generation
|
|
216
|
+
# of `scope`: another scope's, one that lost its top bits, or a bare 0
|
|
217
|
+
# (no generation in any scope).
|
|
218
|
+
def restored(limits, scope, last_generation) = native_restored(limits, scope, last_generation)
|
|
219
|
+
|
|
220
|
+
private :native_with_scope, :native_restored, :native_scope_of
|
|
221
|
+
end
|
|
222
|
+
|
|
223
|
+
def limits
|
|
224
|
+
Limits.new(*native_limits)
|
|
225
|
+
end
|
|
226
|
+
|
|
227
|
+
def status(partition)
|
|
228
|
+
head, tail = native_status(partition)
|
|
229
|
+
return unless head
|
|
230
|
+
|
|
231
|
+
granted = tail[3] && FencingToken.new(tail[3])
|
|
232
|
+
Status.new(Ticket.new(head[0], head[1]), *head[2..], *tail[0..2], granted, tail[4])
|
|
233
|
+
end
|
|
234
|
+
|
|
235
|
+
# At most `limit` orders from position `from` (zero to begin), and the
|
|
236
|
+
# position to resume at.
|
|
237
|
+
def orders(from, limit)
|
|
238
|
+
rows, position = native_orders(from, limit)
|
|
239
|
+
[rows.map { |row| order(*row) }, position]
|
|
240
|
+
end
|
|
241
|
+
|
|
242
|
+
# At most `limit` overdue tickets from slot `from` (zero to begin), and the
|
|
243
|
+
# slot to resume at.
|
|
244
|
+
def overdue(now, from, limit)
|
|
245
|
+
rows, position = native_overdue(now, from, limit)
|
|
246
|
+
[rows.map { |row| Ticket.new(*row) }, position]
|
|
247
|
+
end
|
|
248
|
+
|
|
249
|
+
private
|
|
250
|
+
|
|
251
|
+
def order(partition, generation, recipient, name, field)
|
|
252
|
+
to = recipient.is_a?(Symbol) ? recipient : Replica.new(recipient)
|
|
253
|
+
Order.new(Ticket.new(partition, generation), to, action(name, field))
|
|
254
|
+
end
|
|
255
|
+
|
|
256
|
+
# The action Data or Symbol a native row names.
|
|
257
|
+
def action(name, field)
|
|
258
|
+
return name unless ACTIONS.key?(name)
|
|
259
|
+
|
|
260
|
+
ACTIONS.fetch(name).new(field && TOKENED.include?(name) ? FencingToken.new(field) : field)
|
|
261
|
+
end
|
|
262
|
+
end
|
|
263
|
+
end
|
|
Binary file
|