Struct KvStack 

pub struct KvStack { /* private fields */ }

A stack of seg files for one domain, queried newest-first so overrides win.

The salt is resolved once at open time (brute-forced from the oldest file when Salt::Find is used) and then applied to every file’s bloom, so a wrong or absent salt only disables the negative-lookup speedup — it can never cause a missed key.

Implementations

impl KvStack

pub fn open<I, P>(paths: I, salt: Salt) -> Result<KvStack>

where I: IntoIterator<Item = P>, P: AsRef<Path>,

Open an explicit set of .kv files as a newest-wins stack. The files are sorted oldest → newest by their <from>-<to> step range (parsed from the file name), so the caller need not pre-sort them. Errors if paths is empty or any file fails to open.

salt controls the .kvei bloom accelerator (see Salt): the salt is resolved once (brute-forced from the oldest file for Salt::Find) and each file’s bloom is enabled only if it self-validates against that file’s real keys.

pub fn open_dir( dir: impl AsRef<Path>, name_filter: &str, salt: Salt, ) -> Result<KvStack>

Open every .kv in dir whose file name contains name_filter, as a newest-wins stack. Use name_filter to select a single domain (e.g. "accounts") so files from different domains in the same directory are not mixed. Errors if no matching .kv file is found.

pub fn salt(&self) -> Option<u32>

The resolved bloom salt, if one was supplied or found.

pub fn bloom_count(&self) -> usize

Number of files with an active (validated) bloom accelerator.

pub fn len(&self) -> usize

Number of files in the stack.

pub fn is_empty(&self) -> bool

Whether the stack has no files. (Never true for a stack from open, which rejects an empty input.)

pub fn readers(&self) -> &[KvReader]

The readers, oldest → newest.

pub fn files(&self) -> impl Iterator<Item = (&str, u64)>

Iterate (file name, key count) for each file, oldest → newest.

pub fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>>

Look up key across all files, newest-first; returns the value from the newest file that contains it (overrides win), or None if no file has it.

pub fn advise_random(&self) -> Result<()>

Advise the kernel that every file in the stack is read by point lookup. See KvReader::advise_random for when this is worth setting.

pub fn index_bytes(&self) -> u64

Total bytes preload_index would make resident across the stack. A stack lookup consults every file, so this is the figure to budget.

pub fn preload_index(&self) -> u64

Preload every file’s index into the page cache. See KvReader::preload_index — the case for it is stronger here, because a stack lookup searches each file in turn until one hits.

pub fn lock_index(&self) -> Result<()>

Pin every file’s index in RAM. See KvReader::lock_index for the RLIMIT_MEMLOCK caveat, which applies to the stack’s total.

pub fn unlock_index(&self) -> Result<()>

Release the pages pinned by lock_index.