Skip to main content

GroupPageBuilder

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

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<()>

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>

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.

Trait Implementations§

§

impl Debug for GroupPageBuilder

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.