booblik-core

Generated page

Model gemma-mtp, commit ef58254ca7be, 2026-08-16, sources: 6. Edit the code or the hand-written documentation instead.

Position

The Position value class represents a byte position inside a single segment file, using an Int to match the indexing limits of MappedByteBuffer and transferTo calls Position.kt:6-8.

PartitionLog is the high-level abstraction of an ordered list of segments PartitionLog.kt:33. It manages the lifecycle of segments, including rolling to a new segment when the active one is full PartitionLog.kt:75 and implementing a retention mechanism that unlinks old segments to maintain a maximum size or age PartitionLog.kt:178.

More: PartitionLog

LogSegment

A LogSegment is the physical storage unit consisting of a data file and a sparse index LogSegment.kt:28. It supports a dual read/write architecture where a single writer owns the write path while multiple readers can concurrently access the segment via acquire and release mechanisms LogSegment.kt:194.

More: LogSegment

SegmentMode

The write path used by a segment is determined by the SegmentMode enum LogSegment.kt:25:

Mode	Description
`FILE_CHANNEL`	Uses a standard `FileChannel` for writes.
`MAPPED`	Uses a memory-mapped buffer for writes.

Recovery after a crash

During startup, LogSegment performs a recovery process by walking the record headers from the start of the segment to rebuild the SparseOffsetIndex LogSegment.kt:309. This process verifies each record's checksum to ensure data integrity, discarding any trailing partial records LogSegment.kt:354.

The write actor and group commit

The PartitionWriter acts as a single-threaded actor that owns the write side of a partition PartitionWriter.kt:18. It uses a mailbox to receive WriteCommand batches and implements "group commit" by draining the mailbox to process multiple commands in a single batch, only triggering a costly Log.force if any command in the group requires it PartitionWriter.kt:34.

Key files

File	Lines	What is there
`…/booblik/Position.kt`	`19-20`	The `Position` value class definition.
`…/storage/Log.kt`	`17-33`	The `Log` interface and `CorruptRecordException`.
`…/storage/PartitionLog.kt`	`33-258`	The `PartitionLog` class and its companion object.
`…/storage/LogSegment.kt`	`41-407`	The `LogSegment` class and its recovery logic.
`…/log/PartitionWriter.kt`	`45-312`	The `PartitionWriter` actor and its run loop.
`…/storage/SegmentWriter.kt`	`18`	The `SegmentWriter` interface.

Public API

What	Where	Why
`Position`	`Position.kt:19`	Represents a byte offset within a segment.
`Log`	`Log.kt:17`	Interface for append-only log operations.
`CorruptRecordException`	`Log.kt:43`	Thrown when a record fails checksum verification.
`PartitionLog`	`PartitionLog.kt:33`	High-level partition management.
`LogSegment`	`LogSegment.kt:41`	Physical segment storage and indexing.
`PartitionWriter`	`PartitionWriter.kt:45`	The actor responsible for writing to a partition.
`WriterClosedException`	`PartitionWriter.kt:312`	Thrown when attempting to write to a closed writer.
`SegmentWriter`	`SegmentWriter.kt:18`	Interface for segment-level writing.

Behaviour that surprises

PartitionWriter.append returns null when using AckPolicy.NONE because the offset is not yet assigned by the actor PartitionWriter.kt:130.
LogSegment.acquire may return false if the segment was retired while the caller was attempting to acquire it, requiring a retry LogSegment.kt:195.
PartitionLog.transferTo is designed to never cross a segment boundary because it uses a single file descriptor for the operation PartitionLog.kt:163.