Skip to main content

MemoryProjectionStore

Struct MemoryProjectionStore 

Source
pub struct MemoryProjectionStore { /* private fields */ }
Available on crate feature memory only.
Expand description

The reference implementation of ProjectionStore.

It exists for the same three reasons MemoryEventStore does, in the same order of importance:

  1. it is the oracle the conformance suite is validated against, so that a failing adapter is known to be the adapter’s fault and not the suite’s;
  2. it makes this crate’s examples runnable, so the documentation cannot drift from the API;
  3. it lets application code be written and tested before any real adapter exists.

It is deliberately obvious rather than fast. When a conformance rule fails, the adapter is presumed wrong and this store is presumed right, so its correctness has to be readable in one sitting: one lock over one struct holding both halves, and commit takes that lock exactly once. Splitting it into more than one guarded section is precisely the shape a store that writes the checkpoint without its read model fails for.

§One end of the batch-shape axis

This store applies on write: a batch is a materialised delta layered over committed state, so it can be read back through before it commits, and ProjectionProbe::READS_THROUGH_BATCH is true here. The other end of that axis — a batch that buffers and replays at commit, where read-through is impossible and declining it is the conformant answer — is a separate implementation. Nothing a conformance rule needs may assume read-through beyond that constant.

The probe’s name is deliberately not a link, for the reason the crate root gives twice: this page renders whenever memory is on, ProjectionProbe exists only under conformance, and rustdoc::broken_intra_doc_links is deny — so a link here is a hard error on the crate’s default feature set, which is what a consumer builds.

§Examples

The whole loop: open a batch, write through it, commit the rows and the checkpoint as one unit, read both back, then return the projection to Checkpoint::NeverRun with the caller’s own deletes.

use happenstance_core::{
    Authority, Checkpoint, MemoryProjectionStore, ProjectionId, ProjectionStore,
    SequencePosition,
};

let store = MemoryProjectionStore::new();
let id = ProjectionId::new("van_stock")?;

// Never run: the enum says so, and no `Option` is involved.
assert_eq!(store.checkpoint(&id).await?, Checkpoint::NeverRun);

// `begin` never yields and never fails here: opening a buffer is free.
let mut batch = store.begin().await?;
batch.write("depot-7", 12);

// Nothing is visible yet — not the row, not the checkpoint.
assert_eq!(store.get("depot-7"), None);
assert_eq!(store.checkpoint(&id).await?, Checkpoint::NeverRun);

// One unit of work: the row and the checkpoint, or neither.
store
    .commit(batch, &id, SequencePosition::FIRST, Authority::Live)
    .await?;

assert_eq!(store.get("depot-7"), Some(12));
assert_eq!(
    store.checkpoint(&id).await?,
    Checkpoint::Live { through: SequencePosition::FIRST },
);

// The dual: the caller's own batch carries the deletes, because the port
// has no idea what the read model is.
let mut clearing = store.begin().await?;
clearing.delete_all();
store.reset(clearing, &id).await?;

assert_eq!(store.get("depot-7"), None);
assert_eq!(store.checkpoint(&id).await?, Checkpoint::NeverRun);

Implementations§

Source§

impl MemoryProjectionStore

Source

pub fn new() -> Self

A store with no rows and no checkpoints.

Source

pub fn open(&self) -> MemoryProjectionBatch

Opens a batch. The inherent twin of begin, so an application author can drive this store without importing the port.

Source

pub fn get(&self, key: &str) -> Option<u64>

One committed row, or None.

Source

pub fn snapshot(&self) -> BTreeMap<String, u64>

Every committed row, in key order.

Source

pub fn len(&self) -> usize

How many committed rows the read model holds.

Source

pub fn is_empty(&self) -> bool

Whether the read model holds no committed rows.

Trait Implementations§

Source§

impl Debug for MemoryProjectionStore

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for MemoryProjectionStore

