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§
- Entry
Counts - 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::inventorycounts 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§
- Store
Error - 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
SurrealKVwould stall writes, as the store sets it: the largest number there is.