WorkerThread Object

The WorkerThread object is used to manage a worker thread. For more details, see Worker Thread API.

The WorkerThread Object contains the following API elements.

Methods

The WorkerThread object contains the following methods.

addEventListener

Event Handlers can be registered using addEventListener() method on the worker Objects and once registered messages and errors from a worker thread can be received in parent thread.

Due to the asynchronous parallel execution nature of the newly created worker thread, which starts executing the worker JS script upon creation. It is always advisable to immediately register the ‘message’ event handler as well as ‘error’ event handler on the worker handle in parent thread context after creation of the worker. This ensures that posted messages or errors in worker scope are handed over to the respective ‘message’ or ‘error’ event listeners in parent scope.

message event handler:

Registered "message" event handler will be invoked in Parent or Worker thread whenever postMessage() is called from inner scope of Worker or Parent thread.

In parent scope, call to worker.postmessage() invokes message event handler registered using addEventListener() in Workers inner Scope.
In worker scope, call to postmessage() invokes message event handler registered using addEventListener() in Parents scope.

Multiple message event handlers can also be registered in parent scope and workers inner scope and all the registered event handlers will be invoked in the registered order whenever a postMessage() is called.

error event listener:

The error handler can also be registered using addEventListener () in parent thread scope on worker object and as well as in worker thread’s inner scope, which will be invoked whenever an unhandled exception occurs in workers inner scope.

The error event object has the following three fields: message, filename, lineno.

If an error event handler is registered in worker inner scope and in parent scope on the worker object, then both the event handlers are invoked in case of an unhandled exception in worker’s inner scope.

Multiple error event handlers can be registered on the worker handle in parent scope and also in worker threads inner scope. Registered error event handlers will be invoked in the order of registration in case of unhandled exception in worker thread.

If an error event handler is not registered for a worker in parent scope or in worker inner scope and if an unhandled exception arises in worker’s inner scope then worker halts execution and no error info is propagated.

The error event handlers work for unhandled exceptions occurring only in worker scope but not in main parent scope.

Syntax

Parent Scope:

worker.addEventListener(key,listener)

Worker Scope:

addEventListener(key,listener)  
self.addEventListener(key,listener)  
this.addEventListener(key, listener)

Input Parameters

Parameter	Description
key	message: When message event handler is being registered. error: When error event handler is being registered.
listener	The listener parameter indicates the event listener function to be added.

Example

//Parent Scope
var worker = new voltmx.worker.WorkerThread("worker1.js");

var evtMessageHandler_1 = function(event) {
    voltmx.print("Parent Scope : In message handler 1");
};
var evtErrorHandler_1 = function(event) {
    voltmx.print("Parent Scope: In error handler 1");

    voltmx.print('ERROR: Line ' + event.lineno + ' in ' + event.filename + ': ' + event.message);
};


//"message" event handler:


//Parent Scope
var worker = new voltmx.worker.WorkerThread("worker1.js");

var evtMessageHandler\_1 = function(event) {
    voltmx.print("Parent Scope : In message handler 1");
};

var evtMessageHandler\_2 = function(event) {
    voltmx.print("Parent Scope : In message handler 2");
};

worker.addEventListener("message", evtMessageHandler\_1);
worker.addEventListener("message", evtMessageHandler\_2);



//Worker Scope
var evtMessageHandler\_1 = function(event) {
    voltmx.print("Worker Scope : In message handler 1");
};

self.addEventListener("message", evtMessageHandler\_1);
//or
this.addEventListener("message", evtMessageHandler\_1);
//or
addEventListener("message", evtMessageHandler\_1);


//"error" event listener:


//Parent Scope
var worker = new voltmx.worker.WorkerThread("worker1.js");

var evtErrorHandler\_1 = function (event) {
     voltmx.print("Parent Scope: In error handler 1");

voltmx.print('ERROR: Line ' + event.lineno + ' in ' + event.filename + ': ' + event.message);

};

var evtErrorHandler\_2 = function (event) {
     voltmx.print("Parent Scope: In error handler 2");
};

//
worker.addEventListener("error", evtErrorHandler\_1);
worker.addEventListener("error", evtErrorHandler\_2);



//Worker Scope
var evtErrorHandler\_1 = function (event) {
     voltmx.print("Worker Scope: In error handler 1");
};


self.addEventListener("error", evtErrorHandler\_1);

//or
this.addEventListener("error", evtErrorHandler\_1);

//or
addEventListener("error", evtErrorHandler\_1);

Return Values

None

Exceptions

