pigeonhole-db 1.1.0

data/vendor/sst/src/lib.rs

@@ -0,0 +1,695 @@
+//! Sorted string tables for Pigeonhole: blocks, filters, partitioned index, filtered
+//! iteration.
+//!
+//! An SST is an immutable sorted run of one `(tablet, family)` inside one extent of the main
+//! file (layout in `FORMAT.md` §4). [`SstWriter`] builds one from entries in key order;
+//! [`SstReader`] opens one with its top-level index and filters pinned in memory, so a point
+//! lookup is at most one cached index-partition lookup plus one data-block read.
+//! [`SstIter`] is a zero-copy [`Cursor`](pigeonhole_format::Cursor) that applies a [`ScanFilter`] inside the block
+//! decoder (the same `CompiledFilter::check` every source uses) and skips rows using the
+//! row-start table. It owns an `Arc<SstReader>` and a pinned block, so it can be stored
+//! anywhere (scan cursors, compaction jobs) without borrowing.
+//!
+//! Blob extents (separated values) are read and written here too ([`BlobWriter`],
+//! [`BlobReader`]); deciding what to separate is compaction's job.
+//!
+//! The mock for the layer above is the real writer and reader over
+//! [`SimVfs`](pigeonhole_io::sim::SimVfs).
+//!
+//! Part of [Pigeonhole](https://github.com/CodingAnarchy/pigeonhole). See the crate README.
+//!
+//! **Cache keys.** Blocks are cached under [`BlockKey`](pigeonhole_cache::BlockKey)s whose
+//! `file` is [`sst_cache_file`] for SST blocks and [`blob_cache_file`] for blob records, so
+//! the two id spaces never collide; pass the same values to `BlockCache::erase_files` when an
+//! SST or blob file is deleted.
+#![forbid(unsafe_code)]
+
+mod blob;
+mod iter;
+mod reader;
+mod writer;
+
+use std::fmt;
+use std::sync::Arc;
+
+use pigeonhole_cache::{BlockCache, Cell, Priority};
+use pigeonhole_format::compress::Compression;
+use pigeonhole_format::manifest::{FamilyOptions, SstMeta};
+use pigeonhole_format::sst::Properties;
+use pigeonhole_format::superblock::ExtentRef;
+use pigeonhole_format::value::BlobPointer;
+use pigeonhole_format::{BlobFileId, FamilyId, SstId, TableId, TabletId};
+
+pub use iter::{ReadaheadRamp, SstIter};
+pub use pigeonhole_format::scan::{QualifierFilter, ScanFilter};
+use pigeonhole_io::FileRef;
+pub use reader::Fetch;
+
+/// Tag bit separating blob-file cache namespaces from SST ones.
+const BLOB_NAMESPACE: u64 = 1 << 63;
+
+/// The block-cache `file` namespace of an SST's blocks. SST ids must stay below `2^63` (the
+/// top bit tags blob files); the engine's id counter never gets near it.
+pub fn sst_cache_file(id: SstId) -> u64 {
+    debug_assert!(
+        id.0 < BLOB_NAMESPACE,
+        "SST id {} collides with blob namespaces",
+        id.0
+    );
+    id.0 & !BLOB_NAMESPACE
+}
+
+/// The block-cache `file` namespace of a blob file's records (blob ids are `u32`, so always
+/// below `2^63`).
+pub fn blob_cache_file(id: BlobFileId) -> u64 {
+    const { assert!((u32::MAX as u64) < BLOB_NAMESPACE) };
+    BLOB_NAMESPACE | u64::from(id.0)
+}
+
+/// Result alias for this crate.
+pub type Result<T, E = Error> = std::result::Result<T, E>;
+
+thread_local! {
+    /// While `counting_file_reads` runs on this thread: the block reads made from the file.
+    static FILE_READS: std::cell::Cell<Option<u64>> = const { std::cell::Cell::new(None) };
+}
+
+/// Runs `f`, counting the block reads it makes from the file on this thread (an async
+/// scan's step, whose unpredicted misses are read synchronously and counted: D196, #398).
+/// Cache hits are not counted, and only the miss paths pay for the count.
+pub fn counting_file_reads<T>(f: impl FnOnce() -> T) -> (T, u64) {
+    struct Restore(Option<u64>);
+    impl Drop for Restore {
+        fn drop(&mut self) {
+            FILE_READS.with(|c| c.set(self.0));
+        }
+    }
+    let restore = Restore(FILE_READS.with(|c| c.replace(Some(0))));
+    let out = f();
+    let n = FILE_READS.with(std::cell::Cell::get).unwrap_or(0);
+    drop(restore);
+    (out, n)
+}
+
+/// Counts a block read from the file, if `counting_file_reads` is running.
+#[cold]
+pub(crate) fn note_file_read() {
+    FILE_READS.with(|c| {
+        if let Some(n) = c.get() {
+            c.set(Some(n + 1));
+        }
+    });
+}
+
+thread_local! {
+    /// While `counting_readahead` runs on this thread: what its cursors' readahead did.
+    static READAHEAD: std::cell::Cell<Option<ReadaheadCounts>> = const { std::cell::Cell::new(None) };
+}
+
+/// What scan readahead did ([`ReadOptions::readahead_blocks`], #402), as counted by
+/// [`counting_readahead`].
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+#[non_exhaustive]
+pub struct ReadaheadCounts {
+    /// Block fetches submitted ahead of the scan.
+    pub issued: u64,
+    /// Blocks the scan took from its readahead instead of the cache or the file.
+    pub used: u64,
+    /// Blocks the scan reached while their fetch was still in flight, and waited for (read
+    /// once, late: a readahead that did not run far enough ahead).
+    pub waited: u64,
+}
+
+/// Runs `f` and returns what the readahead of cursors stepped on this thread did during it
+/// (nested calls restore the outer count). A bench and test hook, like
+/// [`counting_file_reads`].
+pub fn counting_readahead<T>(f: impl FnOnce() -> T) -> (T, ReadaheadCounts) {
+    struct Restore(Option<ReadaheadCounts>);
+    impl Drop for Restore {
+        fn drop(&mut self) {
+            READAHEAD.with(|c| c.set(self.0));
+        }
+    }
+    let restore = Restore(READAHEAD.with(|c| c.replace(Some(ReadaheadCounts::default()))));
+    let out = f();
+    let n = READAHEAD.with(std::cell::Cell::get).unwrap_or_default();
+    drop(restore);
+    (out, n)
+}
+
+/// Counts readahead, if `counting_readahead` is running.
+#[cold]
+pub(crate) fn note_readahead(f: impl FnOnce(&mut ReadaheadCounts)) {
+    READAHEAD.with(|c| {
+        if let Some(mut n) = c.get() {
+            f(&mut n);
+            c.set(Some(n));
+        }
+    });
+}
+
+/// SST errors.
+#[derive(Debug)]
+#[non_exhaustive]
+pub enum Error {
+    /// The file failed.
+    Io(pigeonhole_io::Error),
+    /// A block, footer or filter failed to decode or verify.
+    Format(pigeonhole_format::Error),
+    /// The SST would not fit in its extent; the caller should have cut earlier.
+    ExtentFull,
+    /// Keys were not added in strictly increasing order.
+    OutOfOrder,
+    /// A cache-only read ([`ReadOptions::cache_only`], [`SstReader::open_cache_only`]) missed:
+    /// the block it needs, to fetch asynchronously and admit before reading again (ICR 0014).
+    WouldBlock(Box<Fetch>),
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Io(e) => write!(f, "sst: {e}"),
+            Self::Format(e) => write!(f, "sst: {e}"),
+            Self::ExtentFull => write!(f, "sst: the extent is full"),
+            Self::OutOfOrder => write!(f, "sst: keys added out of order"),
+            Self::WouldBlock(fetch) => write!(f, "sst: a cache-only read missed ({fetch:?})"),
+        }
+    }
+}
+
+impl std::error::Error for Error {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Io(e) => Some(e),
+            Self::Format(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+impl Error {
+    /// Whether the error means stored bytes are bad (checksum, structure, truncation), as
+    /// opposed to an I/O failure, a caller mistake or an unsupported feature.
+    pub fn is_corruption(&self) -> bool {
+        use pigeonhole_format::Error as F;
+        matches!(
+            self,
+            Self::Format(
+                F::Truncated { .. } | F::BadMagic { .. } | F::Checksum { .. } | F::Corrupt { .. }
+            )
+        )
+    }
+}
+
+impl From<pigeonhole_io::Error> for Error {
+    fn from(e: pigeonhole_io::Error) -> Self {
+        Self::Io(e)
+    }
+}
+
+impl From<pigeonhole_format::Error> for Error {
+    fn from(e: pigeonhole_format::Error) -> Self {
+        Self::Format(e)
+    }
+}
+
+/// How to build an SST.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub struct SstWriterOptions {
+    /// Target uncompressed data-block size.
+    pub block_size: usize,
+    /// Restart interval within data blocks.
+    pub restart_interval: usize,
+    /// Block codec.
+    pub compression: Compression,
+    /// zstd level (ignored by the other codecs).
+    pub compression_level: i8,
+    /// Bloom bits per key; 0 writes no filters.
+    pub bloom_bits: u8,
+    /// Table (recorded in properties).
+    pub table: TableId,
+    /// Family (recorded in properties).
+    pub family: FamilyId,
+    /// Tablet (recorded in properties).
+    pub tablet: TabletId,
+    /// Merge operator name (recorded in properties).
+    pub merge_operator: String,
+    /// Creation time recorded in properties, microseconds since the Unix epoch (the engine
+    /// passes `Vfs::now_micros`, so simulated runs stay deterministic). Default 0.
+    pub created_micros: u64,
+    /// Recorded as `Properties::fully_purged`: `Some(max_versions)` when the writer is a
+    /// bottommost compaction that nothing held back (D268). Default `None`.
+    pub fully_purged: Option<u32>,
+}
+
+impl SstWriterOptions {
+    /// Options derived from a family's persisted policy.
+    pub fn for_family(
+        options: &FamilyOptions,
+        table: TableId,
+        family: FamilyId,
+        tablet: TabletId,
+    ) -> Self {
+        Self {
+            block_size: options.block_size as usize,
+            restart_interval: pigeonhole_format::block::DEFAULT_RESTART_INTERVAL,
+            compression: options.compression,
+            compression_level: options.compression_level,
+            bloom_bits: options.bloom_bits,
+            table,
+            family,
+            tablet,
+            merge_operator: options.merge_operator.clone(),
+            created_micros: 0,
+            fully_purged: None,
+        }
+    }
+}
+
+/// Builds one SST into a pre-allocated extent. Entries must arrive in strictly increasing
+/// internal-key order. Does not fsync: the pager's root commit syncs before publishing.
+///
+/// Data blocks are written to the extent as they fill (in 1 MiB batches); the index
+/// partitions, top index, filters and properties follow at [`finish`](Self::finish), and the
+/// footer is written last in its own write, so an interrupted build leaves no footer that
+/// [`SstReader::open`] would accept in front of missing blocks.
+///
+/// ```
+/// use pigeonhole_format::key::{Kind, encode_key, encode_marker_key};
+/// use pigeonhole_format::manifest::FamilyOptions;
+/// use pigeonhole_format::superblock::ExtentRef;
+/// use pigeonhole_format::{FamilyId, SstId, TableId, TabletId};
+/// use pigeonhole_io::{OpenOptions, Vfs};
+/// use pigeonhole_io::sim::SimVfs;
+/// use pigeonhole_sst::{SstWriter, SstWriterOptions};
+///
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// let file = SimVfs::new(7).open("/db".as_ref(), OpenOptions::read_write_create())?;
+/// let options = SstWriterOptions::for_family(&FamilyOptions::default(), TableId(1), FamilyId(2), TabletId(3));
+/// let mut w = SstWriter::new(file, ExtentRef { page: 16, size_class: 0 }, SstId(9), options);
+///
+/// let mut key = Vec::new();
+/// encode_marker_key(&mut key, b"row", 50, 4)?; // a family delete sorts before the row's cells
+/// assert!(w.fits(key.len(), 0));
+/// w.add(&key, b"")?;
+/// key.clear();
+/// encode_key(&mut key, b"row", b"q", 40, 3, Kind::Put)?;
+/// w.add(&key, b"\x00value")?;
+///
+/// let meta = w.finish()?;
+/// assert_eq!((meta.entries, meta.deletes), (2, 1));
+/// assert_eq!(meta.seqno_range, (3, 4));
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug)]
+pub struct SstWriter {
+    inner: writer::Writer,
+}
+
+impl SstWriter {
+    /// A writer for SST `id` into `extent` of `file`.
+    pub fn new(file: FileRef, extent: ExtentRef, id: SstId, options: SstWriterOptions) -> Self {
+        Self {
+            inner: writer::Writer::new(file, extent, id, options),
+        }
+    }
+
+    /// Whether an entry of these sizes still fits, leaving room for index, filters and
+    /// footer. Callers cut a new SST when it returns false. Conservative: if every `add` was
+    /// preceded by a `true` answer, [`finish`](Self::finish) never fails with
+    /// [`Error::ExtentFull`].
+    pub fn fits(&self, key_len: usize, value_len: usize) -> bool {
+        self.inner.fits(key_len, value_len)
+    }
+
+    /// Adds an entry: a valid internal key (else [`Error::Format`]) above the previous one
+    /// (else [`Error::OutOfOrder`]) and its stored value. After an error, abandon the writer.
+    pub fn add(&mut self, key: &[u8], value: &[u8]) -> Result<()> {
+        self.inner.add(key, value)
+    }
+
+    /// Data bytes written so far: sealed blocks and the open one, without the index, filters
+    /// and footer still to come. A writer that cuts its outputs by size reads it.
+    pub fn data_len(&self) -> u64 {
+        self.inner.data_len()
+    }
+
+    /// An upper bound on the SST's whole length if it were finished now: the data so far plus
+    /// the index, filters and footer it would carry. What a reader of the SST's length (a
+    /// manifest's `SstMeta::len`) sees, where [`data_len`](Self::data_len) leaves those out:
+    /// a writer that cuts outputs to fit a size measured that way reads this (#1324).
+    pub fn len_bound(&self) -> u64 {
+        self.inner.len_bound()
+    }
+
+    /// Entries added.
+    pub fn entries(&self) -> u64 {
+        self.inner.entries()
+    }
+
+    /// Writes the remaining data block, index partitions, top index, filters, properties and
+    /// footer, and returns the manifest record.
+    pub fn finish(self) -> Result<SstMeta> {
+        self.inner.finish()
+    }
+
+    /// Gives up; returns the extent for `Pager::abandon`.
+    pub fn abandon(self) -> ExtentRef {
+        self.inner.extent()
+    }
+}
+
+/// An open SST. Shared by every reader (`Send + Sync`); the engine keeps one per live SST.
+///
+/// Opening reads the footer, then the top-level index and both filters through the block
+/// cache and keeps them pinned, so a point lookup costs at most one cached index-partition
+/// lookup and one data-block read, and a filter miss costs no I/O.
+///
+/// ```
+/// use std::sync::Arc;
+/// use pigeonhole_cache::{BlockCache, Priority};
+/// use pigeonhole_format::filter::{column_hash, row_hash};
+/// use pigeonhole_format::key::{Kind, encode_column_prefix, encode_key, encode_marker_prefix};
+/// use pigeonhole_format::manifest::FamilyOptions;
+/// use pigeonhole_format::superblock::ExtentRef;
+/// use pigeonhole_format::{Cursor, FamilyId, SstId, TableId, TabletId};
+/// use pigeonhole_io::{OpenOptions, Vfs};
+/// use pigeonhole_io::sim::SimVfs;
+/// use pigeonhole_sst::{ReadOptions, ScanFilter, SstReader, SstWriter, SstWriterOptions};
+///
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// let file = SimVfs::new(3).open("/db".as_ref(), OpenOptions::read_write_create())?;
+/// let options = SstWriterOptions::for_family(&FamilyOptions::default(), TableId(1), FamilyId(1), TabletId(1));
+/// let mut w = SstWriter::new(file.clone(), ExtentRef { page: 16, size_class: 0 }, SstId(1), options);
+/// let mut key = Vec::new();
+/// encode_key(&mut key, b"alice", b"email", 10, 1, Kind::Put)?;
+/// w.add(&key, b"\x00a@example.com")?;
+/// let meta = w.finish()?;
+///
+/// let cache = Arc::new(BlockCache::new(1 << 20, 1));
+/// let sst = Arc::new(SstReader::open(file, &meta, cache, Priority::Normal)?);
+///
+/// // A point get probes the column and the row's marker key (FORMAT §6).
+/// let mut probe = Vec::new();
+/// encode_column_prefix(&mut probe, b"alice", b"email")?;
+/// assert!(sst.may_contain_column(column_hash(&probe)));
+/// assert!(sst.may_contain_row(row_hash(b"alice")));
+///
+/// let mut it = sst.iter(ScanFilter::all(), ReadOptions::default());
+/// it.seek(&probe)?;
+/// assert_eq!(it.key(), &key[..]);
+/// assert_eq!(&it.value_cell()[..], b"\x00a@example.com");
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug)]
+pub struct SstReader {
+    inner: reader::Reader,
+}
+
+impl SstReader {
+    /// Opens an SST: reads the footer, pins the top-level index and both filters, and reads
+    /// the properties. Verifies their checksums, but not those of data blocks and index
+    /// partitions, which are verified when first read (a damaged one is a corruption error,
+    /// never wrong data). Reading the whole SST at open is unnecessary: nothing references an
+    /// SST before its manifest commit, whose root commit syncs it first.
+    pub fn open(
+        file: FileRef,
+        meta: &SstMeta,
+        cache: Arc<BlockCache>,
+        priority: Priority,
+    ) -> Result<SstReader> {
+        Ok(Self {
+            inner: reader::Reader::open(file, meta, cache, priority, false)?,
+        })
+    }
+
+    /// As [`SstReader::open`], reading only from the block cache: whatever the open needs that
+    /// is not cached (the footer, the top-level index, the filters, the properties) fails it
+    /// with [`Error::WouldBlock`], to fetch and admit before opening again (ICR 0014).
+    pub fn open_cache_only(
+        file: FileRef,
+        meta: &SstMeta,
+        cache: Arc<BlockCache>,
+        priority: Priority,
+    ) -> Result<Self> {
+        Ok(Self {
+            inner: reader::Reader::open(file, meta, cache, priority, true)?,
+        })
+    }
+
+    /// The SST id.
+    pub fn id(&self) -> SstId {
+        self.inner.blocks.id
+    }
+
+    /// The SST's length in bytes (`SstMeta::len`).
+    pub fn len_bytes(&self) -> u64 {
+        self.inner.len_bytes()
+    }
+
+    /// The properties block.
+    pub fn properties(&self) -> &Properties {
+        &self.inner.properties
+    }
+
+    /// Row filter check with a precomputed `pigeonhole_format::filter::row_hash`. `true` if
+    /// the SST has no filter.
+    pub fn may_contain_row(&self, row_hash: u64) -> bool {
+        self.inner.may_contain_row(row_hash)
+    }
+
+    /// Column filter check with a precomputed `pigeonhole_format::filter::column_hash`. For a
+    /// row's family markers the column key is the marker prefix
+    /// (`pigeonhole_format::key::encode_marker_prefix`), which every SST holding a marker
+    /// adds; a point get probes both. `true` if the SST has no filter.
+    pub fn may_contain_column(&self, column_hash: u64) -> bool {
+        self.inner.may_contain_column(column_hash)
+    }
+
+    /// The first block a fresh cursor's first read loads past the pinned top index (the first
+    /// index partition, then its first data block), if the cache does not hold it: an async
+    /// scan fetches it before a level cursor moves into this SST (D196).
+    pub fn first_fetch(&self, priority: Priority) -> Option<Fetch> {
+        use pigeonhole_format::block::{Block, BlockAddr, BlockKind};
+        use pigeonhole_format::cursor::Cursor as _;
+        let blocks = &self.inner.blocks;
+        let mut top = Block::new(self.inner.top.clone()).ok()?.into_cursor();
+        top.seek_to_first().ok()?;
+        if !top.valid() {
+            return None;
+        }
+        let addr = BlockAddr::decode_varint(top.value()).ok()?;
+        match blocks.lookup(addr) {
+            Ok(None) => Some(blocks.fetch(addr, BlockKind::Index, priority)),
+            Ok(Some(h)) => {
+                let mut it = Block::new(h).ok()?.into_cursor();
+                it.seek_to_first().ok()?;
+                let first = BlockAddr::decode_varint(it.value()).ok()?;
+                blocks.fetch_if_missing(first, BlockKind::Data, priority, true)
+            }
+            Err(_) => None,
+        }
+    }
+
+    /// The first block a point read's seek to `target` loads past the pinned top index (the
+    /// index partition, then the data block it names), if the cache does not hold it: read
+    /// from the index only, so an async multi-get fetches the blocks of the keys after the one
+    /// it reads before it reaches them (D299). `None` when both are cached or `target` sorts
+    /// past the SST's last block.
+    pub fn fetch_for(&self, target: &[u8], priority: Priority) -> Option<Fetch> {
+        use pigeonhole_format::block::{Block, BlockAddr, BlockKind};
+        use pigeonhole_format::cursor::Cursor as _;
+        let blocks = &self.inner.blocks;
+        let mut top = Block::new(self.inner.top.clone()).ok()?.into_cursor();
+        top.seek(target).ok()?;
+        if !top.valid() {
+            return None;
+        }
+        let addr = BlockAddr::decode_varint(top.value()).ok()?;
+        let partition = match blocks.lookup(addr).ok()? {
+            Some(h) => h,
+            None => return Some(blocks.fetch(addr, BlockKind::Index, priority)),
+        };
+        let mut index = Block::new(partition).ok()?.into_cursor();
+        index.seek(target).ok()?;
+        if !index.valid() {
+            return None;
+        }
+        let data = BlockAddr::decode_varint(index.value()).ok()?;
+        blocks.fetch_if_missing(data, BlockKind::Data, priority, true)
+    }
+
+    /// A cursor applying `filter`; unpositioned until a seek. Owns a clone of the `Arc`.
+    /// Allocation-free.
+    #[inline]
+    pub fn iter(self: &Arc<Self>, filter: ScanFilter, options: ReadOptions) -> SstIter {
+        SstIter::new(Arc::clone(self), filter, options)
+    }
+}
+
+/// Per-read I/O policy.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub struct ReadOptions {
+    /// Insert blocks read from disk into the cache (false for compaction inputs).
+    pub fill_cache: bool,
+    /// Cache priority for inserted blocks.
+    pub priority: Priority,
+    /// Data blocks to fetch ahead during forward scans (0 = none, the default): on a cache
+    /// miss, the cursor submits fetches for up to this many of the next blocks the cache lacks
+    /// ([`SstIter::upcoming`]) and reads on while they complete, one batch at a time (#402).
+    /// Never on seeks. With `fill_cache` false the blocks are held by the cursor, not cached,
+    /// and a seek drops them.
+    pub readahead_blocks: u32,
+    /// Forward blocks a cursor reads past its seek before it reads ahead (2 by default,
+    /// #712): a scan that ends sooner submits no fetch. Raised for a scan expected to be
+    /// short (D293), which then reads ahead only once it proves long.
+    pub readahead_after: u32,
+    /// Readahead submits each run of blocks adjacent on disk as one read instead of one read
+    /// per block (#402; off by default, measured before it is decided).
+    #[doc(hidden)]
+    pub readahead_merge: bool,
+    /// Read only what is cached: a block that is not fails the read with
+    /// [`Error::WouldBlock`] instead of being read from the file (async reads, ICR 0014).
+    pub cache_only: bool,
+    /// The read stays within one row: its caller stops at the first key past the row of the
+    /// keys it reads (a point get or a single-row read). Leaving a data block whose index
+    /// separator marks the end of a row (the writer's row-end separators, ICR 0039), the
+    /// cursor ends instead of reading the next block, which holds only later rows.
+    pub one_row: bool,
+}
+
+impl Default for ReadOptions {
+    fn default() -> Self {
+        Self {
+            fill_cache: true,
+            priority: Priority::Normal,
+            readahead_blocks: 0,
+            readahead_after: iter::RAMP_AFTER,
+            readahead_merge: false,
+            cache_only: false,
+            one_row: false,
+        }
+    }
+}
+
+/// Appends separated values to one logical blob file. The caller supplies extents (from the
+/// pager) whenever [`BlobWriter::needs_extent`] says so. Like [`SstWriter`], it does not
+/// fsync.
+///
+/// ```
+/// use std::sync::Arc;
+/// use pigeonhole_cache::BlockCache;
+/// use pigeonhole_format::BlobFileId;
+/// use pigeonhole_format::superblock::ExtentRef;
+/// use pigeonhole_io::{OpenOptions, Vfs};
+/// use pigeonhole_io::sim::SimVfs;
+/// use pigeonhole_sst::{BlobReader, BlobWriter};
+///
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// let file = SimVfs::new(5).open("/db".as_ref(), OpenOptions::read_write_create())?;
+/// let mut w = BlobWriter::new(file.clone(), BlobFileId(4), 0);
+/// let big = vec![7u8; 100_000]; // larger than one 64 KiB extent: the record spans two
+/// let mut next_page = 16;
+/// assert_eq!(w.reserve_for(big.len()), 2);
+/// while w.needs_extent(big.len()) {
+///     w.add_extent(ExtentRef { page: next_page, size_class: 0 })?;
+///     next_page += 16;
+/// }
+/// let ptr = w.append(&big)?;
+/// let (extents, bytes) = w.finish()?;
+/// assert_eq!((extents.len(), bytes), (2, 100_016));
+///
+/// let r = BlobReader::new(file, BlobFileId(4), extents, Arc::new(BlockCache::new(1 << 20, 1)));
+/// assert_eq!(&r.read(&ptr)?[..], &big[..]);
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug)]
+pub struct BlobWriter {
+    inner: blob::Writer,
+}
+
+impl BlobWriter {
+    /// A writer for `blob_file`, whose extents are all of `size_class`.
+    pub fn new(file: FileRef, blob_file: BlobFileId, size_class: u8) -> Self {
+        Self {
+            inner: blob::Writer::new(file, blob_file, size_class),
+        }
+    }
+
+    /// Whether appending a value of `len` bytes needs more extents first.
+    pub fn needs_extent(&self, len: usize) -> bool {
+        self.inner.needs_extent(len)
+    }
+
+    /// How many extents appending a value of `len` bytes needs first (as many
+    /// [`add_extent`](Self::add_extent) calls as [`needs_extent`](Self::needs_extent) asks
+    /// for), with room for them reserved, so adding them allocates nothing more.
+    pub fn reserve_for(&mut self, len: usize) -> usize {
+        self.inner.reserve_for(len)
+    }
+
+    /// Adds the next extent (writes its header). It must be of the writer's size class.
+    pub fn add_extent(&mut self, extent: ExtentRef) -> Result<()> {
+        self.inner.add_extent(extent)
+    }
+
+    /// Appends a value and returns the pointer the LSM entry stores. Fails with
+    /// [`Error::ExtentFull`] if [`needs_extent`](Self::needs_extent) said more extents were
+    /// needed and none were added.
+    pub fn append(&mut self, value: &[u8]) -> Result<BlobPointer> {
+        self.inner.append(value)
+    }
+
+    /// Finishes; returns the extents in logical order and total bytes written (the logical
+    /// length: every record's 16-byte header and value).
+    pub fn finish(self) -> Result<(Vec<ExtentRef>, u64)> {
+        Ok(self.inner.finish())
+    }
+}
+
+/// Reads separated values of one logical blob file. Records are cached (at low priority)
+/// under [`blob_cache_file`]; see [`BlobWriter`] for an example.
+#[derive(Debug)]
+pub struct BlobReader {
+    inner: blob::Reader,
+}
+
+impl BlobReader {
+    /// A reader over the blob file's extents.
+    pub fn new(
+        file: FileRef,
+        blob_file: BlobFileId,
+        extents: Vec<ExtentRef>,
+        cache: Arc<BlockCache>,
+    ) -> Self {
+        Self {
+            inner: blob::Reader::new(file, blob_file, extents, cache),
+        }
+    }
+
+    /// Reads and verifies the value `ptr` points to (verification is skipped on a cache
+    /// hit). A pointer past the blob file or a checksum mismatch is a [`Error::Format`]
+    /// corruption error.
+    pub fn read(&self, ptr: &BlobPointer) -> Result<Cell> {
+        self.inner.read(ptr)
+    }
+
+    /// The value `ptr` names if its record is cached: a lookup only, which never reads the
+    /// file (async reads count the reads they make synchronously, ICR 0014).
+    pub fn cached(&self, ptr: &BlobPointer) -> Option<Cell> {
+        self.inner.cached(ptr)
+    }
+
+    /// A cache-only read of `ptr` (ICR 0014): the value if its record is cached; otherwise
+    /// [`Error::WouldBlock`] with the fetch it needs (an extent header not verified yet, then
+    /// the record); or `None` for a record too large to cache, which the caller reads with
+    /// [`BlobReader::read`].
+    pub fn read_cache_only(self: &Arc<Self>, ptr: &BlobPointer) -> Result<Option<Cell>> {
+        self.inner.read_cache_only(self, ptr)
+    }
+}