dymokomi/luce-std
Source of release 0.7.1
0.7.1 / src / files / temporary.lucb
#==============================================================================================
#
# temporary - Temporary files and atomic writes
#
# DESCRIPTION:
# A temporary file with an owned pathname, and write_atomic, which writes through a
# temporary sibling and renames it over the destination.
#
#==============================================================================================
# mark: The temporary file ====================================================================
## A temporary file and its owned pathname. The zero value is closed. Copying does
## not duplicate ownership. Borrow the object for I/O and serialize its use. The
## pathname lives on the process heap, so any thread may close or discard the file.
pub struct TemporaryFile: io.Reader, io.Writer:
var file: File
var name: str?
## Create an exclusive close-on-exec file in directory, with permissions
## filtered by umask. The OS supplies 128 random filename bits per attempt;
## collisions retry up to 128 times. Entropy acquisition may block. No
## existing entry is opened or overwritten, and failure retains no allocation.
pub static func create(directory: c.str, permissions: u32 = 384) -> TemporaryFile!:
let candidate = try paths.join((str)directory, ".luce-00000000000000000000000000000000")
defer candidate.release()
let name = try heap_text(candidate.value)
errdefer release_heap_text(name)
let digits = "0123456789abcdef"
let data = (u8*)name.bytes.data
let suffix = name.length - 32
var attempt: usize = 0
while attempt < 128:
var random: u8[16]
os.random_bytes(random) catch:
error(failed, "temporary filename randomness is unavailable")
for i in 0..<random.length:
data[suffix + i * 2] = digits.bytes[random[i] >> 4]
data[suffix + i * 2 + 1] = digits.bytes[random[i] & 15]
let file = File.open((c.str)name, OpenMode.create_new_read_write, permissions) catch failure:
if failure.code == already_exists:
attempt += 1
continue
error(failure.code, failure.message)
return TemporaryFile(file = file, name = name)
error(already_exists, "no unused temporary filename was found")
## Borrowed NUL-terminated pathname, valid until publication or cleanup.
pub func path() -> str:
return self.name else ""
## Read into `buffer`; the bytes read.
pub func read(buffer: u8[]) -> usize!:
return try self.file.read(buffer)
## Write `data`; the bytes written.
pub func write(data: const u8[]) -> usize!:
return try self.file.write(data)
## Move the read/write offset and report the new one.
pub func seek(offset: i64, origin: SeekOrigin = SeekOrigin.start) -> i64!:
return try self.file.seek(offset, origin)
## Flush the file's data to the device.
pub func sync() -> !:
try self.file.sync()
## Close successfully, then rename over destination. A close failure does
## not publish. A rename failure leaves the temporary pathname owned here
## for retry or discard. With replace=false, an existing destination is
## atomically refused. Success consumes ownership and invalidates path().
## With synchronize=true, flush the temporary data before publication and
## request write-through rename semantics on Windows. Other callers must sync
## data and the destination directory themselves when those guarantees matter.
pub func publish(destination: c.str, replace: bool = true, synchronize: bool = false) -> !:
let name = self.name else error(io.closed, "the temporary file has no owned pathname")
try self.file.close()
try rename((c.str)name, destination, replace, synchronize)
self.release_name()
func release_name():
if let name = self.name:
release_heap_text(name)
self.name = none
func remove_name() -> !:
let name = self.name else return
remove_file((c.str)name) catch failure:
if failure.code != missing:
error(failure.code, failure.message)
self.release_name()
## Close and remove the temporary entry. Report the first failure; still
## attempt removal after a close failure. A failed removal retains path()
## for retry. Repeated successful discard calls are safe.
pub func dispose() -> !:
self.file.close() catch failure:
self.remove_name() catch cleanup:
_ = cleanup
error(failure.code, failure.message)
try self.remove_name()
## Best-effort cleanup, releasing pathname memory even if the OS refuses
## removal. Such a refusal can leave a file behind; use discard to observe it.
pub func destroy():
self.dispose() catch failure:
_ = failure
self.release_name()
## A NUL-terminated copy of `text` on the process heap, which any thread may release.
func heap_text(text: str) -> str!:
with memory.heap:
return try strings.copy(text)
## Release a text `heap_text` made, from whichever thread holds it.
func release_heap_text(text: str):
with memory.heap:
strings.release(text)
# mark: Atomic writes =========================================================================
## Write through a temporary sibling, then atomically rename it over path. The
## replacement receives permissions filtered by umask; existing ownership, mode
## and extended metadata are not preserved. A final symlink is replaced itself.
## Parent directories must remain stable throughout the operation.
## With synchronize, fsync the file before publication and its parent afterward;
## this also requires read access to the parent directory. Optional published is
## reset on entry and set immediately after successful rename, before directory
## sync/close. A later failure can therefore report published=true. It must not
## overlap input or allocator state. Temporary cleanup on failure is best effort.
pub func write_atomic(path: c.str, data: const u8[], permissions: u32 = 420, synchronize: bool = false, published: bool*? = none) -> !:
if let flag = published:
*flag = false
var replacement = try Replacement.prepare(path, permissions, synchronize)
defer replacement.destroy()
try io.write_all(&replacement.temporary, data)
try replacement.finish(path, true, published)
## Shared ownership and publication ordering for atomic writes and file copies.
struct Replacement:
var parent: File
var temporary: TemporaryFile
var synchronize: bool
static func prepare(path: c.str, permissions: u32, synchronize: bool) -> Replacement!:
let parent_name = try strings.copy(paths.directory((str)path))
defer strings.release(parent_name)
var parent: File
errdefer parent.destroy()
if synchronize and not platform.windows:
parent = try File.open((c.str)parent_name)
let temporary = try TemporaryFile.create((c.str)parent_name, permissions)
return Replacement(parent = parent, temporary = temporary, synchronize = synchronize)
func finish(path: c.str, replace: bool, published: bool*?) -> !:
if self.synchronize:
try self.temporary.sync()
try self.temporary.publish(path, replace, self.synchronize)
if let flag = published:
*flag = true
if self.synchronize and not platform.windows:
try self.parent.sync()
try self.parent.close()
func destroy():
self.temporary.destroy()
self.parent.destroy()