If no argument is given or if the number of arguments are less than two, it raises an exception and throws a “VoltMXError” JS Object with the following attributes:
```
errorCode: 3001.  
name: "WorkerThreadError".  
message: "addEventListener: MissingMandatoryParameter. Mandatory arguments missing"
```
If the first argument is not equal to “message” or “error” and if second argument is not a function object, it raises an exception and throws a “VoltMXError” JS Object with the following attributes:
```
errorCode: 3002.
name: “WorkerThreadError”.
message: “addEventListener: InvalidParameter. Invalid arguments”
```
In Worker scope if these exceptions are not handled and if an “error” event handler is registered in worker’s inner scope or/and in Parent scope for this worker object then it is invoked with an error event object and its message attribute set to following.

In case of exception 1)
message: “addEventListener: MissingMandatoryParameter . Mandatory arguments missing”
In case of exception 2)
message: “addEventListener: InvalidParameter. Invalid arguments”
In Parent(not a worker to some other parent) scope if these exceptions are not handled registered “error” event handler will not be invoked.

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see Scope.

close

Worker thread can be terminated from inner scope of the worker by invoking close(). The worker thread is killed immediately without an opportunity to complete its operations or clean up.

The tasks pending in the message queue and callbacks registered for network, timer APIs etc are discarded without wait until completion.

Syntax

Worker Scope:

close()  
self.close()  
this.close()

Input Parameters

None

Example


//worker init

//post a message to parent
self.postMessage("Hello from Worker");

//do some work

//terminate this worker from inner scope
self.close();

Return Values

None

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see Scope.

Limitations

As the worker threading model is mapped to underlying native threading models in native platforms, there can be some deviations from what specification says, this is due to technical limitations in the underlying platforms which include:

When close() is invoked in worker scope, and if worker is currently executing a large task, it might not immediately terminate, it will continue to execute the task to completion and then terminate.
When close () is invoked in worker scope, and if there are pending tasks waiting in the message queues for this worker to perform, some platforms might discard all the pending tasks without accepting them for execution and terminate, and on some platform all the pending tasks are executed to completion and then the worker terminates.
Hence it is to be noted that to achieve cross platform consistency, it is always advised that close() be invoked in worker scope once all the tasks in message queues are completed.

postMessage

postMessage() sends a JSON object or String message to the Parent/worker's scope by invoking respective registered "message" event handlers.

In Parent thread scope, call to worker.postMessage() invokes "message" event handler which is registered using addEventListener() in Workers inner Scope.
In Worker thread scope, call to postMessage() invokes "message" event handler which is registered using addEventListener() in Parents scope.

The JSON or string object passed to postMessage() is delivered to the registered "message" event handler. The "event" object "data" attribute will have the message passed: "event.data".

Adhering to the JSON standard, the JSON object passed to postMessage() API should be serializeble JSON without opaque object handles or function object handles.

Syntax

postMessage(<String> or <JSON>)

Parent Scope:

//JSON Object  
worker.postMessage({‘msg’ : ‘hello’})

//String  
worker.postMessage("messsage hello")

Worker Scope:

//JSON Object  
postMessage({‘msg’ : ‘hello’})

//String  
postMessage("messsage hello")

Input Parameters

Parameter	Description
String	For parent scope, here is an example: worker.`postMessage("messsage hello");` For worker scope, here is an example: `postMessage("messsage hello");`
JSON Object	For parent scope, here is an example: worker.`postMessage({'msg' : 'hello'});` For worker scope, here is an example: `postMessage({'msg' : 'hello'});`

Example

var worker = new voltmx.worker.WorkerThread("worker1.js");

// Parent scope:
//JSON Object
worker.postMessage({
    'msg': 'hello'
});

//String
worker.postMessage('message hello');

// Worker scope: 

//JSON Object
postMessage({
    'msg': 'hello'
});
//or
this.postMessage({
    'msg': 'hello'
});
//or
self.postMessage({
    'msg': 'hello'
});


//String
postMessage('message hello');
//or
this.postMessage('message hello');
//or
self.postMessage('message hello');

Return Values

None

Exceptions

If no argument is given it raises an exception and throws a "VoltMXError" JS Object with the following attributes:


errorCode: 3001.  
name: "WorkerThreadError".  
message: "postMessage: MissingMandatoryParameter. Message undefined"

If the message argument passed is not String or JSON object, it raises an exception and throws a "VoltMXError" JS Object with the following attributes:
```
errorCode: 3002.  
name: "WorkerThreadError".  
message: "postMessage: InvalidParameter. Invalid Message"
```
In Worker scope if these exceptions are not handled and if an "error" event handler is registered in worker’s inner scope or/and in Parent scope for this worker object then it is invoked with an error event object and its message attribute set to following.

In case of exception 1:
message: "postMessage: MissingMandatoryParameter. Message undefined"
In case of exception 2:
message: "postMessage: InvalidParameter. Invalid Message"
In Parent (not a worker to some other parent) scope if these exceptions are not handled registered "error" event handler will not be invoked.

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see Scope.

removeEventListener

This API is used to remove the previously registered message or error event listener that was registered using addEventListener().

