dojo.require("esri.workers.WorkerClient");
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
Properties
Methods
Constructor Details
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
Return Deferreds rather than Promises from
postMessage.
Known values: true | false
Default value: false
Reference to the actual HTML5 Worker instance.
Method Details
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.
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. |
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
Parameters:
<String | String[] > paths |
Required |
An AMD require path to a script file to import. Multiple items may be passed in an array. |
Posts a message to the worker.
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. |
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. |
Terminates the worker and cancels all unresolved messages.