doc.go RawHistoryFolder

1// SPDX-License-Identifier: MIT
2
3// Package kv is an embedded key-value store. The whole dataset lives in
4// memory as immutable snapshots and is persisted to an append-only log.
5// A single writer goroutine applies batches and groups their fsync calls;
6// readers load the current snapshot without locks.
7//
8// # Guarantees
9//
10//   - Durability: DB.Apply returns only after the batch is written and
11//     synced (fdatasync), unless Options.NoSync is set. After a crash or a
12//     power loss, Open recovers every acknowledged batch, and the state is
13//     exactly a prefix of the applied batches.
14//   - Atomicity: a Batch is applied entirely or not at all. Its
15//     preconditions (RequireAbsent, RequireVersion) are checked against the
16//     latest state before any op; a failed precondition returns ErrConflict.
17//   - Visibility: a successful Apply is visible to the next DB.Snapshot or
18//     DB.Get (read-your-writes). Nothing is visible before it is durable.
19//   - Snapshots are immutable and safe for concurrent use. Keys yielded by
20//     iterators and Item.Value are owned by the snapshot and must not be
21//     modified.
22//   - ErrFailed means a write or sync failed. The outcome of the batches in
23//     that commit group is unknown (they may be replayed by the next Open);
24//     every later Apply fails, while reads keep serving the last snapshot.
25//     Close the DB and open it again to recover.
26//   - ErrCorrupt means Open found damage that is not a torn tail of the last
27//     log. Open never silently drops acknowledged data.
28//
29// One process at a time may open a directory (ErrLocked otherwise). Linux
30// only. Logs go through the zerowrap logger carried by the ctx given to Open.
31package kv