This API can be used in both parent and worker scope.

Syntax

Parent Scope:

worker.removeEventListener(key,listener)

Worker Scope:

removeEventListener(key,listener)
self.removeEventListener(key,listener)
this.removeEventListener(key, listener)

Input Parameters

key

Key	Description
message	In case of message event handler.
error	In case of error event handler.
listener	The listener parameter indicates the event listener function to be removed.

Example

 "message" event handler:

//Parent Scopevar worker = new voltmx.worker.WorkerThread("worker1.js");

var evtMessageHandler_1 = function(event) {
    voltmx.print("Parent Scope : In message handler 1");
};

var evtMessageHandler_2 = function(event) {
    voltmx.print("Parent Scope : In message handler 2");
};

//Adding event listeners
worker.addEventListener("message", evtMessageHandler_1);
worker.addEventListener("message", evtMessageHandler_2);

//Removing event listener
worker.removeEventListener("message", evtMessageHandler_2);


//Worker Scope
var evtMessageHandler_1 = function(event) {
    voltmx.print("Worker Scope : In message handler 1");
};

var evtMessageHandler_2 = function(event) {
    voltmx.print("Worker Scope : In message handler 2");
};

//Adding event listeners
self.addEventListener("message", evtMessageHandler_1);
self.addEventListener("message", evtMessageHandler_2);

//Removing event listener
self.removeEventListener("message", evtMessageHandler_2);

 "error" event listener:

//Parent Scope
var worker = new voltmx.worker.WorkerThread("worker1.js");

var evtErrorHandler\_1 = function(event) {
    voltmx.print("Parent Scope: In error handler 1");
};

var evtErrorHandler\_2 = function(event) {
    voltmx.print("Parent Scope: In error handler 2");
};

//adding event listeners
worker.addEventListener("error", evtErrorHandler\_1);
worker.addEventListener("error", evtErrorHandler\_2);

//removing event listener
worker.removeEventListener("error", evtErrorHandler\_2);


//Worker Scope
var evtErrorHandler\_1 = function(event) {
    voltmx.print("Worker Scope: In error handler 1");
};

var evtErrorHandler\_2 = function(event) {
    voltmx.print("Worker Scope: In error handler 2");
};

//adding event listeners
self.addEventListener("error", evtErrorHandler\_1);
self.addEventListener("error", evtErrorHandler\_2);

//removing event listener
self.removeEventListener("error", evtErrorHandler\_2);

Exceptions

If no argument is given or if the number of arguments are less than two, it raises an exception and throws a "VoltMXError" JS Object with the following attributes:
```
errorCode: 3001.  
name: "WorkerThreadError".  
message: "removeEventListener: MissingMandatoryParameter. Mandatory arguments missing"
```
If the first argument is not equal to "message" or "error" and if second argument is not a function object, it raises an exception and throws a "VoltMXError" JS Object with the following attributes:
```
errorCode: 3002.  
name: "WorkerThreadError".  
message: "removeEventListener: InvalidParameter. Invalid arguments"
```
In Worker scope if these exceptions are not handled and if an "error" event handler is registered in worker’s inner scope or/and in Parent scope for this worker object then it is invoked with an error event object and its message attribute set to following.

In case of exception 1:
message: "removeEventListener: MissingMandatoryParameter. Mandatory arguments missing"
In case of exception 2:
message: "removeEventListener: InvalidParameter. Invalid arguments"
In Parent(not a worker to some other parent) scope if these exceptions are not handled registered "error" event handler will not be invoked.

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see Scope.

terminate

When called from parent scope immediately terminates the worker. This does not offer the worker an opportunity to finish its operations. It is simply stopped at once.

The tasks pending in the message queue and callbacks registered for network, timer APIs are discarded without wait until completion.

Syntax

worker.terminate()

Input Parameters

None

Example

var worker = new voltmx.worker.WorkerThread("worker1.js");

//Post a message to the worker
worker.postMessage("Hello from Parent");

//Terminate the worker
worker.terminate();

Return Values

None

Platform Availability

Available for iOS, Android, Windows, SPA, and Desktop Web. For more information, see Scope.

Limitations

As the worker threading model is mapped to underlying native threading models in native platforms, there can be some deviations from what specification says, this is due to technical limitations in the underlying platforms which include:

When terminate() is invoked in Parent thread on worker, and if worker is currently executing a large task, it might not immediately terminate, it will continue to execute the task to completion and terminate.
When terminate() is invoked in Parent thread on worker, and if there are pending tasks waiting in the message queues for this worker to perform, some platforms might discard all the pending tasks without accepting them for execution and terminate, and on some platform all the pending tasks are executed to completion and then the worker terminates.
Hence it is to be noted that to achieve cross platform consistency, it is always advised that terminate() be invoked on the worker once all the tasks in message queues are completed.