pub struct Db { /* private fields */ }Expand description
Open handle on a btree database file.
Wraps a read-only mmap of the file plus the parameters decoded
from its meta page (page size, host/foreign byte order).
Because the file is held via mmap, the caller is responsible for
ensuring it is not mutated by another process for the lifetime of
the Db. External writes can observably change bytes the API
hands out and would constitute undefined behaviour at the mmap
layer. For the typical pkgsrc use case - a single short-lived
reader over pkgdb.byfile.db - this is trivially satisfied.
Implementations§
Source§impl Db
impl Db
Sourcepub fn open(path: impl AsRef<Path>) -> Result<Self>
pub fn open(path: impl AsRef<Path>) -> Result<Self>
Open path for reading.
Maps the file with mmap(2) and validates the meta page.
Recno trees are rejected; btree pages themselves are
validated lazily on first access.
See the Db type-level documentation for the mmap
concurrent-writer invariant the caller must uphold.
§Errors
Returns Error::Io if the file cannot be opened or mapped,
or Error::ShortFile if it is too small to contain a meta
page. Returns Error::BadMagic, Error::BadVersion,
Error::BadPageSize, Error::UnsupportedFlags or
Error::UnalignedFileLength when the meta page is
recognisable but its contents fall outside the supported
subset.
Sourcepub fn get(&self, key: &[u8]) -> Result<Option<Cow<'_, [u8]>>>
pub fn get(&self, key: &[u8]) -> Result<Option<Cow<'_, [u8]>>>
Look up a key.
Returns Ok(Some(value)) on hit and Ok(None) if the key is
absent. Inline values are returned as Cow::Borrowed slices
into the mmap; overflow values are materialised into
Cow::Owned. Keys are compared as raw byte strings with
unsigned byte-by-byte ordering and shorter-wins (matching
__bt_defcmp in bt_utils.c, which is equivalent to
<[u8] as Ord>::cmp).
§Errors
Returns an Error on I/O failure or on-disk corruption
encountered while descending the tree.