The Process API

Plugins often want to interact with files, processes and network within the user's workspace. Because all Cloud9 plugins run in the browser and there is a network between the browser and the user's workspace we looked for an API that would work asynchronously. The Node.js APIs were an obvious match and so we based our Filesystem (fs), Process (proc) and Network (net) APIs on Node's fs, child_process and net modules.

Getting a reference to the plugin

The following examples show how to gain access to the proc API.

First, make sure to add "proc" to your list of plugins you depend on like so:

main.consumes = ["Plugin", "proc"];

And then get a reference to the plugin in the main function:

function main(options, imports, register) {
    var proc = imports.proc;

Process

For a complete reference to all the methods and events of the proc plugin check out the proc api reference.

The following table lists of all the methods supported by the proc plugin.

execFileExecutes an executable file in the workspace and buffers the stdout and stderr until the process is complete.
ptySpawns a child process in a PTY and returns a stream object.
spawnSpawns a child process and returns a process object complete with three stdio streams.
tmuxSpawns a child process in a TMUX session and returns a stream object.

The following examples show some of the most common use cases dealing with processes. The paths are always absolute or when specifying only a filename, the executable will be looked up in the PATH environment variable.

Executing a utility and fetching the output as a string:

proc.execFile("find", { 
    args: ["."],
    cwd: "/home/ubuntu/workspace"
}, function(err, stdout, stderr) {
    if (err) return console.error(err);

    console.log(stderr, stdout);
});

Executing a long running process and interacting using stderr and stdin

proc.spawn("python", {
    args: ["-i"]
}, function(err, process) {
    if (err) return console.error(err);

    var executed;
    process.stderr.on("data", function(chunk) {
        console.log(chunk);    

        if (chunk.indexOf(">>>") > -1) {
            if (!executed) 
                process.stdin.write("1+1\n");
            else 
                process.stdin.write("exit()\n");
            executed = true;
        }
    });
    process.on("exit", function(code) {
        console.log("Process Stopped"); 
    });
});

Long Running Processes

In some cases you want a process to run for a long time, surviving the session of the user. When the user's session ends, the vfs process in the user's workspace will kill all it's child processes - which include all the processes started with the API described above. If you don't want this to happen call unref() to detach your process from it's parent.

process.unref();