Process

A Process object can be used to launch a subprocess, establish communication channels, and listen for events.

The Process class is not subclassable.

Class Methods

constructor(command, [options])

Creates a Process object that will launch the executable represented by command.

The optional options can contain the following values:

// Launches the Python executable to determine its current version
var options = {
    args: ["python", "--version"]
};

var process = new Process("/usr/bin/env", options);

process.onStdout(function(line) {
    console.log("Running " + line);
});

process.start();

Setting Up Standard IO for a Subprocess

The stdio constructor option is used to configure the behavior of the subprocess’s standard IO channels.

To directly configure each of the stdio channels, specify an array of three elements, each representing how to set up standard in, standard out, and standard error, respectively.

If an element is 'pipe', then a standard pipe will be set up for the channel. The pipe will be exposed through the resulting process’s stdio array property at the corresponding index as a WritableStream (stdin) or ReadableStream (stdout and stderr) object.

If an element is ignore, then no channel will be set up.

Passing a number for the element will treat the value as a file descriptor, which must already exist, and set up a channel reading or writing to that descriptor. Passing the values 0, 1, and 2 is effectively the same as setting up a pipe to the parent process’s standard in, standard out, and standard error.

For convenience, passing the values 'pipe' of 'ignore' instead of an array is effectively the same as passing an array of three of that value (such as ['pipe', 'pipe', 'pipe']).

Additionally, the value 'jsonrpc' may be passed instead of an array to set up the entire stdio suite to use JSON-RPC communication. If this is done, then the .request(), .notify(), .onRequest(), and .onNotify() methods of the resulting process object become available.

The stdio property of the resulting process will only contain a stream value for an element if that element was set up using pipe. In all other cases, the value of the stdio property’s element will be null and it is up to the caller to set up any additional communication.

By default, if no stdio option is passed, it is the same as passing the value ['pipe', 'pipe', 'pipe'].

Running Processes in a Shell

The shell constructor option allows the subprocess to be invoked within a shell, as if the user was running it themselves. If the value of the shell option is true, the subprocess will be invoked using /bin/sh. If it’s a string, the shell path specified by the string will be used.

Any arguments and environment set up for the subprocess will be passed to the shell, and then forwarded to the subprocess by the shell normally.

Warning: Executing arbitrary processes with arguments within a shell environment may be susceptible to shell injection attacks. Care should be taken to sanitize any input that is passed to the shell environment.

Properties

args

The arguments passed to the process (as an Array), including any specified when the Process was constructed.

This property is readonly.

command

The command used to launch the process.

This property is readonly.

cwd

The current working directory for the process. If not specified, the project directory will be used.

This property is readonly.

env

The environment variables (as an Object) set for the process, including any specified when the Process was constructed.

This property is readonly.

pid

The process identifier (PID) of the subprocess. If the process has not been started, this property will be zero.

This property is readonly.

stdio

An array of three elements, representing the standard in, standard out, and standard error communication channels, respectively. If the process was set up using pipes for the stdio elements, this array will contain corresponding WritableStream (stdin) or ReadableStream (stdout and stderr) objects at the appropriate index. Otherwise, the value at the given index will be null.

This property is readonly.

stdin

Returns the standard in channel from the receiver’s stdio array. This is the same as calling process.stdio[0]

This property is readonly.

stdout

Returns the standard out channel from the receiver’s stdio array. This is the same as calling process.stdio[1]

This property is readonly.

stderr

Returns the standard error channel from the receiver’s stdio array. This is the same as calling process.stdio[2]

This property is readonly.

Methods

onStdout(callback, [thisValue])

Adds an event listener that invokes the provided callback when a line is read from the subprocess’s stdout pipe. The callback will receive the line that was read as a string argument. Data from stdout will be read as UTF-8 text.

This method is effectively a convenience for getting the process’s stdout stream, acquiring a reader on it, and using that reader to read lines as UTF-8 text. While a handler is set, this effectively means the stdout reader is always locked.

If you need to access standard out data in a different way (such as by bytes), consider accessing the stdout property and configuring the stream directly.

If the process was not configured to use a pipe for standard out, this method will throw an Error.

