Enum AnyTree 

pub enum AnyTree {
    Standard(Tree),
    Blob(BlobTree),
}

May be a standard Tree or a BlobTree

Closed like either: once the TreeClose of close fires, the tree writes nothing into its directory.

Variants

Standard(Tree)

Standard LSM-tree, see Tree

Blob(BlobTree)

Key-value separated LSM-tree, see BlobTree

Implementations

impl AnyTree

pub fn downgrade(&self) -> WeakTree

A handle that does not keep the tree open; see WeakTree.

pub fn close(self) -> TreeClose

Gives up this handle and returns the signal of the tree being closed; see Tree::close.

pub fn start_multi_get<K: Into<UserKey>>( &self, keys: impl IntoIterator<Item = K>, seqno: SeqNo, ) -> Result<Step>

Starts a multi-get of keys at seqno that its caller drives: see Tree::start_multi_get.

Errors

Returns crate::Error::SnapshotBelowRetention when seqno is below what the tree retains.

impl AnyTree

pub fn ingestion(&self) -> Result<AnyIngestion<'_>>

Starts an ingestion for any tree type (standard or blob).

Errors

Will return Err if an IO error occurs.

pub fn columnar_scan<R: RangeBounds<UserKey>>( &self, projection: impl Into<Projection>, predicate: Option<&ColumnRangePredicate>, seqno: SeqNo, range: R, ) -> Result<ColumnarScan>

Runs a projected columnar scan across the tree.

Delegates to Tree::columnar_scan on a standard tree and to BlobTree::columnar_scan on a blob tree: reads the memtables and every table intersecting range at seqno, and yields projected ColumnBatches in key order, one row per key, its newest visible version. See Tree::columnar_scan for the full contract.

Errors

As Tree::columnar_scan and BlobTree::columnar_scan.

Examples

use lsm_tree::table::columnar::{Column, TypeTag, entries_to_column_batch};
use lsm_tree::{AnyTree, Config, InternalValue, SeqNo, ValueType};

let folder = tempfile::tempdir()?;
let any = Config::new(folder, Default::default(), Default::default()).open()?;
if let AnyTree::Standard(tree) = &any {
    tree.update_runtime_config(|cfg| cfg.columnar = true)?;
}

// Ingest one row whose value is a single fixed-4 sub-column (id 3).
let mut batch = entries_to_column_batch(&[InternalValue::from_components(
    b"k0".to_vec(),
    b"x".to_vec(),
    0,
    ValueType::Value,
)])?;
batch.columns.pop();
batch.columns.push(Column {
    column_id: 3,
    type_tag: TypeTag::Fixed(4),
    validity: None,
    data: vec![1, 0, 0, 0].into(),
});
let mut ingestion = any.ingestion()?;
ingestion.write_columnar_batch(&batch)?;
ingestion.finish()?;

// Scan projecting only sub-column 3 across the whole tree.
let mut rows = 0;
for batch in any.columnar_scan(&[3], None, SeqNo::MAX, ..)? {
    rows += batch?.row_count;
}
assert_eq!(rows, 1);

Trait Implementations

impl AbstractTree for AnyTree

fn table_file_cache_size(&self) -> usize

Returns the number of cached table file descriptors.

fn storage_stats(&self) -> Result<StorageStats>

Returns a read-only snapshot of the tree’s on-disk storage footprint: total used bytes, entry count, the average shape of a stored entry (average key / value bytes), and an estimate of how many more average-shaped entries fit in a byte budget (see StorageStats::estimated_remaining_entries).

fn level_segment_stats(&self) -> Result<Vec<LevelStats>>

Per-LSM-level and per-segment size + entry-count stats, for tiering and erasure-coding placement decisions (which level / segment is large enough to demote, EC-encode, or migrate).

fn compaction_debt(&self, strategy: &dyn CompactionStrategy) -> u64

Estimated bytes pending compaction under strategy: on-disk data above its level’s target that must eventually be rewritten downward (a RocksDB estimate-pending-compaction-bytes analog), a compaction-debt signal for a scheduler / tiering consumer.

fn write_backpressure(&self, strategy: &dyn CompactionStrategy) -> Backpressure

Computed write-backpressure verdict from the live L0 run count, the strategy’s pending-compaction bytes and the unflushed memtable bytes, against the configured RuntimeConfig::backpressure thresholds.

fn write_backpressure_for( &self, strategy: &dyn CompactionStrategy, bytes: u64, ) -> Backpressure

