Struct Store 

pub struct Store<S: Storage> {
    container: Container<S>,
    repo: Repo,
    trail: Trail,
    clock: Clock,
    head: Digest,
    rows: Vec<Row>,
    tags: Tags,
    tail: Tail,
}

Fields

container: Container<S>

repo: Repo

trail: Trail

Where this session’s history stands. Beside the repo rather than in it: a step adopts the rev copy this container holds, which is something only the store can read (docs/log-vs-snapshot.md).

clock: Clock

head: Digest

The digest the next row must name as its parent.

rows: Vec<Row>

Every row this container’s manifest holds that spends a rev, in rev order: rows()[i] describes rev i + 1. What the history panel, the rev pick and blockworx log all read.

tags: Tags

What the manifest’s tag rows name its revs. Rebuilt at every open and never handed to the repo.

tail: Tail

Implementations

impl<S: Storage> Store<S>

pub fn create(storage: S, clock: Clock) -> Result<Self, ContainerError>

Lay out a new container and open it at the empty document.

Errors

As Container::create.

pub async fn creating(storage: S, clock: Clock) -> Result<Self, ContainerError>

Self::create for a storage whose futures are not ready when they are made.

Errors

As Self::create.

pub fn seeded( storage: S, clock: Clock, commits: &[Commit], author: &Identity, ) -> Result<Self, SeedFailure>

Lay out a new container and put commits into it, each as one row and one rev of its own.

This is how a scratch session becomes durable: each commit lands as its own rev, so the container’s history is the session’s history. Nothing is trailed — the commits are the new container’s past.

A session that already has a container does not come this way: commits are all this can carry, so the wall times, the authors, the edit/undo/redo kinds and the tags would be flattened into a run of fresh edits by whoever pressed Save-as. That path copies the manifest’s own rows instead (super::prefix::save_through).

Errors

SeedFailure::Create as Self::create, and SeedFailure::Append naming the commit that did not land — which leaves a container holding the prefix that did.

pub async fn seeding( storage: S, clock: Clock, commits: &[Commit], author: &Identity, ) -> Result<Self, SeedFailure>

Self::seeded for a storage whose futures are not ready when they are made. The commits themselves are folded and written synchronously either way; what a resident container owes its storage afterwards is Self::drain’s.

Errors

As Self::seeded.

fn seeded_with( self, commits: &[Commit], author: &Identity, ) -> Result<Self, SeedFailure>

pub fn open(storage: S, clock: Clock) -> Result<Self, ContainerError>

Open a container: read the manifest, verify its chain, and read the head rev.

A manifest that does not verify is not a failure to open: the container opens read-only at the last good prefix, with the break as its ReadOnlyReason, because the reader is owed a look at the past that is intact. A manifest with a partial trailing row opens writable, the row dropped and the file cut back to the last whole line.

Errors

As Container::open — there is no container, or it cannot be read.

pub async fn opening(storage: S, clock: Clock) -> Result<Self, ContainerError>

Self::open for a storage whose futures are not ready when they are made.

The open is where a resident container is read in — the manifest, every rev and every payload — so everything after it, this function’s own second half included, reads out of memory.

Errors

As Self::open.

pub fn reading(storage: S) -> Result<Self, ContainerError>

Open a container to be read and never written.

The same read as Self::open over a handle that never claimed the lock (Container::reading), so reading someone’s document — or a fixture out of fixtures/ — cannot cost its owner the right to write it. Every write door refuses with Refusal::ReadOnly, which is why this takes no Clock: nothing here mints a row.

Errors

As Self::open.

pub async fn opening_to_read(storage: S) -> Result<Self, ContainerError>

Self::reading for a storage whose futures are not ready when they are made.

Errors

As Self::reading.

pub(crate) fn over( container: Container<S>, clock: Clock, ) -> Result<Self, ContainerError>

Read an already-attached container — Self::open’s second half, shared with the prefix Save-as, which lays a container out with a manifest already in it.

Errors

The manifest that could not be read.

pub fn name(&self) -> Name

What this document is called.

pub fn path(&self) -> Option<&Path>

Where this container sits on a filesystem, for a shell that can name one. None for a container that is not on one.

pub fn rename(&mut self, to: &Name) -> Result<(), Refusal>

Rename this store’s container, keeping the lock and the manifest with it. The document is untouched: only what it is called changes, so nothing is appended and no rev is spent.

Errors

Refusal::ReadOnly on a container this session may not write — renaming someone else’s open document is not a read — and Refusal::Rename when the container does not move, which leaves the store where it was.

