Struct FileStorage 

pub struct FileStorage { /* private fields */ }

A file-based storage implementation.

FileStorage provides persistent disk-based storage with two read modes:

1. Traditional I/O (default): Uses buffered file reads with BufReader
2. Memory-mapped I/O: Uses mmap for zero-copy reads when config.use_mmap is true

The mmap mode includes caching and automatic invalidation on file changes, making it suitable for read-heavy workloads with large files.

Implementations

impl FileStorage

pub fn new<P: AsRef<Path>>( directory: P, config: FileStorageConfig, ) -> Result<Self>

Create a new file storage in the given directory.

Trait Implementations

impl Debug for FileStorage

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

Formats the value using the given formatter.

impl Storage for FileStorage

fn create_output(&self, name: &str) -> Result<Box<dyn StorageOutput>>

Create a fresh output for name, truncating any existing file.

Concurrency

On Windows the OS holds an exclusive lock on memory-mapped files. This method evicts the storage’s own mmap cache entry for name before the truncate so the file lock can be released (Issue #508). Any StorageInput previously returned by Self::open_input for the same name must already be dropped before another code path invokes this method — otherwise the outstanding Arc<Mmap> clone will keep the Windows lock alive and the OS returns ERROR_USER_MAPPED_FILE. See Self::evict_mmap for the full lifetime contract.

fn create_output_append(&self, name: &str) -> Result<Box<dyn StorageOutput>>

Open name for append, creating it if necessary.

Concurrency

Append-mode targets (WAL, log files) are not memory-mapped in the current codebase, so the cache eviction below is purely defensive. If a future change starts mmap’ing one of these files, the Windows lifecycle contract documented on Self::evict_mmap already applies (Issue #508).

fn delete_file(&self, name: &str) -> Result<()>

Delete name from the storage directory.

Concurrency

On Windows, remove_file returns ERROR_USER_MAPPED_FILE if any process still holds an mmap for the file. This method evicts the storage’s own cached Arc<Mmap> first to release the lock (Issue #508). Outstanding StorageInput clones held elsewhere keep the lock alive until they drop; the same lifetime contract documented on Self::evict_mmap applies.

fn loading_mode(&self) -> LoadingMode

Get the preferred loading mode for this storage.

fn open_input(&self, name: &str) -> Result<Box<dyn StorageInput>>

Open a file for reading.

fn file_exists(&self, name: &str) -> bool

Check if a file exists.

fn list_files(&self) -> Result<Vec<String>>

List all files in the storage.

fn file_size(&self, name: &str) -> Result<u64>

Get the size of a file in bytes.

fn metadata(&self, name: &str) -> Result<FileMetadata>

Get file metadata.

fn rename_file(&self, old_name: &str, new_name: &str) -> Result<()>

Rename a file.

fn create_temp_output( &self, prefix: &str, ) -> Result<(String, Box<dyn StorageOutput>)>

Create a temporary file.

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

Sync all pending writes to storage.

fn close(&mut self) -> Result<()>

Close the storage and release resources.