Skip to main content

Crate logdb

Crate logdb 

Source
Expand description

§logdb — Embedded Append-Only Log Database

logdb is an embedded, append-only, crash-recoverable, optionally tamper-proof, optionally remotely-pushable local log database.

§Features

  • High-throughput append: lock-free fast path with CAS-based ring buffer
  • Crash recovery: automatic torn-write detection and truncation on restart
  • Optional hash chain: SHA-256 forward-linking for tamper detection (hash-chain feature)
  • Segment management: automatic rolling, configurable retention
  • Segment pre-allocation: next segment is pre-created at 80% capacity, reducing roll-time blocking to a single fdatasync call

§Performance: Inline vs Spill

Records ≤ INLINE_CAP (256) bytes take the inline fast path: zero heap allocation, zero extra memcpy. p50 is typically <100ns.

Records > 256 bytes take the spill path: a heap allocation in the append thread. The spill path is ~4x slower in throughput with ~80x higher p99.9 tail latency due to allocator jitter. Keep latency-sensitive records ≤ 256B.

Structs§

Config
Complete configuration for a LogDb instance.
KeyRing
A resolved, in-memory set of AES-256-GCM keys supporting rotation without a disk-format change (cr-032).
LogDb
The main log database handle.
Record
A fully owned record, typically read back from a segment file.
RecordId
Logical position of a record in the log.
RecoveryReport
Recovery report returned by LogDb::recovery_report.
ScanIter
Public scan iterator returned by LogDb::scan and LogDb::replay_from.
Tailer
A named consumer with independent read progress.
WaitStrategy
Wait strategy for background thread spinning.

Enums§

AppendError
Errors that can occur during append.
ConfigError
Errors that can occur while validating a Config.
DurabilityMode
Durability mode for the Committer.
FlushError
Errors that can occur during flush.
IoBackend
I/O backend for the Committer.
OpenError
Errors that can occur while opening a LogDb.
QueueFullPolicy
Policy when the ring buffer is full.
ReadError
Errors that can occur during read or scan.
RetentionPolicy
Retention policy for old segments.
ShutdownError
Errors that can occur during shutdown.
ShutdownReport
Result of a shutdown operation.
TailerError
Errors that can occur while reading the next batch from a Tailer.

Functions§

decode_record_id
Decode a global record_id into (shard_id, local_seq).
encode_record_id
Encode a (shard_id, local_seq) pair into a global record_id.
shard_bits
Compute the number of bits needed to represent shards - 1.