pub async fn renaming_to(&mut self, to: &Name) -> Result<(), Refusal>

Self::rename for a storage whose futures are not ready when they are made.

Errors

As Self::rename.

pub fn pending(&self) -> usize

How many writes this session has made to its container’s memory and not yet to its storage — what a status line reads “writing…” off. Always zero where the writes are made as they are asked for.

pub async fn drain(&mut self) -> Result<Drained>

Make the writes this session owes its storage, in the order it made them. See Container::drain: a write that does not land costs the container its lock, as a failed append does.

Errors

The write that did not land.

pub fn repo(&self) -> &Repo

Readable, never writable: Self::submit_edit and its two neighbours are the only way a commit gets into this repo, which is what keeps the repo and the files in step.

pub fn trail(&self) -> &Trail

Where this session’s history stands: what one press would take back, what one would put back, and which rev’s document the head holds.

pub fn document(&self) -> &Document

pub fn access(&self) -> &Access

pub fn read_only_reason(&self) -> Option<&ReadOnlyReason>

pub fn tail(&self) -> Tail

Whether load dropped an unfinished row, and which.

pub fn rows(&self) -> &[Row]

The manifest’s rows, one per rev, in rev order.

pub fn row(&self, at: Rev) -> Option<&Row>

The row rev at was written under, or None for a rev this history does not hold.

pub fn framing(&self, at: Rev) -> Option<&Row>

The row a reader frames rev at from: its own, or — for a step — the row of the act it moves.

A step frames what it moved, so the scope it opens and the view it replays are the ones the act was made in, not where the hand that pressed undo happened to be standing. The row itself still records the undoer’s own circumstances; the derivation happens at read time.

pub fn tags(&self) -> &Tags

What this manifest’s tag rows call its revs.

pub fn document_at(&self, at: Rev) -> Result<Document, Refusal>

The document this container holds at at, payloads and all.

Errors

Refusal::Unreachable for a rev whose copy the container cannot show.

fn head_hash(&self) -> Digest

What the head row stamps. Read off the row rather than recomputed: the row was written after the bytes landed, and the open checked them against each other.

pub fn submit_edit<'a>( &mut self, commit: Commit, by: impl Into<Attribution<'a>>, ) -> Result<Rev, Refusal>

Fold commit, write its rev, and append its row. See Store’s note on the write path: a write that fails costs the container its lock.

Errors

Refusal::ReadOnly when this handle may not write, Refusal::Fold when the fold refuses the commit, and Refusal::Append when the row does not reach the file.

pub fn undo<'a>( &mut self, edit: Rev, by: impl Into<Attribution<'a>>, ) -> Result<Rev, Refusal>

Adopt the document the trail’s top entry restores, recorded as an undo of edit.

Errors

As Self::submit_edit, with Refusal::Step in place of Refusal::Fold when the trail will not take the step, and Refusal::Unreachable for a rev this container cannot read back.

pub fn redo<'a>( &mut self, edit: Rev, by: impl Into<Attribution<'a>>, ) -> Result<Rev, Refusal>

Errors

As Self::undo.

pub fn tag<'a>( &mut self, at: Rev, name: &str, how: Tagging, by: impl Into<Attribution<'a>>, ) -> Result<(), Refusal>

Put a name on at, or take one off.

One appended row, chained like any other, that no rev is spent on and the trail never hears about: tagging is not an edit, and undo after it still takes back the last one.

Errors

Refusal::ReadOnly when this handle may not write, Refusal::NoSuchRev for a rev this history does not hold, and Refusal::Append when the row does not reach the file.

fn write(&mut self, step: Step, by: Attribution<'_>) -> Result<Rev, Refusal>

Take the step, write the rev, then append the row. A write that fails leaves this session’s document ahead of the files, so the container gives up its lock rather than carrying on writing into a history with a hole in it.

Errors

Refusal::ReadOnly when this handle may not write, Refusal::Fold or Refusal::Step when the repo refuses the step, and Refusal::Append when the row does not reach the file.

fn step( &mut self, edit: Rev, direction: Direction, ) -> Result<(Rev, RowKind, String, Vec<EntityRef>), Refusal>

Take one history step, adopting the rev copy this container holds, and carry the stepped row’s own touched names onto the row this step writes — so a step frames what it moved.

fn row_for(&mut self, written: Written<'_>) -> Row

fn parted_from(&mut self, error: Error) -> Refusal

This session’s document is now ahead of the files, so the container gives up its lock rather than carrying on writing into a history with a hole in it.