Process

The Process API creates new processes that have their own window and Javascript VM. Processes created this way can communicate with each other. All processes terminate when the main process exits.

Every process can create a subprocess via Process.spawn, indicating the main Javascript module that the subprocess loads on startup. Process.spawn returns a Process instance used for communications with the subprocess.

Subprocesses have a similar handle to their parent process in Process.parent.

Because each process runs in its own Javascript VM, inter-process communications can only send and receive JSON objects and TypedArrays.

Messages are sent via process.postMessage, and received as “message” events on the process handle.

“exception”

Sent to parent processes when a child process throws an uncaught exception. Event listeners for "exception" events must be added first via process.addEventListener:

const child = Process.spawn('child_code.js');

child.addEventListener('exception', (event) => {
    console.log('Exception in child process', event.message);
    for (let frame of event.stacktrace) {
      console.log(frame);
    }
});

The event object passed to the event listener has these properties:

message string A string describing the exception.
stacktrace string[] The stack trace where the exception occurred.

“exit”

Sent to parent processes when a child process terminates. Event listeners for "exit" events must be added first via process.addEventListener:

const child = Process.spawn('child_code.js');

child.addEventListener('exit', (event) => {
    console.log('Child process terminated with status ' + event.status);
});

The event object passed to the event listener has these properties:

error string? A string describing the termination cause, in case of errors.
status number The exit code of the child process.

“log”

Sent to parent processes when a child process logs to the console. Event listeners for "log" events must be added first via process.addEventListener:

const child = Process.spawn('child_code.js');

child.addEventListener('log', (event) => {
    console.log('Child log: ' + event.message);
});

The event object passed to the event listener has these properties:

message string The string that was logged from the child process.
level string The log level corresponding to the console method used: “debug”, “log”, “info”, “warn” or “error”.

“message”

Sent to a process handle when the corresponding process posts a message to the current process via process.postMessage. Event listeners for message events must be added first via process.addEventListener.

To receive messages from a child process:

const child = Process.spawn('child_code.js');

child.addEventListener('message', (event) =>
  console.log('Message from the child: ' + event);
});

To receive messages from the parent process (in a child process):

Process.parent.addEventListener('message', (event) => {
  console.log('Message from the parent: ' + event);
});

The event object passed to the listeners is either a JSON object or a TypedArray, and has the value that was passed to process.postMessage in the other process.

Process.argsstring[]

The list of arguments passed to the process, via the command line or Process.spawn. Does not include the executable name nor arguments processed by Window.js internally.

This command line:

./windowjs main.js --disable-dev-keys -- hello world

With this Javascript content in main.js:

for (let arg of Process.args) {
  console.log('Argument: ' + arg);
}

Outputs the two arguments passed to the Javascript process:

Argument: hello
Argument: world

Process.cpusnumber

The number of logical CPUs in the current machine. This is usually the number of CPU cores, or twice that for cores with HyperThreading.

The CPU count gives an estimate of the maximum level of parallelism that can be obtained in the current machine when using multiple processes.

Process.parentProcess?

A handle to the parent process. This is only present in child processes, as the main process doesn’t have a parent.

Process.parent can be used to call addEventListener to receive messages from the parent process, or to call postMessage to send messages.

Process.exit()(number) => void

Terminates the current process immediately, with the given status code value.

If the current process is a child process then its parent process will receive an “exit” event in its handle for this process.

process.exit() is an abrupt termination that is appropriate for unrecoverable errors. Normal process termination should call window.close instead.

Process.spawn()(string, string[]?, Object?) => Process

spawn creates a new subprocess and returns a handle to the parent.

It takes one to three arguments:

module string The initial Javascript module to load in the child process.
args string[]? Optional list of string arguments to pass to the child process. They will be available in Process.args in the child process.
options Object? Optional object with options to spawn.

The options object contains parameters for the child process:

headless boolean Whether to run the child process without a window. This isn’t supported yet.
log boolean Whether output of the child process to stdout and stderr should appear in the parent’s stdout and stderr.

process.addEventListener()(string, Function) => void

addEventListener registers a listener callback to receive events in a given process handle. Subprocess have a process handle to their parent processes in Process.parent, and parent processes get handles to their subprocesses returned from Process.spawn.

Child processes receive only the message event.

Parent processes receive message, exit, exception and log events from their child processes.

To receive messages from a child process:

const child = Process.spawn('child_code.js');

child.addEventListener('message', (event) =>
  console.log('Message from the child: ' + event);
});

To receive messages from the parent process (in a child process):

Process.parent.addEventListener('message', (event) => {
  console.log('Message from the parent: ' + event);
});

process.close()() => void

Closes the handle to a child process and terminates it.

Note: child processes can’t close their parents via Process.parent.close().

process.postMessage()(Json | TypedArray) => void

Sends a message to the process represented by this handle.

The message can be a JSON object or a TypedArray, and is received as the single argument to the message event listener in the other process.

const child = Process.spawn('child_code.js');

child.postMessage({type: 'hello', target: 'world'});

The child process can receive the message with a listener:

Process.parent.addEventListener('message', (event) {
  if (event.type == 'hello') {
    console.log(`Received hello from parent to ${event.target}`);
  }
});
Process.parent.addEventListener('message', (event) => {
  console.log('Message from the parent: ' + event);
});

process.removeEventListener()(string, Function) => void

Removes an event listener that has previously been registered via process.addEventListener.