Documentation
¶
Overview ¶
Package dirpublish replaces a directory whole: the new tree is built in a staging directory beside the destination and published by rename, so a reader finds either the previous tree or the new one, never a mix, and two writers of the same destination at once never share a half-built tree. The last to publish wins, and what it leaves is whole.
It is for a directory more than one process may write at the same time, such as the runner home's plan and release directories, which a CLI run and a desktop run started together both write. CreateFile and ReplaceFile do the same for a single file (file.go).
Index ¶
- func CreateFile(dest string, data []byte, perm fs.FileMode) (created bool, err error)
- func InFlight(e fs.DirEntry) bool
- func Replace(dest string, fill func(dir string) error) error
- func ReplaceFile(dest string, data []byte, perm fs.FileMode) error
- func ReplaceUnless(dest string, fill func(dir string) error, settled func() bool) (published bool, err error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateFile ¶
CreateFile puts data at dest only if nothing is there: it is written to a staging file beside dest, private to this writer, and hard-linked into place, which fails while dest exists, so a file another writer (or a person) put there meanwhile is never replaced and a reader never sees it partly written. created is false when dest was already there; either way the staging file is removed.
On a filesystem without hard links (FAT, some network shares) dest is created exclusively and written in place instead: still never replacing a file that is there, but a reader in the instant of the write can find it partial, as before this package wrote files.
func InFlight ¶
InFlight reports whether a directory entry is a staging or retired sibling (a directory, or a file CreateFile or ReplaceFile is staging) a writer may still be using (younger than an abandoned one): something a sweep of the parent directory must leave alone, or it can delete a tree from under the rename that publishes it.
func Replace ¶
Replace builds a new tree for dest with fill, in a staging directory beside dest that is this writer's alone, and publishes it in place of whatever is at dest: the last writer to publish wins. If fill fails, or the tree cannot be published, the staging directory is removed and dest is left as it was; fill's own error comes back unwrapped.
func ReplaceFile ¶
ReplaceFile puts data at dest in place of whatever is there: it is written to a staging file beside dest and renamed over it, so a reader finds the previous file or the new one whole. The last writer wins. When dest is a symbolic link, the file it points to is the one replaced, and an existing file keeps its permission bits (perm applies to a new one), as a write in place would have left them. A rename refused because a reader briefly holds dest open (Windows) is retried for about a second.
Windows also refuses to replace a file by rename for a while after it was written, when a scanner such as Defender has mapped it, though the file can still be renamed away. When the rename over dest is refused, dest is retired aside and the new file renamed into the name it leaves free, as Replace does for a directory; a reader in between finds no file.
func ReplaceUnless ¶
func ReplaceUnless(dest string, fill func(dir string) error, settled func() bool) (published bool, err error)
ReplaceUnless is Replace for a destination whose content is fixed by its name, such as a release directory named for its digest: settled, called before each attempt to put the new tree in place, reports whether dest already holds a whole tree this writer would only duplicate (another writer finished first). Then the staged tree is discarded and dest, with whatever its writer has since put inside it, is left alone; published is false. A nil settled never settles.
Types ¶
This section is empty.