js_worker_module

Introduction

Worker enables JS to have the ability of multithreading, and completes the communication between worker thread and host thread through PostMessage.

Interface description

For interface implementation, see: js_worker_module/jsapi/worker

Worker object description

The object object used by the host thread to communicate with the worker thread.

Interface

• name

constructor(scriptURL:string, options? WorkerOptions)	worker constructor to Creates a worker instance

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");

• name

postMessage(message:Object, options?:PostMessageOptions)	Sends a message to the worker thread
postMessage(message:Object, transfer:ArrayBuffer[])	Sends a message to the worker thread

• example

// example 1
import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.postMessage("hello world");
 
// example 2
import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
var buffer = new ArrayBuffer(8);
worker.postMessage(buffer, [buffer]);

• name

on(type:string, listener:EventListener)	Adds an event listener to the worker

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.on("alert", (e)=>{
     console.log("worker on...");
})

• name

once(type:string, listener:EventListener)	Adds an event listener to the worker and removes the event listener automically after it is invoked once

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.once("alert", (e)=>{
    console.log("worker on...");
})

• name

off(type:string, listener?:EventListener)	Removes an event listener to the worker

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.off("alert");

• name

terminate()	Terminates the worker thread to stop the worker from receiving messages

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.terminate();

• name

removeEventListener(type:string, listener?:EventListener)	Removes an event defined for the worker

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.removeEventListener("alert");

• name

dispatchEvent(event: Event)	Dispatches the event defined for the worker

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.dispatchEvent({type:"alert"});

• name

removeAllListener()	Removes all event listeners for the worker

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.removeAllListener();

Attribute

• name

onexit?:(code:number)=>void	The onexit attribute of the worker specifies the event handler to be called when the worker exits. The handler is executed in the host thread

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.onexit = function(e) {
    console.log("onexit...");
}

• name

onerror?:(ev:ErrorEvent)=>void	The onerror attribute of the worker specifies the event handler to be called when an exception occurs during worker execution. The event handler is executed in the host thread

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.onerror = function(e) {
    console.log("onerror...");
}

• name

onmessage?:(ev:MessageEvent)=>void	The onmessage attribute of the worker specifies the event handler to be called then the host thread receives a message created by itself and sent by the worker through the parentPort.postMessage. The event handler is executed in the host thread

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.onmessage = function(e) {
    console.log("onmessage...");
}

• name

onmessageerror?:(event:MessageEvent)=>void	The onmessage attribute of the worker specifies the event handler when the worker receives a message that cannot be serialized. The event handler is executed in the host thread

• example

import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.onmessageerror = function(e) {
    console.log("onmessageerror...");
}

parentPort object description

Object of the worker thread used to communicate with the host thread

Interface

• name

postMessage(message:Object, options?:PostMessageOptions)	Send a message to host thread
postMessage(message:Object, transfer:ArrayBuffer[])	Send a message to host thread

• example

// main.js
import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.postMessage("hello world");

// worker.js
import worker from "@ohos.worker"
const parentPort = worker.parentPort;
parentPort.onmessage = function(e) {
    parentPort.postMessage("hello world from worker.js");
}

• name

close()	Close the worker thread to stop the worker from receiving messages

• example

// main.js
import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.postMessage("hello world");

// worker.js
import worker from "@ohos.worker"
const parentPort = worker.parentPort;
parentPort.onmessage = function(e) {
    parentPort.close();
}

Attribute

• name

onmessage?:(event:MessageEvent)=>void	The onmessage attribute of parentPort specifies the event handler to be called then the worker thread receives a message sent by the host thread through worker postMessage. The event handler is executed in the worker thread

• example

// main.js
import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.postMessage("hello world");

// worker.js
import worker from "@ohos.worker"
const parentPort = worker.parentPort;
parentPort.onmessage = function(e) {
    console.log("receive main.js message");
}

• name

onerror?:(ev: ErrorEvent)=>void	The onerror attribute of parentPort specifies the event handler to be called when an exception occurs during worker execution. The event handler is executed in the worker thread

• example

// main.js
import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.postMessage("hello world");

// worker.js
import worker from "@ohos.worker"
const parentPort = worker.parentPort;
parentPort.onerror = function(e) {
    console.log("onerror...");
}

• name

onmessageerror?:(event: MessageEvent)=>void	The onmessage attribute of parentPort specifies the event handler to be called then the worker receives a message that cannot be deserialized. The event handler is executed in the worker thread.

• example

// main.js
import worker from "@ohos.worker"
const worker = new worker.Worker("workers/worker.js");
worker.postMessage("hello world");

// worker.js
import worker from "@ohos.worker"
const parentPort = worker.parentPort;
parentPort.onmessageerror = function(e) {
    console.log("onmessageerror...");
}

Repositories Involved

• ace_ace_engine(foundation/arkui/ace_engine-readme.md)
• ace_napi(foundation/arkui/napi-readme.md)

Related warehouse

js_worker_module Subsystem

License

Worker is available under Mozilla license, and the documentation is detailed in documentation. See LICENSE for the full license text.