dymokomi/luce-std
Source of release 0.7.4
0.7.4 / 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 func getdtablesize() -> i32
extern func syscall(number: i64, ...) -> i64
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
## Linux's close_range(2), which closes a range of descriptors in one call (5.9 and later).
let close_range_call: i64 = 436
## The most descriptors a child closes one by one when the system has no faster way.
let most_descriptors: i32 = 65536
## The process could not be started or managed.
pub let failed: ErrorCode = ErrorCode.package(8)
## How far a child closes descriptors (`close_inherited`): the soft open-files limit,
## at most `most_descriptors`. Read in the parent, before the fork.
func descriptor_limit() -> i32:
let limit = getdtablesize()
return limit if limit > 3 and limit < most_descriptors else most_descriptors
## In a forked child before exec: close every descriptor past the standard streams, so
## the program inherits none of this process's files and pipes. Without this, a child
## forked while another thread holds a pipe for its own child keeps that pipe's write end
## open, and whoever reads the pipe waits for the end of output until this child exits.
## Only close and syscall, which are async-signal-safe.
func close_inherited(limit: i32):
if platform.linux and syscall(close_range_call, (i64)3, (i64)4294967295, (i64)0) == 0:
return
var descriptor: i32 = 3
while descriptor < limit:
_ = close(descriptor)
descriptor += 1
## 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, and no other descriptor of this process reaches it (on POSIX it closes the
## rest before exec). 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 limit = descriptor_limit()
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])
close_inherited(limit)
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 limit = descriptor_limit()
let pid = fork()
if pid < 0:
free(argv)
error(failed, "run")
if pid == 0:
close_inherited(limit)
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)