pub struct FixedColumn { /* private fields */ }Implementations§
Source§impl FixedColumn
impl FixedColumn
pub fn new(path: PathBuf, value_size: usize) -> Result<FixedColumn, Error>
pub fn append_u32(&mut self, value: u32) -> Result<(), Error>
pub fn read_u32(&self, index: usize) -> Result<u32, Error>
pub fn append_u64(&mut self, value: u64) -> Result<(), Error>
pub fn read_u64(&self, index: usize) -> Result<u64, Error>
pub fn append_i32(&mut self, value: i32) -> Result<(), Error>
pub fn read_i32(&self, index: usize) -> Result<i32, Error>
pub fn append_i64(&mut self, value: i64) -> Result<(), Error>
pub fn read_i64(&self, index: usize) -> Result<i64, Error>
pub fn append_f64(&mut self, value: f64) -> Result<(), Error>
pub fn read_f64(&self, index: usize) -> Result<f64, Error>
pub fn append_bool(&mut self, value: bool) -> Result<(), Error>
pub fn read_bool(&self, index: usize) -> Result<bool, Error>
pub fn append_uuid(&mut self, value: [u8; 16]) -> Result<(), Error>
pub fn read_uuid(&self, index: usize) -> Result<[u8; 16], Error>
pub fn append_timestamp(&mut self, value: i64) -> Result<(), Error>
pub fn read_timestamp(&self, index: usize) -> Result<i64, Error>
Sourcepub fn append_bytes(&mut self, value: &[u8]) -> Result<(), Error>
pub fn append_bytes(&mut self, value: &[u8]) -> Result<(), Error>
Append arbitrary bytes for complex fixed-size types (char arrays, structs, fixed arrays)
Sourcepub fn read_bytes(&self, index: usize) -> Result<Vec<u8>, Error>
pub fn read_bytes(&self, index: usize) -> Result<Vec<u8>, Error>
Read arbitrary bytes for complex fixed-size types (char arrays, structs, fixed arrays)
Sourcepub fn gather(&self, indices: &[usize]) -> Result<Vec<u8>, Error>
pub fn gather(&self, indices: &[usize]) -> Result<Vec<u8>, Error>
Copy the physical rows at indices into one contiguous owned buffer, in
the order given (indices.len() * value_size bytes).
This is the class-1 columnar-read primitive behind the language bindings’
Arrow / columnar-export gather path — the fallback taken whenever the
live selection is not an aliasable dense prefix (update-heavy or
tombstoned tables) and a contiguous copy of exactly the live rows is
needed. It is schema-agnostic: indices are opaque physical row
positions the caller computed (generated code derives the live set from
id_to_row + tombstone liveness, exactly as all() / all_at() do
today); gather never reads a field name, type, or schema.
§Performance (#221)
For a selection of at least [GATHER_MMAP_MIN_ROWS] rows this maps the
spanned region [min(indices), max(indices)] once and copies out of
that mapping in contiguous runs, rather than issuing one read_exact_at
per index. Live selections under append-only churn are long runs broken
by the holes superseded rows leave behind, so runs are typically far
longer than one row and the copy collapses to a handful of memcpys.
The mapping is held only for the duration of the call and the returned
buffer is owned, so this relies on a strictly weaker form of the
aliasing invariant documented on ColumnExport: the spanned rows are
committed (< row_count, so within the file’s length) and no concurrent
truncation runs, which the single-writer discipline already guarantees.
Known-unmeasured case: a sparse selection spanning a very large file faults in one page per isolated row, reading more bytes than the per-row path would. It still trades syscalls for faults plus readahead, and real live sets stay dense (amplification is bounded by the generated compaction ceiling), but it has not been benchmarked.
§Errors
Returns Err(InvalidInput) if any index is >= self.len().
Sourcepub fn export(&self, indices: &[usize]) -> Result<ColumnExport, Error>
pub fn export(&self, indices: &[usize]) -> Result<ColumnExport, Error>
Export the physical rows at indices as a ColumnExport, taking the
zero-copy mmap alias fast path when indices is the contiguous
dense prefix [0, n) and falling back to gather
(an owned copy) otherwise. The returned buffer is identical bytes either
way (indices.len() * value_size), so the FFI / Arrow consumer is
alias-or-gather transparent.
This is the class-1 columnar-read primitive the language bindings’ Arrow
export links: indices are opaque physical row positions the caller
(generated code) computed from the live set; export reads no field
name, type, or schema — it only inspects the indices’ shape to decide
whether they alias a prefix.
§Errors
Returns Err(InvalidInput) if any index is >= self.len(), or an I/O
error if the mmap of the aliasable prefix fails.
Sourcepub fn gather_buffered(
&self,
indices: &[usize],
) -> Result<BufferedFixedColumn, Error>
pub fn gather_buffered( &self, indices: &[usize], ) -> Result<BufferedFixedColumn, Error>
Bulk-load the physical rows at indices into an in-memory
BufferedFixedColumn whose positional read_*(slot) accessors read
from memory instead of the file (#168 column scan).
This is the class-1 read primitive behind the generated column-pruned
sequential scan: a scan over n rows pays one bulk read per column
(a zero-copy mmap alias when indices is the dense prefix [0, n) — the
common append-only case — or a single gathered copy otherwise) rather than
n per-row read_exact_at syscalls. indices are opaque physical row
positions the caller (generated code) computed from the live set; the
returned buffer’s read_* methods take a slot 0..indices.len()
indexing into that selection, in the given order. Reads no field name,
type, or schema.
§Errors
Propagates export’s errors (out-of-bounds index or a
failed mmap).
Sourcepub fn flush(&mut self) -> Result<(), Error>
pub fn flush(&mut self) -> Result<(), Error>
Flush all pending writes to disk (fsync).
This is the explicit durability checkpoint: after flush() returns Ok(()),
all previous appends are guaranteed to survive a crash. Call this at transaction
commit boundaries or before advancing the WAL checkpoint.
Sourcepub fn sync_to_drive(&self) -> Result<(), Error>
pub fn sync_to_drive(&self) -> Result<(), Error>
Push this column’s data to the drive cache without a device barrier
(#153). Pair with a single FixedColumn::barrier (on any column of the
same device) to make a whole checkpoint’s columns durable with ONE
barrier instead of N. See [fsync_to_drive].
Sourcepub fn barrier(&self) -> Result<(), Error>
pub fn barrier(&self) -> Result<(), Error>
Issue the single device-cache barrier for a checkpoint (#153): flushes the
drive’s write cache to permanent media, making durable every column
previously sync_to_drived on the same device. See [device_barrier].
pub fn len(&self) -> usize
pub fn is_empty(&self) -> bool
Sourcepub fn sync_from_disk(&mut self) -> Result<(), Error>
pub fn sync_from_disk(&mut self) -> Result<(), Error>
Refresh the in-memory row_count from the on-disk file length (#84).
Reads read_exact_at the file positionally, bounded by row_count. For
the Tier 3 multi-process writer path a peer process may have appended
values since this handle opened; sync_from_disk re-derives row_count
from the shared file so the peer’s committed rows become readable (paired
with Tombstones::sync_from_disk and VariableColumn::sync_from_disk).
A no-op for the single-writer path, which maintains row_count in memory.
Sourcepub fn truncate_to_rows(&mut self, rows: usize) -> Result<(), Error>
pub fn truncate_to_rows(&mut self, rows: usize) -> Result<(), Error>
Truncate the column to hold exactly rows rows, discarding everything
after that point.
This is the crash-recovery primitive: after replaying a WAL, generated
code calls truncate_to_rows on every column to realign them back to the
last consistent row watermark before resuming appends. Any partial
trailing value left by a torn write is physically removed so the next
append_* lands at exactly row rows.
§Errors
Returns Err(InvalidInput) if rows > self.len() — truncation cannot
extend a column. All other errors come from the underlying set_len
syscall.
Sourcepub fn reader(&self) -> Result<FixedColumnReader, Error>
pub fn reader(&self) -> Result<FixedColumnReader, Error>
Open a read-only, positionally-reading view over this column’s file
(#56 Direction B). The returned FixedColumnReader shares the file
via an independent (try_cloned) descriptor, so a single &mut self
writer can keep appending while many &self readers read concurrently
without a lock. See FixedColumnReader for the full model.