Previous  Up  Next

Module Process

module Process: sig .. end
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.
type t 
val pid : t -> Core.Std.Pid.t
val stdin : t -> Writer.t
val stdout : t -> Reader.t
val stderr : t -> Reader.t
type env = [ `Extend of (string * string) list | `Replace of (string * string) list ]
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.
type 'a with_create_args = ?working_dir:string ->
       ?env:env -> prog:string -> args:string list -> unit -> 'a
with_create_args specifies the arguments used to create a child process.
val create : t Core.Std.Or_error.t Import.Deferred.t with_create_args
create ~prog ~args ?working_dir ?env () uses fork+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.

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.).

module Output: sig .. end
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. 
val wait : t -> Output.t Import.Deferred.t
val run : string Core.Std.Or_error.t Import.Deferred.t with_create_args
run creates a process and waits for it to complete. If the process exits with status zero, then run returns its stdout. Otherwise, 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.
val sexp_of_t : t -> Sexplib.Sexp.t
val env_of_sexp : Sexplib.Sexp.t -> env
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.
val __env_of_sexp__ : Sexplib.Sexp.t -> env
val sexp_of_env : env -> Sexplib.Sexp.t

with_create_args specifies the arguments used to create a child process.

create ~prog ~args ?working_dir ?env () uses fork+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.

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. As usual, other async jobs can run before the deferred returned by wait becomes determined.

run creates a process and waits for it to complete. If the process exits with status zero, then run returns its stdout. Otherwise, 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.