The verdict for one write of bytes: write_backpressure, except that a slowdown on a tree with a write rate limit (see Config::write_rate_limit) debits bytes from the tree’s write limiter and suggests waiting until they, and every byte debited before them, are paid off at its rate. Writes honouring it are then bounded by the rate in bytes per second, large and small alike, however many writers share the limiter. Outside the slowdown tier nothing is debited.

fn write_rate_limiter(&self) -> Arc<RateLimiter>

The limiter writes are paced with under backpressure slowdown: shared with other trees if one was supplied through Config::write_rate_limiter, else the tree’s own. Retune it live with RateLimiter::set_rate; 0 turns byte pacing off.

fn write_admission(&self) -> Result<()>

Storage admission gate: Ok(()) if a write may proceed, or Error::StorageFull if the tree is over budget and should be treated as read-only.

fn is_read_only(&self) -> bool

true when the admission gate is currently closed (see write_admission). Convenience for callers that want a boolean rather than a Result. Always false unless admission control is enabled and the tree is over budget.

fn verify_checksum(&self) -> BlockVerifyReport

where Self: Sized,

Proactively verifies every block’s XXH3 checksum across every SST in the tree’s current version — a scrubber for catching bit rot before it surfaces as a user-visible read failure (cron / scrub jobs).

fn verify_checksum_with(&self, options: &VerifyOptions) -> BlockVerifyReport

where Self: Sized,

Like Self::verify_checksum but with configurable parallelism and I/O throttle (see VerifyOptions).

fn create_checkpoint(&self, target_path: &Path) -> Result<CheckpointInfo>

Creates a hard-linked checkpoint of the tree’s on-disk state in target_path for point-in-time recovery (PITR) backup.

fn pin(&self) -> PinnedVersion

Pins the tree’s current state for a point-in-time copy that costs no file I/O: seals the active memtable and returns a PinnedVersion holding the sealed memtables, tables, blob files and dictionaries as they are now.

fn acknowledge_repair_report(&self, id: u128) -> Result<bool>

Stops the tree owing the repair report with this RepairReport::id, installing a version that no longer carries it: no later Config::open_or_repair hands it out.

fn flush_active_memtable(&self, gc_watermark: SeqNo) -> Result<()>

Seals the active memtable and flushes it, with every memtable sealed before it, to tables: the durability barrier for a caller that keeps its own journal of the writes.

fn persist_flushes(&self) -> Result<()>

Makes every flush installed before this call durable, under FlushDurability::Deferred: the tables and blob files those flushes wrote are synced, then their folders, then the manifest is written. Once it returns Ok a caller may drop its own log up to the writes those flushes held; under SyncMode::Barrier after sync_devices as well. A no-op when nothing is pending, and under FlushDurability::Synced every flush is durable when it returns.

fn sync_devices(&self) -> Result<()>

Makes durable everything this tree synced on each device it lies on: the tree folder’s, that of every level’s tables, that of the dictionaries folder and, with KV separation, that of the blobs folder.

