/// Running another program to its end (ADR 0085). /// /// let out = command.run (command.new "/usr/bin/pdftotext" ["in.pdf", "-"]) /// /// - **No shell.** The program gets exactly `args`: spaces, quotes, `$` /// and `;` reach it as they are. /// - **Nothing inherited.** Its environment is exactly `env`; a program /// named without a `/` is looked up in the `PATH` of `env` (absolute /// entries only), never in the caller's. /// - **Bounded.** Output past `max_stdout` or `max_stderr` is read and /// dropped (the run says it was cut). At `timeout_ms` the program and /// everything it started (its process group) get SIGTERM, and SIGKILL /// `grace_ms` later. When it ends, what is left of its group is killed. /// - **Never blocking.** The calling actor waits; the scheduler's threads /// do not. If the actor is killed, the program is killed and reaped. /// /// A `Scratch` working directory is a fresh private directory: its inputs /// are written in first, the listed outputs are read back when the program /// ends (regular files only, at most `max_file` bytes each), and the /// directory is removed. A program that writes files thus needs no /// file-system access of the caller's. /// /// `commands` is the same as an effect, for code that should be tested /// without running anything: `natively` runs for real, `scripted` answers /// from a function. import std/bytes import std/list /// Where a program runs. pub type Workdir { /// The caller's working directory. Inherit /// This directory. , In(path: String) /// A fresh private directory holding `inputs`; `outputs` are read back. , Scratch(inputs: List<(String, Bytes)>, outputs: List, max_file: Int) } /// A program to run, with its arguments, environment and limits. pub type Command { Command( program: String , args: List , env: List<(String, String)> , workdir: Workdir , stdin: Bytes , max_stdout: Int , max_stderr: Int , timeout_ms: Int , grace_ms: Int ) } /// `program` with `args`: no environment, the caller's directory, no /// input, 16 MiB of stdout and 64 KiB of stderr kept, 30 seconds, then /// 2 more after SIGTERM. Change a field with `Command(..cmd, env: …)`. pub fn new :: program: String args: List -> Command { Command( program , args , [] , Inherit , bytes.empty () , 16777216 , 65536 , 30000 , 2000 ) } /// How a program ended. @derive Eq Show Debug pub type Exit { /// It exited with this status. Exited(code: Int) /// A signal ended it, not the timeout's. , Signalled(signal: Int) /// The timeout passed: the last signal it was sent (SIGTERM is 15, /// SIGKILL 9). , TimedOut(signal: Int) } /// A `Scratch` output, read back. pub type Collected { Found(name: String, data: Bytes) /// Past `max_file`: not read. , TooLarge(name: String, size: Int) /// Not there, or not a regular file. , Absent(name: String) } /// A program's end and what it wrote. pub type Output { Output( exit: Exit , stdout: Bytes , stderr: Bytes , stdout_cut: Bool , stderr_cut: Bool , files: List ) } /// Why a program did not run. @derive Eq Show Debug pub type Error { /// No such program (or working directory). NotFound(String) /// Not allowed to run it. , Denied(String) /// A NUL byte, an environment name with `=`, a scratch name with a `/`, /// a timeout that is not positive… , BadArgument(String) /// Anything else the system refused. , Failed(String) } /// Runs `cmd` to its end. pub fn run :: cmd: Command -> Result / { let ( kind , dir , inputs , outputs , max_file ) = match cmd.workdir { Inherit -> (0, "", [], [], 0) , In(path) -> (1, path, [], [], 0) , Scratch(inputs, outputs, max_file) -> (2, "", inputs, outputs, max_file) } let (names, values) = list.unzip cmd.env let (in_names, in_data) = list.unzip inputs let ran = run_raw cmd.program cmd.args names values kind dir in_names in_data outputs max_file cmd.stdin cmd.max_stdout cmd.max_stderr cmd.timeout_ms cmd.grace_ms match ran { Ok((exit, value, stdout, stderr, stdout_cut, stderr_cut, files)) -> Ok( Output( ended exit value , stdout , stderr , stdout_cut , stderr_cut , collected outputs files ) ) , Error((code, message)) -> Error(refused code message) } } /// Whether `out`'s program exited with status 0. pub fn succeeded :: out: Output -> Bool { out.exit == Exited(0) } /// Running programs, as an effect. pub effect commands { fn run_command :: cmd: Command -> Result } /// Runs `action`, its programs run for real. pub fn natively :: action: fn() -> a / -> a / { handle { action () } with { run_command cmd -> run cmd } } /// Runs `action`, each of its programs answered by `answer` instead of /// run (for tests). pub fn scripted :: answer: fn(Command) -> Result action: fn() -> a / -> a / { handle { action () } with { run_command cmd -> answer cmd } } fn ended :: kind: Int value: Int -> Exit { match kind { 0 -> Exited(value), 1 -> Signalled(value), _ -> TimedOut(value) } } fn refused :: code: Int message: String -> Error { match code { 0 -> NotFound(message) , 1 -> Denied(message) , 2 -> BadArgument(message) , _ -> Failed(message) } } fn collected :: names: List files: List<(Int, Int, Bytes)> -> List { list.map (list.zip names files) fn pair { let (name, (kind, size, data)) = pair match kind { 0 -> Found(name, data), 1 -> TooLarge(name, size), _ -> Absent(name) } } } @extern c "tl_command_run" fn run_raw :: program: String args: List env_names: List env_values: List dir_kind: Int dir: String in_names: List in_data: List out_names: List max_file: Int stdin: Bytes max_stdout: Int max_stderr: Int timeout_ms: Int grace_ms: Int -> Result< (Int, Int, Bytes, Bytes, Bool, Bool, List<(Int, Int, Bytes)>) , (Int, String) > /