Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.1

0.7.1 / src / files / handles.lucb

#==============================================================================================
#
#   handles - Open files and their descriptors
#
#   DESCRIPTION:
#       A File over an OS descriptor, opened by policy (replace, create_new, append), with
#       read, write, seek, sync, truncate, metadata and permission operations, and the line,
#       text and byte reads a Luce program uses through `files.open`.
#
#==============================================================================================

## File opening policy. `replace` creates or truncates; `create_new` refuses an
## existing path; `create_new_read_write` also permits reads. `append` creates if
## needed and makes each write append atomically. `create_temporary` is
## `create_new_read_write` for a file nobody else should find: it goes away with
## its last handle, even when the process is killed. On POSIX its name is removed
## as soon as it is open; on Windows the system deletes it when the last handle
## closes (FILE_FLAG_DELETE_ON_CLOSE).
## Creation permissions are filtered by the process umask, never changed afterward.
pub enum OpenMode as u8:
    read = 0
    read_write = 1
    replace = 2
    create_new = 3
    append = 4
    create_new_read_write = 5
    create_temporary = 6

## Where a seek offset is measured from.
pub enum SeekOrigin as u8:
    start = 0
    current = 1
    end = 2

# mark: The open file =========================================================================

## One owned descriptor. The zero value is closed. Borrow through a pointer or an
## io interface; copying this value does not duplicate ownership or the OS handle.
## A copied value must not be independently closed. Calls on one handle require
## external synchronization. `close` reports errors; `destroy` is unwind cleanup.
## Luce sees a File as an object, opened by `files.open` and closed by `with` or `close()`.
pub struct File: io.Reader, io.Writer:
    var handle: i32?
    ## Bytes `read_line` and `read_text` fetched beyond what they answered; `read` and
    ## `seek` account for them.
    var ahead: readahead.ReadAhead

    ## Open a close-on-exec descriptor. Only the named creation modes create paths.
    pub static func open(path: c.str, mode: OpenMode = OpenMode.read, permissions: u32 = 420) -> File!:
        let temporary = mode == OpenMode.create_temporary
        let flags = try file_open_flags(OpenMode.create_new_read_write if temporary else mode, permissions)
        var fd = try open_descriptor(path, flags, permissions, temporary)
        while fd < 0 and c.errno() == c.interrupted:
            fd = try open_descriptor(path, flags, permissions, temporary)
        if fd < 0:
            error(classify_error(c.errno()), "the file could not be opened")
        var opened = File(handle = fd)
        if temporary:
            try forget_name(path, &opened)
        return opened

    ## Borrow the descriptor for OS interoperability; none after close. The caller
    ## must not close it or retain it past this owner's lifetime.
    pub func descriptor() -> i32?:
        return self.handle

    ## Query the open object, even after its pathname has been renamed or removed.
    pub func metadata() -> Metadata!:
        let descriptor = self.handle else error(io.closed, "the file is closed")
        return try metadata_descriptor(descriptor)

    ## Set the logical length without moving the file position. Shrinking
    ## discards the suffix; extension reads as zero bytes. Requires a writable
    ## descriptor. Reject negative lengths before calling the OS.
    pub func truncate(length: i64) -> !:
        let descriptor = self.handle else error(io.closed, "the file is closed")
        if length < 0:
            error(invalid_options, "a file length cannot be negative")
        var result = ftruncate(descriptor, length)
        while result != 0 and c.errno() == c.interrupted:
            result = ftruncate(descriptor, length)
        if result != 0:
            error(classify_error(c.errno()), "the file length could not be changed")

    ## Set permission and special mode bits on this opened object, independent
    ## of pathname changes. Umask is not applied. Host permission rules may
    ## reject or clear requested special bits; inspect metadata for the result.
    pub func set_permissions(permissions: u32) -> !:
        let descriptor = self.handle else error(io.closed, "the file is closed")
        if permissions > 4095:
            error(invalid_options, "file permissions must fit the Unix mode bits")
        if platform.windows:
            try windows_permissions(descriptor, permissions)
            return
        else:
            while true:
                let result = fchmod_macos(descriptor, (u16)permissions) if platform.macos else fchmod_linux(descriptor, permissions)
                if result == 0:
                    return
                if c.errno() != c.interrupted:
                    error(classify_error(c.errno()), "file permissions could not be changed")

    ## Set explicit access and modification times; creation/status-change times
    ## are not set by this operation. Validate nanoseconds before the OS call.
    ## The filesystem's range and timestamp resolution still apply.
    pub func set_times(accessed: FileTime, modified: FileTime) -> !:
        let descriptor = self.handle else error(io.closed, "the file is closed")
        if accessed.nanoseconds >= 1000000000 or modified.nanoseconds >= 1000000000:
            error(invalid_options, "a timestamp nanosecond fraction must be below one billion")
        if platform.windows:
            try windows_set_times(descriptor, accessed, modified)
            return
        else:
            let times: NativeFileTime[2] = [NativeFileTime(seconds = accessed.seconds, nanoseconds = (i64)accessed.nanoseconds),
                                            NativeFileTime(seconds = modified.seconds, nanoseconds = (i64)modified.nanoseconds)]
            var result = futimens(descriptor, &times[0])
            while result != 0 and c.errno() == c.interrupted:
                result = futimens(descriptor, &times[0])
            if result != 0:
                error(classify_error(c.errno()), "file timestamps could not be changed")

    ## Read some bytes, retrying interruption. Zero for nonempty storage is EOF;
    ## empty input makes no system call. The handle must be open even for empty I/O.
    pub func read(buffer: u8[]) -> usize!:
        let fd = self.handle else error(io.closed, "the file is closed")
        if self.ahead.count() > 0:
            return self.ahead.take(buffer)
        return try read_descriptor(fd, buffer)

    ## Write some bytes, retrying interruption. Use io.write_all for a full payload.
    ## Success confirms an OS write, not durable storage; call sync when required.
    pub func write(data: const u8[]) -> usize!:
        let fd = self.handle else error(io.closed, "the file is closed")
        if data.length == 0:
            return 0
        if self.ahead.count() > 0:
            # bytes read ahead were not answered yet: write where the reader stands
            _ = try self.seek(0, SeekOrigin.current)
        let count = data.length if data.length < transfer_limit else transfer_limit
        var written = c_write(fd, data.data, count)
        while written < 0 and c.errno() == c.interrupted:
            written = c_write(fd, data.data, count)
        if written < 0:
            error(classify_error(c.errno()), "the file could not be written")
        return (usize)written

    ## Seek a seekable file and return its resulting byte offset. Pipes and other
    ## unseekable descriptors report failure instead of pretending their size is zero.
    pub func seek(offset: i64, origin: SeekOrigin = SeekOrigin.start) -> i64!:
        let fd = self.handle else error(io.closed, "the file is closed")
        # the descriptor stands past the bytes read ahead; a relative seek starts before them
        let target = offset - (i64)self.ahead.count() if origin == SeekOrigin.current else offset
        var position = lseek(fd, target, (i32)origin)
        while position < 0 and c.errno() == c.interrupted:
            position = lseek(fd, target, (i32)origin)
        if position < 0:
            error(classify_error(c.errno()), "the file could not be positioned")
        self.ahead.clear()
        return position

    ## Request the OS's fsync durability boundary for this file; this does not sync
    ## a containing directory or promise persistence beyond the OS/device contract.
    pub func sync() -> !:
        let fd = self.handle else error(io.closed, "the file is closed")
        var result = fsync(fd)
        while result < 0 and c.errno() == c.interrupted:
            result = fsync(fd)
        if result < 0:
            error(classify_error(c.errno()), "the file could not be synchronized")

    # mark: Lines, text and bytes ============================================================

    ## The next line without its `\n` or `\r\n`; the unfinished last line at the end, and
    ## none after it. A line that is not UTF-8 is invalid_text. The view lasts until the
    ## next read.
    pub func read_line() -> str?!:
        var source = Descriptor(handle = self.handle else error(io.closed, "the file is closed"))
        return try self.ahead.line(&source)

    ## Up to `maximum` bytes, or all the rest with a negative maximum; empty at the end. The
    ## view lasts until the next read.
    pub func read_bytes(maximum: i64 = -1) -> const u8[]!:
        var source = Descriptor(handle = self.handle else error(io.closed, "the file is closed"))
        return try self.ahead.bytes(&source, read_limit(maximum), true)

    ## Up to `maximum` bytes as text, or all the rest with a negative maximum, ending on a
    ## whole character; empty at the end. Text that is not UTF-8 is invalid_text.
    pub func read_text(maximum: i64 = -1) -> str!:
        var source = Descriptor(handle = self.handle else error(io.closed, "the file is closed"))
        return try self.ahead.text(&source, read_limit(maximum), true)

    ## Write all of `data`.
    pub func write_bytes(data: const u8[]) -> !:
        try io.write_all(&self, data)

    ## Write all of `text`.
    pub func write_text(text: str) -> !:
        try io.write_all(&self, text.bytes)

    ## Consume ownership before closing, so repeated calls on this value are safe
    ## even after failure. Never retry close: a reused descriptor may belong to
    ## another thread. A reported failure must not be retried using descriptor().
    pub func close() -> !:
        let fd = self.handle else return
        self.handle = none
        self.ahead.release()
        if close(fd) != 0:
            error(classify_error(c.errno()), "the file could not be closed")

    ## Best-effort cleanup while unwinding another error. Use close explicitly on
    ## the successful path when delayed close errors must be reported to the caller.
    pub func destroy():
        self.close() catch failure:
            _ = failure

