Enum Waiting
pub enum Waiting {
Nothing,
Unknown,
Events(NonZeroU64),
}Expand description
What the far side still holds past the token a pull
returned, as Pulled::waiting reports it.
Three cases, because a runner faces three: it knows there is nothing more,
it knows how much more there is, or it was not told. Spelled as an enum
rather than an Option<u64>, which cannot say “not told” without a
sentinel, and rather than a flag beside an optional count, which can say
“nothing more, and here are three”.
The count is a NonZeroU64, so “nothing” has one
spelling: Events(0) cannot be written, and a runner matching on
Nothing misses no second form of it. Its decoder refuses
a zero from the wire for the same reason. Not #[non_exhaustive]: the three
cases are the whole space, and a runner should get the compiler’s
exhaustiveness check when it matches.
§On the wire
Externally tagged, in snake case: "nothing", "unknown", or
{"events":3}. In postcard the variant index is the declaration order —
Nothing 0, Unknown 1, Events 2 — so the variants are never reordered.
§Examples
A runner that believes Nothing stops after the pull that
says it, rather than spending one more round trip on a pull that comes back
empty — the round trip SY-15 says is the expensive one:
use happenstance_core::{Event, EventId, RecordedAt, SequencePosition, StoreId};
use happenstance_sync::{
EventGroup, MemorySyncPeer, ReplicatedEvent, SyncPeer, Waiting,
};
let tablet = StoreId::from_bytes([1; 16]);
let hub = MemorySyncPeer::new(StoreId::from_bytes([2; 16]));
hub.seed(EventGroup::new(None, vec![ReplicatedEvent::new(
EventId::new(tablet, SequencePosition::FIRST),
RecordedAt::from_millis(1_700_000_000_000),
Event::new("ReadingTaken", &b"{\"celsius\":4}"[..])?,
)]))?;
let mut from = None;
let mut pulls = 0;
loop {
let pulled = hub.pull(from.as_ref()).await?;
pulls += 1;
// ... ingest `pulled.batch` here, then keep the token ...
let caught_up = pulled.waiting == Waiting::Nothing || pulled.batch.groups.is_empty();
from = Some(pulled.resume);
if caught_up {
break;
}
}
assert_eq!(pulls, 1, "told nothing is waiting, the runner skips the empty pull");Variants§
Nothing
Nothing: no group lies past this answer’s token, so the next pull from
it returns an empty batch unless the far side takes a write in between
(SY-37). A peer stalled behind a group it cannot carry says
Events, never this.
Unknown
The peer did not say. The caller pulls again to find out, which is what every pull cost before this field existed.
Events(NonZeroU64)
This many events lay past the token when the far side answered.
Advisory: more may have arrived since, and a group too large for the next pull’s budget can hold that pull empty while this is non-zero.