Struct Container 

pub struct Container<S: Storage> {
    storage: S,
    access: Access,
    kept: Kept,
}

Fields

storage: S

access: Access

kept: Kept

Implementations

impl<S: Storage> Container<S>

pub fn create(storage: S, now: WallTime) -> Result<Self, ContainerError>

Lay out a new container and take its lock.

Errors

ContainerError::Exists if the storage already holds a manifest, or the underlying I/O failure.

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

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

The layout goes down through the storage itself rather than through the journal: there is no container to owe a write to until this returns.

Errors

As Self::create.

pub fn create_holding( storage: S, now: WallTime, rows: &[u8], ) -> Result<Self, ContainerError>

The same, with rows already in it — the prefix Save-as, which copies an existing manifest’s lines rather than re-writing them. The bytes go down before the lock is taken, so nothing can append into the middle of them.

Errors

As Self::create.

pub async fn creating_holding( storage: S, now: WallTime, rows: &[u8], ) -> Result<Self, ContainerError>

Errors

As Self::create_holding.

pub fn open(storage: S, now: WallTime) -> Result<Self, ContainerError>

Open an existing container, taking its lock if nobody holds it.

Errors

ContainerError::NotAContainer when there is no manifest to open, or the underlying I/O failure.

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

Self::open for a storage whose futures are not ready when they are made — which, being a resident one, is where the container is read into memory.

Errors

As Self::open.

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

Open an existing container to be read and never written, leaving the lock untouched.

The honest mode for a reader: claiming the lock merely to look would either demote the session editing that container or hold a lock against one nobody is writing, and a handle that will refuse every write anyway has no business taking either.

Errors

As Self::open.

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

Errors

As Self::reading.

async fn require_manifest(storage: &S) -> Result<(), ContainerError>

async fn attach(storage: S, now: WallTime) -> Result<Self, ContainerError>

async fn kept(storage: &S) -> Result<Kept, ContainerError>

Read the container in, for a storage that says its reads are not ready when they are made: the manifest, then every rev and every payload.

pub fn storage(&self) -> &S

pub fn name(&self) -> Name

What this container is called — the document’s own name.

pub fn access(&self) -> &Access

pub fn read(&self, at: &Entry) -> Result<Option<Vec<u8>>>

The bytes at at, off the shelf when the container is held in memory and out of the storage when it is not.

Errors

The read that did not work — which is not the same as nothing being there.

pub fn exists(&self, at: &Entry) -> Result<bool>

Errors

The read that did not work.

pub fn write(&self, at: &Entry, bytes: &[u8]) -> Result<()>

Errors

The write that did not land — which a held container’s cannot, since it has only reached memory when this returns.

fn append(&self, at: &Entry, bytes: &[u8]) -> Result<()>

fn truncate(&self, at: &Entry, len: u64) -> Result<()>

pub fn pending(&self) -> usize

How many writes this container has made to its memory and not yet to its storage. Zero for a container that writes as it goes.

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

Make the writes this container owes, one at a time, in the order it made them — the payload before the rev, the rev before the row that names it, as a container that writes as it goes makes them.

A write that does not land leaves this session’s document ahead of the files, so the container gives up its lock, as a failed append does where there is no journal. What it had not yet written goes with the lock: nothing more is written to a container this session has parted from.

Errors

The write that did not land.

fn next_owed(&self) -> Option<(Entry, Op)>

fn forget_what_is_owed(&self)

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

Rename this container — which renames the document, since the container’s name is what the document is called.

The session carries on through it: every entry is named relative to the container, so an edit made after the rename lands in the same manifest the edits before it did, and the lock moves with what it locks.

Errors

std::io::ErrorKind::AlreadyExists when something already stands under that name, or the rename’s own failure.

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

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

Errors

As Self::rename.

pub fn demote(&mut self, reason: ReadOnlyReason)

Give up the right to write, releasing the lock with it. Called when the manifest turns out not to verify, and when an append fails.

fn release(&mut self)

Let go of the lock, if this handle was holding it.

pub fn read_manifest(&self) -> Result<String>

Errors

The underlying read failure.

pub fn assets(&self) -> Artwork<'_, S>

Where this container’s artwork is read and written.

pub fn revs(&self) -> Revs<'_, S>

Where this container keeps the document at every rev.

pub fn write_rev( &self, rev: Rev, document: &Document, ) -> Result<Digest, WriteRefusal>

Write the document as it stands at rev into revs/, its payloads into assets/, and hand back the digest of the rev’s bytes.

Called before the row that names the rev is appended, so the manifest never names bytes a crash could still take away — and the payloads land before the rev that references them, for the same reason one level down.

Errors

WriteRefusal::ReadOnly if this handle does not hold the lock, or the write that did not land.

pub fn read_rev(&self, rev: Rev) -> Result<Document, RevFault>

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

Errors

revs::RevFault: no file, one that is not a document this build reads, or artwork the container cannot hand back.

pub fn append_row(&self, row: &Row) -> Result<(), WriteRefusal>

Append one row and make it durable before returning: the line and its newline in one write, then an fsync. A crash anywhere in here loses at most this row, and loses it visibly — the manifest then ends without a newline, which is how load knows to drop it.

Errors

WriteRefusal::ReadOnly if this handle does not hold the lock, or the underlying write failure.

pub fn truncate_manifest(&self, bytes: u64) -> Result<(), WriteRefusal>

Cut a partial trailing row off, so the next append does not splice itself onto half a line.

Errors

As Self::append_row.

impl<S: Storage> Container<S>

pub async fn glance(storage: S) -> Result<Option<Glance>, ContainerError>

A glance at the container in storage, read without touching its lock. None for one no rev has been written into yet.

Errors

As Self::reading, or the manifest that could not be read.

Trait Implementations

impl<S: Storage> Drop for Container<S>

fn drop(&mut self)

The lock’s lifetime is the writable handle’s lifetime, rather than something a caller has to remember.