gizdb/kv/local
the KV engine in this process, with no server. The same key space and log as the Redis-protocol server (space.giz, store.giz), seen as ordered byte keys and values with one global revision.
- A commit is a set of writes and deletes with conditions on the keys' revisions. It gets the next revision, and is all or nothing: its records end in one checksummed pass of the log, so a cut tail drops it whole. - apply runs a commit in memory; flush makes every applied commit durable with one write and one sync of each file. A caller that has several commits at once applies them all, then flushes once (group commit). - Each key keeps the revision of its last write in the first 8 bytes of its record's value, and database 1 keeps the store's revision (written once a flush), so both survive a restart without a second structure. - changes gives each key changed after a revision, in the order of its last change, with its current value. The recent changes are kept as keys only (gizlang/state Recent); a reader behind them, or one that comes back after a restart, gets the current keys of its prefix instead (reset). - The keys are also kept packed in byte order (Keys), so a prefix range is a search and a walk.
It is single-threaded: one task owns a Kv. gizdb/kv/state serves one to other tasks and processes.
import * as Local from "gizdb/kv/local";Types
Kv
type Kv = { ks: Keyspace; dir: Option<Dir>; revision: i64; durable: i64; keys: Keys; recent: Recent; }A key-value store: its keyspace, its folder when on disk, and its revisions.
ks:_gizlang_lib_db__kv__space.Keyspacedir:_gizlang_sdk_core.Option<gizlang_system.Dir>revision:i64— The last applied revision, and the last one on disk (equal in memory).durable:i64keys:M109.Keys— Every key, in byte order.recent:gizlang_state.Recent— The recent changes, as keys.
Size
type Size = { keys: i64; logBytes: i64; residentBytes: i64; }The keys, the log and the memory the store holds.
keys:i64logBytes:i64residentBytes:i64
Functions
open
function open(dir: Option<Dir>, budget: i64 = BUDGET): Kv throws IoErrorThe store in DIR (its log is read back; a torn last commit is cut), or one in memory when DIR is none. On disk, at most BUDGET bytes of the log stay in memory from the open on: the newest segment and the most read ones. Reads of the rest go to the files. The keys and their index stay in memory.
Effects: fail, read, write, console, io, alloc.
medium
function medium(kv: Kv): MediumKV, owned by a typed store from now on (gizlang/state open): its functions over the one copy.
Effects: fail, write, alloc.
Methods
Kv.get
function Kv.get(self: mut Kv, key: bytes): Option<Entry>The entry of KEY, or none.
Effects: fail, read, console, io, alloc.
Kv.revisionOf
function Kv.revisionOf(self: mut Kv, key: bytes): i64The revision of KEY's last write, or 0 when it is absent.
Effects: fail, read, console, io, alloc.
Kv.range
function Kv.range(self: mut Kv, prefix: bytes): Vec<Entry>The entries whose keys start with PREFIX, in byte order.
Effects: fail, read, console, io, alloc.
Kv.apply
function Kv.apply(self: mut Kv, writes: Vec<Write>): i64 throws KvErrorRuns WRITES as the next commit, in memory: every condition first, then every write. Its revision; a failed condition changes nothing. Durable after the next flush.
Effects: fail, read, console, io, alloc.
Kv.flush
function Kv.flush(self: mut Kv): void throws KvErrorMakes every applied commit durable: the store's revision, then the log's new bytes in one write and one sync a file (Store.flush). Then a step of compaction, whose moves the next flush makes durable, and the memory budget.
Effects: fail, read, console, io, alloc.
Kv.commit
function Kv.commit(self: mut Kv, writes: Vec<Write>): i64 throws KvErrorapply, then flush: WRITES are durable when it returns.
Effects: fail, read, console, io, alloc.
Kv.changes
function Kv.changes(self: mut Kv, prefix: bytes, after: i64): ChangedThe durable changes after revision AFTER of the keys that start with PREFIX: each key once, at its last change, with its value now (none: deleted).
Effects: fail, read, console, io, alloc.
Kv.size
function Kv.size(self: Kv): SizeWhat the store holds now (Size).
Effects: fail.
Kv.dispose
function Kv.dispose(self: mut Kv): void throws KvErrorFlushes and closes the log's files.
Effects: fail, read, console, io, alloc.
Constants
BUDGET
const BUDGET: i64 = 4194304The log bytes a store keeps in memory unless open is given another budget: a settings store of 10,000 objects whole (2.2 MB of segments). The read-hot segments stay; a read of another goes to its file.