Skip to main content

Module store

Module store 

Source
Expand description

The cache database: SurrealKV, embedded, in the db directory of the cache.

A Store is shared by the threads of one process. Every read and write goes through a Txn, which sees a consistent snapshot; a write transaction changes nothing until Txn::commit, and then changes every record it wrote or none.

SurrealKV commits and closes asynchronously on a Tokio runtime, so the store owns a small runtime and waits for each commit and for the close. After each commit the store hands the write-ahead log to the operating system, so a committed record survives a crash of the process.

The store starts no thread of its own (“Kizz never panics”), so it cannot fail when the system cannot start one. Its runtime is a current-thread runtime, which runs SurrealKV’s tasks on the threads that call the store, while they wait for a commit or the close. Kizz builds SurrealKV from a patched copy in vendor/surrealkv, and the store opens it with the copy’s direct clock, [ClockMode::Direct], which reads the system clock on every reading instead of keeping a thread that brings it up to date. Its stall thresholds, STALL_THRESHOLD, are so high that SurrealKV never paces or stalls a write, which a cache of small records does not need. When it replays several log segments after a crash, the copy starts a thread when it can and otherwise replays them on the thread that opens the store.

The store waits for SurrealKV with Runtime::block_on only after it checks, with Handle::try_current, that the calling thread is in no runtime, because block_on panics when it is called within an asynchronous execution context (“Kizz never panics”); a call from inside a runtime is StoreError::InsideRuntime instead. Its runtime never panics when it is dropped either: inside an asynchronous context, where dropping a Tokio runtime panics, it shuts down in the background instead.

When the store creates the database it writes SCHEMA_VERSION and the current CacheIdentity into it. It refuses to open a database with another version, and then one whose identity differs from the current one or that has none, because the cache is not portable between machines and users. It never wipes a cache by itself: kizz cache reset --all does, after asking, through Store::inventory, which counts the entries of a cache of any schema version and reads its identity, and Store::wipe.

Structs§

EntryCounts
How many entries of each family a set of cache entries holds, and how many tasks they belong to.
Inventory
What a whole cache holds, as Store::inventory counts it.
Store
The cache database, shared by the threads of one process.
Txn
A transaction on the Store: a consistent snapshot of the records, and for a write transaction, the changes to commit. Dropping it without committing discards the changes.

Enums§

StoreError
Why a store operation failed.

Constants§

DATABASE_DIR
The name of the database directory in the cache directory.
SCHEMA_VERSION
The version of the record encoding that this build of kizz reads and writes.
STALL_THRESHOLD
The number of immutable memory tables, and of level-0 files, at which SurrealKV would stall writes, as the store sets it: the largest number there is.