Struct Store 

pub struct Store { /* private fields */ }

A handle on an open store.

One type over every engine - which one is behind it is settled by StoreBuilder when the store is opened, and nothing downstream is generic over it.

Cheap to clone and shared by every clone: the file stays open as long as one handle is alive, and closes when the last is dropped.

Dropping the last handle writes what is still buffered, but it is the one write whose failure it cannot report: Drop has no caller to return an error to, and by then there is rarely anyone left to tell. An application that would rather find out calls Store::close on the way out and reads the result.

Finding out is all it buys. A close that failed has closed the store anyway, a second one answers Ok without flushing again, and the writes are gone - a retry belongs to Store::save_now, while the store is still open.

Implementations

impl Store

pub fn from_arc(inner: Arc<dyn StoreBackend>) -> Self

Wraps a backend that was built by hand.

StoreBuilder is the ordinary way in; this is for a StoreBackend implemented outside the crate.

pub fn fallbacks(&self) -> Fallbacks

What a field falls back to here when neither it nor its struct said, put there by StoreBuilder::rules.

pub fn context(&self) -> &RuleContext

What the application handed this store for its declared rules, put there by StoreBuilder::context.

A store opened any other way carries an empty one, and a rule asking it for something is refused with what was on offer.

pub fn as_dyn(&self) -> &Arc<dyn StoreBackend>

The erased backend underneath, for code that is generic over StoreBackend rather than over this handle.

pub fn places(&self) -> &Places

The places that are spoken for and by whom, shared by every clone of this handle.

