AtomicWrite structv0.1.0

pub struct AtomicWrite {
    // private fields
}

Move-only. Commit syncs the contents and moves them onto the target; Abandon, or destroying the value, deletes the partial file and leaves the target as it was. An early return therefore leaves the old contents in place, which is the behavior that makes this worth using.

Associated functions

Begin

pub func Begin(
    allocator: Allocator,
    target: Path
) -> AtomicWrite ! IoError

Begins replacing target. The temporary is created in the target's own directory, which is what keeps the final rename atomic. The target need not exist; if it does, it is untouched until Commit.

Returns: a write in progress against a temporary file

Source

Methods

Stream

pub func Stream(self: &var AtomicWrite) -> FileStream

A stored writer over the partial file. Only for a value that must keep the stream, such as a buffered writer. Writing to the replacement for the duration of a call borrows the AtomicWrite itself, which is a Writer. The AtomicWrite must outlive the result and must not be moved while it exists. See FileStream.

Returns: a stream over the partial file, held by address

Source

Target

pub func Target(self: &AtomicWrite) -> Path

The name the finished file will take.

Returns: the path the contents will take when committed

Source

Commit

pub func Commit(
    self: &var AtomicWrite,
    allocator: Allocator
) -> ! IoError

Forces the contents to the device and moves them onto the target. The sync happens before the rename, so the final name can never point at contents that never arrived. Afterwards the target holds the new file and the temporary is gone; a reader that opened the name at any moment saw the old file or the new one. What this does not promise is that the directory entry survives a crash: that needs the containing directory synced too, which Windows does not offer, so the guarantee stops at atomicity on every system rather than being durable on some and pretending on the rest.

Returns: success when the target now holds the contents; on failure it still holds the old ones

Source

Abandon

pub func Abandon(
    self: &var AtomicWrite,
    allocator: Allocator
) -> ! IoError

Throws the partial file away and leaves the target as it was.

Returns: success when the temporary file was removed and the target left alone

Source

Release

pub func Release(self: &var AtomicWrite)

Gives the buffers back. The temporary's own destructor removes any partial file.

Source

Implements Writer

AtomicWrite conforms to Writer.

Write

pub func Write(
    self: &var AtomicWrite,
    bytes: char8[..]
) -> uint ! IoError

Writes into the partial file. Writing to a replacement is what the type is for, so it is a Writer itself rather than something a caller reaches a stream out of: let sink: &var Writer = replacement; borrows it, and nothing has to be kept alive beside it. One attempt, partial on purpose, exactly as the underlying file's is; WriteAll does the looping.

Returns: how much of it the file took

Source

Flush

pub func Flush(self: &var AtomicWrite) -> ! IoError

Flushes the partial file, which holds nothing back. Commit is what makes the contents durable, and it syncs before it renames.

Returns: what the file reported

Source

Destructor

func ~AtomicWrite(self: &var AtomicWrite)

Discards an uncommitted replacement, leaving the target untouched. This is the property that makes the type worth using: an early return or a failure part-way through writing leaves the old contents exactly where they were, with no partial file left behind.

Source

Related

WriteAtomically

pub func WriteAtomically(
    allocator: Allocator,
    target: Path,
    contents: char8[..]
) -> ! IoError

Replaces target with contents, atomically. The one-shot form of the type above, for the common case where the whole file is already in hand.

Source

Parameters

Returns: success when the target now holds exactly contents