Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.0

0.7.0 / src / process / module.lucb

#==============================================================================================
#
#   process - Running a child process to completion
#
#   DESCRIPTION:
#       Run a program with arguments, capture its standard output and error or let it write
#       to ours, and return its exit status; the process's environment, working directory
#       and own exit.
#
#==============================================================================================

import c
import core
import interop
import memory
import owned
import strings
import windows_text
import platform
import os
extern func pipe(descriptors: i32*) -> i32
extern func fork() -> i32
extern func dup2(from_fd: i32, to_fd: i32) -> i32
extern func close(descriptor: i32) -> i32
extern func execvp(program: c.str, arguments: void*?*) -> i32
extern func _exit(code: i32) -> never
extern func waitpid(pid: i32, status: i32*, options: i32) -> i32
extern func kill(pid: i32, signal: i32) -> i32
extern func c_read as "read"(descriptor: i32, buffer: void*, count: usize) -> isize
extern func poll(descriptors: Poll*, count: u32, timeout: i32) -> i32
extern func fcntl(descriptor: i32, command: i32, ...) -> i32

extern struct Poll:
    descriptor: i32
    events: i16
    returned: i16

let poll_in: i16 = 1
let poll_hang_up: i16 = 16
let poll_error: i16 = 8
let set_flags: i32 = 4
## `O_NONBLOCK`: 4 on macOS, 2048 on Linux.
let non_blocking: i32 = 4 if platform.macos else 2048
let would_block: i32 = 35 if platform.macos else 11
## The process could not be started or managed.
pub let failed: ErrorCode = ErrorCode.package(8)

## A captured stream: bytes in the current allocator, grown as the program writes.
struct Capture:
    var descriptor: i32
    var data: u8[]
    var used: usize
    var open: bool

    func pull() -> !:
        if self.data.length - self.used < 256:
            if self.data.length == 0:
                self.data = try new u8[1024] ---
            else:
                self.data = try memory.grow(self.data, self.data.length * 2)
        let n = c_read(self.descriptor, self.data[self.used..].data, self.data.length - self.used)
        if n == 0:
            self.open = false
        elif n > 0:
            self.used += (usize)n
        elif c.errno() != c.interrupted and c.errno() != would_block:
            error(failed, "the program's output cannot be read")

    ## What was captured, as a text of its own; the capture's storage is given back.
    func take() -> str!:
        let text = try captured((str)self.data[..<self.used])
        self.drop()
        return text

    func drop():
        if self.data.length > 0:
            free(self.data)
            var empty: u8[]
            self.data = empty

## A captured text: a NUL-terminated copy, even when empty.
func captured(bytes: str) -> str!:
    return try strings.copy(bytes)

## Give back a captured text.
func release_output(text: str):
    strings.release(text)

# mark: Running a program =====================================================================

## What a program `run` waited for left behind.
pub struct Completed:
    ## The program's exit status, 0 to 255.
    pub let exit_code: i32
    ## What it wrote to its standard output.
    pub let output: str
    ## What it wrote to its standard error.
    pub let error_output: str

## Run `program` with `arguments`, wait for it, and answer its exit status and what it
## wrote to its standard output and error. The result owns the two texts: Luce copies
## them; a Base caller reads `.value` and calls `release()`. Standard input is the
## parent's. A capture failure terminates and reaps the child, then closes the pipes and
## releases the captures; waiting never depends on output we stopped reading. The child
## only uses async-signal-safe operations between `fork` and `exec`,
## so a parent with other threads is safe (ยง15.3).
## directory="" inherits the working directory. environment overrides selected
## inherited variables with NAME=value strings; none inherits everything unchanged.
## Duplicate names are rejected (case-insensitively on Windows). The parent must
## serialize mutations of its process-wide environment during process creation.
pub func run(program: c.str, arguments: const c.str[], directory: c.str = "", environment: const c.str[]? = none) -> interop.Owned[Completed]!:
    let finished = try run_controlled(program, arguments, directory, environment, none, false)
    var texts = new str[2] --- catch failure:
        release_output(finished.1)
        release_output(finished.2)
        error(failure.code, failure.message)
    texts[0] = finished.1
    texts[1] = finished.2
    let storage = try owned.adopt_texts(texts)
    return interop.Owned[Completed](Completed(exit_code = finished.0, output = finished.1, error_output = finished.2), storage.owner)

## Run `program` with `arguments` as `run` does, but writing to this process's standard
## output and error as it goes, which suits a child whose output is the user's to read
## (a test runner, a build step); wait for it and answer its exit status.
pub func call(program: c.str, arguments: const c.str[], directory: c.str = "", environment: const c.str[]? = none) -> i32!:
    let finished = try run_controlled(program, arguments, directory, environment, none, true)
    release_output(finished.1)
    release_output(finished.2)
    return finished.0

