Struct FileHandle 

pub struct FileHandle { /* private fields */ }

A handle to a database file capable of positioned reads and writes at page boundaries.

FileHandle is intentionally minimal — it exposes only the operations the pager (L1) and WAL (L2) need. Higher layers must never reach past it into std::fs directly; routing every syscall through this type is how the project keeps Rule 8 enforceable.

Implementations

impl FileHandle

pub fn try_lock_writer(&self) -> Result<Option<WriterLock>>

Try once, non-blocking, to acquire the WRITER_LOCK. Returns Ok(Some(guard)) if the lock was acquired, Ok(None) if it is held by someone else, or Err(Error::Io) on syscall failure.

Errors

Returns Error::Io on syscall failure other than “would-block / already-locked”.

pub fn lock_writer(&self, timeout: Duration) -> Result<WriterLock>

Acquire the WRITER_LOCK, retrying with bounded exponential backoff until either acquired or timeout elapses. Returns Err(Error::Busy { kind: LockKind::Writer }) on timeout.

Errors

• Error::Busy with LockKind::Writer on timeout.
• Error::Io on any non-“would-block” syscall failure.

pub fn lock_reader(&self, timeout: Duration) -> Result<ReaderLock>

Acquire any one of the 31 reader-lock slots in shared mode, retrying with bounded backoff until either acquired or timeout elapses.

The slot is chosen with a per-process round-robin counter so concurrent readers in the same process do not all race for the same byte. Shared locks compose, so falling on the same byte is not a correctness bug — just a hot-spot the spread avoids in practice.

Errors

• Error::Busy with LockKind::Reader on timeout (very rare — shared locks rarely contend).
• Error::Io on syscall failure.

impl FileHandle

pub fn open_or_create<P: AsRef<Path>>(path: P) -> Result<Self>

Open path for read-write access, creating it if it does not exist. The new file is empty; the caller is responsible for writing the file header.

Errors

Returns Error::Io if the file cannot be opened or created (permission denied, missing parent directory, etc.).

pub fn create_new<P: AsRef<Path>>(path: P) -> Result<Self>

Open path for read-write access, failing if the file already exists (O_CREAT | O_EXCL on POSIX, CREATE_NEW on Windows). Used by M11 #92 hot-backup to guarantee the destination is never overwritten.

Errors

Returns Error::Io if the file already exists, the parent directory does not exist, or any other syscall failure occurs.

pub fn len(&self) -> Result<u64>

Length of the file in bytes.

Errors

Returns Error::Io if the metadata syscall fails.

pub fn is_empty(&self) -> Result<bool>

true if the file is zero-length (i.e. just created).

Errors

Returns Error::Io if the metadata syscall fails.

pub fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()>

Positioned read. Fills buf from byte offset offset.

Errors

Returns Error::Io on syscall failure or on short read (e.g. file shorter than offset + buf.len()).

pub fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()>

Positioned write. Writes buf to byte offset offset.

Errors

Returns Error::Io on syscall failure or on short write.

pub fn set_len(&self, new_len: u64) -> Result<()>

Truncate or extend the file to new_len bytes.

Used by the pager when the freelist is exhausted and a fresh page must be appended.

On Windows this call wraps SetEndOfFile, which can transiently return ERROR_LOCK_VIOLATION when Windows Defender holds a short byte-range lock on the extending region. We retry under the same bounded scheme as positioned reads and writes (up to 10 attempts with linear backoff capped at 250 ms). On Unix the call is forwarded unchanged.

Errors

Returns Error::Io on syscall failure.

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

Force file contents and metadata to disk. Used at close.

Power-of-ten Rule 7: the underlying call returns io::Result<()> and is propagated explicitly.

Errors

Returns Error::Io on syscall failure.

pub fn sync_data(&self, mode: SyncMode) -> Result<()>

Force file data (and on Full, the drive cache) to persistent storage according to mode. See SyncMode for the exact per-variant durability promise.

On SyncMode::Off this call is a no-op.

Errors

Returns Error::Io on syscall failure.

Trait Implementations

impl Debug for FileHandle

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

Formats the value using the given formatter.

impl FileBackend for FileHandle

fn len(&self) -> Result<u64>

Length of the file in bytes. See FileHandle::len.

fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()>

Positioned read. See FileHandle::read_exact_at.

fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()>

Positioned write. See FileHandle::write_all_at.

fn set_len(&self, new_len: u64) -> Result<()>

Truncate or extend the file. See FileHandle::set_len.

fn sync_data(&self, mode: SyncMode) -> Result<()>

See FileHandle::sync_data.

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

See FileHandle::sync_all.

fn is_empty(&self) -> Result<bool>

true iff the file has zero length.