pub fn on_persist_failure( &self, observer: impl Fn(&PersistEvent<'_>) + Send + Sync + 'static, ) -> PersistWatch

Attaches an observer to this store’s background saving, for as long as the returned watch is kept.

It hears every failing streak that outlives the retry budget, with what Disk::on_failure decided about it, and the save that lands after one. It decides nothing: any number can be attached, from anywhere that holds the store. It runs on the flush thread, where closing the store is refused.

A backend that saves on its own terms has nothing to report, and its watch hears nothing.

pub fn persist_failure(&self) -> Option<Arc<Report<StorageError>>>

The failure the last failing streak gave up with, until a save lands again - whatever was decided about it.

pub fn open( config: StoreConfig, mset: MigrationSet, ) -> StorageResult<(Self, MigrationReport)>

Opens the store with the first engine this build has, and refuses in a build with none.

impl Store

The typed surface, inherent so a call site needs no trait in scope.

pub fn subscribe( &self, kind: SubscriptionKind, callback: StoreCallback, ) -> StoreSubscription

Hears the changes kind names for as long as what comes back is held.

Dropping the StoreSubscription is how it stops, and it can only stop its own: it carries the store it was made on. StoreBackend::subscribe is the same without the guard, for whoever keeps the id and ends it by hand.

let heard = Arc::new(AtomicU32::new(0));
let counter = Arc::clone(&heard);
let listening = store.subscribe(
    SubscriptionKind::Any,
    Arc::new(move |_| {
        counter.fetch_add(1, Ordering::Relaxed);
        Ok(())
    }),
);

store.set(["ui", "width"], &1280u32).unwrap();
drop(listening);
store.set(["ui", "width"], &800u32).unwrap();

assert_eq!(heard.load(Ordering::Relaxed), 1);

pub fn get<T: DeserializeOwned>( &self, path: impl IntoStorePath, ) -> ReadResult<Option<T>>

Reads a value by path, or None if nothing is stored there.

Sees buffered writes as well as committed ones. The type is whatever you ask for and nothing remembers it - Kv::cell is the variant that does.

The levels are given as a list, and a string is not one of them - a name holding a separator is a name, and nesting is spelled out:

store.set(["ui", "width"], &1280u32).unwrap();

assert_eq!(store.get::<u32>(["ui", "width"]).unwrap(), Some(1280));
assert_eq!(store.get::<u32>(["ui", "height"]).unwrap(), None);

// One level called `ui.width`, which is somewhere else entirely.
store.set(["ui.width"], &7u32).unwrap();
assert_eq!(store.get::<u32>(["ui", "width"]).unwrap(), Some(1280));

pub fn set<T: Serialize>( &self, path: impl IntoStorePath, value: &T, ) -> Result<(), WriteValue>

Writes a value at path, creating it or replacing what was there.

The write lands in the buffer and notifies subscribers; the debouncer commits it later. Nothing here carries provenance, so a subscription cannot tell this apart from its own write - use Store::set_with_source when it must.

pub fn set_owned<T: Serialize>( &self, path: StorePath, value: &T, ) -> Result<(), WriteValue>

Store::set for a path already owned, saving the clone the borrowed form would make.

pub fn set_with_source<T: Serialize>( &self, path: impl IntoStorePath, value: &T, source: Option<Uuid>, ) -> Result<(), WriteValue>

Store::set tagged with who made the write.

Subscribers receive the id, which is how a component ignores the echo of its own change instead of reacting to it.

pub fn set_owned_with_source<T: Serialize>( &self, path: StorePath, value: &T, source: Option<Uuid>, ) -> Result<(), WriteValue>

Store::set_with_source for a path already owned.

pub fn delete(&self, path: impl IntoStorePath) -> Result<(), WriteValue>

Removes whatever is at path. Removing an absent path is not an error.

pub fn delete_prefix( &self, prefix: impl IntoStorePath, ) -> Result<(), WriteValue>

Removes every level under prefix, and the value at prefix itself.

pub fn flush_prefix(&self, prefix: impl IntoStorePath) -> FlushResult<()>

Commits what is buffered under prefix.

How much else goes with it is the engine’s answer: redb and sqlite commit what is under the prefix and leave the rest buffered, a document engine rewrites the whole file and so commits everything. See Backend::a_commit_covers_the_whole_store.

pub fn save_now(&self) -> FlushResult<()>

Writes everything buffered, and waits for it to land.

pub fn close(&self) -> FlushResult<()>

Writes what is buffered, stops the background threads and lets go of the file.

pub fn scan_keys( &self, prefix: impl IntoStorePath, ) -> ScanResult<Vec<StorePath>>

The keys under prefix, sorted, without reading their values.

pub fn scan_prefix( &self, prefix: impl IntoStorePath, ) -> ScanResult<Vec<(StorePath, Vec<u8>)>>

Every key under prefix with its bytes, sorted by key.

pub fn decode<T: DeserializeOwned>(&self, bytes: &[u8]) -> StorageResult<T>

Decodes bytes that arrived in a StoreEvent, in whatever format this backend writes.

Bytes that will not decode - because the file was edited by hand, or the field changed type - are an error naming the type that was asked for and what the codec made of them, so a caller can tell a stored default from a value it could not read.

impl Store

Reactive values addressed by path, without declaring a struct. See crate::store::Kv.

pub fn kv(&self) -> Kv

Trait Implementations

impl Clone for Store

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Store

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

Formats the value using the given formatter.

impl Deref for Store

type Target = dyn StoreBackend

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Eq for Store

impl PartialEq for Store

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StoreBackend for Store

Addressing the store by path, with nothing in the way - and what that costs is written on StoreBackend itself, which is worth reading before reaching for any of it. The short of it: a write here lands wherever it is aimed, declared paths included, and Kv is the surface that refuses to.

Store::get and Store::set are the same operations under a shorter name, so they carry the same warning.

fn get_raw(&self, path: &StorePath) -> StorageResult<Option<Vec<u8>>>

fn set_erased( &self, path: &StorePath, value: &dyn Serialize, by: Writer, ) -> StorageResult<()>

fn set_owned_erased( &self, path: StorePath, value: &dyn Serialize, by: Writer, ) -> StorageResult<()>

fn get_erased( &self, path: &StorePath, f: &mut dyn FnMut(&mut dyn Deserializer<'_>) -> StorageResult<()>, ) -> StorageResult<bool>

Runs f against a deserializer positioned at path, in the backend’s own format. Ok(false) means the key is absent and f never ran.

fn decode_erased( &self, bytes: &[u8], f: &mut dyn FnMut(&mut dyn Deserializer<'_>) -> StorageResult<()>, ) -> StorageResult<()>

Same, for bytes carried by a crate::StoreEvent.

fn delete_with_source( &self, path: &StorePath, source: Option<Uuid>, ) -> StorageResult<()>

fn delete(&self, path: &StorePath) -> StorageResult<()>

fn delete_prefix_with_source( &self, prefix: &StorePath, source: Option<Uuid>, ) -> StorageResult<()>

Removes every key under prefix, emitting one crate::StoreOp::DeletePrefix instead of a Delete per key.

fn scan_prefix( &self, prefix: &StorePath, ) -> StorageResult<Vec<(StorePath, Vec<u8>)>>

Every key under prefix, sorted by key on every backend.

fn visit_prefix( &self, prefix: &StorePath, visit: &mut dyn FnMut(PathRef<'_>, &[u8]) -> StorageResult<()>, ) -> StorageResult<()>

Hands every entry under prefix to visit, in the order a scan lists.

fn scan_keys(&self, prefix: &StorePath) -> StorageResult<Vec<StorePath>>

The keys under prefix, sorted, without reading their values.

fn parallel_reads(&self) -> bool

Whether this store was asked to read large collections on more than one core - StoreConfig::parallel_reads.

fn files_layout(&self) -> Option<StoreLayout>

Where this store keeps what it keeps.

fn persist_health(&self) -> Option<Arc<PersistHealth>>

How this store’s background saving is faring, and who is listening.

fn save_now(&self) -> StorageResult<()>

Writes everything buffered and says whether it landed.

fn close(&self) -> StorageResult<()>

Writes what is buffered, stops the background threads and lets go of the file.

fn is_closed(&self) -> bool

Whether StoreBackend::close has already run.

fn subscribe( &self, kind: SubscriptionKind, callback: StoreCallback, ) -> SubscriptionId

Registers callback for the changes kind names, under an id from SubscriptionId::next.

fn unsubscribe(&self, id: SubscriptionId) -> bool

Removes the subscription id names, and says whether this store held it. An id another store handed out is never held here.

fn flush_prefix(&self, prefix: &StorePath) -> StorageResult<()>

Gets what is buffered under prefix onto disk.

fn flush_async(&self) -> Commit

Commits without blocking; the future resolves once a flush has landed.

fn save_async(&self) -> Commit

Writes everything buffered, as StoreBackend::save_now does, and resolves with how that write ended - without blocking the thread that awaits it.

fn close_async(&self) -> Commit

Closes the store, as StoreBackend::close does, and resolves with what the closing write did - without blocking the thread that awaits it.

fn is_initialized(&self, namespace: &StorePath) -> StorageResult<bool>

fn record_schema( &self, at: &StorePath, schema: &SchemaSnapshot, ) -> StorageResult<()>

Writes down the places a declaration claims, at the prefix it claims them under.

fn set_initialized( &self, namespace: &StorePath, state: InitState, ) -> StorageResult<()>

Records whether namespace has been seeded.

fn delete_prefix(&self, prefix: &StorePath) -> StorageResult<()>

fn mark_initialized(&self, namespace: &StorePath) -> StorageResult<()>