Hand-written, and not #[derive(Default)], for the same reason MemoryEventStore’s is hand-written: stamp is this instance’s identity, and the derive would fill it with 0 without ever calling the counter, which starts at 1. Two default() stores would then share identity 0, each would accept the other’s batch, and CommitError::ForeignBatch — the check the oracle exists to be right about — would be unreachable through that constructor. commit_rejects_a_foreign_batch_from_default_stores and its reset twin in tests/projection_memory.rs are what keep the derive from coming back.

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl ProjectionProbe for MemoryProjectionStore

Source§

const READS_THROUGH_BATCH: bool = true

Available on crate feature conformance only.

true, because this store applies on write and a batch can therefore be read back through before it commits.

Source§

async fn probe_write( &self, batch: &mut Self::Batch, key: &str, value: u64, ) -> Result<(), Self::Error>

Available on crate feature conformance only.
Writes one probe row into an open batch. Read more
Source§

async fn probe_delete_all( &self, batch: &mut Self::Batch, ) -> Result<(), Self::Error>

Available on crate feature conformance only.
Queues deletion of every probe row into an open batch. Read more
Source§

async fn probe_read(&self, key: &str) -> Result<Option<u64>, Self::Error>

Available on crate feature conformance only.
Reads one probe row from the committed read model. Read more
Source§

async fn probe_read_through( &self, batch: &mut Self::Batch, key: &str, ) -> Result<Option<u64>, Self::Error>

Available on crate feature conformance only.
Reads one probe row through an open batch, committed state included. Read more
Source§

impl SendProjectionStore for MemoryProjectionStore

Source§

type Error = MemoryProjectionStoreError

How this adapter fails.
Source§

type Batch = MemoryProjectionBatch

The adapter’s write set. Read more
Source§

async fn begin(&self) -> Result<Self::Batch, Self::Error>

Opens a write set. Read more
Source§

async fn checkpoint(&self, id: &ProjectionId) -> Result<Checkpoint, Self::Error>

How far this projection has been brought, and whether its rows are authoritative. Read more
Source§

async fn commit( &self, batch: Self::Batch, id: &ProjectionId, position: SequencePosition, authority: Authority, ) -> Result<(), CommitError<Self::Error>>

Applies batch and moves id’s checkpoint to position, as one unit. Read more
Source§

async fn reset( &self, batch: Self::Batch, id: &ProjectionId, ) -> Result<(), ResetError<Self::Error>>

Applies batch and returns id to Checkpoint::NeverRun, as one unit. Read more
Source§

async fn rollback(&self, batch: Self::Batch) -> Result<(), Self::Error>

Discards the batch without committing. 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<TraitVariantBlanketType> ProjectionStore for TraitVariantBlanketType
where TraitVariantBlanketType: SendProjectionStore,

Source§

type Error = <TraitVariantBlanketType as SendProjectionStore>::Error

How this adapter fails.
Source§

type Batch = <TraitVariantBlanketType as SendProjectionStore>::Batch

The adapter’s write set. Read more
Source§

async fn begin( &self, ) -> Result<<TraitVariantBlanketType as ProjectionStore>::Batch, <TraitVariantBlanketType as ProjectionStore>::Error>

Opens a write set. Read more
Source§

async fn checkpoint( &self, id: &ProjectionId, ) -> Result<Checkpoint, <TraitVariantBlanketType as ProjectionStore>::Error>

How far this projection has been brought, and whether its rows are authoritative. Read more
Source§

async fn commit( &self, batch: <TraitVariantBlanketType as ProjectionStore>::Batch, id: &ProjectionId, position: SequencePosition, authority: Authority, ) -> Result<(), CommitError<<TraitVariantBlanketType as ProjectionStore>::Error>>

Applies batch and moves id’s checkpoint to position, as one unit. Read more
Source§

async fn reset( &self, batch: <TraitVariantBlanketType as ProjectionStore>::Batch, id: &ProjectionId, ) -> Result<(), ResetError<<TraitVariantBlanketType as ProjectionStore>::Error>>

Applies batch and returns id to Checkpoint::NeverRun, as one unit. Read more
Source§

async fn rollback( &self, batch: <TraitVariantBlanketType as ProjectionStore>::Batch, ) -> Result<(), <TraitVariantBlanketType as ProjectionStore>::Error>

Discards the batch without committing. Read more
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.