The optional thisValue argument may be used to set what this is bound to when the callable is invoked. If omitted, this will be undefined.

This method returns a Disposable that can be used to unregister the listener.

onStderr(callback, [thisValue])

Adds an event listener that invokes the provided callback when a line is read from the subprocess’s stderr pipe. The callback will receive the line that was read as a string argument. Data from stderr will be read as UTF-8 text.

This method is effectively a convenience for getting the process’s stderr stream, acquiring a reader on it, and using that reader to read lines as UTF-8 text. While a handler is set, this effectively means the stderr reader is always locked.

If you need to access standard error data in a different way (such as by bytes), consider accessing the stderr property and configuring the stream directly.

If the process was not configured to use a pipe for standard error, this method will throw an Error.

The optional thisValue argument may be used to set what this is bound to when the callable is invoked. If omitted, this will be undefined.

This method returns a Disposable that can be used to unregister the listener.

onDidExit(callback, [thisValue])

Adds an event listener that invokes the provided callback when the subprocess terminates. The callback will receive as an argument the exit status (as a Number) of the subprocess.

The optional thisValue argument may be used to set what this is bound to when the callable is invoked. If omitted, this will be undefined.

This method returns a Disposable that can be used to unregister the listener.

start()

Starts the subprocess. If the process could not be launched because a valid executable was not found, this method will raise an Error. Likewise, if the process has already been launched, this method will also raise an Error.

signal(signal)

Sends a signal to the subprocess, specified by the signal argument. The signal may be a string (such as 'SIGINT', 'SIGTERM', or 'SIGHUP') or a number.

kill()

Attempts to terminate the subprocess using SIGKILL. If the subprocess successfully terminates, then event handlers registered using onDidExit() will be invoked just as if the subprocess terminated on its own.

terminate()

Attempts to terminate the subprocess using SIGTERM. If the subprocess successfully terminates, then event handlers registered using onDidExit() will be invoked just as if the subprocess terminated on its own.

notify(methodName, [params])

Sends a JSON-RPC notification with a provided method name and parameters to a process. The parameters object must be JSON-encodable.

If the process was not configured to use JSON-RPC communication, calling this method will throw an Error.

Example of sending a notification:

process.notify('didSave', {'file': 'foo.txt'});

request(methodName, [params])

Sends a JSON-RPC request with a provided method name and parameters to a process. The parameters object must be JSON-encodable.

This method returns a Promise object that will resolve or reject once the request has been handled by the process, or if communication fails or the connection is terminated prematurely.

The argument passed to any resolution (then()) hander will be a JSON-encodable object representing the result of the request.

The argument passed to any rejection (catch()) handler will be a ProcessMessage object.

If the process was not configured to use JSON-RPC communication, calling this method will immediately throw an Error.

Example of sending a request, and handling the response:

process.request('getNames', {'sort': 'alpha'}).then(function(reply) {
    console.log("Received response: " + reply.result);
});

onNotify(methodName, callback)

If the process was configured to use JSON-RPC (see the Standard I/O section, above), then this method will add an event handler for a provided notification method name.

The callback will be invoked when the extension receives a notification with a matching name from the process. The callback will be provided the ProcessMessage that was sent.

Example of handing a notification:

process.onNotify('didConnect', function(message) {
    console.log("The server successfully connected.");
});

If the process was not configured to use JSON-RPC communication, calling this method will throw an Error.

onRequest(methodName, callback)

If the process was configured to use JSON-RPC (see the Standard I/O section, above), then this method will add an event handler for a provided request method name.

The callback will be invoked when the extension receives a request with a matching name from the process. The callback will be provided the ProcessMessage that was sent.

The callback should return a reply to be transmitted back to the process (which may be any object that is JSON-encodable). If the reply is a Promise object, then the extension runtime will automatically wait until the promise is resolved before sending the response.

Should the promise be rejected, the runtime will attempt to form an reply from the rejection reason, returned as a JSON-RPC error message.

Example of handing a request, and returning a Promise object:

process.onRequest('getCount', function(request) {
    return Promise(function(resolve, reject) {
        resolve({'count': 10});
    });
});

If the process was not configured to use JSON-RPC communication, calling this method will throw an Error.