## Open `path` as a File object for Luce: `files.open("notes.txt")` reads, and a mode
## such as `files.OpenMode.replace` or `.append` writes. It closes with `with` or `close()`.
## Base programs use `File.open`, which answers the File as a value.
pub func open(path: c.str, mode: OpenMode = OpenMode.read, permissions: u32 = 420) -> interop.Reference[File]!:
    var reservation = try interop.Reservation[File](file_type)
    errdefer reservation.cancel()
    var opened = try File.open(path, mode, permissions)
    let native = new File(handle = opened.handle) catch failure:
        opened.destroy()
        error(failure.code, failure.message)
    return reservation.publish(native)

## The interop type of an open file.
pub let file_type: interop.Type[File] = interop.Type[File]("File", File.destroy, closeable = true)

## The text read is not valid UTF-8.
pub let invalid_text: ErrorCode = readahead.invalid_text

## A descriptor read directly, under the file's read-ahead bytes.
struct Descriptor: io.Reader:
    var handle: i32

    func read(buffer: u8[]) -> usize!:
        return try read_descriptor(self.handle, buffer)

## Read some bytes, retrying interruption; zero at the end.
func read_descriptor(fd: i32, buffer: u8[]) -> usize!:
    if buffer.length == 0:
        return 0
    let count = buffer.length if buffer.length < transfer_limit else transfer_limit
    var received = c_read(fd, buffer.data, count)
    while received < 0 and c.errno() == c.interrupted:
        received = c_read(fd, buffer.data, count)
    if received < 0:
        error(classify_error(c.errno()), "the file could not be read")
    return (usize)received

