GizStack
View .mdOpen in ChatGPTOpen in Claude

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.

gizlang
import * as Local from "gizdb/kv/local";

Types

Kv

gizlang
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.Keyspace
  • dir: _gizlang_sdk_core.Option<gizlang_system.Dir>
  • revision: i64 — The last applied revision, and the last one on disk (equal in memory).
  • durable: i64
  • keys: M109.Keys — Every key, in byte order.
  • recent: gizlang_state.Recent — The recent changes, as keys.

Size

gizlang
type Size = { keys: i64; logBytes: i64; residentBytes: i64; }

The keys, the log and the memory the store holds.

  • keys: i64
  • logBytes: i64
  • residentBytes: i64

Functions

open

gizlang
function open(dir: Option<Dir>, budget: i64 = BUDGET): Kv throws IoError

The 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

gizlang
function medium(kv: Kv): Medium

KV, owned by a typed store from now on (gizlang/state open): its functions over the one copy.

Effects: fail, write, alloc.

Methods

Kv.get

gizlang
function Kv.get(self: mut Kv, key: bytes): Option<Entry>

The entry of KEY, or none.

Effects: fail, read, console, io, alloc.

Kv.revisionOf

gizlang
function Kv.revisionOf(self: mut Kv, key: bytes): i64

The revision of KEY's last write, or 0 when it is absent.

Effects: fail, read, console, io, alloc.

Kv.range

gizlang
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

gizlang
function Kv.apply(self: mut Kv, writes: Vec<Write>): i64 throws KvError

Runs 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

gizlang
function Kv.flush(self: mut Kv): void throws KvError

Makes 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

gizlang
function Kv.commit(self: mut Kv, writes: Vec<Write>): i64 throws KvError

apply, then flush: WRITES are durable when it returns.

Effects: fail, read, console, io, alloc.

Kv.changes

gizlang
function Kv.changes(self: mut Kv, prefix: bytes, after: i64): Changed

The 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

gizlang
function Kv.size(self: Kv): Size

What the store holds now (Size).

Effects: fail.

Kv.dispose

gizlang
function Kv.dispose(self: mut Kv): void throws KvError

Flushes and closes the log's files.

Effects: fail, read, console, io, alloc.

Constants

BUDGET

gizlang
const BUDGET: i64 = 4194304

The 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.