Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: WorkerClient

require(["esri/workers/WorkerClient"], function(WorkerClient) { /* code goes here */ });

Description

(Added at v3.9)
The WorkerClient is the primary entry point for interfacing with background Workers. You can use any valid and accessible worker script file. See importScripts for limitations on what can be used and assumed in a worker script.

Additionally, the worker script should expect messages to contain a msgId property and responses from that worker should contain the msgId of the message that they are responding to.

If you want the the addWorkerCallback or importScripts functions to work, then workers used here should use "esri/workers/mutableWorker" as the worker and build it up via this class's methods.

Samples

Search for samples that use this class.

Constructors

NameSummary
new WorkerClient(path, deferreds?)Creates a WorkerClient.

Properties

NameTypeSummary
returnDeferredsBooleanReturn Deferreds rather than Promises from postMessage.
workerWorkerReference to the actual HTML5 Worker instance.

Methods

NameReturn typeSummary
addWorkerCallback(module, name?)PromiseAdds a function to the worker that takes the worker's internal calls to postMessage and calls this function before sending the original message back to the main thread.
importScripts(paths)PromiseImport any script or function into the worker.
postMessage(msg, transfers?)PromisePosts a message to the worker.
setWorker(paths)NoneSets the worker that is used in the Worker Client.
terminate()NoneTerminates the worker and cancels all unresolved messages.
Constructor Details

new WorkerClient(path, deferreds?)

Creates a WorkerClient.
Parameters:
<String> path Required A require style string path to the worker script.
<Boolean> deferreds Optional Whether to return Deferreds rather than Promises from methods.
Property Details

<Boolean> returnDeferreds

Return Deferreds rather than Promises from postMessage.
Known values: true | false
Default value: false

<Worker> worker

Reference to the actual HTML5 Worker instance.
Method Details

addWorkerCallback(module, name?)

Adds a function to the worker that takes the worker's internal calls to postMessage and calls this function before sending the original message back to the main thread. The function takes the same inputs as postMessage. The function should act on these inputs. This obviously assumes some familiarity with the type of messages that a worker is passing. The function should be able to correctly interogate the message to determine if it is an appropiate message to act on. Additional calls to addWorkerCallback can be used to chain functions together in a "last in, first executed" fashion.

The script file whose path is passed in will be imported into the worker directly. It will not pass through the main thread and can not expect to have access to any objects in the main thread. This script is not required to have a message event handler or even postMessage calls back to the main thread. However, it must conform to the same limitations listed for importScripts. By default, the script should provide a function named main. If not then you must indicate the function via the name parameter. This function will be executed each time that the worker attempts to postMessage back to the main thread.

Note. If a callback or any callback in a series of chained callbacks returns false then postMessage is never executed, thus preventing the main UI thread from recieving the message.
Return type: Promise
Parameters:
<String> module Required A require path to a worker-compatible script containing the callback function.
<String> name Optional The name of the callback function. Defaults to "main". Does not need to be unique as it will be enclosured.

importScripts(paths)

Import any script or function into the worker. Please note the following conditions:
  • Script(s) / function(s) can ONLY include objects, classes, or methods available to Workers, plus whatever else has already been imported.
  • The imported items will be executed immediately and in the same order they are specified
  • The imported script won't be able to share or directly access any objects in the main thread or other workers
  • The worker can't access the DOM and thus can't use libraries which assume a browser environment
Return type: Promise
Parameters:
<String | String[]> paths Required An AMD require path to a script file to import. Multiple items may be passed in an array.

postMessage(msg, transfers?)

Posts a message to the worker.
Return type: Promise
Parameters:
<Object | Object[]> msg Required The data to post to the worker. If it is an array or a primitive, it will be put in an object as the 'data' member before being posted to the worker.
<Object[]> transfers Optional An optional array of transferable objects.

setWorker(paths)

Sets the worker that is used in the Worker Client. Please note the following conditions:
  • Script(s) / function(s) can ONLY include objects, classes, or methods available to Workers, plus whatever else has already been imported.
  • The imported items will be executed immediately and in the same order they are specified
  • The imported script won't be able to share or directly access any objects in the main thread or other workers
  • The worker can't access the DOM and thus can't use libraries which assume a browser environment
Generally, it is better to use the worker provided by 'esri/workers/mutableWorker', and use importScript to bring in other worker scripts and functions.
Parameters:
<String | String[]> paths Required An AMD require path to a script file to import.

terminate()

Terminates the worker and cancels all unresolved messages.