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.

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.