## A Luce read maximum: a negative one is everything.
func read_limit(maximum: i64) -> usize:
    return ~(usize)0 if maximum < 0 else (usize)maximum

func classify_error(number: i32) -> ErrorCode:
    if number == 2:
        return missing
    if number == 1 or number == 13:
        return permission_denied
    if number == 17:
        return already_exists
    if number == 28:
        return no_space
    if number == 20:
        return not_directory
    if number == 21:
        return is_directory
    if number == 30:
        return read_only_filesystem
    # the UCRT numbers its errors its own way: `ENOTEMPTY` 41, `ENAMETOOLONG` 38, no `ELOOP`
    if number == (66 if platform.macos else (41 if platform.windows else 39)):
        return not_empty
    if number == 18:
        return cross_device
    if number == (62 if platform.macos else 40) and not platform.windows:
        return symlink_loop
    if number == (63 if platform.macos else (38 if platform.windows else 36)):
        return name_too_long
    if number == would_block_errno:
        return would_block
    return failed

## Shared mode validation for path-based and directory-relative file opening.
func open_descriptor(path: c.str, flags: i32, permissions: u32, temporary: bool = false) -> i32!:
    if platform.windows:
        return try windows_open(path, flags, permissions, delete_on_close = temporary)
    else:
        return posix_open(path, flags, permissions)

## A temporary file's name goes once it is open (POSIX); Windows deletes it when
## its last handle closes, so the name stays until then.
func forget_name(path: c.str, opened: File*) -> !:
    if platform.windows:
        return
    else:
        remove_file(path) catch failure:
            opened.destroy()
            error(failure.code, failure.message)

func file_open_flags(mode: OpenMode, permissions: u32) -> i32!:
    if permissions > 4095:
        error(invalid_options, "file permissions must fit the Unix mode bits")
    var flags = close_on_exec
    if platform.windows:
        flags |= 32768
    if mode == OpenMode.read:
        flags |= read_only_flag
    elif mode == OpenMode.read_write:
        flags |= read_write_flag
    elif mode == OpenMode.replace:
        flags |= write_only | create | truncate
    elif mode == OpenMode.create_new or mode == OpenMode.create_new_read_write:
        flags |= create | exclusive_flag | (read_write_flag if mode == OpenMode.create_new_read_write else write_only)
    elif mode == OpenMode.append:
        flags |= write_only | create | append_flag
    elif mode != OpenMode.read:
        error(invalid_options, "unknown file opening mode")
    return flags