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.
@@ -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
+ }