Struct Store 

pub struct Store { /* private fields */ }

An embedded, persistent knowledge-graph store.

Implementations

impl Store

pub fn create(dir: impl AsRef<Path>, cfg: Config) -> Result<Self>

Create a fresh store in dir (created if absent; must not already contain a store) and open it read-write. Creation runs under the commit lock, so a racing creator either finds the store already made (and is refused) or waits for this one — it never lays fresh files over a store another process has committed to.

pub fn open_or_create(dir: impl AsRef<Path>, cfg: Config) -> Result<Self>

Open the store in dir read-write, creating it first when absent. Safe when many processes race to create the same store: creation happens once, under the commit lock (waiting up to Config::lock_wait for a creator in progress), and everyone opens the result. An existing store is opened without taking any lock.

pub fn open(dir: impl AsRef<Path>) -> Result<Self>

Open an existing store read-write. Takes no lock: any number of read-write handles may be open at once (see the module docs). A torn log tail is repaired by the next commit, or right here when no other writer holds the commit lock.

pub fn open_cfg(dir: impl AsRef<Path>, cfg: Config) -> Result<Self>

Open with an explicit configuration.

pub fn open_read_only(dir: impl AsRef<Path>) -> Result<Self>

Open read-only: no lock taken, no repair performed; replay simply stops at a torn tail. Use Store::reload_if_stale to observe other handles’ commits and compactions.

pub fn open_image(base: Bytes, wal: &[u8]) -> Result<Self>

Serve a store straight from memory: base is a graph.base image and wal a graph.wal image (possibly empty), e.g. objects fetched from a bucket. The base is read in place — no copy, no file, no mapping — and fully validated exactly like Store::open. The store is read-only and has no directory (Store::dir is empty); keep it current with Store::reload_image.

pub fn reload_image(&self, base: Option<Bytes>, wal: &[u8]) -> Result<bool>

Keep an image store current. Pass the new base when the generation changed (a compaction), else None and the current log image: frames not yet visible are published. Returns true when anything new became visible. Works on file-backed read-only stores too.

pub fn is_image(&self) -> bool

True for a store served from memory (Store::open_image).

pub fn len(&self) -> usize

Number of live (non-tombstoned, non-stub) documents in the current snapshot view.

pub fn is_empty(&self) -> bool

True when the store holds no live documents.

pub fn dir(&self) -> &Path

The directory this store lives in.

pub fn generation(&self) -> u64

The generation currently served (advances by one per compaction, or when a catch-up installs a newer one).

pub fn set_compact_inline(&self, inline: bool)

Whether Writer::commit compacts inline once the configured thresholds are reached (the default, and the 0.2 behaviour). Services that must keep commit latency flat turn it off and call Store::compact off the hot path whenever Store::compaction_due says so.

pub fn compaction_due(&self) -> bool

True when a threshold was reached while inline compaction was off and no compaction has run since.

pub fn snapshot(&self) -> Snapshot<'_>

Pin the current generation and return a read view. Never blocks in steady state; spins only across a slot-install window.

pub fn writer(&self) -> Result<Writer<'_>>

This handle’s writer. Error::ReadOnly on read-only stores.

Blocks while another thread holds a Writer on this handle. Writers on other handles — in this process or another — stage freely; only their commits take turns, on the commit lock.

pub fn transact<F, R>(&self, f: F) -> Result<R>

where F: for<'t> FnOnce(&mut Txn<'t>) -> Result<R>,

Run f as one serializable transaction and commit what it stages.

The commit lock is taken (waiting up to Config::lock_wait) and this handle caught up before f runs, and held until its single append (one fsync) lands: Txn::snapshot is the latest committed state of every writer, and no other writer can commit between that read and this transaction’s write. Err from f aborts with nothing written. The view shows committed state only — ops staged by f are not visible in it.

pub fn try_transact<F, R>(&self, f: F) -> Result<R>

where F: for<'t> FnOnce(&mut Txn<'t>) -> Result<R>,

Store::transact that never waits: Error::Locked at once when another writer holds the commit lock (f does not run), so an async caller can retry on its own schedule instead of parking a thread.

pub fn commit_lock(&self) -> Result<CommitLock>

Take the commit lock now and catch this handle up, for a transaction that spans several calls (a language binding’s with block). Commit under it with Store::transact_with; drop it to release. While it is held, a commit on this same handle from another thread waits for it like any other writer would.

pub fn try_commit_lock(&self) -> Result<CommitLock>

Store::commit_lock that never waits: Error::Locked at once when another writer holds it.

pub fn commit_lock_within(&self, wait: Duration) -> Result<CommitLock>

Store::commit_lock waiting up to wait instead of Config::lock_wait (zero: never waits, as Store::try_commit_lock).

pub fn transact_with<F, R>(&self, lock: &CommitLock, f: F) -> Result<R>

where F: for<'t> FnOnce(&mut Txn<'t>) -> Result<R>,

Store::transact under a lock already taken with Store::commit_lock on this store (refused for another store’s).

pub fn compact(&self) -> Result<CompactStats>

Fold the WAL into a new base generation now. Also triggered automatically by Writer::commit past the configured thresholds. Runs under the commit lock, on a caught-up handle.

pub fn reload_if_stale(&self) -> Result<bool>

Pick up commits and compactions made through other handles (other processes, or other handles in this one). Returns true when anything new became visible.

Cheap when nothing changed: two stat calls, no mapping, no reads. When only the log grew, only the appended bytes are read. Reloads on one handle run one at a time; snapshots are never blocked. A writable handle whose Writer is held by another thread returns Ok(false) rather than wait (it catches up at that writer’s commit anyway).

Trait Implementations

impl Debug for Store

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

Formats the value using the given formatter.