causal_machines 0.6.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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +84 -0
- data/Cargo.lock +307 -0
- data/Cargo.toml +27 -0
- data/LICENSE.txt +21 -0
- data/README.md +288 -0
- data/ext/causal_machines_native/core/CHANGELOG.md +59 -0
- data/ext/causal_machines_native/core/Cargo.toml +17 -0
- data/ext/causal_machines_native/core/README.md +118 -0
- data/ext/causal_machines_native/core/src/lib.rs +53 -0
- data/ext/causal_machines_native/core/src/tracker.rs +626 -0
- data/ext/causal_machines_native/core/src/vector.rs +200 -0
- data/ext/causal_machines_native/extconf.rb +2 -0
- data/ext/causal_machines_native/ffi/Cargo.toml +21 -0
- data/ext/causal_machines_native/ffi/extconf.rb +14 -0
- data/ext/causal_machines_native/ffi/src/classes.rs +43 -0
- data/ext/causal_machines_native/ffi/src/init.rs +56 -0
- data/ext/causal_machines_native/ffi/src/lib.rs +247 -0
- data/ext/causal_machines_native/ffi/src/values.rs +108 -0
- data/ext/causal_machines_native/ffi/src/vectors.rs +152 -0
- data/lib/causal_machines/version.rb +5 -0
- data/lib/causal_machines.rb +93 -0
- data/sig/causal_machines.rbs +148 -0
- metadata +89 -0
|
@@ -0,0 +1,626 @@
|
|
|
1
|
+
//! Causal-delivery readiness for one replica.
|
|
2
|
+
|
|
3
|
+
use crate::{Membership, Refusal, ReplicaId, VersionVector};
|
|
4
|
+
|
|
5
|
+
/// The causal metadata one message travels with.
|
|
6
|
+
///
|
|
7
|
+
/// `clock` is the sender's version vector at the moment it sent: its own
|
|
8
|
+
/// entry numbers this message, every other entry names what the sender had
|
|
9
|
+
/// delivered before sending.
|
|
10
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
11
|
+
pub struct Stamp<const N: usize> {
|
|
12
|
+
generation: u64,
|
|
13
|
+
sender: ReplicaId,
|
|
14
|
+
clock: VersionVector<N>,
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
impl<const N: usize> Stamp<N> {
|
|
18
|
+
/// A stamp from its parts.
|
|
19
|
+
#[must_use]
|
|
20
|
+
pub const fn new(generation: u64, sender: ReplicaId, clock: VersionVector<N>) -> Self {
|
|
21
|
+
Self {
|
|
22
|
+
generation,
|
|
23
|
+
sender,
|
|
24
|
+
clock,
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/// Membership generation the stamp was issued under.
|
|
29
|
+
#[must_use]
|
|
30
|
+
pub const fn generation(&self) -> u64 {
|
|
31
|
+
self.generation
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/// Replica that sent the message.
|
|
35
|
+
#[must_use]
|
|
36
|
+
pub const fn sender(&self) -> ReplicaId {
|
|
37
|
+
self.sender
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/// Sender's version vector, including this message.
|
|
41
|
+
#[must_use]
|
|
42
|
+
pub const fn clock(&self) -> &VersionVector<N> {
|
|
43
|
+
&self.clock
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/// Whether a stamped message may be delivered now.
|
|
48
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
49
|
+
pub enum Readiness {
|
|
50
|
+
/// Every dependency is delivered and this is the sender's next message.
|
|
51
|
+
Deliverable,
|
|
52
|
+
/// The sender's counter is already covered by the delivered clock.
|
|
53
|
+
Duplicate,
|
|
54
|
+
/// At least one dependency is undelivered.
|
|
55
|
+
Missing,
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/// What an honoured [`Causal::receive`] did with a stamp.
|
|
59
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
60
|
+
pub enum Receipt {
|
|
61
|
+
/// Delivered: the delivered clock advanced.
|
|
62
|
+
Delivered,
|
|
63
|
+
/// Dependencies are missing; the stamp is parked until they arrive.
|
|
64
|
+
Held,
|
|
65
|
+
/// An idempotent repeat: the same stamp is already parked. Nothing
|
|
66
|
+
/// changed.
|
|
67
|
+
AlreadyHeld,
|
|
68
|
+
/// An idempotent repeat: already delivered. Nothing changed.
|
|
69
|
+
Duplicate,
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/// What an honoured [`Causal::forget`] did.
|
|
73
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
74
|
+
pub enum Forgetting {
|
|
75
|
+
/// The parked stamp was dropped; its hold slot is free.
|
|
76
|
+
Forgotten,
|
|
77
|
+
/// No such stamp was parked: an idempotent repeat that changed nothing.
|
|
78
|
+
NotHeld,
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/// What an honoured [`Causal::absorb`] did.
|
|
82
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
83
|
+
pub enum Absorbing {
|
|
84
|
+
/// The clock taught something new: the delivered clock advanced.
|
|
85
|
+
Absorbed,
|
|
86
|
+
/// An idempotent repeat: the delivered clock already covers the clock.
|
|
87
|
+
/// Nothing changed.
|
|
88
|
+
AlreadyCovered,
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/// A parked stamp leaving the hold table.
|
|
92
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
93
|
+
pub enum Release<const N: usize> {
|
|
94
|
+
/// Its dependencies arrived; it is now delivered.
|
|
95
|
+
Deliver(Stamp<N>),
|
|
96
|
+
/// The delivered clock already covers it; drop the payload.
|
|
97
|
+
Obsolete(Stamp<N>),
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/// A run of undelivered messages from one replica, inclusive at both ends.
|
|
101
|
+
///
|
|
102
|
+
/// `Gap::default()` is a placeholder for pre-filling an output buffer: its
|
|
103
|
+
/// `from` is 0, and counters start at 1, so [`Causal::missing`] never emits it
|
|
104
|
+
/// and [`Gap::new`] never builds it.
|
|
105
|
+
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
|
|
106
|
+
pub struct Gap {
|
|
107
|
+
replica: ReplicaId,
|
|
108
|
+
from: u64,
|
|
109
|
+
through: u64,
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
impl Gap {
|
|
113
|
+
/// A gap from its parts, as [`Causal::missing`] emits it.
|
|
114
|
+
///
|
|
115
|
+
/// Returns `None` when `from` is 0 (counters start at 1) or `from` is
|
|
116
|
+
/// past `through`.
|
|
117
|
+
#[must_use]
|
|
118
|
+
pub const fn new(replica: ReplicaId, from: u64, through: u64) -> Option<Self> {
|
|
119
|
+
if from == 0 || from > through {
|
|
120
|
+
return None;
|
|
121
|
+
}
|
|
122
|
+
Some(Self {
|
|
123
|
+
replica,
|
|
124
|
+
from,
|
|
125
|
+
through,
|
|
126
|
+
})
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/// Replica whose messages are missing.
|
|
130
|
+
#[must_use]
|
|
131
|
+
pub const fn replica(&self) -> ReplicaId {
|
|
132
|
+
self.replica
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/// First missing counter.
|
|
136
|
+
#[must_use]
|
|
137
|
+
pub const fn from(&self) -> u64 {
|
|
138
|
+
self.from
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/// Last missing counter.
|
|
142
|
+
#[must_use]
|
|
143
|
+
pub const fn through(&self) -> u64 {
|
|
144
|
+
self.through
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/// One bounded page of a missing-dependency listing.
|
|
149
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
150
|
+
pub struct Page {
|
|
151
|
+
gaps: usize,
|
|
152
|
+
next: Option<usize>,
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
impl Page {
|
|
156
|
+
/// A page as [`Causal::missing`] answers it for `N` membership slots.
|
|
157
|
+
///
|
|
158
|
+
/// Each gap comes from its own slot, and a page that stops early stops at
|
|
159
|
+
/// the slot it could not write, after the slots it did. So `None` when
|
|
160
|
+
/// `gaps` exceeds `N`, `next` is not a slot below `N`, or `gaps`
|
|
161
|
+
/// exceeds `next`.
|
|
162
|
+
#[must_use]
|
|
163
|
+
pub const fn new<const N: usize>(gaps: usize, next: Option<usize>) -> Option<Self> {
|
|
164
|
+
let fits = match next {
|
|
165
|
+
Some(slot) => slot < N && gaps <= slot,
|
|
166
|
+
None => gaps <= N,
|
|
167
|
+
};
|
|
168
|
+
if fits {
|
|
169
|
+
Some(Self { gaps, next })
|
|
170
|
+
} else {
|
|
171
|
+
None
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/// Gaps written to the front of the output buffer.
|
|
176
|
+
#[must_use]
|
|
177
|
+
pub const fn gaps(&self) -> usize {
|
|
178
|
+
self.gaps
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/// Cursor to pass to the next call, or `None` when the listing is done.
|
|
182
|
+
#[must_use]
|
|
183
|
+
pub const fn next(&self) -> Option<usize> {
|
|
184
|
+
self.next
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
189
|
+
struct Parked<const N: usize> {
|
|
190
|
+
slot: usize,
|
|
191
|
+
counter: u64,
|
|
192
|
+
stamp: Stamp<N>,
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
impl<const N: usize> Parked<N> {
|
|
196
|
+
/// Whether this is the sender's message numbered `counter` from `slot`.
|
|
197
|
+
const fn numbers(&self, slot: usize, counter: u64) -> bool {
|
|
198
|
+
self.slot == slot && self.counter == counter
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/// One replica's causal-delivery state: `N` membership slots, `P` hold slots.
|
|
203
|
+
///
|
|
204
|
+
/// Tracks the delivered clock and parks the stamps of messages that arrived
|
|
205
|
+
/// ahead of their dependencies. It never sees a payload.
|
|
206
|
+
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
207
|
+
pub struct Causal<const N: usize, const P: usize> {
|
|
208
|
+
members: Membership<N>,
|
|
209
|
+
local: usize,
|
|
210
|
+
replica: ReplicaId,
|
|
211
|
+
generation: u64,
|
|
212
|
+
delivered: VersionVector<N>,
|
|
213
|
+
parked: [Option<Parked<N>>; P],
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
impl<const N: usize, const P: usize> Causal<N, P> {
|
|
217
|
+
/// A replica that has delivered nothing.
|
|
218
|
+
///
|
|
219
|
+
/// Returns `None` when `local` is not in `members`.
|
|
220
|
+
#[must_use]
|
|
221
|
+
pub fn new(members: Membership<N>, local: ReplicaId, generation: u64) -> Option<Self> {
|
|
222
|
+
Self::restore(members, local, generation, VersionVector::new())
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/// A replica resuming from a persisted delivered clock.
|
|
226
|
+
///
|
|
227
|
+
/// Returns `None` when `local` is not in `members` or `delivered` counts
|
|
228
|
+
/// a slot outside them.
|
|
229
|
+
#[must_use]
|
|
230
|
+
pub fn restore(
|
|
231
|
+
members: Membership<N>,
|
|
232
|
+
local: ReplicaId,
|
|
233
|
+
generation: u64,
|
|
234
|
+
delivered: VersionVector<N>,
|
|
235
|
+
) -> Option<Self> {
|
|
236
|
+
if !members.admits(&delivered) {
|
|
237
|
+
return None;
|
|
238
|
+
}
|
|
239
|
+
Some(Self {
|
|
240
|
+
local: members.slot(local)?,
|
|
241
|
+
replica: local,
|
|
242
|
+
members,
|
|
243
|
+
generation,
|
|
244
|
+
delivered,
|
|
245
|
+
parked: [None; P],
|
|
246
|
+
})
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/// The fixed membership.
|
|
250
|
+
#[must_use]
|
|
251
|
+
pub const fn membership(&self) -> &Membership<N> {
|
|
252
|
+
&self.members
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/// The replica this state belongs to.
|
|
256
|
+
#[must_use]
|
|
257
|
+
pub const fn local(&self) -> ReplicaId {
|
|
258
|
+
self.replica
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/// Membership generation this replica accepts stamps from.
|
|
262
|
+
#[must_use]
|
|
263
|
+
pub const fn generation(&self) -> u64 {
|
|
264
|
+
self.generation
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/// Everything delivered here so far, own sends included.
|
|
268
|
+
#[must_use]
|
|
269
|
+
pub const fn clock(&self) -> &VersionVector<N> {
|
|
270
|
+
&self.delivered
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/// Number of parked stamps.
|
|
274
|
+
#[must_use]
|
|
275
|
+
pub fn held(&self) -> usize {
|
|
276
|
+
self.parked.iter().flatten().count()
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/// Number of hold slots.
|
|
280
|
+
#[must_use]
|
|
281
|
+
pub const fn capacity(&self) -> usize {
|
|
282
|
+
P
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/// Numbers a new local message and returns its stamp.
|
|
286
|
+
///
|
|
287
|
+
/// The message counts as delivered here from this moment.
|
|
288
|
+
///
|
|
289
|
+
/// # Errors
|
|
290
|
+
///
|
|
291
|
+
/// [`Refusal::Exhausted`] once the local counter is `u64::MAX`.
|
|
292
|
+
pub fn stamp(&mut self) -> Result<Stamp<N>, Refusal> {
|
|
293
|
+
self.delivered.increment(self.local)?;
|
|
294
|
+
Ok(Stamp::new(self.generation, self.replica, self.delivered))
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/// Whether `stamp` could be delivered now. Changes nothing.
|
|
298
|
+
///
|
|
299
|
+
/// It answers what [`Causal::receive`] would do with the stamp, short of
|
|
300
|
+
/// the hold table being full.
|
|
301
|
+
///
|
|
302
|
+
/// # Errors
|
|
303
|
+
///
|
|
304
|
+
/// In this order: [`Refusal::StaleGeneration`] or
|
|
305
|
+
/// [`Refusal::FutureGeneration`], [`Refusal::UnknownMember`] for the
|
|
306
|
+
/// sender, [`Refusal::Malformed`], and [`Refusal::Conflict`] when a
|
|
307
|
+
/// different stamp with the same sender and counter is parked, whatever
|
|
308
|
+
/// the readiness of either.
|
|
309
|
+
pub fn check(&self, stamp: &Stamp<N>) -> Result<Readiness, Refusal> {
|
|
310
|
+
self.classify(stamp).map(|(_, _, readiness)| readiness)
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/// Delivers `stamp` if it is ready, parks it if it is not.
|
|
314
|
+
///
|
|
315
|
+
/// A stamp that is already delivered or already parked is honoured again
|
|
316
|
+
/// and changes nothing. When the very stamp being delivered is also
|
|
317
|
+
/// parked, because its dependencies arrived and it was received again
|
|
318
|
+
/// before [`Causal::release`] was called, the parked copy leaves the hold
|
|
319
|
+
/// table with it: it is the same message, delivered once.
|
|
320
|
+
///
|
|
321
|
+
/// A parked stamp is never dropped or replaced for a different one. A
|
|
322
|
+
/// stamp whose sender and counter match a parked stamp but whose clock
|
|
323
|
+
/// does not is refused whether it would have been delivered, parked or
|
|
324
|
+
/// called a duplicate: the two cannot both be the sender's message, and
|
|
325
|
+
/// the tracker cannot tell which is. [`Causal::forget`] the parked one to
|
|
326
|
+
/// take the other.
|
|
327
|
+
///
|
|
328
|
+
/// # Errors
|
|
329
|
+
///
|
|
330
|
+
/// As [`Causal::check`], [`Refusal::Conflict`] included, plus
|
|
331
|
+
/// [`Refusal::Full`] when the stamp must wait and no hold slot is free.
|
|
332
|
+
/// A refused stamp changes nothing.
|
|
333
|
+
pub fn receive(&mut self, stamp: &Stamp<N>) -> Result<Receipt, Refusal> {
|
|
334
|
+
let (slot, counter, readiness) = self.classify(stamp)?;
|
|
335
|
+
match readiness {
|
|
336
|
+
Readiness::Duplicate => Ok(Receipt::Duplicate),
|
|
337
|
+
Readiness::Deliverable => {
|
|
338
|
+
if !advance(&mut self.delivered, slot, counter) {
|
|
339
|
+
return Err(Refusal::Malformed);
|
|
340
|
+
}
|
|
341
|
+
// `classify` refused any other stamp: a parked one is this one.
|
|
342
|
+
self.remove(slot, counter);
|
|
343
|
+
Ok(Receipt::Delivered)
|
|
344
|
+
}
|
|
345
|
+
Readiness::Missing => self.park(slot, counter, stamp),
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
/// Takes one parked stamp that no longer needs to wait.
|
|
350
|
+
///
|
|
351
|
+
/// Stamps the delivered clock already covers come out first as
|
|
352
|
+
/// [`Release::Obsolete`], lowest slot then lowest counter. Then ready
|
|
353
|
+
/// stamps come out as [`Release::Deliver`], lowest slot first, each
|
|
354
|
+
/// advancing the delivered clock. Call until `None`, which is a drain's
|
|
355
|
+
/// "nothing is ready" and not a refusal; it changes nothing.
|
|
356
|
+
pub fn release(&mut self) -> Option<Release<N>> {
|
|
357
|
+
let (delivered, len) = (&mut self.delivered, self.members.len());
|
|
358
|
+
if let Some((entry, parked)) = pick(&mut self.parked, |parked| {
|
|
359
|
+
parked.counter <= seen(delivered, parked.slot)
|
|
360
|
+
}) {
|
|
361
|
+
*entry = None;
|
|
362
|
+
return Some(Release::Obsolete(parked.stamp));
|
|
363
|
+
}
|
|
364
|
+
let (entry, parked) = pick(&mut self.parked, |parked| {
|
|
365
|
+
!blocked(delivered, len, parked.slot, &parked.stamp.clock)
|
|
366
|
+
})?;
|
|
367
|
+
if !advance(delivered, parked.slot, parked.counter) {
|
|
368
|
+
return None;
|
|
369
|
+
}
|
|
370
|
+
*entry = None;
|
|
371
|
+
Some(Release::Deliver(parked.stamp))
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/// Drops the parked stamp numbered `counter` from `sender`.
|
|
375
|
+
///
|
|
376
|
+
/// This is the only call that discards a parked stamp without handing it
|
|
377
|
+
/// back, and it does so by name: it is how a caller resolves a
|
|
378
|
+
/// [`Refusal::Conflict`] in favour of the stamp that was refused.
|
|
379
|
+
///
|
|
380
|
+
/// [`Forgetting::NotHeld`] is an idempotent repeat: no such stamp is
|
|
381
|
+
/// parked, which is what the caller asked for, so nothing changes.
|
|
382
|
+
///
|
|
383
|
+
/// # Errors
|
|
384
|
+
///
|
|
385
|
+
/// [`Refusal::UnknownMember`] when `sender` is not in the membership.
|
|
386
|
+
pub fn forget(&mut self, sender: ReplicaId, counter: u64) -> Result<Forgetting, Refusal> {
|
|
387
|
+
let slot = self.members.slot(sender).ok_or(Refusal::UnknownMember)?;
|
|
388
|
+
Ok(if self.remove(slot, counter) {
|
|
389
|
+
Forgetting::Forgotten
|
|
390
|
+
} else {
|
|
391
|
+
Forgetting::NotHeld
|
|
392
|
+
})
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
/// Lists what must be delivered before `stamp`, one bounded page a call.
|
|
396
|
+
///
|
|
397
|
+
/// Start with `cursor` 0 and pass each page's `next` back until it is
|
|
398
|
+
/// `None`. Gaps are measured against the delivered clock; a parked stamp
|
|
399
|
+
/// does not close one. A deliverable or duplicate stamp lists nothing.
|
|
400
|
+
///
|
|
401
|
+
/// A cursor is a membership slot: the listing resumes at that slot. Every
|
|
402
|
+
/// `next` the tracker hands out is one, and 0 always is, so a cursor past
|
|
403
|
+
/// the last slot is one it never issued and is refused.
|
|
404
|
+
///
|
|
405
|
+
/// The first [`Page::gaps`] entries of `out` are written; the rest are
|
|
406
|
+
/// left untouched. Build the buffer as `[Gap::default(); K]`.
|
|
407
|
+
///
|
|
408
|
+
/// # Errors
|
|
409
|
+
///
|
|
410
|
+
/// As [`Causal::check`], [`Refusal::Conflict`] included, then
|
|
411
|
+
/// [`Refusal::UnknownMember`] when `cursor` is not a membership slot. A
|
|
412
|
+
/// refusal writes nothing to `out`.
|
|
413
|
+
pub fn missing(
|
|
414
|
+
&self,
|
|
415
|
+
stamp: &Stamp<N>,
|
|
416
|
+
cursor: usize,
|
|
417
|
+
out: &mut [Gap],
|
|
418
|
+
) -> Result<Page, Refusal> {
|
|
419
|
+
let (sender, _, readiness) = self.classify(stamp)?;
|
|
420
|
+
if cursor >= self.members.len() {
|
|
421
|
+
return Err(Refusal::UnknownMember);
|
|
422
|
+
}
|
|
423
|
+
let mut page = Page {
|
|
424
|
+
gaps: 0,
|
|
425
|
+
next: None,
|
|
426
|
+
};
|
|
427
|
+
if readiness != Readiness::Missing {
|
|
428
|
+
return Ok(page);
|
|
429
|
+
}
|
|
430
|
+
for (slot, replica) in self.members.ids().iter().enumerate().skip(cursor) {
|
|
431
|
+
let Some((from, through)) = gap(&self.delivered, slot, sender, &stamp.clock) else {
|
|
432
|
+
continue;
|
|
433
|
+
};
|
|
434
|
+
let Some(entry) = out.get_mut(page.gaps) else {
|
|
435
|
+
page.next = Some(slot);
|
|
436
|
+
break;
|
|
437
|
+
};
|
|
438
|
+
*entry = Gap {
|
|
439
|
+
replica: *replica,
|
|
440
|
+
from,
|
|
441
|
+
through,
|
|
442
|
+
};
|
|
443
|
+
page.gaps += 1;
|
|
444
|
+
}
|
|
445
|
+
Ok(page)
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
/// Folds a clock learned elsewhere into the delivered clock.
|
|
449
|
+
///
|
|
450
|
+
/// For state transfer: after installing a snapshot that already reflects
|
|
451
|
+
/// `clock`, those messages count as delivered. Parked stamps this covers
|
|
452
|
+
/// leave through [`Causal::release`] as obsolete.
|
|
453
|
+
///
|
|
454
|
+
/// [`Absorbing::AlreadyCovered`] is an idempotent repeat: the delivered
|
|
455
|
+
/// clock already dominates `clock`, so nothing changes.
|
|
456
|
+
///
|
|
457
|
+
/// # Errors
|
|
458
|
+
///
|
|
459
|
+
/// Generation refusals, or [`Refusal::Malformed`] when `clock` counts a
|
|
460
|
+
/// slot outside the membership.
|
|
461
|
+
pub fn absorb(
|
|
462
|
+
&mut self,
|
|
463
|
+
generation: u64,
|
|
464
|
+
clock: &VersionVector<N>,
|
|
465
|
+
) -> Result<Absorbing, Refusal> {
|
|
466
|
+
self.admit(generation)?;
|
|
467
|
+
if !self.members.admits(clock) {
|
|
468
|
+
return Err(Refusal::Malformed);
|
|
469
|
+
}
|
|
470
|
+
if self.delivered.dominates(clock) {
|
|
471
|
+
return Ok(Absorbing::AlreadyCovered);
|
|
472
|
+
}
|
|
473
|
+
self.delivered.merge(clock);
|
|
474
|
+
Ok(Absorbing::Absorbed)
|
|
475
|
+
}
|
|
476
|
+
|
|
477
|
+
const fn admit(&self, generation: u64) -> Result<(), Refusal> {
|
|
478
|
+
if generation < self.generation {
|
|
479
|
+
Err(Refusal::StaleGeneration)
|
|
480
|
+
} else if generation > self.generation {
|
|
481
|
+
Err(Refusal::FutureGeneration)
|
|
482
|
+
} else {
|
|
483
|
+
Ok(())
|
|
484
|
+
}
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
fn classify(&self, stamp: &Stamp<N>) -> Result<(usize, u64, Readiness), Refusal> {
|
|
488
|
+
self.admit(stamp.generation)?;
|
|
489
|
+
let slot = self
|
|
490
|
+
.members
|
|
491
|
+
.slot(stamp.sender)
|
|
492
|
+
.ok_or(Refusal::UnknownMember)?;
|
|
493
|
+
if !self.members.admits(&stamp.clock) {
|
|
494
|
+
return Err(Refusal::Malformed);
|
|
495
|
+
}
|
|
496
|
+
let Some(counter) = stamp.clock.get(slot) else {
|
|
497
|
+
debug_assert!(false, "a sender's slot is a membership slot");
|
|
498
|
+
return Err(Refusal::Malformed);
|
|
499
|
+
};
|
|
500
|
+
if counter == 0 {
|
|
501
|
+
return Err(Refusal::Malformed);
|
|
502
|
+
}
|
|
503
|
+
if self.conflicts(slot, counter, stamp) {
|
|
504
|
+
return Err(Refusal::Conflict);
|
|
505
|
+
}
|
|
506
|
+
let readiness = if counter <= seen(&self.delivered, slot) {
|
|
507
|
+
Readiness::Duplicate
|
|
508
|
+
} else if blocked(&self.delivered, self.members.len(), slot, &stamp.clock) {
|
|
509
|
+
Readiness::Missing
|
|
510
|
+
} else {
|
|
511
|
+
Readiness::Deliverable
|
|
512
|
+
};
|
|
513
|
+
Ok((slot, counter, readiness))
|
|
514
|
+
}
|
|
515
|
+
|
|
516
|
+
/// Whether a parked stamp numbers the same message as `stamp` but is not
|
|
517
|
+
/// `stamp`. At most one stamp is parked per sender and counter.
|
|
518
|
+
fn conflicts(&self, slot: usize, counter: u64, stamp: &Stamp<N>) -> bool {
|
|
519
|
+
self.parked
|
|
520
|
+
.iter()
|
|
521
|
+
.flatten()
|
|
522
|
+
.any(|parked| parked.numbers(slot, counter) && parked.stamp != *stamp)
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
fn holds(&self, slot: usize, counter: u64) -> bool {
|
|
526
|
+
self.parked
|
|
527
|
+
.iter()
|
|
528
|
+
.flatten()
|
|
529
|
+
.any(|parked| parked.numbers(slot, counter))
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
/// Drops the parked stamp numbered `counter` from `slot`, if there is
|
|
533
|
+
/// one, and says whether there was.
|
|
534
|
+
fn remove(&mut self, slot: usize, counter: u64) -> bool {
|
|
535
|
+
let Some(entry) = self
|
|
536
|
+
.parked
|
|
537
|
+
.iter_mut()
|
|
538
|
+
.find(|entry| entry.is_some_and(|parked| parked.numbers(slot, counter)))
|
|
539
|
+
else {
|
|
540
|
+
return false;
|
|
541
|
+
};
|
|
542
|
+
*entry = None;
|
|
543
|
+
true
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
fn park(&mut self, slot: usize, counter: u64, stamp: &Stamp<N>) -> Result<Receipt, Refusal> {
|
|
547
|
+
// `classify` refused any other stamp: a parked one is this one.
|
|
548
|
+
if self.holds(slot, counter) {
|
|
549
|
+
return Ok(Receipt::AlreadyHeld);
|
|
550
|
+
}
|
|
551
|
+
let free = self
|
|
552
|
+
.parked
|
|
553
|
+
.iter_mut()
|
|
554
|
+
.find(|entry| entry.is_none())
|
|
555
|
+
.ok_or(Refusal::Full)?;
|
|
556
|
+
*free = Some(Parked {
|
|
557
|
+
slot,
|
|
558
|
+
counter,
|
|
559
|
+
stamp: *stamp,
|
|
560
|
+
});
|
|
561
|
+
Ok(Receipt::Held)
|
|
562
|
+
}
|
|
563
|
+
}
|
|
564
|
+
|
|
565
|
+
/// What `delivered` has seen from `slot`.
|
|
566
|
+
fn seen<const N: usize>(delivered: &VersionVector<N>, slot: usize) -> u64 {
|
|
567
|
+
delivered.get(slot).unwrap_or_else(|| {
|
|
568
|
+
debug_assert!(false, "only membership slots are read");
|
|
569
|
+
0
|
|
570
|
+
})
|
|
571
|
+
}
|
|
572
|
+
|
|
573
|
+
/// Records `counter` as the last message `delivered` has seen from `slot`.
|
|
574
|
+
///
|
|
575
|
+
/// Callers pass a sender's membership slot, so this always succeeds; `false`
|
|
576
|
+
/// is the arm that invariant rules out, with nothing changed.
|
|
577
|
+
fn advance<const N: usize>(delivered: &mut VersionVector<N>, slot: usize, counter: u64) -> bool {
|
|
578
|
+
let Some(seen) = delivered.counter_mut(slot) else {
|
|
579
|
+
debug_assert!(false, "a sender's slot is a membership slot");
|
|
580
|
+
return false;
|
|
581
|
+
};
|
|
582
|
+
*seen = counter;
|
|
583
|
+
true
|
|
584
|
+
}
|
|
585
|
+
|
|
586
|
+
/// The undelivered run at `slot` that a message from `sender` stamped `clock`
|
|
587
|
+
/// waits for, against `delivered`.
|
|
588
|
+
fn gap<const N: usize>(
|
|
589
|
+
delivered: &VersionVector<N>,
|
|
590
|
+
slot: usize,
|
|
591
|
+
sender: usize,
|
|
592
|
+
clock: &VersionVector<N>,
|
|
593
|
+
) -> Option<(u64, u64)> {
|
|
594
|
+
let stamped = clock.get(slot)?;
|
|
595
|
+
let needed = if slot == sender {
|
|
596
|
+
stamped.checked_sub(1)?
|
|
597
|
+
} else {
|
|
598
|
+
stamped
|
|
599
|
+
};
|
|
600
|
+
let seen = seen(delivered, slot);
|
|
601
|
+
(seen < needed).then(|| (seen.saturating_add(1), needed))
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
fn blocked<const N: usize>(
|
|
605
|
+
delivered: &VersionVector<N>,
|
|
606
|
+
len: usize,
|
|
607
|
+
sender: usize,
|
|
608
|
+
clock: &VersionVector<N>,
|
|
609
|
+
) -> bool {
|
|
610
|
+
(0..len).any(|slot| gap(delivered, slot, sender, clock).is_some())
|
|
611
|
+
}
|
|
612
|
+
|
|
613
|
+
/// The hold-table entry of the matching stamp with the lowest slot, then the
|
|
614
|
+
/// lowest counter, with a copy of the stamp.
|
|
615
|
+
fn pick<const N: usize>(
|
|
616
|
+
parked: &mut [Option<Parked<N>>],
|
|
617
|
+
matches: impl Fn(&Parked<N>) -> bool,
|
|
618
|
+
) -> Option<(&mut Option<Parked<N>>, Parked<N>)> {
|
|
619
|
+
parked
|
|
620
|
+
.iter_mut()
|
|
621
|
+
.filter_map(|entry| {
|
|
622
|
+
let held = (*entry)?;
|
|
623
|
+
matches(&held).then_some((entry, held))
|
|
624
|
+
})
|
|
625
|
+
.min_by_key(|(_, held)| (held.slot, held.counter))
|
|
626
|
+
}
|