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

