Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.3

0.7.3 / src / process / command / module.lucb

#==============================================================================================
#
#   command - A background child process with captured output
#
#   DESCRIPTION:
#       A command owns a background worker and its child process tree. Only byte storage crosses
#       the worker boundary; ARC objects stay on their owning thread.
#
#==============================================================================================

import collections
import thread
import utf8

struct CommandState:
    var cancelled: @bool
    var done: @bool
    var changed: @u64
    var lock: sync.Mutex
    var output: u8[]
    var used: usize
    var limit: usize
    var program: str
    var directory: str
    var arguments: c.str[]
    var argument_count: usize
    var environment: c.str[]
    var environment_count: usize
    var code: i64
    var failure: str

func command_text(text: str) -> str!:
    if not utf8.valid(text.bytes):
        error(failed, "a command argument must be UTF-8")
    for byte in text.bytes:
        if byte == 0:
            error(failed, "a command argument cannot contain NUL")
    with memory.heap:
        return try strings.copy(text)

# mark: The command ===========================================================================

## Launch without invoking a shell. `arguments` excludes the program name.
## Output merges stdout/stderr in observation order, bounded by output_limit.
## wait blocks until the program ends; poll with is_finished without blocking the UI;
## close cancels a program still running, then joins.
pub struct Command:
    var storage: CommandState*?
    var worker: thread.Handle?

    ## Start `program` with `arguments` in a background worker, capturing output up to `output_limit`.
    pub func init(program: str, arguments: const str[], directory: str = "", output_limit: usize = 1048576, environment: const str[]? = none) -> !:
        if program.length == 0 or output_limit < 1 or output_limit > 16777216:
            error(failed, "a command needs a program and an output limit in 1..16 MiB")
        let state = try new CommandState(limit = output_limit, code = -1) in memory.heap
        errdefer command_dispose(state)
        state.program = try command_text(program)
        state.directory = try command_text(directory)
        state.arguments = try new c.str[arguments.length] --- in memory.heap
        for index in 0..<arguments.length:
            state.arguments[index] = (c.str)(try command_text(arguments[index]))
            state.argument_count += 1
        if let overrides = environment:
            state.environment = try new c.str[overrides.length] --- in memory.heap
            for index in 0..<overrides.length:
                state.environment[index] = (c.str)(try command_text(overrides[index]))
                state.environment_count += 1
        let worker = try thread.spawn(command_entry, state, name = "command")
        self.storage = state
        self.worker = worker

    func state() -> CommandState*:
        return self.storage else trap("the command is closed")

    ## Whether the child has exited.
    pub func is_finished() -> bool:
        return self.state().done.load(.acquire)

    ## A counter that advances as captured output and status change.
    pub func revision() -> i64:
        return (i64)self.state().changed.load(.acquire)

    ## The child's exit code, or `none` while it is still running.
    pub func exit_code() -> i64?:
        if not self.is_finished():
            return none
        return self.state().code

    ## A stable UTF-8 snapshot. Invalid bytes and NUL are shown as replacement
    ## characters; split multibyte output is repaired by the next full snapshot.
    pub func output() -> interop.Owned[str]!:
        self.state().lock.lock()
        defer self.state().lock.unlock()
        with memory.heap:
            # a child that has printed nothing has no buffer yet
            if self.state().used == 0:
                return try interop.copy_text("")
            var text: collections.Buffer
            try text.reserve(self.state().used)
            defer text.destroy()
            var offset: usize = 0
            let bytes = self.state().output[..<self.state().used]
            while offset < bytes.length:
                if let scalar = utf8.decode(bytes, offset):
                    if (u32)scalar.scalar == 0:
                        try text.put_text("�")
                    else:
                        _ = try text.write(bytes[offset..<offset + scalar.width])
                    offset += scalar.width
                else:
                    try text.put_text("�")
                    offset += 1
            return try interop.copy_text(text.text())

    ## The captured standard error, as owned text.
    pub func error_message() -> interop.Owned[str]!:
        if not self.is_finished():
            return try interop.copy_text("")
        return try interop.copy_text(self.state().failure)

    ## Block until the program ends, then its exit code. A program that could not be
    ## started, outgrew its output limit or was cancelled is a failure.
    pub func wait() -> i64!:
        let state = self.state()
        if let worker = self.worker:
            self.worker = none
            worker.join() catch failure:
                trap("a command worker could not be joined")
        if state.code < 0:
            error(failed, state.failure if state.failure.length > 0 else "the command did not finish")
        return state.code

    ## Request cancellation of the child process tree.
    pub func cancel():
        if let state = self.storage:
            state.cancelled.store(true, .release)

    ## Wait for the worker, reap the child, and release resources.
    pub func close():
        if let worker = self.worker:
            self.cancel()
            worker.join() catch failure:
                trap("a command worker could not be joined")
            self.worker = none
        let state = self.storage else return
        self.storage = none
        command_dispose(state)

## The interop type of a Command.
pub let command_type: interop.Type[Command] = interop.Type[Command]("Command", Command.close, closeable = true)

func command_dispose(state: CommandState*):
    with memory.heap:
        if state.program.length > 0:
            strings.release(state.program)
        # Empty copied strings still own the trailing NUL.
        if (usize)state.directory.bytes.data != 0:
            strings.release(state.directory)
        # a list never allocated is not sliced, even empty
        if (usize)state.arguments.data != 0:
            for argument in state.arguments[..<state.argument_count]:
                strings.release((str)argument)
            free(state.arguments)
        if (usize)state.environment.data != 0:
            for override in state.environment[..<state.environment_count]:
                strings.release((str)override)
            free(state.environment)
        if state.output.length > 0:
            free(state.output)
        if state.failure.length > 0:
            strings.release(state.failure)
        free(state)

func command_entry(raw: void*?):
    let state = (CommandState*)(raw else return)
    let outcome = run_controlled((c.str)state.program, state.arguments, (c.str)state.directory, state.environment if state.environment_count > 0 else none, state, false) catch failure:
        state.failure = strings.copy(failure.message) catch ignored: recover ""
        state.done.store(true, .release)
        return
    state.code = (i64)outcome.0
    release_output(outcome.1)
    release_output(outcome.2)
    state.done.store(true, .release)

func command_append(state: CommandState*, bytes: const u8[]) -> !:
    state.lock.lock()
    defer state.lock.unlock()
    if bytes.length > state.limit - state.used:
        error(failed, "the command exceeded its output limit")
    let size = state.used + bytes.length
    if size > state.output.length:
        let capacity = math_min_size(state.limit, math_max_size(size, math_max_size(4096, state.output.length * 2)))
        if state.output.length == 0:
            state.output = try new u8[capacity] ---
        else:
            state.output = try memory.grow(state.output, capacity)
    memory.copy(state.output[state.used..], bytes, bytes.length)
    state.used = size
    _ = state.changed.add(1, .release)

func math_min_size(a: usize, b: usize) -> usize:
    return a if a < b else b

func math_max_size(a: usize, b: usize) -> usize:
    return a if a > b else b