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