Struct Writer 

pub struct Writer {
    file: Option<JournalFile>,
    header_written: bool,
}

Append-only writer for a journal file with compaction support.

Fields

file: Option<JournalFile>

None only transiently while append’s blocking operation owns the handle, or permanently after that operation panicked, or after compact renamed the journal but could not reopen it (in which case further ops error).

header_written: bool

Whether the header has been written. Left false while the file is empty, so an unused journal stays a zero-byte file.

Implementations

impl Writer

pub async fn open(path: PathBuf) -> Result<Self>

Opens (or creates) the journal file for appending.

Concurrency

Only one Writer should hold a given journal file open at a time. This method does not acquire an advisory file lock; callers that need multi-process mutual exclusion must implement their own locking (e.g. a companion .lock file) outside this crate.

Errors

Returns an I/O error if the file cannot be opened, or if it starts with a header naming a format version this crate does not write.

pub async fn append(&mut self, buf: &mut Vec<u8>) -> Result<()>

Appends framed journal bytes and fsyncs, writing the file header first if this is the first data written to the file.

Moves buf’s contents to the blocking pool without a copy and restores them into buf afterwards, on success and on a write error alike, so the caller can refill and reuse the same allocation; a steady stream of flushes therefore allocates nothing once warm. The bytes are produced by encode_frames.

A write or sync failure partway through is rolled back to the file’s pre-append length, so the file always ends at a clean boundary and a retried append never layers new bytes after a torn write.

Errors

Returns an I/O error if the write or sync fails.

pub async fn compact(&mut self, snapshot: Vec<u8>) -> Result<()>

Atomically replaces the journal with snapshot, a freshly framed encoding of the whole session state.

Writes the header (unless snapshot is empty) followed by the snapshot to a temp path, fsyncs it, then renames it over the existing journal. A crash during compaction never corrupts the existing file. Produce snapshot by framing snapshot_ops with encode_frames.

Errors

Returns an I/O error if any file operation fails. A failure writing or syncing the temp file leaves the writer exactly as usable as before this call, since its existing handle is never touched until the rename below succeeds. A failure reopening the file after that rename is the one case that leaves the writer without a handle: see file.

fn take_file(&mut self) -> Result<JournalFile>

Takes the file handle for a blocking operation, erroring if a previous operation left the writer without one (only possible after a panic, or after compact failed to reopen the file post-compaction).