StorageEngine class final

Local storage engine: WAL → memtable → immutable segments.

The core is synchronous and this is the only class that knows about all the pieces: the WAL knows nothing about memtables or segments, the memtable knows nothing about files, and segments are pure byte codecs.

Durability ordering on every write:

append the frame to the WAL,
apply it to the arena and memtable.

Durability ordering on a flush:

write and flush the segment file,
write and flush the manifest (the commit point),
truncate the WAL and drop the memtable.

A crash between 2 and 3 replays the WAL again, which is idempotent: the same key/value pairs overwrite themselves in the new memtable.

Constructors

StorageEngine({required SyncStorageDirectory directory, int arenaChunkSize = 1 << 20, int maxMemtableBytes = 64 << 20, int blockTargetSize = 64 * 1024, Durability durability = Durability.batched, bool autoFlush = false, bool autoCompact = true, int compactionThreshold = 4, MaintenanceScheduler? maintenanceScheduler, SegmentBuildFunction? backgroundSegmentBuilder, bool readOnly = false}): Creates an engine over directory.

Properties

arena → DocArena: The document arena, exposed for flushing.
no setter
autoCompact → bool: Whether crossing compactionThreshold segments compacts automatically.
final
autoFlush → bool: Whether crossing maxMemtableBytes flushes to a segment automatically.
final
autoSync → bool: Whether every write flushes the WAL before returning.
no setter
backgroundSegmentBuilder → SegmentBuildFunction?: Builds segments off the engine isolate.
final
blockTargetSize → int: Target block size when building a segment.
final
compactionThreshold → int: Number of segments that triggers an automatic compaction after a flush.
final
durability → Durability: Durability level for committed writes.
final
generation → int: Manifest generation, or 0 when nothing has been flushed yet.
no setter
hashCode → int: The hash code for this object.
no setterinherited
inTransaction → bool: Whether a transaction is currently open.
no setter
maintenanceScheduled → bool: Whether deferred maintenance is pending.
no setter
maintenanceScheduler → MaintenanceScheduler?: Optional scheduler for deferred flush/compaction.
final
maxMemtableBytes → int: Threshold at which shouldFlush becomes true.
final
memoryBytes → int: Bytes of document payload plus keys currently held in memory.
no setter
memtable → MemTable: The memtable, exposed for flushing and tests.
no setter
readOnly → bool: Whether writes are rejected and the WAL is never modified.
final
recoveredFromWal → bool: Whether the last openSync rebuilt the state from the WAL because no manifest slot decoded. Orphan segment files are kept and reported by checkSync; a caller can use this flag to surface the event.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
segments → List<SegmentReader>: Segments currently searched, oldest first.
no setter
shouldFlush → bool: Whether the write buffer should be flushed to a segment.
no setter
transactionOps → Iterable<WalOp>?: Writes buffered by the open transaction, or null outside one.
no setter

Methods

applyBatchSync(List<WalOp> ops) → void: Applies puts and deletes as one WAL frame.
checkSync({bool verifyBlocks = true}) → CheckReport: Verifies the manifest, every referenced segment and the file set.
close() → Future<void>: Async facade over closeSync.
closeSync() → void: Flushes pending writes and releases the directory lock.
compactSync() → bool: Merges every segment into one, keeping the newest version of each key.
delete(Uint8List key) → Future<void>: Async facade over deleteSync.
deleteSync(Uint8List key) → void: Deletes key. Deleting a missing key is allowed.
flush() → Future<SegmentInfo?>: Async facade over flushSync.
flushSync() → SegmentInfo?: Flushes the memtable into a new segment and resets the WAL.
get(Uint8List key) → Bytes?: Reads key, or null when absent, deleted, or shadowed by a tombstone.
maybeFlushSync() → bool: Flushes when shouldFlush is true.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
open() → Future<void>: Async facade over openSync.
openSync() → void: Loads the manifest and replays the WAL. Call once before serving reads.
put(Uint8List key, Bytes document) → Future<void>: Async facade over putSync.
putMany(List<({Bytes document, Uint8List key})> entries) → Future<void>: Async facade over putManySync.
putManySync(List<({Bytes document, Uint8List key})> entries) → void: Inserts or replaces several documents with a single WAL frame.
putSync(Uint8List key, Bytes document) → void: Inserts or replaces key with the encoded document.
sync() → Future<void>: Async facade over syncNow.
syncNow() → void: Makes everything appended so far durable.
toString() → String: A string representation of this object.
inherited
transactionSync<T>(T body()) → T: Runs body as one atomic transaction.
waitForMaintenance() → Future<void>: Waits for any in-flight background segment build.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Constants

segmentPrefix → const String: Prefix of segment files.
segmentSuffix → const String: Suffix of segment files.
walFileName → const String: Name of the write-ahead log file.