Struct GroupPageBuilder
pub struct GroupPageBuilder { /* private fields */ }Expand description
Folds rows, offered in group order, into a page of whole groups.
Offer each row with the group it belongs to. Rows of one group must be
offered together, in local position order, and groups in ascending
first order: a store that serialises its writers gets
that from a scan by position, and one that does not orders by group.
The order is checked, not trusted. A row that names a group at or below
one already passed is refused: offer breaks, the builder
takes nothing more, and finish returns a
GroupOrderError. That is the mistake a store that does not serialise its
writers makes by scanning in position order, where G = {5, 7} and H = {6}
arrive as 5, 6, 7: without the refusal the page would carry G torn in two,
under one name twice.
§Examples
use core::num::NonZeroUsize;
use core::ops::ControlFlow;
use happenstance_core::{Event, EventId, RecordedAt, SequencePosition, StoreId};
use happenstance_sync::write_group::GroupPageBuilder;
use happenstance_sync::{ReplicatedEvent, Waiting};
let row = |position: u64| -> Result<(SequencePosition, ReplicatedEvent), Box<dyn core::error::Error>> {
let position = SequencePosition::new(position).ok_or("position zero")?;
let id = EventId::new(StoreId::from_bytes([1; 16]), position);
let event = Event::new("Written", &b""[..])?;
Ok((position, ReplicatedEvent::new(id, RecordedAt::from_millis(0), event)))
};
// Two groups, of two events and one, under a budget of two.
let mut page = GroupPageBuilder::new(NonZeroUsize::MIN.saturating_add(1));
let (a, a1) = row(1)?;
let (_, a2) = row(2)?;
let (b, b1) = row(3)?;
assert!(page.offer(a, None, a1).is_continue());
assert!(page.offer(a, None, a2).is_continue());
assert!(page.offer(b, None, b1).is_break(), "the second group would overflow");
let page = page.finish(Waiting::Nothing)?;
assert_eq!(page.groups.len(), 1);
assert_eq!(page.waiting, Waiting::Unknown);Implementations§
§impl GroupPageBuilder
impl GroupPageBuilder
pub const fn new(max_events: NonZeroUsize) -> Self
pub const fn new(max_events: NonZeroUsize) -> Self
An empty page that holds at most max_events events, past which only
a first group may go.
pub fn offer(
&mut self,
first: SequencePosition,
guard: Option<AppendCondition>,
event: ReplicatedEvent,
) -> ControlFlow<()>
pub fn offer( &mut self, first: SequencePosition, guard: Option<AppendCondition>, event: ReplicatedEvent, ) -> ControlFlow<()>
Offers the next row: event, written in the group named first.
guard is read only from the row that opens a group, which is the row
at first; pass None for the rest. Returns
ControlFlow::Break once the page is full, and the caller stops
reading: the row that broke it is not on the page.
Also breaks, for good, on a row whose first is at or below the
first of a group already offered and left: the builder is then
refused, takes nothing more, and finish says why.
pub fn finish(self, past_rows: Waiting) -> Result<GroupPage, GroupOrderError>
pub fn finish(self, past_rows: Waiting) -> Result<GroupPage, GroupOrderError>
The page, given what lay past the last row offered: past_rows is
Waiting::Nothing when the read reached the end of the log, and
Waiting::Unknown when it stopped short of it.
A page that stopped before a group always says
Waiting::Unknown.
§Errors
GroupOrderError if a row was offered out of group order, in which
case no page is returned: what the builder held is not known to be
whole groups.