Async.Process
is for creating child processes of the current process, and
communicating with children via their stdin, stdout, and stderr. Async.Process
is
the Async analog of Core.Unix.create_process
and related functions.
env
specifies how to construct the environment that the child process will start
with. With `Extend [ x1,v1; x2,v2; ... ]
, the child's environment will be the same
as the parent's, except for xi
will have value vi
. With `Replace
, the only
variables in the child's environment will be the xi
. In either case, the child's
environment is established by first clearing environ
and then repeatedly calling
putenv
to establish the desired environment.
with_create_args
specifies the arguments used to create a child process.
create ~prog ~args ?working_dir ?env ()
uses fork
and exec
to create a child
process that runs the executable prog
with args
as arguments. It creates pipes to
communicate with the child process's stdin
, stdout
, and stderr
.
Unlike exec
, args
should not include prog
as the first argument.
If working_dir
is supplied, then the child process will chdir()
there before
calling exec()
.
env
specifies the environment of the child process.
create
returns Error
if it is unable to create the child process. This can happen
in any number of situations (unable to fork, unable to create the pipes, unable to cd
to working_dir
, unable to exec, etc.).
wait t
closes stdin t
and then begins collecting the output produced on t
's
stdout
and stderr
, continuing to collect output until t
terminates and the pipes
for stdout
and stderr
are closed. Usually when t
terminates, the pipes are
closed; however, t
could fork other processes which survive after t
terminates and
in turn keep the pipes open -- wait
will not become determined until both pipes are
closed in all descendant processes.
run
create
s a process and wait
s for it to complete. If the process exits with
an acceptable status, then run
returns its stdout. Acceptable statuses are zero,
and any nonzero values specified in accept_nonzero_exit
. If the process exits
unacceptably, then run
returns an error indicating what went wrong that includes
stdout and stderr.
Some care is taken so that an error displays nicely as a sexp---in particular, if the child's output can already be parsed as a sexp, then it will display as a sexp (rather than a sexp embedded in a string). Also, if the output isn't a sexp, it will be split on newlines into a list of strings, so that it displays on multiple lines rather than a single giant line with embedded "\n"'s.
run_lines
is like run
but returns the lines of stdout as a string list, using
String.split_lines
.
wait_stdout
and wait_stdout_lines
are alike run
and run_lines
but work from an
existing process instead of creating a new one.