## `run`, `call` and `Command`'s child: with `inherit`, it writes to this process's
## standard streams and the texts answered are empty.
func run_controlled(program: c.str, arguments: const c.str[], directory: c.str, environment: const c.str[]?, control: CommandState*?, inherit: bool) -> (i32, str, str)!:
    if platform.windows:
        return try run_windows(program, arguments, directory, environment, control, inherit)
    else:
        let slot = environment_address()
        var selected: (c.str?)[]
        if let overrides = environment:
            selected = try environment_posix(overrides, *slot)
        defer release_storage(selected)
        let argv = try new void*?[arguments.length + 2] ---
        argv[0] = (void*)program
        var i: usize = 0
        while i < arguments.length:
            argv[i + 1] = (void*)arguments[i]
            i += 1
        argv[arguments.length + 1] = none
        if inherit:
            return try call_posix(program, argv, directory, selected, slot)
        var out_pipe: i32[2]
        var err_pipe: i32[2]
        if pipe((i32*)&out_pipe) != 0:
            free(argv)
            error(failed, "run")
        if pipe((i32*)&err_pipe) != 0:
            _ = close(out_pipe[0])
            _ = close(out_pipe[1])
            free(argv)
            error(failed, "run")
        let pid = fork()
        if pid < 0:
            _ = close(out_pipe[0])
            _ = close(out_pipe[1])
            _ = close(err_pipe[0])
            _ = close(err_pipe[1])
            free(argv)
            error(failed, "run")
        if pid == 0:
            if control != none:
                if setpgid(0, 0) != 0:
                    _exit(127)
                let input = open("/dev/null", 0)
                if input < 0 or dup2(input, 0) < 0:
                    _exit(127)
                if input > 2:
                    _ = close(input)
            _ = close(out_pipe[0])
            _ = close(err_pipe[0])
            if dup2(out_pipe[1], 1) < 0 or dup2(err_pipe[1], 2) < 0:
                _exit(127)
            _ = close(out_pipe[1])
            _ = close(err_pipe[1])
            if ((str)directory).length > 0 and chdir(directory) != 0:
                _exit(127)
            if selected.length > 0:
                *slot = selected.data
            _ = execvp(program, argv.data)
            _exit(127)
        if control != none:
            _ = setpgid(pid, pid)
        free(argv)
        _ = close(out_pipe[1])
        _ = close(err_pipe[1])
        var empty: u8[]
        var out = Capture(descriptor = out_pipe[0], data = empty, used = 0, open = true)
        var err = Capture(descriptor = err_pipe[0], data = empty, used = 0, open = true)
        defer _ = close(out_pipe[0])
        defer _ = close(err_pipe[0])
        defer out.drop()
        defer err.drop()
        var status: i32 = 0
        if let observer = control:
            status = try capture_command(pid, &out, &err, observer)
        else:
            try capture(pid, &out, &err)
            status = try wait_for(pid)
        if (status & 127) != 0:
            error(failed, "the program was stopped by a signal")
        let out_text = try out.take()
        let err_text = err.take() catch failure:
            release_output(out_text)
            error(failure.code, failure.message)
        return ((status >> 8) & 255, out_text, err_text)

## `call` on POSIX: the child keeps this process's standard streams; `argv` is freed.
func call_posix(program: c.str, argv: void*?[], directory: c.str, selected: (c.str?)[], slot: (c.str?)**) -> (i32, str, str)!:
    let pid = fork()
    if pid < 0:
        free(argv)
        error(failed, "run")
    if pid == 0:
        if ((str)directory).length > 0 and chdir(directory) != 0:
            _exit(127)
        if selected.length > 0:
            *slot = selected.data
        _ = execvp(program, argv.data)
        _exit(127)
    free(argv)
    let status = try wait_for(pid)
    if (status & 127) != 0:
        error(failed, "the program was stopped by a signal")
    let out_text = try captured("")
    let err_text = captured("") catch failure:
        release_output(out_text)
        error(failure.code, failure.message)
    return ((status >> 8) & 255, out_text, err_text)

## Optional child state has no allocation when inherited unchanged.
func release_storage[T](storage: T[]):
    if storage.length > 0:
        free(storage)

## Only capture owns the cancellation path. Once it returns, result allocation can fail
## after wait_for has reaped the child; that must never signal a potentially reused pid.
func capture(pid: i32, out: Capture*, err: Capture*) -> !:
    errdefer terminate(pid)
    if fcntl(out.descriptor, set_flags, non_blocking) < 0 or fcntl(err.descriptor, set_flags, non_blocking) < 0:
        error(failed, "the program's output cannot be read")
    while out.open or err.open:
        var watched: Poll[2] = ---
        watched[0] = Poll(descriptor = out.descriptor if out.open else -1, events = poll_in, returned = 0)
        watched[1] = Poll(descriptor = err.descriptor if err.open else -1, events = poll_in, returned = 0)
        if poll((Poll*)&watched, 2, -1) < 0:
            if c.errno() == c.interrupted:
                continue
            error(failed, "the program's output cannot be read")
        if out.open and (watched[0].returned & (poll_in | poll_hang_up | poll_error)) != 0:
            try out.pull()
        if err.open and (watched[1].returned & (poll_in | poll_hang_up | poll_error)) != 0:
            try err.pull()

## The child's wait status, waited for again when a signal interrupts the wait.
func wait_for(pid: i32) -> i32!:
    var status: i32 = 0
    while waitpid(pid, &status, 0) < 0:
        if c.errno() != c.interrupted:
            error(failed, "run")
    return status

## A child may ignore a broken pipe or SIGTERM. SIGKILL stops its writes before waiting.
func terminate(pid: i32):
    _ = kill(pid, 9)
    var status: i32 = 0
    while waitpid(pid, &status, 0) < 0 and c.errno() == c.interrupted:
        continue

## Terminate the current process with `code`.
pub func exit(code: i32) -> never:
    core.exit(code)