Source src/silo:std.effects.process

1##! Process effect — spawn, wait on, kill, and pipe child processes.
2##!
3##! Sub-effect of `IO`. `Child` handles and byte payloads are carried
4##! as `AnyUInt` and `Bytes` placeholders; richer
5##! `Command` / `Output` / `ExitStatus` / `ProcessError` records arrive
6##! with the host handler.
7##!
8##! The process-level free `:fn`s `process-args`, `process-exit`, and
9##! `process-env-get` read process-wide state and do not require the
10##! `+Process` effect. Child-process operations (`.spawn-process`,
11##! `.wait`, `.kill`, …) are still declaration-only.
12
13:use
14  :open core AnyInt AnyUInt Bytes Never Option Str Unit Result Vec
15  :open effects.io IO
16:end
17
18# si[impl effect.process.decl]
19## Process effect — spawn, wait, kill, and pipe data through child
20## processes. Handles are carried as `AnyUInt` identifiers in this
21## placeholder decl.
22:effect(pub) Process IO
23  # si[impl effect.process.spawn-process]
24  ## Spawn a new child process from a program path and return its handle.
25  .spawn-process ( Str -> (Result AnyUInt Str) )
26  # si[impl effect.process.wait]
27  ## Wait for a child process to exit; returns the numeric exit code.
28  .wait ( AnyUInt -> (Result AnyInt Str) )
29  # si[impl effect.process.kill]
30  ## Signal a child process to terminate.
31  .kill ( AnyUInt -> (Result Unit Str) )
32  # si[impl effect.process.run]
33  ## Convenience: spawn, wait, and collect the child's stdout.
34  .run ( Str -> (Result Bytes Str) )
35  # si[impl effect.process.child-stdin-write]
36  ## Write bytes to the child's stdin pipe.
37  .child-stdin-write ( Bytes AnyUInt -> (Result Unit Str) )
38  # si[impl effect.process.child-stdin-close]
39  ## Close the child's stdin pipe (EOF).
40  .child-stdin-close ( AnyUInt -> )
41  # si[impl effect.process.child-stdout-read]
42  ## Read up to `n` bytes from the child's stdout pipe.
43  .child-stdout-read ( AnyInt AnyUInt -> (Result Bytes Str) )
44  # si[impl effect.process.child-stderr-read]
45  ## Read up to `n` bytes from the child's stderr pipe.
46  .child-stderr-read ( AnyInt AnyUInt -> (Result Bytes Str) )
47:end
48
49# si[impl effect.process.args]
50## Returns the program's command-line arguments as a `(Vec Str)`.
51## Wraps `std::env::args`.
52@host
53:fn(pub) process-args ( -> (Vec Str) ) :end
54
55# si[impl effect.process.exit]
56## Terminates the process with the given exit code; never returns.
57## Wraps `std::process::exit(code as i32)`.
58@host
59:fn(pub) process-exit ( AnyInt -> Never ) :end
60
61# si[impl effect.process.env-get]
62## Returns the value of an environment variable, or `None` if unset.
63## Wraps `std::env::var(name).ok()`.
64@host
65:fn(pub) process-env-get ( Str -> (Option Str) ) :end