Eio.Process
Managing child processes.
Example:
# Eio_main.run @@ fun env ->
let proc_mgr = Eio.Stdenv.process_mgr env in
Eio.Process.parse_out proc_mgr Eio.Buf_read.line ["echo"; "hello"]
type status = [
| exit_status
| `Stopped of int
Process was stopped (paused) by the given signal.
*) ]
type error =
| Executable_not_found of string
The requested executable does not exist.
*)| Child_error of exit_status
The process exited with an error status.
*)val err : error -> exn
err e
is Eio.Exn.create (E e)
val pp_args : string list Fmt.t
Formats a list of arguments, quoting any that might cause confusion to the reader.
This is intended for use in error messages and logging.
A process manager capable of spawning new processes.
val pid : _ t -> int
pid t
is the process ID of t
.
val await : _ t -> exit_status
await t
waits for process t
to exit and then reports the status.
val await_exn : ?is_success:(int -> bool) -> _ t -> unit
Like await
except an exception is raised if does not return a successful exit status.
val signal : _ t -> int -> unit
signal t i
sends the signal i
to process t
.
If the process has already exited then this does nothing (it will not signal a different process, even if the PID has been reused).
See Sys
for the signal numbers.
val spawn :
sw:Switch.t ->
[> 'tag mgr_ty ] Std.r ->
?cwd:Fs.dir_ty Path.t ->
?stdin:_ Flow.source ->
?stdout:_ Flow.sink ->
?stderr:_ Flow.sink ->
?env:string array ->
?executable:string ->
string list ->
'tag ty Std.r
spawn ~sw mgr args
creates a new child process that is connected to the switch sw
.
The child process will be sent Sys.sigkill
when the switch is released.
If the flows stdin
, stdout
and stderr
are not backed by file descriptors then this also creates pipes and spawns fibers to copy the data as necessary. If you need more control over file descriptors, see Eio_unix.Process
.
val run :
_ mgr ->
?cwd:_ Path.t ->
?stdin:_ Flow.source ->
?stdout:_ Flow.sink ->
?stderr:_ Flow.sink ->
?is_success:(int -> bool) ->
?env:string array ->
?executable:string ->
string list ->
unit
run
does spawn
followed by await_exn
, with the advantage that if the process fails then the error message includes the command that failed.
When is_success
is provided, it is called with the exit code to determine whether it indicates success or failure. Without is_success
, success requires the process to return an exit code of 0.
Note: If spawn
needed to create extra fibers to copy stdin
, etc, then it also waits for those to finish.
val parse_out :
_ mgr ->
'a Buf_read.parser ->
?cwd:_ Path.t ->
?stdin:_ Flow.source ->
?stderr:_ Flow.sink ->
?is_success:(int -> bool) ->
?env:string array ->
?executable:string ->
string list ->
'a
parse_out mgr parser args
runs args
and parses the child's stdout with parser
.
It also waits for the process to finish and checks its exit status is zero.
Note that parser
must consume the entire output of the process (like Buf_read.parse
).
To return all the output as a string, use Buf_read.take_all
as the parser.
This is a convenience wrapper around run
, and the optional arguments have the same meanings.
val pipe :
sw:Switch.t ->
_ mgr ->
[ Flow.source_ty | Resource.close_ty ] Std.r
* [ Flow.sink_ty | Resource.close_ty ] Std.r
pipe ~sw mgr
creates a pipe backed by the OS.
The flows can be used by spawn
without the need for extra fibers to copy the data. This can be used to connect multiple processes together.
module Pi : sig ... end