Struct Database 

pub struct Database(/* private fields */);

Memory-mapped database with dynamic space allocation and hole punching.

Provides efficient storage through memory mapping with automatic region management, space reclamation via hole punching, and dynamic file growth as needed.

Implementations

impl Database

pub fn open(path: &Path) -> Result<Self>

Opens or creates a database at the specified path.

pub fn open_with_min_len(path: &Path, min_len: usize) -> Result<Self>

Opens or creates a database with a minimum initial file size.

pub fn file_len(&self) -> Result<usize>

Returns the current length of the database file in bytes.

pub fn set_min_len(&self, len: usize) -> Result<()>

Ensures the database file is at least the specified length.

This pre-allocates file space to avoid expensive growth during writes. The length is rounded up to the next page size multiple (4096 bytes).

pub fn set_min_regions(&self, regions: usize) -> Result<()>

Pre-allocates space for at least the specified number of regions.

This avoids expensive reallocations when creating many regions.

pub fn get_region(&self, id: &str) -> Option<Region>

Gets an existing region by ID.

pub fn create_region_if_needed(&self, id: &str) -> Result<Region>

Creates a region with the given ID, or returns it if it already exists.

pub fn remove_region_if_exists(&self, id: &str) -> Result<()>

Removes a region by ID if it exists, otherwise does nothing.

Returns Ok(()) whether the region existed or not.

pub fn remove_region(&self, id: &str) -> Result<()>

Removes a region by ID.

Returns Error::RegionNotFound if the region doesn’t exist.

pub fn retain_regions(&self, ids: HashSet<String>) -> Result<()>

Removes all regions except those in the provided set.

This is useful for garbage collection - keeping only regions that are still in use and removing all others.

pub fn open_read_only_file(&self) -> Result<File>

Open a dedicated file handle for sequential reading This enables optimal kernel readahead for iteration

pub fn disk_usage(&self) -> Result<DiskUsage>

Returns the actual disk usage (accounting for sparse files and hole punching).

On Unix systems, this uses fstat to get the number of blocks actually allocated. On Windows, this falls back to the logical file size (less accurate for sparse files).

pub fn flush(&self) -> Result<usize>

Flushes all dirty data and metadata to disk.

This ensures durability - all writes are persisted and will survive a crash. Also promotes pending holes so they can be reused by future allocations. Returns the number of regions that had dirty data or metadata.

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

Compact the database by promoting pending holes and punching holes in the file.

This flushes all dirty data first to ensure consistency.

pub fn file(&self) -> RwLockReadGuard<'_, File>

pub fn file_mut(&self) -> RwLockWriteGuard<'_, File>

pub fn mmap(&self) -> RwLockReadGuard<'_, MmapMut>

pub fn mmap_mut(&self) -> RwLockWriteGuard<'_, MmapMut>

pub fn regions(&self) -> RwLockReadGuard<'_, Regions>

pub fn layout(&self) -> RwLockReadGuard<'_, Layout>

pub fn path(&self) -> &Path

pub fn weak_clone(&self) -> WeakDatabase

pub fn name(&self) -> &str

Returns the database name (last path component) for logging.

Trait Implementations

impl Clone for Database

fn clone(&self) -> Database

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Database

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Database

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.