forgedb_storage_native/lib.rs
1//! ForgeDB Storage Engine
2//!
3//! High-performance columnar storage engine for ForgeDB with positional I/O reads,
4//! WAL integration, and tombstone-based deletion tracking.
5//!
6//! # Overview
7//!
8//! `forgedb-storage` is the core storage engine for ForgeDB, implementing a columnar storage
9//! architecture optimized for both read and write performance. The crate provides:
10//!
11//! - **Columnar storage format** - Fixed-size and variable-length columns stored separately
12//! - **Positional I/O reads** - Concurrent-safe reads via `pread(2)`-style positional I/O
13//! (`FileExt::read_exact_at`) that avoids touching the shared file cursor; multiple `&self`
14//! readers on the same column can execute concurrently without synchronisation
15//! - **Seek-based writes** - Append methods seek to end-of-file before writing, taking `&mut self`
16//! for exclusive ownership during the seek + write sequence
17//! - **WAL integration** - Write-Ahead Log support for ACID properties and crash recovery
18//! - **Tombstone tracking** - Efficient soft-delete mechanism without data movement
19//! - **Type-safe API** - Strong typing for columns and database operations
20//!
21//! # Architecture
22//!
23//! ## Columnar Storage Format
24//!
25//! The storage engine uses a columnar layout where each column is stored in separate files:
26//!
27//! ```text
28//! data/
29//! ├── manifest.json # Database metadata
30//! ├── tombstones.bin # Deletion bitmap
31//! ├── fixed/
32//! │ └── u64_0.bin # Fixed-size column (8 bytes per row)
33//! └── variable/
34//! ├── string_data_0.bin # Variable-length data
35//! └── string_offsets_0.bin # (offset, length) pairs
36//! ```
37//!
38//! ## Fixed-Size vs Variable-Length Columns
39//!
40//! **Fixed-Size Columns** (u64, i64, f64, uuid):
41//! - Storage: `fixed/{type}_{index}.bin`
42//! - Layout: Sequential values with no overhead
43//! - Access: O(1) random access via `offset = index * value_size`
44//!
45//! **Variable-Length Columns** (strings):
46//! - Data file: `variable/string_data_{index}.bin` (append-only)
47//! - Offsets file: `variable/string_offsets_{index}.bin` (offset, length pairs)
48//! - Access: O(1) random access (read offset pair, then read string)
49//!
50//! ## Tombstone Bitmap
51//!
52//! Deletions are tracked using a tombstone bitmap:
53//! - Storage: `tombstones.bin` (1 byte per row)
54//! - Format: 0 = active, 1 = deleted
55//! - Benefits: No data movement, fast deletes, preserves row IDs
56//!
57//! # Examples
58//!
59//! ## Describing a model's physical layout (`Manifest`)
60//!
61//! Generated code owns the directory layout and drives the column types directly;
62//! the schema-blind [`Manifest`] records the physical layout (read by backup /
63//! the inspector), persisted next to the column files.
64//!
65//! ```rust,no_run
66//! use forgedb_storage_native::{Manifest, ColumnMetadata, ColumnType};
67//! use std::path::PathBuf;
68//!
69//! let manifest = Manifest {
70//! schema_version: 1,
71//! engine_version: 1,
72//! row_count: 42,
73//! columns: vec![
74//! ColumnMetadata { name: "id".to_string(), column_type: ColumnType::U64, column_index: 0, ..Default::default() },
75//! ColumnMetadata { name: "email".to_string(), column_type: ColumnType::String, column_index: 1, ..Default::default() },
76//! ],
77//! wal_enabled: false,
78//! last_checkpoint: 0,
79//! compaction_epoch: 0,
80//! row_anchor: None,
81//! auto_sequences: Default::default(),
82//! };
83//! manifest.save_to(&PathBuf::from("./mydb/manifest.json"))?;
84//! let reopened = Manifest::load_from(&PathBuf::from("./mydb/manifest.json"))?;
85//! assert_eq!(reopened.row_count, 42);
86//! # Ok::<(), std::io::Error>(())
87//! ```
88//!
89//! ## Working with Columns
90//!
91//! ```rust,no_run
92//! use forgedb_storage_native::FixedColumn;
93//! use std::path::PathBuf;
94//!
95//! // Fixed-size column
96//! let mut id_column = FixedColumn::new(PathBuf::from("./data/fixed/u64_0.bin"), 8)?;
97//! id_column.append_u64(1001)?;
98//! let id = id_column.read_u64(0)?; // &self — concurrent reads are safe
99//! assert_eq!(id, 1001);
100//! id_column.flush()?; // explicit fsync before a checkpoint or close
101//! # Ok::<(), std::io::Error>(())
102//! ```
103//!
104//! # Durability Model
105//!
106//! Column files (`FixedColumn`, `VariableColumn`, `Tombstones`) **do not fsync on every append**.
107//! Appended bytes are visible to subsequent reads via the OS page cache, but a crash before an
108//! explicit [`FixedColumn::flush`] / [`VariableColumn::flush`] / [`Tombstones::flush`] call can
109//! lose the most recent appends from those files.
110//!
111//! The **WAL is the crash-durability boundary**: all mutations should be recorded in the WAL
112//! (via [`WalManager`]) before being applied to the column files. On recovery, the WAL is replayed
113//! into the columnar materialization. Call `flush()` at commit / checkpoint boundaries to durably
114//! persist the column files.
115//!
116//! # Public API
117//!
118//! ## Core Types
119//!
120//! - [`Manifest`] - Physical-layout metadata stored in manifest.json
121//! - [`FixedColumn`] - Storage for fixed-size column data
122//! - [`VariableColumn`] - Storage for variable-length column data
123//! - [`Tombstones`] - Deletion tracking bitmap
124//!
125//! ## WAL Re-exports
126//!
127//! Types from [`forgedb-wal`](../forgedb_wal) for convenience:
128//! - [`FsyncPolicy`] - Controls when WAL is fsynced to disk
129//! - [`WalEntry`] - A framed opaque-bytes entry (model tag + `Raw` payload)
130//! - [`WalManager`] - High-level WAL interface
131//! - [`WalOperation`] - The `Raw { payload }` operation variant
132//!
133//! # Related Crates
134//!
135//! - [`forgedb-wal`](../forgedb_wal) - Write-Ahead Log for durability
136//! - [`forgedb-compaction`](../forgedb_compaction) - Background compaction for space reclamation
137
138// WAL re-exports (schema-agnostic substrate surface only)
139pub use forgedb_wal::{FsyncPolicy, WalEntry, WalManager, WalOperation};
140
141mod dir_lock;
142pub use dir_lock::DirLock;
143
144use std::fs::{self, File, OpenOptions};
145use std::io::{self, IoSlice, Seek, SeekFrom, Write};
146use std::os::unix::fs::FileExt;
147use std::path::PathBuf;
148
149/// Push a file's dirty page-cache pages to the storage device **without** a
150/// device-cache barrier (#153 — single-barrier checkpoint).
151///
152/// On macOS, `File::sync_all`/`sync_data` both map to `fcntl(F_FULLFSYNC)` — an
153/// expensive device barrier (~3.5 ms). `libc::fsync` is the *cheap* flush
154/// (~27 µs) that only pushes the file's data into the drive's (volatile) write
155/// cache; a single [`device_barrier`] afterward flushes that whole cache to
156/// permanent media, covering **every** file `fsync`ed this way on the same
157/// device. So a checkpoint of N columns costs N cheap fsyncs + ONE barrier
158/// instead of N barriers. On non-macOS, `sync_data` (fdatasync) is the cheapest
159/// available durable flush.
160#[cfg(target_os = "macos")]
161fn fsync_to_drive(file: &File) -> io::Result<()> {
162 use std::os::unix::io::AsRawFd;
163 // SAFETY: `file` is a live, open descriptor for the duration of the call.
164 if unsafe { libc::fsync(file.as_raw_fd()) } == -1 {
165 return Err(io::Error::last_os_error());
166 }
167 Ok(())
168}
169
170#[cfg(not(target_os = "macos"))]
171fn fsync_to_drive(file: &File) -> io::Result<()> {
172 file.sync_data()
173}
174
175/// Issue ONE device-cache barrier (#153). On macOS `fcntl(F_FULLFSYNC)` tells
176/// the drive to flush its entire write cache to permanent media — which makes
177/// durable every file previously handed to [`fsync_to_drive`] on the same
178/// device, so a checkpoint needs only one of these. On non-macOS, `sync_all` is
179/// the barrier.
180#[cfg(target_os = "macos")]
181fn device_barrier(file: &File) -> io::Result<()> {
182 use std::os::unix::io::AsRawFd;
183 // SAFETY: `file` is a live, open descriptor for the duration of the call.
184 if unsafe { libc::fcntl(file.as_raw_fd(), libc::F_FULLFSYNC) } == -1 {
185 return Err(io::Error::last_os_error());
186 }
187 Ok(())
188}
189
190#[cfg(not(target_os = "macos"))]
191fn device_barrier(file: &File) -> io::Result<()> {
192 file.sync_all()
193}
194
195/// Default schema serial for manifests written before the field existed.
196/// Old on-disk manifests deserialize as v1 (the original layout), not v0.
197fn default_schema_version() -> u32 {
198 1
199}
200
201/// Default engine generation for every manifest written before #254 added the
202/// field: generation 1, the baseline. This is what makes the counter additive
203/// rather than a second format break.
204fn default_engine_version() -> u32 {
205 1
206}
207
208/// Manifest stores metadata about the database
209#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
210pub struct Manifest {
211 /// The **app's** schema-migration serial: how many migrations from its own
212 /// `migrations/` lineage have been applied. Derived by
213 /// `MigrationLineage::current_schema_version`, baked into generated code as
214 /// `EXPECTED_SCHEMA_VERSION`, and compared by the generated `open()` guard,
215 /// which refuses a dir whose schema is not the one this binary was generated
216 /// from (#74 Phase 1). Lineage-sourced, never hand-edited.
217 ///
218 /// **The on-disk key stays `format_version` (#254).** Only the Rust name
219 /// changed, because the old one described the engine rather than the app.
220 /// A *different* vestigial `schema_version` key — hardcoded to `1` at every
221 /// write site, never incremented, never compared — used to occupy this name
222 /// on disk; it is deleted, and serde's unknown-key tolerance is what lets a
223 /// manifest still carrying it deserialize. Reading the wrong one of those two
224 /// is not a subtle bug: it would compare the open-guard against a constant.
225 #[serde(rename = "format_version", default = "default_schema_version")]
226 pub schema_version: u32,
227 /// ForgeDB's own **engine byte-format generation** (#254) — owned by the
228 /// released version line, not by the app. It covers both value
229 /// reinterpretation and physical layout, which is why it is not
230 /// `layout_version`.
231 ///
232 /// Orthogonal to `schema_version` above: a schema mismatch means *the app's
233 /// schema changed* and is fixed by the app's migration bin; an engine
234 /// mismatch means *ForgeDB changed* and is fixed by `forgedb migrate engine`.
235 /// Conflating them would send a user to regenerate a schema that is correct.
236 ///
237 /// Generations are assigned at merge order, not at design time — two format
238 /// changes in one cycle would otherwise both claim the same number and
239 /// whichever landed second would silently redefine the other's meaning.
240 ///
241 /// | gen | change |
242 /// |---|---|
243 /// | 1 | baseline — everything written before this field existed |
244 /// | 2 | timestamp values are microseconds, not seconds (#254) |
245 #[serde(default = "default_engine_version")]
246 pub engine_version: u32,
247 pub row_count: usize,
248 pub columns: Vec<ColumnMetadata>,
249 #[serde(default)]
250 pub wal_enabled: bool,
251 #[serde(default)]
252 pub last_checkpoint: u64,
253 /// Generation counter bumped on every compaction. A byte-watermark
254 /// incremental backup (#57) is valid only within one epoch — compaction
255 /// rewrites files and shifts offsets, so crossing an epoch forces a fresh
256 /// full backup. Additive (`#[serde(default)]`) for on-disk back-compat.
257 #[serde(default)]
258 pub compaction_epoch: u64,
259 /// On-disk layout format version, so a schema-blind reader (backup #57,
260 /// inspector #63) can refuse mismatched bytes instead of misreading them.
261 /// Which file's length authoritatively counts committed rows, and how many
262 /// bytes it spends per row. For a model this is `tombstones.bin` (1 byte/row,
263 /// appended last per insert); for an M2M junction it is `fixed/right.bin`
264 /// (16 bytes/row, appended last per link). A schema-blind reader derives the
265 /// committed row count as `len(anchor) / bytes_per_row` — the live watermark,
266 /// independent of the (possibly stale) `row_count` field above. `None` on
267 /// legacy manifests ⇒ fall back to `tombstones.bin`.
268 #[serde(default)]
269 pub row_anchor: Option<RowAnchor>,
270 /// Per-field allocation high-water marks, as an **opaque** `name -> highest
271 /// value handed out` map (#187).
272 ///
273 /// The substrate neither parses these keys nor branches on them: it stores
274 /// and returns strings and integers. Which fields appear, what the numbers
275 /// mean, and every read and write of them belong to generated code — the
276 /// same class of layout metadata as `compaction_epoch`.
277 ///
278 /// It exists because a rescan alone cannot survive compaction: compaction
279 /// physically drops dead rows, so a post-compaction reopen derives a *lower*
280 /// maximum than was actually issued and hands the same value out twice. The
281 /// contract is a **floor, not a source of truth** — a reader takes
282 /// `max(persisted, scanned)`, so a crash that loses the tip falls back to the
283 /// scan, which is always safe. That is what buys durability without an fsync
284 /// per allocation.
285 ///
286 /// `BTreeMap` (not `HashMap`) so the serialized JSON is byte-stable across
287 /// writes. Additive (`#[serde(default)]`) for on-disk back-compat.
288 #[serde(default)]
289 pub auto_sequences: std::collections::BTreeMap<String, u64>,
290}
291
292/// Physical descriptor of the file whose length counts committed rows.
293/// Layout fact only — names a file and a per-row byte stride, never a schema
294/// semantic. See [`Manifest::row_anchor`].
295#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
296pub struct RowAnchor {
297 /// Anchor file path relative to the model/junction directory.
298 pub relative_path: String,
299 /// Bytes the anchor file spends per committed row (`1` for tombstones,
300 /// `16` for a junction's uuid `right` column).
301 pub bytes_per_row: usize,
302}
303
304impl Manifest {
305 /// Load a manifest from an explicit path (e.g. a per-model
306 /// `<model>/manifest.json`). Used by
307 /// schema-blind ops tooling — `forgedb-backup` (#57), the inspector (#63) —
308 /// that reads layout metadata for one model directory.
309 pub fn load_from(path: &std::path::Path) -> io::Result<Manifest> {
310 let content = fs::read_to_string(path)?;
311 serde_json::from_str(&content)
312 .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
313 }
314
315 /// Atomically write this manifest to `path` via temp-file + `fsync` +
316 /// `rename`. A crash mid-write leaves the intact previous manifest rather
317 /// than a truncated/garbage one that would fail to parse on the next open.
318 /// The temp file is `<path>.tmp`.
319 pub fn save_to(&self, path: &std::path::Path) -> io::Result<()> {
320 let content = serde_json::to_string_pretty(self)
321 .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
322
323 if let Some(parent) = path.parent() {
324 fs::create_dir_all(parent)?;
325 }
326
327 let mut tmp_path = path.as_os_str().to_owned();
328 tmp_path.push(".tmp");
329 let tmp_path = PathBuf::from(tmp_path);
330 {
331 let mut tmp = OpenOptions::new()
332 .write(true)
333 .create(true)
334 .truncate(true)
335 .open(&tmp_path)?;
336 tmp.write_all(content.as_bytes())?;
337 tmp.sync_all()?;
338 }
339 fs::rename(&tmp_path, path)?;
340 Ok(())
341 }
342}
343
344/// Whether a column is fixed-width (positional I/O) or variable-length
345/// (offset-indexed data file). Physical-layout fact only — never a schema
346/// semantic. Lets a schema-blind reader bound each file without guessing.
347#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
348pub enum ColumnKind {
349 #[default]
350 Fixed,
351 Variable,
352}
353
354#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
355pub struct ColumnMetadata {
356 pub name: String,
357 pub column_type: ColumnType,
358 pub column_index: usize,
359 /// Bytes per row for a fixed column; `0` for a variable column (its width
360 /// lives in the offsets file). Lets backup compute a fixed column's exact
361 /// committed length as `row_count * value_size` without guessing.
362 #[serde(default)]
363 pub value_size: usize,
364 /// Fixed vs. variable — selects how a reader bounds the column's files.
365 #[serde(default)]
366 pub kind: ColumnKind,
367 /// Column file path relative to the model directory (e.g.
368 /// `fixed/u32_0.bin` or `variable/string_data_1.bin`). For a variable
369 /// column this is the data file; the offsets file is the same path with
370 /// `_data.bin` → `_offsets.bin` (the storage-layout convention `stats.rs`
371 /// already relies on).
372 #[serde(default)]
373 pub relative_path: String,
374}
375
376#[derive(Debug, Clone, Default, PartialEq, serde::Serialize, serde::Deserialize)]
377pub enum ColumnType {
378 #[default]
379 U32,
380 U64,
381 I32,
382 I64,
383 F64,
384 Bool,
385 Uuid,
386 Timestamp,
387 String,
388 /// Fixed-size byte array (for char(N), structs, fixed arrays)
389 FixedBytes(usize),
390}
391
392/// A read snapshot: an immutable row-count watermark captured at a point in time.
393///
394/// This is the substrate primitive behind lock-free snapshot-isolated reads
395/// (see the `mvcc-concurrency` proposal, Direction A). Because the storage
396/// engine is **append-only** — rows are only ever appended, never moved or
397/// mutated in place — a row's *position* is stable for its whole lifetime.
398/// So a single integer, the row count at capture time, fully defines a
399/// consistent view: exactly the rows whose index is below the watermark were
400/// committed when the snapshot was taken, and every one of them is still at the
401/// same index now.
402///
403/// A `Snapshot` carries **no** per-row version metadata and no reference to any
404/// column data — it is a bare `usize`. Readers pass it to `*_at` accessors,
405/// which clamp their scan to `visible(index)`. Rows appended after capture have
406/// `index >= watermark` and are therefore invisible, so concurrent writers
407/// cannot make a reader observe a torn or partial row.
408///
409/// It is schema-agnostic substrate: it knows nothing about any `.forge` model,
410/// only about row positions. Generated code composes per-model watermarks into
411/// its own snapshot struct.
412#[derive(Debug, Clone, Copy, PartialEq, Eq)]
413pub struct Snapshot {
414 watermark: usize,
415}
416
417impl Snapshot {
418 /// Capture a snapshot at the given committed row count.
419 pub fn new(row_count: usize) -> Self {
420 Self {
421 watermark: row_count,
422 }
423 }
424
425 /// The captured row count. Rows at index `0..watermark` are visible.
426 pub fn watermark(&self) -> usize {
427 self.watermark
428 }
429
430 /// Whether the row at `index` was committed as of this snapshot.
431 pub fn visible(&self, index: usize) -> bool {
432 index < self.watermark
433 }
434}
435
436/// Fixed-size column storage backed by a seek-based file.
437///
438/// # Durability
439///
440/// Append methods write to the OS page cache but do **not** call `fsync` per append.
441/// Data written by `append_*` is immediately readable (via `read_*`) on the same or
442/// any other file descriptor to the same file, but a crash before [`flush`](FixedColumn::flush)
443/// may lose the most recent appends. Call `flush()` at commit boundaries or before
444/// advancing the WAL checkpoint.
445/// The backing of one columnar export batch — the substrate half of the
446/// language bindings' Arrow / columnar-export path.
447///
448/// A columnar export hands the caller (generated FFI glue) a single contiguous,
449/// stable-pointer byte buffer for one column at one live-row selection. This
450/// type owns that buffer through *whichever* of the two production paths
451/// produced it, behind an identical `as_ptr()` / `len()` surface so the consumer
452/// (e.g. an Arrow `ArrowArray`) is **alias-or-gather transparent**:
453///
454/// - [`ColumnExport::Mapped`] — a **zero-copy `mmap` alias** of the column
455/// file's dense prefix, taken when the live selection is exactly the
456/// contiguous prefix `[0, n)` (no updates, no tombstones). No bytes are
457/// copied; the pointer aliases the page cache directly. Because numeric
458/// columns are stored little-endian (`to_le_bytes`), the mapped prefix *is* a
459/// valid Arrow primitive buffer as-is.
460/// - [`ColumnExport::Owned`] — a gathered contiguous copy (`FixedColumn::gather`),
461/// the fallback whenever the selection is not an aliasable dense prefix
462/// (update-heavy or tombstoned tables), or is empty.
463///
464/// # Safety / aliasing invariant (`Mapped`)
465///
466/// The mapped prefix aliases live file pages, so it relies on the same
467/// single-writer, append-only discipline the reader handles already assume:
468/// prefix rows `[0, n)` are committed and immutable (appends only ever extend
469/// past `n`, never rewrite mapped bytes), and a compaction/rollback that would
470/// renumber or truncate below `n` does not run while an export is outstanding
471/// (exports are synchronous reads taken on the single writer). Under that
472/// discipline the alias observes a stable snapshot.
473pub enum ColumnExport {
474 /// A gathered / copied contiguous buffer.
475 Owned(Vec<u8>),
476 /// A zero-copy read-only `mmap` alias of the column file's dense prefix.
477 Mapped(memmap2::Mmap),
478}
479
480impl ColumnExport {
481 /// Pointer to the first byte of the exported buffer. Stable across moving
482 /// the `ColumnExport` (both a `Vec`'s heap allocation and an `Mmap`'s mapped
483 /// address are independent of where the owner struct itself lives), so the
484 /// FFI layer can capture it, then move `self` into an owner box.
485 #[must_use]
486 pub fn as_ptr(&self) -> *const u8 {
487 match self {
488 ColumnExport::Owned(v) => v.as_ptr(),
489 ColumnExport::Mapped(m) => m.as_ptr(),
490 }
491 }
492
493 /// Total exported byte length (`live_rows * value_size`).
494 #[must_use]
495 pub fn len(&self) -> usize {
496 match self {
497 ColumnExport::Owned(v) => v.len(),
498 ColumnExport::Mapped(m) => m.len(),
499 }
500 }
501
502 #[must_use]
503 pub fn is_empty(&self) -> bool {
504 self.len() == 0
505 }
506
507 /// The exported bytes as a slice.
508 #[must_use]
509 pub fn as_slice(&self) -> &[u8] {
510 match self {
511 ColumnExport::Owned(v) => v.as_slice(),
512 ColumnExport::Mapped(m) => &m[..],
513 }
514 }
515}
516
517/// An in-memory bulk-loaded selection of a [`FixedColumn`]'s rows (#168).
518///
519/// Produced by [`FixedColumn::gather_buffered`], it holds one column's selected
520/// rows as a single contiguous buffer (a zero-copy `mmap` alias of the dense
521/// prefix, or a gathered copy) and exposes the **same** positional
522/// `read_*` accessors as [`FixedColumn`], addressed by **slot** (`0..n` over the
523/// selection order) rather than physical row index. Decoding one column of a
524/// scan from this buffer costs no syscalls; it lets the generated column scan
525/// decode with the identical per-field logic it uses for per-row reads.
526///
527/// Errors mirror [`FixedColumn`]: an out-of-range slot returns `InvalidInput`.
528pub struct BufferedFixedColumn {
529 buf: ColumnExport,
530 value_size: usize,
531}
532
533impl BufferedFixedColumn {
534 /// Number of buffered slots (`indices.len()` from the gather).
535 #[must_use]
536 pub fn len(&self) -> usize {
537 self.buf.len() / self.value_size
538 }
539
540 #[must_use]
541 pub fn is_empty(&self) -> bool {
542 self.len() == 0
543 }
544
545 /// The `value_size`-wide bytes at `slot`, or `InvalidInput` if out of range.
546 fn slot_bytes(&self, slot: usize) -> io::Result<&[u8]> {
547 let start = slot * self.value_size;
548 let end = start + self.value_size;
549 self.buf.as_slice().get(start..end).ok_or_else(|| {
550 io::Error::new(io::ErrorKind::InvalidInput, "Slot out of bounds")
551 })
552 }
553
554 pub fn read_u32(&self, slot: usize) -> io::Result<u32> {
555 let b = self.slot_bytes(slot)?;
556 Ok(u32::from_le_bytes(b[..4].try_into().unwrap()))
557 }
558
559 pub fn read_u64(&self, slot: usize) -> io::Result<u64> {
560 let b = self.slot_bytes(slot)?;
561 Ok(u64::from_le_bytes(b[..8].try_into().unwrap()))
562 }
563
564 pub fn read_i32(&self, slot: usize) -> io::Result<i32> {
565 let b = self.slot_bytes(slot)?;
566 Ok(i32::from_le_bytes(b[..4].try_into().unwrap()))
567 }
568
569 pub fn read_i64(&self, slot: usize) -> io::Result<i64> {
570 let b = self.slot_bytes(slot)?;
571 Ok(i64::from_le_bytes(b[..8].try_into().unwrap()))
572 }
573
574 pub fn read_f64(&self, slot: usize) -> io::Result<f64> {
575 let b = self.slot_bytes(slot)?;
576 Ok(f64::from_le_bytes(b[..8].try_into().unwrap()))
577 }
578
579 pub fn read_bool(&self, slot: usize) -> io::Result<bool> {
580 let b = self.slot_bytes(slot)?;
581 Ok(b[0] != 0)
582 }
583
584 pub fn read_uuid(&self, slot: usize) -> io::Result<[u8; 16]> {
585 let b = self.slot_bytes(slot)?;
586 Ok(b[..16].try_into().unwrap())
587 }
588
589 pub fn read_timestamp(&self, slot: usize) -> io::Result<i64> {
590 let b = self.slot_bytes(slot)?;
591 Ok(i64::from_le_bytes(b[..8].try_into().unwrap()))
592 }
593
594 /// The whole `value_size`-wide value at `slot` (for char(N) / struct /
595 /// fixed-array / nullable / optional-FK columns decoded via `read_unaligned`).
596 pub fn read_bytes(&self, slot: usize) -> io::Result<Vec<u8>> {
597 Ok(self.slot_bytes(slot)?.to_vec())
598 }
599
600 /// The whole `value_size`-wide slot at `slot`, **borrowed** (#238).
601 ///
602 /// The zero-copy counterpart of [`Self::read_bytes`], which is exactly this
603 /// plus a `.to_vec()`; both stay, because a caller that wants an owned buffer
604 /// should not have to write the copy itself.
605 ///
606 /// Borrowing is sound here and nowhere else on the fixed path: this type owns
607 /// its bytes (a gathered `Vec` or an `Mmap` alias of the dense prefix), so the
608 /// `&self` lifetime is the buffer's. [`FixedColumn`] and [`FixedColumnReader`]
609 /// read through the file on every access and have nothing to lend — the same
610 /// split that put [`BufferedVariableColumn::read_str`] on the buffered tier
611 /// only (#224).
612 pub fn read_slice(&self, slot: usize) -> io::Result<&[u8]> {
613 self.slot_bytes(slot)
614 }
615
616 /// The whole `value_size`-wide slot at `slot` as UTF-8, **borrowed** (#238).
617 ///
618 /// For a column where the slot *is* the value and carries no framing:
619 /// `string(N!)` (#238 res 6 — exactly N ASCII characters, therefore exactly N
620 /// bytes, therefore no length prefix), and any other fixed UTF-8 payload.
621 ///
622 /// It deliberately does **not** understand a length prefix. Which slots carry
623 /// one, and how wide it is, is #238's per-declaration layout choice; teaching
624 /// it to a schema-agnostic crate would move generated knowledge into the
625 /// substrate. Prefixed slots read through [`Self::read_slice`] and decode in
626 /// generated code.
627 ///
628 /// # Errors
629 ///
630 /// `InvalidInput` if the slot is out of range; `InvalidData` if the slot's
631 /// bytes are not valid UTF-8 — same contract as
632 /// [`BufferedVariableColumn::read_str`].
633 pub fn read_str(&self, slot: usize) -> io::Result<&str> {
634 std::str::from_utf8(self.slot_bytes(slot)?)
635 .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
636 }
637}
638
639/// Selection size at or above which [`FixedColumn::gather`] maps the spanned
640/// region once and copies out of memory, instead of issuing one `read_exact_at`
641/// per index (#221).
642///
643/// Below this a handful of `pread`s beats a mapping's setup + teardown; above
644/// it the per-row syscall loop dominates completely — a 22-column scan of
645/// 10 000 live rows was 220 000 syscalls (~112 ms) before #221. Deliberately
646/// conservative rather than tuned: the point is to leave tiny gathers exactly
647/// as they were while removing the per-row syscall from bulk scans.
648const GATHER_MMAP_MIN_ROWS: usize = 8;
649
650pub struct FixedColumn {
651 file: File,
652 row_count: usize,
653 value_size: usize, // bytes per value
654}
655
656impl FixedColumn {
657 pub fn new(path: PathBuf, value_size: usize) -> io::Result<Self> {
658 // A zero value_size would divide-by-zero when deriving row_count below,
659 // and makes every offset computation meaningless.
660 if value_size == 0 {
661 return Err(io::Error::new(
662 io::ErrorKind::InvalidInput,
663 "FixedColumn value_size must be non-zero",
664 ));
665 }
666
667 // Create parent directory if needed
668 if let Some(parent) = path.parent() {
669 fs::create_dir_all(parent)?;
670 }
671
672 let file = OpenOptions::new()
673 .read(true)
674 .write(true)
675 .create(true)
676 .truncate(false)
677 .open(&path)?;
678
679 let row_count = file.metadata()?.len() as usize / value_size;
680
681 Ok(FixedColumn {
682 file,
683 row_count,
684 value_size,
685 })
686 }
687
688 pub fn append_u32(&mut self, value: u32) -> io::Result<()> {
689 self.file.seek(SeekFrom::End(0))?;
690 self.file.write_all(&value.to_le_bytes())?;
691 self.row_count += 1;
692 Ok(())
693 }
694
695 pub fn read_u32(&self, index: usize) -> io::Result<u32> {
696 if index >= self.row_count {
697 return Err(io::Error::new(
698 io::ErrorKind::InvalidInput,
699 "Index out of bounds",
700 ));
701 }
702
703 let offset = (index * self.value_size) as u64;
704 let mut buf = [0u8; 4];
705 self.file.read_exact_at(&mut buf, offset)?;
706 Ok(u32::from_le_bytes(buf))
707 }
708
709 pub fn append_u64(&mut self, value: u64) -> io::Result<()> {
710 self.file.seek(SeekFrom::End(0))?;
711 self.file.write_all(&value.to_le_bytes())?;
712 self.row_count += 1;
713 Ok(())
714 }
715
716 pub fn read_u64(&self, index: usize) -> io::Result<u64> {
717 if index >= self.row_count {
718 return Err(io::Error::new(
719 io::ErrorKind::InvalidInput,
720 "Index out of bounds",
721 ));
722 }
723
724 let offset = (index * self.value_size) as u64;
725 let mut buf = [0u8; 8];
726 self.file.read_exact_at(&mut buf, offset)?;
727 Ok(u64::from_le_bytes(buf))
728 }
729
730 pub fn append_i32(&mut self, value: i32) -> io::Result<()> {
731 self.file.seek(SeekFrom::End(0))?;
732 self.file.write_all(&value.to_le_bytes())?;
733 self.row_count += 1;
734 Ok(())
735 }
736
737 pub fn read_i32(&self, index: usize) -> io::Result<i32> {
738 if index >= self.row_count {
739 return Err(io::Error::new(
740 io::ErrorKind::InvalidInput,
741 "Index out of bounds",
742 ));
743 }
744
745 let offset = (index * self.value_size) as u64;
746 let mut buf = [0u8; 4];
747 self.file.read_exact_at(&mut buf, offset)?;
748 Ok(i32::from_le_bytes(buf))
749 }
750
751 pub fn append_i64(&mut self, value: i64) -> io::Result<()> {
752 self.file.seek(SeekFrom::End(0))?;
753 self.file.write_all(&value.to_le_bytes())?;
754 self.row_count += 1;
755 Ok(())
756 }
757
758 pub fn read_i64(&self, index: usize) -> io::Result<i64> {
759 if index >= self.row_count {
760 return Err(io::Error::new(
761 io::ErrorKind::InvalidInput,
762 "Index out of bounds",
763 ));
764 }
765
766 let offset = (index * self.value_size) as u64;
767 let mut buf = [0u8; 8];
768 self.file.read_exact_at(&mut buf, offset)?;
769 Ok(i64::from_le_bytes(buf))
770 }
771
772 pub fn append_f64(&mut self, value: f64) -> io::Result<()> {
773 self.file.seek(SeekFrom::End(0))?;
774 self.file.write_all(&value.to_le_bytes())?;
775 self.row_count += 1;
776 Ok(())
777 }
778
779 pub fn read_f64(&self, index: usize) -> io::Result<f64> {
780 if index >= self.row_count {
781 return Err(io::Error::new(
782 io::ErrorKind::InvalidInput,
783 "Index out of bounds",
784 ));
785 }
786
787 let offset = (index * self.value_size) as u64;
788 let mut buf = [0u8; 8];
789 self.file.read_exact_at(&mut buf, offset)?;
790 Ok(f64::from_le_bytes(buf))
791 }
792
793 pub fn append_bool(&mut self, value: bool) -> io::Result<()> {
794 self.file.seek(SeekFrom::End(0))?;
795 self.file.write_all(&[if value { 1u8 } else { 0u8 }])?;
796 self.row_count += 1;
797 Ok(())
798 }
799
800 pub fn read_bool(&self, index: usize) -> io::Result<bool> {
801 if index >= self.row_count {
802 return Err(io::Error::new(
803 io::ErrorKind::InvalidInput,
804 "Index out of bounds",
805 ));
806 }
807
808 let offset = (index * self.value_size) as u64;
809 let mut buf = [0u8; 1];
810 self.file.read_exact_at(&mut buf, offset)?;
811 Ok(buf[0] != 0)
812 }
813
814 pub fn append_uuid(&mut self, value: [u8; 16]) -> io::Result<()> {
815 self.file.seek(SeekFrom::End(0))?;
816 self.file.write_all(&value)?;
817 self.row_count += 1;
818 Ok(())
819 }
820
821 pub fn read_uuid(&self, index: usize) -> io::Result<[u8; 16]> {
822 if index >= self.row_count {
823 return Err(io::Error::new(
824 io::ErrorKind::InvalidInput,
825 "Index out of bounds",
826 ));
827 }
828
829 let offset = (index * self.value_size) as u64;
830 let mut buf = [0u8; 16];
831 self.file.read_exact_at(&mut buf, offset)?;
832 Ok(buf)
833 }
834
835 pub fn append_timestamp(&mut self, value: i64) -> io::Result<()> {
836 self.file.seek(SeekFrom::End(0))?;
837 self.file.write_all(&value.to_le_bytes())?;
838 self.row_count += 1;
839 Ok(())
840 }
841
842 pub fn read_timestamp(&self, index: usize) -> io::Result<i64> {
843 if index >= self.row_count {
844 return Err(io::Error::new(
845 io::ErrorKind::InvalidInput,
846 "Index out of bounds",
847 ));
848 }
849
850 let offset = (index * self.value_size) as u64;
851 let mut buf = [0u8; 8];
852 self.file.read_exact_at(&mut buf, offset)?;
853 Ok(i64::from_le_bytes(buf))
854 }
855
856 /// Append arbitrary bytes for complex fixed-size types (char arrays, structs, fixed arrays)
857 pub fn append_bytes(&mut self, value: &[u8]) -> io::Result<()> {
858 if value.len() != self.value_size {
859 return Err(io::Error::new(
860 io::ErrorKind::InvalidInput,
861 format!("Expected {} bytes, got {}", self.value_size, value.len()),
862 ));
863 }
864
865 self.file.seek(SeekFrom::End(0))?;
866 self.file.write_all(value)?;
867 self.row_count += 1;
868 Ok(())
869 }
870
871 /// Read arbitrary bytes for complex fixed-size types (char arrays, structs, fixed arrays)
872 pub fn read_bytes(&self, index: usize) -> io::Result<Vec<u8>> {
873 if index >= self.row_count {
874 return Err(io::Error::new(
875 io::ErrorKind::InvalidInput,
876 "Index out of bounds",
877 ));
878 }
879
880 let offset = (index * self.value_size) as u64;
881 let mut buf = vec![0u8; self.value_size];
882 self.file.read_exact_at(&mut buf, offset)?;
883 Ok(buf)
884 }
885
886 /// Copy the physical rows at `indices` into one contiguous owned buffer, in
887 /// the order given (`indices.len() * value_size` bytes).
888 ///
889 /// This is the class-1 columnar-read primitive behind the language bindings'
890 /// Arrow / columnar-export **gather** path — the fallback taken whenever the
891 /// live selection is *not* an aliasable dense prefix (update-heavy or
892 /// tombstoned tables) and a contiguous copy of exactly the live rows is
893 /// needed. It is schema-agnostic: `indices` are opaque physical row
894 /// positions the caller computed (generated code derives the live set from
895 /// `id_to_row` + tombstone liveness, exactly as `all()` / `all_at()` do
896 /// today); `gather` never reads a field name, type, or schema.
897 ///
898 /// # Performance (#221)
899 ///
900 /// For a selection of at least [`GATHER_MMAP_MIN_ROWS`] rows this maps the
901 /// spanned region `[min(indices), max(indices)]` **once** and copies out of
902 /// that mapping in contiguous runs, rather than issuing one `read_exact_at`
903 /// per index. Live selections under append-only churn are long runs broken
904 /// by the holes superseded rows leave behind, so runs are typically far
905 /// longer than one row and the copy collapses to a handful of `memcpy`s.
906 ///
907 /// The mapping is held only for the duration of the call and the returned
908 /// buffer is owned, so this relies on a strictly weaker form of the
909 /// aliasing invariant documented on [`ColumnExport`]: the spanned rows are
910 /// committed (`< row_count`, so within the file's length) and no concurrent
911 /// truncation runs, which the single-writer discipline already guarantees.
912 ///
913 /// Known-unmeasured case: a *sparse* selection spanning a very large file
914 /// faults in one page per isolated row, reading more bytes than the
915 /// per-row path would. It still trades syscalls for faults plus readahead,
916 /// and real live sets stay dense (amplification is bounded by the generated
917 /// compaction ceiling), but it has not been benchmarked.
918 ///
919 /// # Errors
920 ///
921 /// Returns `Err(InvalidInput)` if any index is `>= self.len()`.
922 pub fn gather(&self, indices: &[usize]) -> io::Result<Vec<u8>> {
923 if indices.is_empty() {
924 return Ok(Vec::new());
925 }
926
927 // Bounds-check the whole selection up front: the mapped path spans
928 // `min..=max`, so an out-of-range index has to be rejected before the
929 // span is computed (and `gather` is all-or-nothing either way).
930 let mut lo = usize::MAX;
931 let mut hi = 0usize;
932 for &index in indices {
933 if index >= self.row_count {
934 return Err(io::Error::new(
935 io::ErrorKind::InvalidInput,
936 "Index out of bounds",
937 ));
938 }
939 lo = lo.min(index);
940 hi = hi.max(index);
941 }
942
943 let mut out = vec![0u8; indices.len() * self.value_size];
944
945 if indices.len() >= GATHER_MMAP_MIN_ROWS {
946 let offset = (lo * self.value_size) as u64;
947 let map_len = (hi + 1 - lo) * self.value_size;
948 // A failed mapping is not fatal — the per-row loop below produces
949 // byte-identical output — so fall through instead of propagating.
950 let mapped = unsafe {
951 memmap2::MmapOptions::new()
952 .offset(offset)
953 .len(map_len)
954 .map(&self.file)
955 };
956 if let Ok(mmap) = mapped {
957 let src = &mmap[..];
958 let mut slot = 0usize;
959 while slot < indices.len() {
960 // Extend the run while the selection stays consecutive.
961 let start = slot;
962 while slot + 1 < indices.len() && indices[slot + 1] == indices[slot] + 1 {
963 slot += 1;
964 }
965 slot += 1;
966 let len = (slot - start) * self.value_size;
967 let s = (indices[start] - lo) * self.value_size;
968 let d = start * self.value_size;
969 out[d..d + len].copy_from_slice(&src[s..s + len]);
970 }
971 return Ok(out);
972 }
973 }
974
975 for (slot, &index) in indices.iter().enumerate() {
976 let src = (index * self.value_size) as u64;
977 let dst = slot * self.value_size;
978 self.file
979 .read_exact_at(&mut out[dst..dst + self.value_size], src)?;
980 }
981 Ok(out)
982 }
983
984 /// Export the physical rows at `indices` as a [`ColumnExport`], taking the
985 /// **zero-copy `mmap` alias** fast path when `indices` is the contiguous
986 /// dense prefix `[0, n)` and falling back to [`gather`](Self::gather)
987 /// (an owned copy) otherwise. The returned buffer is identical bytes either
988 /// way (`indices.len() * value_size`), so the FFI / Arrow consumer is
989 /// alias-or-gather transparent.
990 ///
991 /// This is the class-1 columnar-read primitive the language bindings' Arrow
992 /// export links: `indices` are opaque physical row positions the caller
993 /// (generated code) computed from the live set; `export` reads no field
994 /// name, type, or schema — it only inspects the indices' shape to decide
995 /// whether they alias a prefix.
996 ///
997 /// # Errors
998 ///
999 /// Returns `Err(InvalidInput)` if any index is `>= self.len()`, or an I/O
1000 /// error if the `mmap` of the aliasable prefix fails.
1001 pub fn export(&self, indices: &[usize]) -> io::Result<ColumnExport> {
1002 let n = indices.len();
1003 // A dense prefix is `indices == [0, 1, ..., n-1]`, entirely within the
1004 // committed rows. Empty selections take the trivial owned path.
1005 let is_dense_prefix =
1006 n > 0 && n <= self.row_count && indices.iter().enumerate().all(|(i, &x)| x == i);
1007
1008 if is_dense_prefix {
1009 // Alias exactly the first `n * value_size` bytes of the column file
1010 // — no copy. Safe under the single-writer/append-only invariant
1011 // documented on `ColumnExport`.
1012 let map_len = n * self.value_size;
1013 let mmap = unsafe { memmap2::MmapOptions::new().len(map_len).map(&self.file)? };
1014 return Ok(ColumnExport::Mapped(mmap));
1015 }
1016
1017 Ok(ColumnExport::Owned(self.gather(indices)?))
1018 }
1019
1020 /// Bulk-load the physical rows at `indices` into an in-memory
1021 /// [`BufferedFixedColumn`] whose positional `read_*(slot)` accessors read
1022 /// from memory instead of the file (#168 column scan).
1023 ///
1024 /// This is the class-1 read primitive behind the generated column-pruned
1025 /// sequential scan: a scan over `n` rows pays **one** bulk read per column
1026 /// (a zero-copy `mmap` alias when `indices` is the dense prefix `[0, n)` — the
1027 /// common append-only case — or a single gathered copy otherwise) rather than
1028 /// `n` per-row `read_exact_at` syscalls. `indices` are opaque physical row
1029 /// positions the caller (generated code) computed from the live set; the
1030 /// returned buffer's `read_*` methods take a **slot** `0..indices.len()`
1031 /// indexing into that selection, in the given order. Reads no field name,
1032 /// type, or schema.
1033 ///
1034 /// # Errors
1035 ///
1036 /// Propagates [`export`](Self::export)'s errors (out-of-bounds index or a
1037 /// failed `mmap`).
1038 pub fn gather_buffered(&self, indices: &[usize]) -> io::Result<BufferedFixedColumn> {
1039 Ok(BufferedFixedColumn {
1040 buf: self.export(indices)?,
1041 value_size: self.value_size,
1042 })
1043 }
1044
1045 /// Flush all pending writes to disk (fsync).
1046 ///
1047 /// This is the explicit durability checkpoint: after `flush()` returns `Ok(())`,
1048 /// all previous appends are guaranteed to survive a crash. Call this at transaction
1049 /// commit boundaries or before advancing the WAL checkpoint.
1050 pub fn flush(&mut self) -> io::Result<()> {
1051 self.file.sync_all()
1052 }
1053
1054 /// Push this column's data to the drive cache **without** a device barrier
1055 /// (#153). Pair with a single [`FixedColumn::barrier`] (on any column of the
1056 /// same device) to make a whole checkpoint's columns durable with ONE
1057 /// barrier instead of N. See [`fsync_to_drive`].
1058 pub fn sync_to_drive(&self) -> io::Result<()> {
1059 fsync_to_drive(&self.file)
1060 }
1061
1062 /// Issue the single device-cache barrier for a checkpoint (#153): flushes the
1063 /// drive's write cache to permanent media, making durable every column
1064 /// previously `sync_to_drive`d on the same device. See [`device_barrier`].
1065 pub fn barrier(&self) -> io::Result<()> {
1066 device_barrier(&self.file)
1067 }
1068
1069 #[must_use]
1070 pub fn len(&self) -> usize {
1071 self.row_count
1072 }
1073
1074 #[must_use]
1075 pub fn is_empty(&self) -> bool {
1076 self.row_count == 0
1077 }
1078
1079 /// Refresh the in-memory `row_count` from the on-disk file length (#84).
1080 ///
1081 /// Reads `read_exact_at` the file positionally, bounded by `row_count`. For
1082 /// the Tier 3 multi-process writer path a *peer* process may have appended
1083 /// values since this handle opened; `sync_from_disk` re-derives `row_count`
1084 /// from the shared file so the peer's committed rows become readable (paired
1085 /// with `Tombstones::sync_from_disk` and `VariableColumn::sync_from_disk`).
1086 /// A no-op for the single-writer path, which maintains `row_count` in memory.
1087 pub fn sync_from_disk(&mut self) -> io::Result<()> {
1088 self.row_count = self.file.metadata()?.len() as usize / self.value_size;
1089 Ok(())
1090 }
1091
1092 /// Truncate the column to hold exactly `rows` rows, discarding everything
1093 /// after that point.
1094 ///
1095 /// This is the crash-recovery primitive: after replaying a WAL, generated
1096 /// code calls `truncate_to_rows` on every column to realign them back to the
1097 /// last consistent row watermark before resuming appends. Any partial
1098 /// trailing value left by a torn write is physically removed so the next
1099 /// `append_*` lands at exactly row `rows`.
1100 ///
1101 /// # Errors
1102 ///
1103 /// Returns `Err(InvalidInput)` if `rows > self.len()` — truncation cannot
1104 /// extend a column. All other errors come from the underlying `set_len`
1105 /// syscall.
1106 pub fn truncate_to_rows(&mut self, rows: usize) -> io::Result<()> {
1107 if rows > self.row_count {
1108 return Err(io::Error::new(
1109 io::ErrorKind::InvalidInput,
1110 "truncate_to_rows beyond current length",
1111 ));
1112 }
1113 self.file.set_len((rows * self.value_size) as u64)?;
1114 self.row_count = rows;
1115 Ok(())
1116 }
1117
1118 /// Open a read-only, positionally-reading view over this column's file
1119 /// (#56 Direction B). The returned [`FixedColumnReader`] shares the file
1120 /// via an independent (`try_clone`d) descriptor, so a single `&mut self`
1121 /// writer can keep appending while many `&self` readers read concurrently
1122 /// without a lock. See [`FixedColumnReader`] for the full model.
1123 pub fn reader(&self) -> io::Result<FixedColumnReader> {
1124 Ok(FixedColumnReader {
1125 file: self.file.try_clone()?,
1126 value_size: self.value_size,
1127 })
1128 }
1129}
1130
1131/// An in-memory bulk-loaded selection of a [`VariableColumn`]'s rows (#168).
1132///
1133/// Produced by [`VariableColumn::gather_buffered`]; holds the column's data
1134/// bytes plus each selected slot's `(absolute offset, length)` so `read_string`
1135/// slices from memory without a syscall. The variable-column peer of
1136/// [`BufferedFixedColumn`]: same `read_string` name as [`VariableColumn`],
1137/// addressed by **slot** (`0..n` over the selection order).
1138pub struct BufferedVariableColumn {
1139 /// The spanned data region — a lazily-paged `mmap` alias when it is large
1140 /// enough to be worth mapping, an owned copy otherwise (#222).
1141 data: ColumnExport,
1142 /// File offset `data` starts at, so the absolute offsets in `slots` can be
1143 /// rebased onto it. Zero when the whole region is buffered, and zero on the
1144 /// sparse path (#228), where `data` is packed and `slots` already index into it.
1145 base: u64,
1146 // (offset, byte length) per slot, in selection order. The offset is absolute in
1147 // the data FILE on the spanned path and relative to `data` on the packed sparse
1148 // path — `base` is what reconciles them, so `read_str` needs no branch.
1149 slots: Vec<(u64, u64)>,
1150}
1151
1152impl BufferedVariableColumn {
1153 #[must_use]
1154 pub fn len(&self) -> usize {
1155 self.slots.len()
1156 }
1157
1158 #[must_use]
1159 pub fn is_empty(&self) -> bool {
1160 self.slots.is_empty()
1161 }
1162
1163 /// The slot's value **borrowed from the buffered span** — no allocation, no
1164 /// copy (#224).
1165 ///
1166 /// #222 made the span an `mmap` alias of the data region, so a scan already
1167 /// holds every live string's bytes; this is the read that stops copying them
1168 /// back out. The borrow is tied to `&self` and the mapping is owned by `self`,
1169 /// so the compiler guarantees the `&str` cannot outlive the pages it points at
1170 /// — a *tighter* constraint than the type already operates under, not a new
1171 /// aliasing exposure.
1172 ///
1173 /// UTF-8 is validated on every read (cheap next to the allocation it replaces)
1174 /// so an on-disk corruption surfaces as [`io::ErrorKind::InvalidData`] rather
1175 /// than as an unchecked `&str`.
1176 pub fn read_str(&self, slot: usize) -> io::Result<&str> {
1177 let &(offset, length) = self.slots.get(slot).ok_or_else(|| {
1178 io::Error::new(io::ErrorKind::InvalidInput, "Slot out of bounds")
1179 })?;
1180 // Slots carry absolute file offsets; `base` is where the buffered span
1181 // starts. Touching a mapped page here is what pulls it in — dead versions
1182 // between live rows are never addressed, so they are never read.
1183 let start = offset.saturating_sub(self.base) as usize;
1184 let end = start + length as usize;
1185 let bytes = self.data.as_slice().get(start..end).ok_or_else(|| {
1186 io::Error::new(io::ErrorKind::InvalidData, "Variable slot out of data bounds")
1187 })?;
1188 std::str::from_utf8(bytes).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
1189 }
1190
1191 /// The slot's value as an owned `String`. Kept for callers that genuinely need
1192 /// ownership; it is [`read_str`](Self::read_str) plus the copy, so there is one
1193 /// decode path and the two can never disagree.
1194 pub fn read_string(&self, slot: usize) -> io::Result<String> {
1195 self.read_str(slot).map(str::to_owned)
1196 }
1197}
1198
1199/// Variable-length column storage (for strings).
1200///
1201/// Stores data in an append-only data file plus a separate offset index file.
1202///
1203/// # Durability
1204///
1205/// Append methods write to the OS page cache but do **not** call `fsync` per append.
1206/// Call [`flush`](VariableColumn::flush) at commit boundaries to guarantee durability.
1207/// Spanned-data-region size at or above which [`VariableColumn::gather_buffered`]
1208/// maps rather than reads (#222).
1209///
1210/// Below this the span is small enough that a single bounded read costs less than a
1211/// mapping's setup and teardown; above it, mapping is what keeps dead versions inside
1212/// the span from being paid for — untouched pages are never faulted in. Conservative
1213/// rather than tuned; the shape of the win does not depend on the exact crossover.
1214const VAR_MMAP_MIN_BYTES: usize = 64 * 1024;
1215
1216/// Selection sparsity at which [`VariableColumn::gather_buffered`] reads each
1217/// offsets entry on its own instead of the whole spanned slice (#228).
1218///
1219/// The spanned read is one syscall for `span_rows * 16` bytes; the per-index read
1220/// is `n` syscalls of 16 bytes. The former wins while the selection is dense, and
1221/// loses badly once it is not: a two-row selection at opposite ends of a 20 000-row
1222/// column read 320 KB of offsets per column to use 32 bytes of it.
1223///
1224/// That shape is not hypothetical — it is what an index-pushdown candidate set
1225/// looks like. Since #228 unified the pushdown arm on the buffered scan, a handful
1226/// of scattered candidates reach here directly, and before this branch existed the
1227/// pushdown measured **5x slower** than the per-row positional decode it replaced.
1228///
1229/// The crossover is where `n` syscalls cost what the spanned read costs, which on
1230/// a warm page cache lands near `span_rows ≈ 190n`. `128` sits just under that:
1231/// conservative toward the spanned read (better locality, and it is the path the
1232/// dense common case takes), while still catching every sparse case by a wide
1233/// margin. The exact value is not load-bearing — the two costs differ by orders of
1234/// magnitude on either side of it, not by a few percent.
1235const SPARSE_OFFSETS_SPAN_FACTOR: usize = 128;
1236
1237pub struct VariableColumn {
1238 data_file: File,
1239 offsets_file: File,
1240 row_count: usize,
1241 current_data_offset: u64,
1242}
1243
1244impl VariableColumn {
1245 pub fn new(data_path: PathBuf, offsets_path: PathBuf) -> io::Result<Self> {
1246 // Create parent directories
1247 if let Some(parent) = data_path.parent() {
1248 fs::create_dir_all(parent)?;
1249 }
1250
1251 let data_file = OpenOptions::new()
1252 .read(true)
1253 .write(true)
1254 .create(true)
1255 .truncate(false)
1256 .open(&data_path)?;
1257
1258 let offsets_file = OpenOptions::new()
1259 .read(true)
1260 .write(true)
1261 .create(true)
1262 .truncate(false)
1263 .open(&offsets_path)?;
1264
1265 let current_data_offset = data_file.metadata()?.len();
1266 let row_count = offsets_file.metadata()?.len() as usize / 16; // 16 bytes per (offset, length)
1267
1268 Ok(VariableColumn {
1269 data_file,
1270 offsets_file,
1271 row_count,
1272 current_data_offset,
1273 })
1274 }
1275
1276 pub fn append_string(&mut self, value: &str) -> io::Result<()> {
1277 let bytes = value.as_bytes();
1278 let length = bytes.len() as u64;
1279
1280 // Write data to data file
1281 self.data_file.seek(SeekFrom::End(0))?;
1282 self.data_file.write_all(bytes)?;
1283
1284 // Write (offset, length) to offsets file
1285 self.offsets_file.seek(SeekFrom::End(0))?;
1286 self.offsets_file
1287 .write_all(&self.current_data_offset.to_le_bytes())?;
1288 self.offsets_file.write_all(&length.to_le_bytes())?;
1289
1290 self.current_data_offset += length;
1291 self.row_count += 1;
1292
1293 Ok(())
1294 }
1295
1296 /// Append a single tag byte followed by `value`'s bytes, as one row (#231).
1297 ///
1298 /// Exactly equivalent to `append_string(&format!("{tag_char}{value}"))` for any
1299 /// `tag` that is a valid single-byte UTF-8 scalar, but without materializing
1300 /// the concatenation: the tag and the value are written from their own slices
1301 /// in one vectored write, so a tagged append costs no allocation and no copy
1302 /// of the value.
1303 ///
1304 /// This is the write-side sibling of [`BufferedVariableColumn::read_str`]
1305 /// (#224) and it is schema-agnostic in exactly the same way — it knows nothing
1306 /// about what the tag *means*. Generated code uses it for the 1-byte presence
1307 /// tag on nullable `string`/`json` columns (`0x00` = None, `0x01` = Some), but
1308 /// the column stores opaque bytes either way.
1309 ///
1310 /// # Note on UTF-8
1311 ///
1312 /// The stored row is only valid UTF-8 — and so only readable by
1313 /// [`read_string`](VariableColumn::read_string) — when `tag < 0x80`. Tags at or
1314 /// above `0x80` produce a leading continuation/lead byte with nothing to
1315 /// complete it. The column itself is byte-oriented and will store them
1316 /// faithfully; it is the caller's job to keep tags in the ASCII range if the
1317 /// row must round-trip as a `String`.
1318 pub fn append_tagged(&mut self, tag: u8, value: &str) -> io::Result<()> {
1319 let bytes = value.as_bytes();
1320 let length = bytes.len() as u64 + 1;
1321
1322 self.data_file.seek(SeekFrom::End(0))?;
1323 let tag = [tag];
1324 let mut slices = [IoSlice::new(&tag), IoSlice::new(bytes)];
1325 let mut slices: &mut [IoSlice<'_>] = &mut slices;
1326 while !slices.is_empty() {
1327 let written = self.data_file.write_vectored(slices)?;
1328 if written == 0 {
1329 return Err(io::Error::new(
1330 io::ErrorKind::WriteZero,
1331 "failed to write whole tagged value",
1332 ));
1333 }
1334 IoSlice::advance_slices(&mut slices, written);
1335 }
1336
1337 // One 16-byte write rather than two, matching the (offset, length) pair
1338 // layout `append_string` produces.
1339 let mut entry = [0u8; 16];
1340 entry[..8].copy_from_slice(&self.current_data_offset.to_le_bytes());
1341 entry[8..].copy_from_slice(&length.to_le_bytes());
1342 self.offsets_file.seek(SeekFrom::End(0))?;
1343 self.offsets_file.write_all(&entry)?;
1344
1345 self.current_data_offset += length;
1346 self.row_count += 1;
1347
1348 Ok(())
1349 }
1350
1351 pub fn read_string(&self, index: usize) -> io::Result<String> {
1352 if index >= self.row_count {
1353 return Err(io::Error::new(
1354 io::ErrorKind::InvalidInput,
1355 "Index out of bounds",
1356 ));
1357 }
1358
1359 // Read offset and length from offsets file using positional I/O
1360 let offsets_pos = (index * 16) as u64;
1361 let mut offset_buf = [0u8; 8];
1362 let mut length_buf = [0u8; 8];
1363 self.offsets_file.read_exact_at(&mut offset_buf, offsets_pos)?;
1364 self.offsets_file
1365 .read_exact_at(&mut length_buf, offsets_pos + 8)?;
1366
1367 let offset = u64::from_le_bytes(offset_buf);
1368 let length = u64::from_le_bytes(length_buf);
1369
1370 // Read data from data file using positional I/O
1371 let mut data = vec![0u8; length as usize];
1372 self.data_file.read_exact_at(&mut data, offset)?;
1373
1374 String::from_utf8(data).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
1375 }
1376
1377 /// Bulk-load the rows at `indices` into an in-memory
1378 /// [`BufferedVariableColumn`] whose `read_string(slot)` reads from memory
1379 /// (#168 column scan).
1380 ///
1381 /// Reads only the **spanned** slice of the offsets index and maps only the
1382 /// **spanned** data region, so a scan over `n` variable rows pays one bounded
1383 /// read plus one mapping rather than `3n` per-row `read_exact_at` syscalls
1384 /// (offset + length + data). `indices` are opaque physical row positions;
1385 /// reads no schema.
1386 ///
1387 /// # Performance (#222)
1388 ///
1389 /// This used to read the **entire** committed offsets index and the **entire**
1390 /// data region into owned buffers on every call, ignoring `indices` — dead
1391 /// versions included. That made a scan cost `~A x live_bytes`, a slope in
1392 /// amplification rather than the fixed columns' step, and it was measured as
1393 /// exactly that: at 2 000 live rows the narrow scan went 563 µs -> 5.8 ms
1394 /// across A = 1 -> 16, doubling with each doubling of A.
1395 ///
1396 /// Both reads are now bounded to `[min(indices), max(indices)]`. Append order
1397 /// makes data offsets monotonic in row index, so that row span maps to one
1398 /// contiguous byte span. The data span is **mapped** rather than read when it
1399 /// is large enough to be worth it, which is what removes the slope: dead
1400 /// versions inside the span cost address space, not I/O, because only pages
1401 /// actually addressed by `read_string` are ever faulted in.
1402 ///
1403 /// The residual cost is page granularity — a live row drags in its whole page,
1404 /// including any dead bytes sharing it — so the win depends on how clustered
1405 /// the live set is. Append-only helps here: an updated row is re-appended at
1406 /// the tail, so churn tends to concentrate live rows rather than scatter them.
1407 ///
1408 /// # Sparse selections (#228)
1409 ///
1410 /// Bounding to the span is the wrong trade when the selection is a handful of
1411 /// rows scattered across the column — the offsets read is then almost entirely
1412 /// rows nobody asked for. Below [`SPARSE_OFFSETS_SPAN_FACTOR`] density the
1413 /// offsets are read per index instead. This mirrors what
1414 /// [`FixedColumn::gather`] already does via `GATHER_MMAP_MIN_ROWS`; the data
1415 /// region still maps by span, which costs address space rather than I/O.
1416 ///
1417 /// # Errors
1418 ///
1419 /// `InvalidInput` if any index is `>= self.len()`; other errors come from the
1420 /// underlying reads.
1421 pub fn gather_buffered(&self, indices: &[usize]) -> io::Result<BufferedVariableColumn> {
1422 if indices.is_empty() {
1423 return Ok(BufferedVariableColumn {
1424 data: ColumnExport::Owned(Vec::new()),
1425 base: 0,
1426 slots: Vec::new(),
1427 });
1428 }
1429
1430 // Bounds-check the whole selection first, and take the row span.
1431 let mut lo = usize::MAX;
1432 let mut hi = 0usize;
1433 for &index in indices {
1434 if index >= self.row_count {
1435 return Err(io::Error::new(
1436 io::ErrorKind::InvalidInput,
1437 "Index out of bounds",
1438 ));
1439 }
1440 lo = lo.min(index);
1441 hi = hi.max(index);
1442 }
1443
1444 // A few rows scattered across the column: bounding to the span would read
1445 // almost entirely rows nobody asked for, and map a data region orders of
1446 // magnitude larger than the bytes wanted. Gather them individually
1447 // instead (#228 — see `SPARSE_OFFSETS_SPAN_FACTOR`).
1448 if hi + 1 - lo > indices.len().saturating_mul(SPARSE_OFFSETS_SPAN_FACTOR) {
1449 return self.gather_sparse(indices);
1450 }
1451
1452 // Only the spanned slice of the offsets index (16 bytes/row), not all
1453 // `row_count` rows.
1454 let mut offsets = vec![0u8; (hi + 1 - lo) * 16];
1455 self.offsets_file
1456 .read_exact_at(&mut offsets, (lo * 16) as u64)?;
1457
1458 let mut slots = Vec::with_capacity(indices.len());
1459 let mut data_lo = u64::MAX;
1460 let mut data_hi = 0u64;
1461 for &index in indices {
1462 let b = (index - lo) * 16;
1463 let offset = u64::from_le_bytes(offsets[b..b + 8].try_into().unwrap());
1464 let length = u64::from_le_bytes(offsets[b + 8..b + 16].try_into().unwrap());
1465 data_lo = data_lo.min(offset);
1466 data_hi = data_hi.max(offset + length);
1467 slots.push((offset, length));
1468 }
1469
1470 // Every selected row empty (or a zero-length span) — nothing to map.
1471 if data_hi <= data_lo {
1472 return Ok(BufferedVariableColumn {
1473 data: ColumnExport::Owned(Vec::new()),
1474 base: data_lo.min(data_hi),
1475 slots,
1476 });
1477 }
1478
1479 let span = (data_hi - data_lo) as usize;
1480 let data = if span >= VAR_MMAP_MIN_BYTES {
1481 // A failed mapping is not fatal — the bounded read below yields the
1482 // same bytes — so fall through rather than propagate.
1483 let mapped = unsafe {
1484 memmap2::MmapOptions::new()
1485 .offset(data_lo)
1486 .len(span)
1487 .map(&self.data_file)
1488 };
1489 match mapped {
1490 Ok(m) => ColumnExport::Mapped(m),
1491 Err(_) => {
1492 let mut v = vec![0u8; span];
1493 self.data_file.read_exact_at(&mut v, data_lo)?;
1494 ColumnExport::Owned(v)
1495 }
1496 }
1497 } else {
1498 let mut v = vec![0u8; span];
1499 self.data_file.read_exact_at(&mut v, data_lo)?;
1500 ColumnExport::Owned(v)
1501 };
1502
1503 Ok(BufferedVariableColumn { data, base: data_lo, slots })
1504 }
1505
1506 /// The sparse-selection arm of [`gather_buffered`](Self::gather_buffered)
1507 /// (#228): read each selected row's offsets entry and bytes individually, into
1508 /// one **packed** buffer holding only the rows asked for.
1509 ///
1510 /// The spanned arm is the right shape when the selection covers most of its
1511 /// span — one bounded offsets read, and a data region whose dead versions cost
1512 /// address space rather than I/O because only addressed pages fault in. It is
1513 /// the wrong shape when a handful of rows are scattered across the whole
1514 /// column: the offsets read is then almost all rows nobody wants, and the
1515 /// mapping's setup and teardown are paid in full to reach a few hundred bytes.
1516 ///
1517 /// That case is not hypothetical — it is what an index-pushdown candidate set
1518 /// looks like, and since #228 those reach here directly instead of being
1519 /// decoded per row. Measured on a 20 000-row column, two rows at opposite ends
1520 /// cost 5x the per-row positional decode this replaced; packing them brings it
1521 /// back to parity, while every denser selection keeps the spanned arm's win.
1522 ///
1523 /// The packed buffer means `slots` here hold **offsets into `data`**, not
1524 /// absolute file offsets, with `base` 0 — the one place that distinction
1525 /// exists. `read_str` computes `offset - base` either way, so it needs no
1526 /// branch and cannot tell the two apart.
1527 fn gather_sparse(&self, indices: &[usize]) -> io::Result<BufferedVariableColumn> {
1528 let mut slots = Vec::with_capacity(indices.len());
1529 let mut data: Vec<u8> = Vec::new();
1530 let mut entry = [0u8; 16];
1531 for &index in indices {
1532 self.offsets_file
1533 .read_exact_at(&mut entry, (index * 16) as u64)?;
1534 let offset = u64::from_le_bytes(entry[..8].try_into().unwrap());
1535 let length = u64::from_le_bytes(entry[8..].try_into().unwrap());
1536 let start = data.len();
1537 data.resize(start + length as usize, 0);
1538 if length > 0 {
1539 self.data_file.read_exact_at(&mut data[start..], offset)?;
1540 }
1541 slots.push((start as u64, length));
1542 }
1543 Ok(BufferedVariableColumn {
1544 data: ColumnExport::Owned(data),
1545 base: 0,
1546 slots,
1547 })
1548 }
1549
1550 /// Flush all pending writes to disk (fsync both data and offsets files).
1551 ///
1552 /// After `flush()` returns `Ok(())`, all previous appends are guaranteed to
1553 /// survive a crash. Call at commit boundaries or before advancing the WAL checkpoint.
1554 pub fn flush(&mut self) -> io::Result<()> {
1555 self.data_file.sync_all()?;
1556 self.offsets_file.sync_all()
1557 }
1558
1559 /// Push both backing files to the drive cache without a device barrier
1560 /// (#153). Pair with one [`VariableColumn::barrier`] per checkpoint.
1561 pub fn sync_to_drive(&self) -> io::Result<()> {
1562 fsync_to_drive(&self.data_file)?;
1563 fsync_to_drive(&self.offsets_file)
1564 }
1565
1566 /// Issue the single device-cache barrier for a checkpoint (#153). Barriers
1567 /// are device-wide, so one call on the data file covers the offsets file too.
1568 pub fn barrier(&self) -> io::Result<()> {
1569 device_barrier(&self.data_file)
1570 }
1571
1572 #[must_use]
1573 pub fn len(&self) -> usize {
1574 self.row_count
1575 }
1576
1577 #[must_use]
1578 pub fn is_empty(&self) -> bool {
1579 self.row_count == 0
1580 }
1581
1582 /// Refresh the in-memory counters from the on-disk file lengths (#84).
1583 ///
1584 /// Re-derives `row_count` from the offsets file (16 bytes/row) and
1585 /// `current_data_offset` from the data file, so a *peer* process's appended
1586 /// rows (Tier 3 multi-process writer path) become readable through this
1587 /// handle. Paired with `FixedColumn::sync_from_disk` /
1588 /// `Tombstones::sync_from_disk`. A no-op for the single-writer path.
1589 pub fn sync_from_disk(&mut self) -> io::Result<()> {
1590 self.row_count = self.offsets_file.metadata()?.len() as usize / 16;
1591 self.current_data_offset = self.data_file.metadata()?.len();
1592 Ok(())
1593 }
1594
1595 /// Truncate the column to hold exactly `rows` rows, discarding everything
1596 /// after that point.
1597 ///
1598 /// The data file is cut at the byte immediately after the last byte of row
1599 /// `rows - 1` (read from the offsets entry for that row). The offsets file
1600 /// is cut to `rows * 16` bytes. Both in-memory counters are updated so the
1601 /// next `append_string` lands at exactly row `rows`.
1602 ///
1603 /// # Errors
1604 ///
1605 /// Returns `Err(InvalidInput)` if `rows > self.len()`. All other errors
1606 /// come from underlying I/O or `set_len` syscalls.
1607 pub fn truncate_to_rows(&mut self, rows: usize) -> io::Result<()> {
1608 if rows > self.row_count {
1609 return Err(io::Error::new(
1610 io::ErrorKind::InvalidInput,
1611 "truncate_to_rows beyond current length",
1612 ));
1613 }
1614
1615 let data_len: u64 = if rows == 0 {
1616 0
1617 } else {
1618 // Positionally read the (offset, length) pair for row `rows - 1`.
1619 let offsets_pos = ((rows - 1) * 16) as u64;
1620 let mut offset_buf = [0u8; 8];
1621 let mut length_buf = [0u8; 8];
1622 self.offsets_file
1623 .read_exact_at(&mut offset_buf, offsets_pos)?;
1624 self.offsets_file
1625 .read_exact_at(&mut length_buf, offsets_pos + 8)?;
1626 let offset = u64::from_le_bytes(offset_buf);
1627 let length = u64::from_le_bytes(length_buf);
1628 offset + length
1629 };
1630
1631 self.offsets_file.set_len((rows * 16) as u64)?;
1632 self.data_file.set_len(data_len)?;
1633 self.current_data_offset = data_len;
1634 self.row_count = rows;
1635 Ok(())
1636 }
1637
1638 /// Open a read-only, positionally-reading view over this column's data +
1639 /// offsets files (#56 Direction B). The returned [`VariableColumnReader`]
1640 /// shares both files via independent (`try_clone`d) descriptors, so a single
1641 /// `&mut self` writer can keep appending while many `&self` readers read
1642 /// concurrently without a lock. See [`FixedColumnReader`] for the model.
1643 pub fn reader(&self) -> io::Result<VariableColumnReader> {
1644 Ok(VariableColumnReader {
1645 data_file: self.data_file.try_clone()?,
1646 offsets_file: self.offsets_file.try_clone()?,
1647 })
1648 }
1649}
1650
1651/// Tombstone bitmap for tracking deleted records.
1652///
1653/// # Durability
1654///
1655/// Append methods write to the OS page cache but do **not** call `fsync` per append.
1656/// Call [`flush`](Tombstones::flush) at commit boundaries to guarantee durability.
1657pub struct Tombstones {
1658 file: File,
1659 count: usize,
1660}
1661
1662impl Tombstones {
1663 pub fn new(path: PathBuf) -> io::Result<Self> {
1664 if let Some(parent) = path.parent() {
1665 fs::create_dir_all(parent)?;
1666 }
1667
1668 let file = OpenOptions::new()
1669 .read(true)
1670 .write(true)
1671 .create(true)
1672 .truncate(false)
1673 .open(&path)?;
1674
1675 let count = file.metadata()?.len() as usize;
1676
1677 Ok(Tombstones { file, count })
1678 }
1679
1680 pub fn append(&mut self, deleted: bool) -> io::Result<()> {
1681 self.file.seek(SeekFrom::End(0))?;
1682 self.file.write_all(&[if deleted { 1u8 } else { 0u8 }])?;
1683 self.count += 1;
1684 Ok(())
1685 }
1686
1687 pub fn is_deleted(&self, index: usize) -> io::Result<bool> {
1688 if index >= self.count {
1689 return Err(io::Error::new(
1690 io::ErrorKind::InvalidInput,
1691 "Index out of bounds",
1692 ));
1693 }
1694
1695 let mut buf = [0u8; 1];
1696 self.file.read_exact_at(&mut buf, index as u64)?;
1697 Ok(buf[0] != 0)
1698 }
1699
1700 /// Return the subset of `rows` that are **not** tombstoned, preserving order
1701 /// (#168 scan filter). Reads the whole tombstone column **once** rather than
1702 /// a per-row [`is_deleted`](Self::is_deleted) syscall — the bulk liveness
1703 /// filter a column scan applies to its live-row selection. A row index past
1704 /// the committed count is treated as not-live (dropped), matching
1705 /// `is_deleted(..).unwrap_or(true)`.
1706 pub fn live_indices(&self, rows: &[usize]) -> io::Result<Vec<usize>> {
1707 let mut bytes = vec![0u8; self.count];
1708 if !bytes.is_empty() {
1709 self.file.read_exact_at(&mut bytes, 0)?;
1710 }
1711 Ok(rows
1712 .iter()
1713 .copied()
1714 .filter(|&r| bytes.get(r) == Some(&0))
1715 .collect())
1716 }
1717
1718 /// Flush all pending writes to disk (fsync).
1719 ///
1720 /// After `flush()` returns `Ok(())`, all previous appends are guaranteed to
1721 /// survive a crash. Call at commit boundaries or before advancing the WAL checkpoint.
1722 pub fn flush(&mut self) -> io::Result<()> {
1723 self.file.sync_all()
1724 }
1725
1726 /// Push the tombstone column to the drive cache without a barrier (#153).
1727 pub fn sync_to_drive(&self) -> io::Result<()> {
1728 fsync_to_drive(&self.file)
1729 }
1730
1731 /// Issue the single device-cache barrier for a checkpoint (#153).
1732 pub fn barrier(&self) -> io::Result<()> {
1733 device_barrier(&self.file)
1734 }
1735
1736 #[must_use]
1737 pub fn len(&self) -> usize {
1738 self.count
1739 }
1740
1741 #[must_use]
1742 pub fn is_empty(&self) -> bool {
1743 self.count == 0
1744 }
1745
1746 /// Truncate the tombstone bitmap to hold exactly `rows` rows, discarding
1747 /// everything after that point.
1748 ///
1749 /// # Errors
1750 ///
1751 /// Returns `Err(InvalidInput)` if `rows > self.len()`. All other errors
1752 /// come from the underlying `set_len` syscall.
1753 pub fn truncate_to_rows(&mut self, rows: usize) -> io::Result<()> {
1754 if rows > self.count {
1755 return Err(io::Error::new(
1756 io::ErrorKind::InvalidInput,
1757 "truncate_to_rows beyond current length",
1758 ));
1759 }
1760 self.file.set_len(rows as u64)?;
1761 self.count = rows;
1762 Ok(())
1763 }
1764
1765 /// Re-read the on-disk tombstone count from the file metadata and update the
1766 /// cached `count`.
1767 ///
1768 /// Normally `count` is maintained in memory by `append`/`truncate_to_rows`, so
1769 /// this is a no-op for the single-writer path. For the Tier 3 multi-process
1770 /// writer path (#84) a peer process may have appended tombstone bytes since this
1771 /// writer opened the file; calling `sync_from_disk` before `len()` lets the
1772 /// writer see the peer's committed rows without reopening the storage.
1773 ///
1774 /// # Errors
1775 ///
1776 /// Propagates any error from `file.metadata()`.
1777 pub fn sync_from_disk(&mut self) -> io::Result<()> {
1778 self.count = self.file.metadata()?.len() as usize;
1779 Ok(())
1780 }
1781
1782 /// Open a read-only, positionally-reading view over this tombstone file
1783 /// (#56 Direction B). See [`FixedColumn::reader`] for the concurrency model.
1784 pub fn reader(&self) -> io::Result<TombstonesReader> {
1785 Ok(TombstonesReader {
1786 file: self.file.try_clone()?,
1787 })
1788 }
1789}
1790
1791/// Map a positional read that ran past end-of-file back to the same
1792/// out-of-bounds error the cached-count writer columns return (#56 Direction B).
1793///
1794/// A [`FixedColumnReader`] / [`VariableColumnReader`] / [`TombstonesReader`]
1795/// derives length live rather than caching a row count, so an index beyond the
1796/// committed prefix surfaces as `UnexpectedEof` from `read_exact_at`; normalize
1797/// it to `InvalidInput` for parity with the writer's explicit bound check.
1798fn map_out_of_bounds(e: io::Error) -> io::Error {
1799 if e.kind() == io::ErrorKind::UnexpectedEof {
1800 io::Error::new(io::ErrorKind::InvalidInput, "Index out of bounds")
1801 } else {
1802 e
1803 }
1804}
1805
1806/// Read-only, positional view over a [`FixedColumn`]'s backing file
1807/// (#56 Direction B — single writer, many concurrent readers).
1808///
1809/// Created by [`FixedColumn::reader`]; holds an independent file descriptor
1810/// (`try_clone`) to the **same** file as the writer. A single `&mut self`
1811/// writer can keep appending while any number of `&self` readers positionally
1812/// read the committed prefix concurrently, with no lock:
1813///
1814/// - Reads use `read_exact_at` (positional `pread`) — they never touch a shared
1815/// file cursor, so they are safe against a concurrent seek-based append and
1816/// against each other across threads.
1817/// - The engine is append-only: bytes at an already-committed offset never move,
1818/// so a reader observing an offset below the writer's committed length reads
1819/// stable bytes (POSIX page-cache coherence makes the writer's not-yet-fsync'd
1820/// appends visible through this independent fd).
1821/// - Length is derived **live** on every access (never a cached count), so a
1822/// reader created before an append still sees rows the writer commits
1823/// afterward — once the caller's watermark admits them.
1824///
1825/// Callers clamp reads to a captured watermark (the row-count anchor); because
1826/// the anchor column is appended last per row, a row within the watermark has
1827/// all its columns fully written, so a reader never observes a torn row.
1828pub struct FixedColumnReader {
1829 file: File,
1830 value_size: usize,
1831}
1832
1833impl FixedColumnReader {
1834 #[must_use]
1835 pub fn len(&self) -> usize {
1836 self.file
1837 .metadata()
1838 .map(|m| m.len() as usize / self.value_size)
1839 .unwrap_or(0)
1840 }
1841
1842 #[must_use]
1843 pub fn is_empty(&self) -> bool {
1844 self.len() == 0
1845 }
1846
1847 pub fn read_u32(&self, index: usize) -> io::Result<u32> {
1848 let mut buf = [0u8; 4];
1849 self.file
1850 .read_exact_at(&mut buf, (index * self.value_size) as u64)
1851 .map_err(map_out_of_bounds)?;
1852 Ok(u32::from_le_bytes(buf))
1853 }
1854
1855 pub fn read_u64(&self, index: usize) -> io::Result<u64> {
1856 let mut buf = [0u8; 8];
1857 self.file
1858 .read_exact_at(&mut buf, (index * self.value_size) as u64)
1859 .map_err(map_out_of_bounds)?;
1860 Ok(u64::from_le_bytes(buf))
1861 }
1862
1863 pub fn read_i32(&self, index: usize) -> io::Result<i32> {
1864 let mut buf = [0u8; 4];
1865 self.file
1866 .read_exact_at(&mut buf, (index * self.value_size) as u64)
1867 .map_err(map_out_of_bounds)?;
1868 Ok(i32::from_le_bytes(buf))
1869 }
1870
1871 pub fn read_i64(&self, index: usize) -> io::Result<i64> {
1872 let mut buf = [0u8; 8];
1873 self.file
1874 .read_exact_at(&mut buf, (index * self.value_size) as u64)
1875 .map_err(map_out_of_bounds)?;
1876 Ok(i64::from_le_bytes(buf))
1877 }
1878
1879 pub fn read_f64(&self, index: usize) -> io::Result<f64> {
1880 let mut buf = [0u8; 8];
1881 self.file
1882 .read_exact_at(&mut buf, (index * self.value_size) as u64)
1883 .map_err(map_out_of_bounds)?;
1884 Ok(f64::from_le_bytes(buf))
1885 }
1886
1887 pub fn read_bool(&self, index: usize) -> io::Result<bool> {
1888 let mut buf = [0u8; 1];
1889 self.file
1890 .read_exact_at(&mut buf, (index * self.value_size) as u64)
1891 .map_err(map_out_of_bounds)?;
1892 Ok(buf[0] != 0)
1893 }
1894
1895 pub fn read_uuid(&self, index: usize) -> io::Result<[u8; 16]> {
1896 let mut buf = [0u8; 16];
1897 self.file
1898 .read_exact_at(&mut buf, (index * self.value_size) as u64)
1899 .map_err(map_out_of_bounds)?;
1900 Ok(buf)
1901 }
1902
1903 pub fn read_timestamp(&self, index: usize) -> io::Result<i64> {
1904 let mut buf = [0u8; 8];
1905 self.file
1906 .read_exact_at(&mut buf, (index * self.value_size) as u64)
1907 .map_err(map_out_of_bounds)?;
1908 Ok(i64::from_le_bytes(buf))
1909 }
1910
1911 pub fn read_bytes(&self, index: usize) -> io::Result<Vec<u8>> {
1912 let mut buf = vec![0u8; self.value_size];
1913 self.file
1914 .read_exact_at(&mut buf, (index * self.value_size) as u64)
1915 .map_err(map_out_of_bounds)?;
1916 Ok(buf)
1917 }
1918}
1919
1920/// Read-only, positional view over a [`VariableColumn`]'s data + offsets files
1921/// (#56 Direction B). See [`FixedColumnReader`] for the concurrency model.
1922pub struct VariableColumnReader {
1923 data_file: File,
1924 offsets_file: File,
1925}
1926
1927impl VariableColumnReader {
1928 #[must_use]
1929 pub fn len(&self) -> usize {
1930 self.offsets_file
1931 .metadata()
1932 .map(|m| m.len() as usize / 16)
1933 .unwrap_or(0)
1934 }
1935
1936 #[must_use]
1937 pub fn is_empty(&self) -> bool {
1938 self.len() == 0
1939 }
1940
1941 pub fn read_string(&self, index: usize) -> io::Result<String> {
1942 let offsets_pos = (index * 16) as u64;
1943 let mut offset_buf = [0u8; 8];
1944 let mut length_buf = [0u8; 8];
1945 self.offsets_file
1946 .read_exact_at(&mut offset_buf, offsets_pos)
1947 .map_err(map_out_of_bounds)?;
1948 self.offsets_file
1949 .read_exact_at(&mut length_buf, offsets_pos + 8)
1950 .map_err(map_out_of_bounds)?;
1951
1952 let offset = u64::from_le_bytes(offset_buf);
1953 let length = u64::from_le_bytes(length_buf);
1954
1955 let mut data = vec![0u8; length as usize];
1956 self.data_file.read_exact_at(&mut data, offset)?;
1957
1958 String::from_utf8(data).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
1959 }
1960}
1961
1962/// Read-only, positional view over a [`Tombstones`] file (#56 Direction B).
1963/// See [`FixedColumnReader`] for the concurrency model.
1964pub struct TombstonesReader {
1965 file: File,
1966}
1967
1968impl TombstonesReader {
1969 #[must_use]
1970 pub fn len(&self) -> usize {
1971 self.file.metadata().map(|m| m.len() as usize).unwrap_or(0)
1972 }
1973
1974 #[must_use]
1975 pub fn is_empty(&self) -> bool {
1976 self.len() == 0
1977 }
1978
1979 pub fn is_deleted(&self, index: usize) -> io::Result<bool> {
1980 let mut buf = [0u8; 1];
1981 self.file
1982 .read_exact_at(&mut buf, index as u64)
1983 .map_err(map_out_of_bounds)?;
1984 Ok(buf[0] != 0)
1985 }
1986}