Documentation
¶
Overview ¶
Package atomicfile provides durable, crash-safe atomic replacement of one file's contents (spec "docs/specs/long-running-command-supervision.md", "Manifests and durability": "Manifest updates use write-new, sync, and atomic replace semantics"). Replace writes a temporary file in the destination's own directory, syncs it, renames it over the destination, and syncs the containing directory where the platform supports it. The file that exists at the destination path, if any, remains fully readable and unmodified at every point before the rename commits.
This package is stdlib-only and has no dependency on the process package or any other part of this module, so it can be reused by any future durable-storage need without pulling in process-supervision domain types.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Replace ¶
Replace atomically overwrites (or creates) the file at path with data. perm sets the owner-only permission bits of the resulting file. The destination's directory must already exist; Replace never creates it and never writes anywhere outside that directory.
On success, path durably contains exactly data. On a failure at any stage through StageRename, path is left exactly as it was before the call (unchanged if it already existed, absent if it did not); no partial or temporary file is left behind. The one exception is a StageDirSync failure: by that point the rename has already committed, so path already contains data -- the failure only means the containing directory's own entry for that rename could not be confirmed durable (e.g. a crash before the next directory-metadata flush could, in principle, still lose the rename itself on some filesystems). Callers that must distinguish this case from an earlier-stage failure can inspect the returned *Error's Stage field.
Types ¶
type Error ¶
Error reports a failure at a specific Replace durability boundary, wrapping the underlying OS error so callers can errors.As to a *Error to inspect exactly which stage failed and errors.Is/Unwrap to inspect the underlying cause.
Source Files