RingoJS

Module ringo/worker

A Worker API based on the W3C Web Workers. Ringo offers "shared-nothing" workers for parallel execution and abstract JVM threads. A worker has its own private set of modules and an isolated scope, tied together in a single JVM thread. Each worker gets its own single-threaded event loop that behaves just like the event loop in a browser or in Node. Communication between workers uses the postMessage() method and the onmessage event handler. To improve performance Ringo keeps free workers in a queue and only allocates a new one if all existing workers are busy. Workers help to keep multi-threaded JavaScript free from any common threading pitfalls, like synchronization or locking.

See

Simple worker example
RingoJS: Workers and Multithreading

Class Worker

Instance Methods

Class WorkerPromise

Instance Methods


Worker (moduleId)

A Worker thread loosely modeled after the W3C Web Worker API.

The moduleId argument must be the fully resolved id of the module to load in the worker. In order to be able to send messages to the worker using the postMessage method the module must define (though not necessarily export) a onmessage function.

Workers operate on their own set of modules, so a new instance of the module will be created even if the module is already loaded in the current thread or is the same as the currently executing module. Thus, each worker operates in its private module environment, making concurrent programming much more predictable than with shared state multithreading.

Event listeners for callbacks from the worker can be registered by assigning them to the onmessage and onerror properties of the worker.

To free the worker's thread and other resources once the worker is no longer needed its terminate method should be called.

Parameters

String moduleId

the id of the module to load in the worker.


Worker.prototype. postMessage (data, [syncCallbacks])

Post a message to the worker. This enqueues the message in the worker's input queue and returns immediately. The worker thread will then pick up the message and pass it to its onmessage function.

The argument passed to onmessage is an object with a data property containing the message and a source property containing an object with postMessage and postError methods allowing the worker to post messages or report errors back to the original caller.

If syncCallbacks is true, callbacks from the worker will run on the worker's own thread instead of our local event loop thread. This allows callbacks to be delivered concurrently while the local thread is busy doing something else.

Note that in contrast to the Web Workers specification this worker implementation does not require JSON serialization of messages.

Parameters

Object data

the data to pass to the worker

Boolean [syncCallbacks]

flag that indicates whether callbacks from the worker should be called synchronously in the worker's own thread rather than in our own local event loop thread.


Worker.prototype. terminate ()

Release the worker, returning it to the engine's worker pool. Note that this does not terminate the worker thread, or remove any current or future scheduled tasks from its event loop.


WorkerPromise (moduleId, message, [syncCallbacks])

A Promise backed by a Worker.

This creates a new Worker with the given moduleId and calls its postMessage function with the message argument. The first message or error received back from the worker will be used to resolve the promise.

The worker is terminated immediately after it resolves the promise.

Parameters

String moduleId

the id of the module to load in the worker.

Object message

the message to post to the worker.

Boolean [syncCallbacks]

flag that indicates whether callbacks from the worker should be called synchronously in the worker's own thread rather than in our own local event loop thread.


WorkerPromise.prototype. then (callback, errback)

Registers callback and errback functions that will be invoked when the promise is resolved by the worker. See documentation for Promise.then().

Parameters

Function callback

called if the promise is resolved as fulfilled

Function errback

called if the promise is resolved as failed

Returns

Object

a new promise that resolves to the return value of the callback or errback when it is called.


WorkerPromise.prototype. wait (timeout)

Wait for the worker to resolve the promise. See documentation for Promise.wait().

Parameters

Number timeout

optional time in milliseconds to wait for. If timeout is undefined wait() blocks forever.

Returns

Object

the value if the promise is resolved as fulfilled

Throws

Object the error value if the promise is resolved as failed