fn flush( &self, lock: &MutexGuard<'_, ()>, gc_watermark: SeqNo, ) -> Result<Option<u64>>

Synchronously flushes pending sealed memtables to tables.

fn iter( &self, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Box<dyn DoubleEndedIterator<Item = IterGuardImpl> + Send + 'static>

Returns an iterator that scans through the entire tree.

fn prefix<K: AsRef<[u8]>>( &self, prefix: K, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Box<dyn DoubleEndedIterator<Item = IterGuardImpl> + Send + 'static>

Returns an iterator over a prefixed set of items.

fn range<K: AsRef<[u8]>, R: RangeBounds<K>>( &self, range: R, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Box<dyn DoubleEndedIterator<Item = IterGuardImpl> + Send + 'static>

Returns an iterator over a range of items.

fn range_seekable<K: AsRef<[u8]>, R: RangeBounds<K>>( &self, range: R, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Box<dyn SeekableGuardIter + 'static>

Returns a range iterator that can reposition (seek) in place without reopening its per-SST readers.

fn batch_range_scan<K: AsRef<[u8]>, R: RangeBounds<K> + 'static, I: IntoIterator<Item = R>>( &self, intervals: I, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Box<dyn Iterator<Item = IterGuardImpl> + Send + 'static>

where I::IntoIter: Send + 'static,

Scans a sequence of disjoint, ascending key sub-intervals, reusing one set of per-SST readers across all of them.

fn tombstone_count(&self) -> u64

Returns the approximate number of tombstones in the tree.

fn weak_tombstone_count(&self) -> u64

Returns the approximate number of weak tombstones (single deletes) in the tree.

fn weak_tombstone_reclaimable_count(&self) -> u64

Returns the approximate number of values reclaimable once weak tombstones can be GC’d.

fn clear(&self) -> Result<()>

Drops all tables and clears all memtables atomically.

fn major_compact( &self, target_size: u64, gc_watermark: SeqNo, ) -> Result<CompactionResult>

Performs major compaction, blocking the caller until it’s done.

fn stale_blob_bytes(&self) -> u64

Returns the disk space used by stale blobs.

fn filter_size(&self) -> u64

Gets the space usage of all filters in the tree.

fn pinned_filter_size(&self) -> usize

Gets the memory usage of all pinned filters in the tree.

fn filter_memory(&self) -> FilterMemory

The serialised and the resident bytes of the tree’s filters, and how they stand against a FilterAdvisor budget.

fn pinned_block_index_size(&self) -> usize

Gets the memory usage of all pinned index blocks in the tree.

fn metrics(&self) -> &Arc<Metrics>

Returns the metrics structure.

fn cache_stats(&self) -> CacheStats

A point-in-time CacheStats snapshot of block-cache effectiveness (cumulative hit / miss counts and rate) and occupancy (current size against capacity).

fn get_flush_lock(&self) -> MutexGuard<'_, ()>

Acquires the flush lock which is required to call Tree::flush.

fn flush_to_tables( &self, stream: impl Iterator<Item = Result<InternalValue>>, ) -> Result<Option<(Vec<Table>, Option<Vec<BlobFile>>, WritePin)>>

Synchronously flushes a memtable to a table.

fn register_tables( &self, tables: &[Table], blob_files: Option<&[BlobFile]>, frag_map: Option<FragmentationMap>, sealed_memtables_to_delete: &[MemtableId], gc_watermark: SeqNo, collected_below_watermark: bool, ) -> Result<()>

Atomically registers flushed tables into the tree, removing their associated sealed memtables.

fn clear_active_memtable(&self)

Clears the active memtable atomically.

fn sealed_memtable_count(&self) -> usize

Returns the number of sealed memtables.

fn compact( &self, strategy: Arc<dyn CompactionStrategy>, gc_watermark: SeqNo, ) -> Result<CompactionResult>

Performs compaction on the tree’s levels, blocking the caller until it’s done.

fn get_next_table_id(&self) -> TableId

Returns the next table’s ID.

fn tree_config(&self) -> &Config

Returns the tree config.

fn get_highest_seqno(&self) -> Option<SeqNo>

Returns the highest sequence number.

fn active_memtable(&self) -> Arc<Memtable>

Returns the active memtable.

fn tree_type(&self) -> TreeType

Returns the tree type.

fn rotate_memtable(&self) -> Option<Arc<Memtable>>

Seals the active memtable.

fn table_count(&self) -> usize

Returns the number of tables currently in the tree.

fn level_table_count(&self, idx: usize) -> Option<usize>

Returns the number of tables in levels[idx].

fn l0_run_count(&self) -> usize

Returns the number of disjoint runs in L0.

fn blob_file_count(&self) -> usize

Returns the number of blob files currently in the tree.

fn approximate_len(&self) -> usize

Approximates the number of items in the tree.

fn disk_space(&self) -> u64

Returns the disk space usage.

fn approximate_range_stats<K: AsRef<[u8]>, R: RangeBounds<K>>( &self, range: R, seqno: SeqNo, ) -> Result<ApproximateRangeStats>

Estimates the on-disk bytes and entry count contained in range at seqno, WITHOUT reading any data block.

fn approximate_range_cardinality<K: AsRef<[u8]>, R: RangeBounds<K>>( &self, range: R, seqno: SeqNo, ) -> Result<RangeCardinality>

Estimates the row cardinality and selectivity of range at seqno, WITHOUT reading any data block.

fn get_highest_memtable_seqno(&self) -> Option<SeqNo>

Returns the highest sequence number of the active memtable.

fn get_highest_persisted_seqno(&self) -> Option<SeqNo>

Returns the highest sequence number that is flushed to disk.

fn oldest_retained_seqno(&self) -> SeqNo

Returns the retention floor: the lower bound of the readable snapshot window.

fn retention_floor(&self) -> SeqNo

Returns the persisted retention floor: the highest snapshot seqno the tree refuses, now and after a reopen. It always equals oldest_retained_seqno.

fn lower_retention_floor(&self, floor: SeqNo) -> Result<()>

Lowers the persisted retention floor to floor, so snapshots above it are served again, now and after a reopen.

fn compaction_rate_limiter(&self) -> Arc<RateLimiter>

Returns the limiter that throttles this tree’s compactions: the one supplied through Config::compaction_rate_limiter, which other trees may share, or the tree’s own built from Config::compaction_rate_limit.

fn len( &self, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Result<usize>

Scans the entire tree, returning the number of items.

fn is_empty( &self, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Result<bool>

Returns true if the tree is empty.

fn first_key_value( &self, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Option<IterGuardImpl>

Returns the first key-value pair in the tree. The key in this pair is the minimum key in the tree.

fn last_key_value( &self, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Option<IterGuardImpl>

Returns the last key-value pair in the tree. The key in this pair is the maximum key in the tree.

fn size_of<K: AsRef<[u8]>>(&self, key: K, seqno: SeqNo) -> Result<Option<u32>>

Returns the size of a value if it exists.

fn get<K: AsRef<[u8]>>(&self, key: K, seqno: SeqNo) -> Result<Option<UserValue>>

Retrieves an item from the tree.

fn get_pinned<K: AsRef<[u8]>>( &self, key: K, seqno: SeqNo, ) -> Result<Option<PinnableSlice>>

Retrieves an item from the tree as a PinnableSlice.

fn contains_key<K: AsRef<[u8]>>(&self, key: K, seqno: SeqNo) -> Result<bool>

Returns true if the tree contains the specified key.

fn contains_prefix<K: AsRef<[u8]>>( &self, prefix: K, seqno: SeqNo, index: Option<(Arc<Memtable>, SeqNo)>, ) -> Result<bool>

Returns true if the tree contains any key with the given prefix.

fn multi_get<K: AsRef<[u8]>>( &self, keys: impl IntoIterator<Item = K>, seqno: SeqNo, ) -> Result<Vec<Option<UserValue>>>

Reads multiple keys from the tree.

fn apply_batch(&self, batch: WriteBatch, seqno: SeqNo) -> Result<(u64, u64)>

Applies a WriteBatch with the given sequence number.

fn insert<K: Into<UserKey>, V: Into<UserValue>>( &self, key: K, value: V, seqno: SeqNo, ) -> (u64, u64)

Inserts a key-value pair into the tree.

fn try_insert<K: Into<UserKey>, V: Into<UserValue>>( &self, key: K, value: V, seqno: SeqNo, ) -> Result<(u64, u64)>

Admission-gated insert: consults write_admission first and declines with Error::StorageFull when the tree is over budget, otherwise inserts and returns the same (added_bytes, memtable_size) tuple. This is the write entry a space-aware caller uses so over-budget writes are refused up front rather than failing a flush later; bare insert stays infallible for callers that do not opt into admission control.

fn try_merge<K: Into<UserKey>, V: Into<UserValue>>( &self, key: K, operand: V, seqno: SeqNo, ) -> Result<(u64, u64)>

Admission-gated merge. See try_insert.

fn try_remove<K: Into<UserKey>>( &self, key: K, seqno: SeqNo, ) -> Result<(u64, u64)>

Admission-gated remove. See try_insert.

fn try_remove_weak<K: Into<UserKey>>( &self, key: K, seqno: SeqNo, ) -> Result<(u64, u64)>

Admission-gated remove_weak. See try_insert.

fn try_remove_range<K: Into<UserKey>>( &self, start: K, end: K, seqno: SeqNo, ) -> Result<u64>

Admission-gated remove_range. See try_insert.

fn remove<K: Into<UserKey>>(&self, key: K, seqno: SeqNo) -> (u64, u64)

Removes an item from the tree.

fn merge<K: Into<UserKey>, V: Into<UserValue>>( &self, key: K, operand: V, seqno: SeqNo, ) -> (u64, u64)

Writes a merge operand for a key.

fn remove_range<K: Into<UserKey>>(&self, start: K, end: K, seqno: SeqNo) -> u64

Deletes all keys in the range [start, end) by inserting a range tombstone.

fn remove_prefix<K: AsRef<[u8]>>(&self, prefix: K, seqno: SeqNo) -> u64

Deletes all keys with the given prefix by inserting a range tombstone.

impl Clone for AnyTree

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl From<BlobTree> for AnyTree

fn from(tree: BlobTree) -> Self

Converts to this type from the input type.

impl From<Tree> for AnyTree

fn from(tree: Tree) -> Self

Converts to this type from the input type.

impl TryInto<BlobTree> for AnyTree

type Error = &'static str

The type returned in the event of a conversion error.

fn try_into(self) -> Result<BlobTree, Self::Error>

Performs the conversion.

impl TryInto<Tree> for AnyTree

type Error = &'static str

The type returned in the event of a conversion error.

fn try_into(self) -> Result<Tree, Self::Error>

Performs the conversion.