@ohos.worker (Starting the Worker)

The worker thread is an independent thread running in parallel with the main thread. The thread that creates the worker thread is referred to as the host thread. The URL file passed in during worker creation is executed in the worker thread. The worker thread can process time-consuming operations, but cannot directly operate the UI.

With the Worker module, you can provide a multithreading environment for an application, so that the application can perform a time-consuming operation in a background thread. This greatly prevents a computing-intensive or high-latency task from blocking the running of the main thread. A Worker instance will not be proactively destroyed once it is created. It consumes resources to keep running. Therefore, you should call the API to terminate it in a timely manner.

The Context object of the worker thread is different from that of the main thread. The worker thread does not support UI operations.

For details about the precautions for using Worker, see Precautions for Worker.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import worker from '@ohos.worker';

Attributes

System capability: SystemCapability.Utils.Lang

WorkerOptions

Provides options that can be set for the Worker instance to create.

System capability: SystemCapability.Utils.Lang

ThreadWorker⁹⁺

Before using the following APIs, you must create a ThreadWorker instance. The ThreadWorker class inherits from WorkerEventTarget.

constructor⁹⁺

constructor(scriptURL: string, options?: WorkerOptions)

A constructor used to create a ThreadWorker instance.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

The following code snippet shows how to load the worker thread file of the ability in the stage model. For details about how to use the library to load the worker thread file, see Precautions for File URLs.

import worker from '@ohos.worker';

// Two scenarios are involved.

// Scenario 1: URL of the worker thread file: "entry/src/main/ets/workers/worker.ets"
const workerStageModel01 = new worker.ThreadWorker('entry/ets/workers/worker.ets', {name:"first worker in Stage model"});

// Scenario 2: URL of the worker thread file: "phone/src/main/ets/ThreadFile/workers/worker.ets"
const workerStageModel02 = new worker.ThreadWorker('phone/ets/ThreadFile/workers/worker.ets');

postMessage⁹⁺

postMessage(message: Object, transfer: ArrayBuffer[]): void

Used by the host thread to send a message to the worker thread by transferring object ownership.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

let buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

postMessage⁹⁺

postMessage(message: Object, options?: PostMessageOptions): void

Used by the host thread to send a message to the worker thread by transferring object ownership or copying data.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.postMessage("hello world");

let buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

on⁹⁺

on(type: string, listener: WorkerEventListener): void

Adds an event listener for the worker thread. This API provides the same functionality as addEventListener⁹⁺.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.on("alert", (e)=>{
    console.log("alert listener callback");
})

once⁹⁺

once(type: string, listener: WorkerEventListener): void

Adds an event listener for the worker thread and removes the event listener after it is invoked once.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.once("alert", (e)=>{
    console.log("alert listener callback");
})

off⁹⁺

off(type: string, listener?: WorkerEventListener): void

Removes an event listener for the worker thread. This API provides the same functionality as removeEventListener⁹⁺.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
// Use on, once, or addEventListener to add a listener for the "alert" event, and use off to remove the listener.
workerInstance.off("alert");

registerGlobalCallObject¹¹⁺

registerGlobalCallObject(instanceName: string, globalCallObject: Object): void

Registers an object with the ThreadWorker instance of the host thread. In this way, the methods of the object can be called in the worker thread through callGlobalCallObjectMethod.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
class TestObj {
  private message : string = "this is a message from TestObj"
  public getMessage() : string {
    return this.message;
  }
  public getMessageWithInput(str : string) : string {
    return this.message + " with input: " + str;
  }
}
let registerObj = new TestObj();
// Register registerObj with the ThreadWorker instance.
workerInstance.registerGlobalCallObject("myObj", registerObj);
workerInstance.postMessage("start worker")

unregisterGlobalCallObject¹¹⁺

unregisterGlobalCallObject(instanceName?: string): void

Unregisters an object with the ThreadWorker instance of the host thread. This API releases the strong reference between the ThreadWorker instance and the target object. No error is reported if no object is matched.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
class TestObj {
  private message : string = "this is a message from TestObj"
  public getMessage() : string {
    return this.message;
  }
  public getMessageWithInput(str : string) : string {
    return this.message + " with input: " + str;
  }
}
let registerObj = new TestObj();
workerInstance.registerGlobalCallObject("myObj", registerObj);
// Unregister the object.
workerInstance.unregisterGlobalCallObject("myObj");
// Unregister all objects from the ThreadWorker instance.
//workerInstance.unregisterGlobalCallObject();
workerInstance.postMessage("start worker")

terminate⁹⁺

terminate(): void

Terminates the worker thread to stop it from receiving messages.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.terminate();

onexit⁹⁺

onexit?: (code: number) => void

Called when the worker thread exits. The event handler is executed in the host thread. In the callback function, the code value is of the number type, where the value 1 indicates abnormal exit and 0 indicates normal exit.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.onexit = (code) => {
 console.log("onexit");
}

// onexit is executed in either of the following ways:
// Main thread
workerInstance.terminate();

// Worker thread
//workerPort.close()

onerror⁹⁺

onerror?: (err: ErrorEvent) => void

Called when an exception occurs during worker execution. The event handler is executed in the host thread. In the callback function, the err type is ErrorEvent, indicating the received abnormal data.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

import worker, { ErrorEvent } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.onerror = (err: ErrorEvent) => {
  console.log("onerror" + err.message);
}

onmessage⁹⁺

onmessage?: (event: MessageEvents) => void

Called when the host thread receives a message sent by the worker thread through workerPort.postMessage. The event handler is executed in the host thread. In the callback function, the event type is MessageEvents, indicating the received message data.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

import worker, { MessageEvents } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.onmessage = (e: MessageEvents): void => {
 // e: MessageEvents. The usage is as follows:
 // let data = e.data;
 console.log("onmessage");
}

onmessageerror⁹⁺

onmessageerror?: (event: MessageEvents) => void

Called when the worker thread receives a message that cannot be serialized. The event handler is executed in the host thread. In the callback function, the event type is MessageEvents, indicating the received message data.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

import worker, { MessageEvents } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.onmessageerror = (err: MessageEvents) => {
  console.log("onmessageerror");
}

addEventListener⁹⁺

addEventListener(type: string, listener: WorkerEventListener): void

Adds an event listener for the worker thread. This API provides the same functionality as on⁹⁺.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})

removeEventListener⁹⁺

removeEventListener(type: string, callback?: WorkerEventListener): void

Removes an event listener for the worker thread. This API provides the same functionality as off⁹⁺.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})
workerInstance.removeEventListener("alert");

dispatchEvent⁹⁺

dispatchEvent(event: Event): boolean

Dispatches the event defined for the worker thread.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.dispatchEvent({type:"eventType", timeStamp:0}); // timeStamp is not supported yet.

The dispatchEvent API can be used together with the on, once, and addEventListener APIs. The sample code is as follows:

import worker, { MessageEvents } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// Usage 1:
workerInstance.on("alert_on", (e)=>{
    console.log("alert listener callback");
})
workerInstance.once("alert_once", (e)=>{
    console.log("alert listener callback");
})
workerInstance.addEventListener("alert_add", (e)=>{
    console.log("alert listener callback");
})

// The event listener created by once is removed after being executed once.
workerInstance.dispatchEvent({type:"alert_once", timeStamp:0});// timeStamp is not supported yet.
// The event listener created by on will not be proactively deleted.
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
// The event listener created by addEventListener will not be proactively deleted.
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});

// Usage 2:
// The event type can be customized, and the special types "message", "messageerror", and "error" exist.
// When type = "message", the event handler defined by onmessage will also be executed.
// When type = "messageerror", the event handler defined by onmessageerror will also be executed.
// When type = "error", the event handler defined by onerror will also be executed.
// removeEventListener or off can be used to remove an event listener that is created by addEventListener, on, or once.

workerInstance.addEventListener("message", (e)=>{
    console.log("message listener callback");
})
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("onmessage : message listener callback");
}
// When dispatchEvent is called to distribute the "message" event, the callback passed in addEventListener and onmessage will be invoked.
workerInstance.dispatchEvent({type:"message", timeStamp:0});

removeAllListener⁹⁺

removeAllListener(): void

Removes all event listeners for the worker thread.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})
workerInstance.removeAllListener();

WorkerEventTarget⁹⁺

Processes worker listening events.

addEventListener⁹⁺

addEventListener(type: string, listener: WorkerEventListener): void

Adds an event listener for the worker thread. This API provides the same functionality as on⁹⁺.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})

removeEventListener⁹⁺

removeEventListener(type: string, callback?: WorkerEventListener): void

Removes an event listener for the worker thread. This API provides the same functionality as off⁹⁺.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})
workerInstance.removeEventListener("alert");

dispatchEvent⁹⁺

dispatchEvent(event: Event): boolean

Dispatches the event defined for the worker thread.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.dispatchEvent({type:"eventType", timeStamp:0}); // timeStamp is not supported yet.

The dispatchEvent API can be used together with the on, once, and addEventListener APIs. The sample code is as follows:

import worker, { MessageEvents } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// Usage 1:
workerInstance.on("alert_on", (e)=>{
    console.log("alert listener callback");
})
workerInstance.once("alert_once", (e)=>{
    console.log("alert listener callback");
})
workerInstance.addEventListener("alert_add", (e)=>{
    console.log("alert listener callback");
})

// The event listener created by once is removed after being executed once.
workerInstance.dispatchEvent({type:"alert_once", timeStamp:0});// timeStamp is not supported yet.
// The event listener created by on will not be proactively deleted.
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
// The event listener created by addEventListener will not be proactively deleted.
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});

// Usage 2:
// The event type can be customized, and the special types "message", "messageerror", and "error" exist.
// When type = "message", the event handler defined by onmessage will also be executed.
// When type = "messageerror", the event handler defined by onmessageerror will also be executed.
// When type = "error", the event handler defined by onerror will also be executed.
// removeEventListener or off can be used to remove an event listener that is created by addEventListener, on, or once.

workerInstance.addEventListener("message", (e)=>{
    console.log("message listener callback");
})
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("onmessage : message listener callback");
}
// When dispatchEvent is called to distribute the "message" event, the callback passed in addEventListener and onmessage will be invoked.
workerInstance.dispatchEvent({type:"message", timeStamp:0});

removeAllListener⁹⁺

removeAllListener(): void

Removes all event listeners for the worker thread.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})
workerInstance.removeAllListener();

ThreadWorkerGlobalScope⁹⁺

Implements communication between the worker thread and the host thread. The postMessage API is used to send messages to the host thread, and the close API is used to terminate the worker thread. The ThreadWorkerGlobalScope class inherits from GlobalScope⁹⁺.

postMessage⁹⁺

postMessage(messageObject: Object, transfer: ArrayBuffer[]): void;

Used by the worker thread to send a message to the host thread by transferring object ownership.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

// Main thread
import worker, { MessageEvents } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("receive data from worker.ets");
}

// worker.ets
import worker, { MessageEvents } from '@ohos.worker';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    let buffer = new ArrayBuffer(8);
    workerPort.postMessage(buffer, [buffer]);
}

postMessage⁹⁺

postMessage(messageObject: Object, options?: PostMessageOptions): void

Used by the worker thread to send a message to the host thread by transferring object ownership or copying data.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

// Main thread
import worker, { MessageEvents } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("receive data from worker.ets");
}

// worker.ets
import worker, { MessageEvents } from '@ohos.worker';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    workerPort.postMessage("receive data from main thread");
}

callGlobalCallObjectMethod¹¹⁺

callGlobalCallObjectMethod(instanceName: string, methodName: string, timeout: number, ...args: Object[]): Object

Calls a method of an object registered with the host thread. This API is called by the worker thread. The invoking is synchronous for the worker thread and asynchronous for the host thread. The return value is transferred through serialization.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Utils Error Codes.

Example

// worker.ets
import worker, { MessageEvents } from '@ohos.worker';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
  try {
    // The method to call does not carry an input parameter.
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessage", 0) as string;
    console.info("worker:", res) // worker: this is a message from TestObj
  } catch (error) {
    // Exception handling.
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
  try {
    // The method to call carries input parameters.
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessageWithInput", 0, "hello there!") as string;
    console.info("worker:", res) //worker: this is a message from TestObj with input: hello there!
  } catch (error) {
    // Exception handling.
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
}

close⁹⁺

close(): void

Terminates the worker thread to stop it from receiving messages.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// worker.ets
import worker, { MessageEvents } from '@ohos.worker';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    workerPort.close()
}

onmessage⁹⁺

onmessage?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) => void

Called when the worker thread receives a message sent by the host thread through postMessage. The event handler is executed in the worker thread. In the callback function, this indicates the caller's ThreadWorkerGlobalScope, and the ev type is MessageEvents, indicating the received message data.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");

// worker.ets
import worker, { MessageEvents } from '@ohos.worker';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    console.log("receive main thread message");
}

onmessageerror⁹⁺

onmessageerror?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) => void

Called when the worker thread receives a message that cannot be deserialized. The event handler is executed in the worker thread. In the callback function, this indicates the caller's ThreadWorkerGlobalScope, and the ev type is MessageEvents, indicating the received message data.

System capability: SystemCapability.Utils.Lang

Error codes

For details about the error codes, see Utils Error Codes.

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// worker.ets
import worker, { MessageEvents } from '@ohos.worker';

const workerPort = worker.workerPort;
workerPort.onmessageerror = (err: MessageEvents) => {
    console.log("worker.ets onmessageerror");
}

WorkerEventListener⁹⁺

(event: Event): void | Promise<void>

Implements event listening.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Utils Error Codes.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})

GlobalScope⁹⁺

Implements the running environment of the worker thread. The GlobalScope class inherits from WorkerEventTarget.

Attributes

System capability: SystemCapability.Utils.Lang

onerror⁹⁺

onerror?: (ev: ErrorEvent) => void

Called when an exception occurs during worker execution. The event handler is executed in the worker thread. In the callback function, the ev type is ErrorEvent, indicating the received abnormal data.

System capability: SystemCapability.Utils.Lang

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets")

// worker.ets
import worker, { ErrorEvent } from '@ohos.worker';

const workerPort = worker.workerPort
workerPort.onerror = (err: ErrorEvent) => {
    console.log("worker.ets onerror" + err.message)
}

MessageEvents⁹⁺

Holds the data transferred between worker threads.

System capability: SystemCapability.Utils.Lang

RestrictedWorker¹¹⁺

The RestrictedWorker class inherits ThreadWorker⁹⁺ and supports all APIs in ThreadWorker. RestrictedWorker provides a restricted environment for running the worker thread. In this environment, only the Worker module can be imported.

constructor¹¹⁺

constructor(scriptURL: string, options?: WorkerOptions)

A constructor used to create a RestrictedWorker instance. Before using the following APIs, you must create a RestrictedWorker instance.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

The following code snippet shows how to load the worker thread file of the ability in the stage model. For details about how to use the library to load the worker thread file, see Precautions for File URLs.

Only the Worker module can be imported to the restricted worker thread file. Other APIs cannot be imported. The following is sample code:

import worker from '@ohos.worker';

// Two scenarios are involved.

// Scenario 1: URL of the worker thread file: "entry/src/main/ets/workers/worker.ets"
const workerStageModel01 = new worker.RestrictedWorker('entry/ets/workers/worker.ets', {name:"first worker in Stage model"});

// Scenario 2: URL of the worker thread file: "phone/src/main/ets/ThreadFile/workers/worker.ets"
const workerStageModel02 = new worker.RestrictedWorker('phone/ets/ThreadFile/workers/worker.ets');

// Restricted worker thread file
import worker, { MessageEvents } from '@ohos.worker';

// import process from '@ohos.process'; // Only worker APIs can be imported to the restricted worker thread file.

const workerPort = worker.workerPort;

workerPort.onmessage = (e : MessageEvents) : void => {
  console.info("worker:: This is worker thread.")
  // console.info("worker:: worker tid: "+ process.tid) // Run process.tid. The main thread reports the corresponding error.
}

Worker^(deprecated)

Before using the following APIs, you must create a Worker instance. The Worker class inherits from EventTarget.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker⁹⁺ instead.

constructor^(deprecated)

constructor(scriptURL: string, options?: WorkerOptions)

A constructor used to create a Worker instance.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.constructor⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Example

The following code snippet shows how to load the worker thread file of the ability in the stage model. For details about how to use the library to load the worker thread file, see Precautions for File URLs.

import worker from '@ohos.worker';

// Two scenarios are involved.

// Scenario 1: URL of the worker thread file: "entry/src/main/ets/workers/worker.ets"
const workerStageModel01 = new worker.ThreadWorker('entry/ets/workers/worker.ets', {name:"first worker in Stage model"});

// Scenario 2: URL of the worker thread file: "phone/src/main/ets/ThreadFile/workers/worker.ets"
const workerStageModel02 = new worker.ThreadWorker('phone/ets/ThreadFile/workers/worker.ets');

postMessage^(deprecated)

postMessage(message: Object, transfer: ArrayBuffer[]): void

Used by the host thread to send a message to the worker thread by transferring object ownership.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.postMessage⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Example

const workerInstance = new worker.Worker("workers/worker.ets");

let buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

postMessage^(deprecated)

postMessage(message: Object, options?: PostMessageOptions): void

Used by the host thread to send a message to the worker thread by transferring object ownership or copying data.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.postMessage⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Example

const workerInstance = new worker.Worker("workers/worker.ets");

workerInstance.postMessage("hello world");

let buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

on^(deprecated)

on(type: string, listener: EventListener): void

Adds an event listener for the worker thread. This API provides the same functionality as addEventListener^(deprecated).

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.on⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Example

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.on("alert", (e)=>{
    console.log("alert listener callback");
})

once^(deprecated)

once(type: string, listener: EventListener): void

Adds an event listener for the worker thread and removes the event listener after it is invoked once.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.once⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Example

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.once("alert", (e)=>{
    console.log("alert listener callback");
})

off^(deprecated)

off(type: string, listener?: EventListener): void

Removes an event listener for the worker thread. This API provides the same functionality as removeEventListener^(deprecated).

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.off⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Example

const workerInstance = new worker.Worker("workers/worker.ets");
// Use on, once, or addEventListener to add a listener for the "alert" event, and use off to remove the listener.
workerInstance.off("alert");

terminate^(deprecated)

terminate(): void

Terminates the worker thread to stop it from receiving messages.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.terminate⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Example

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.terminate();

onexit^(deprecated)

onexit?: (code: number) => void

Called when the worker thread exits. The event handler is executed in the host thread. In the callback function, the code value is of the number type, where the value 1 indicates abnormal exit and 0 indicates normal exit.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.onexit⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Example

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onexit = (code) => {
    console.log("onexit");
}

// onexit is executed in either of the following ways:
// Main thread
workerInstance.terminate();

// Worker thread
//parentPort.close()

onerror^(deprecated)

onerror?: (err: ErrorEvent) => void

Called when an exception occurs during worker execution. The event handler is executed in the host thread. In the callback function, the err type is ErrorEvent, indicating the received abnormal data.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.onerror⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Example

import worker, { ErrorEvent } from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onerror = (err: ErrorEvent) => {
  console.log("onerror" + err.message);
}

onmessage^(deprecated)

onmessage?: (event: MessageEvent) => void

Called when the host thread receives a message sent by the worker thread through workerPort.postMessage. The event handler is executed in the host thread. In the callback function, the event type is MessageEvent, indicating the received message data.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.onmessage⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Example

import worker from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onmessage = (e): void => {
    console.log("onmessage");
}

onmessageerror^(deprecated)

onmessageerror?: (event: MessageEvent) => void

Called when the worker thread receives a message that cannot be serialized. The event handler is executed in the host thread. In the callback function, the event type is MessageEvent, indicating the received message data.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorker.onmessageerror⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Example

import worker from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onmessageerror = (err) => {
    console.log("onmessageerror");
}

EventTarget^(deprecated)

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use WorkerEventTarget⁹⁺ instead.

addEventListener^(deprecated)

addEventListener(type: string, listener: EventListener): void

Adds an event listener for the worker thread. This API provides the same functionality as on^(deprecated).

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use addEventListener⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Example

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})

removeEventListener^(deprecated)

removeEventListener(type: string, callback?: EventListener): void

Removes an event listener for the worker thread. This API provides the same functionality as off^(deprecated).

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use removeEventListener⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Example

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})
workerInstance.removeEventListener("alert");

dispatchEvent^(deprecated)

dispatchEvent(event: Event): boolean

Dispatches the event defined for the worker thread.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use dispatchEvent⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Example

const workerInstance = new worker.Worker("workers/worker.ets");

workerInstance.dispatchEvent({type:"eventType", timeStamp:0}); // timeStamp is not supported yet.

The dispatchEvent API can be used together with the on, once, and addEventListener APIs. The sample code is as follows:

const workerInstance = new worker.Worker("workers/worker.ets");

// Usage 1:
workerInstance.on("alert_on", (e)=>{
    console.log("alert listener callback");
})
workerInstance.once("alert_once", (e)=>{
    console.log("alert listener callback");
})
workerInstance.addEventListener("alert_add", (e)=>{
    console.log("alert listener callback");
})

// The event listener created by once is removed after being executed once.
workerInstance.dispatchEvent({type:"alert_once", timeStamp:0});// timeStamp is not supported yet.
// The event listener created by on will not be proactively deleted.
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
// The event listener created by addEventListener will not be proactively deleted.
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});

// Usage 2:
// The event type can be customized, and the special types "message", "messageerror", and "error" exist.
// When type = "message", the event handler defined by onmessage will also be executed.
// When type = "messageerror", the event handler defined by onmessageerror will also be executed.
// When type = "error", the event handler defined by onerror will also be executed.
// removeEventListener or off can be used to remove an event listener that is created by addEventListener, on, or once.

workerInstance.addEventListener("message", (e)=>{
    console.log("message listener callback");
})
workerInstance.onmessage = function(e) {
    console.log("onmessage : message listener callback");
}
// When dispatchEvent is called to distribute the "message" event, the callback passed in addEventListener and onmessage will be invoked.
workerInstance.dispatchEvent({type:"message", timeStamp:0});

removeAllListener^(deprecated)

removeAllListener(): void

Removes all event listeners for the worker thread.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use removeAllListener⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Example

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})
workerInstance.removeAllListener();

DedicatedWorkerGlobalScope^(deprecated)

Implements communication between the worker thread and the host thread. The postMessage API is used to send messages to the host thread, and the close API is used to terminate the worker thread. This class inherits from WorkerGlobalScope.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorkerGlobalScope⁹⁺ instead.

postMessage^(deprecated)

postMessage(messageObject: Object, transfer: Transferable[]): void

Used by the worker thread to send a message to the host thread by transferring object ownership.

NOTE
This API is deprecated since API version 9. You are advised to use ThreadWorkerGlobalScope⁹⁺.postMessage⁹⁺.

System capability: SystemCapability.Utils.Lang

Parameters

postMessage⁹⁺

postMessage(messageObject: Object, transfer: ArrayBuffer[]): void

Used by the worker thread to send a message to the host thread by transferring object ownership.

NOTE

The DedicatedWorkerGlobalScope class is deprecated since API version 9. You are advised to use ThreadWorkerGlobalScope⁹⁺.postMessage⁹⁺.

System capability: SystemCapability.Utils.Lang

Parameters

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e): void => {
    // let data = e.data;
    console.log("receive data from worker.ets");
}

// worker.ets
import worker from '@ohos.worker';

const workerPort = worker.workerPort;
workerPort.onmessage = (e): void => {
    // let data = e.data;
    let buffer = new ArrayBuffer(5)
    workerPort.postMessage(buffer, [buffer]);
}

postMessage^(deprecated)

postMessage(messageObject: Object, options?: PostMessageOptions): void

Used by the worker thread to send a message to the host thread by transferring object ownership or copying data.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorkerGlobalScope⁹⁺.postMessage⁹⁺.

System capability: SystemCapability.Utils.Lang

Parameters

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e): void => {
    // let data = e.data;
    console.log("receive data from worker.ets");
}

// worker.ets
import worker from '@ohos.worker';

const parentPort = worker.parentPort;
parentPort.onmessage = (e): void => {
    // let data = e.data;
    parentPort.postMessage("receive data from main thread");
}

close^(deprecated)

close(): void

Terminates the worker thread to stop it from receiving messages.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorkerGlobalScope⁹⁺.close⁹⁺.

System capability: SystemCapability.Utils.Lang

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");

// worker.ets
import workerfrom '@ohos.worker';

const parentPort = worker.parentPort;
parentPort.onmessage = (e): void => {
    parentPort.close()
}

onmessage^(deprecated)

onmessage?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void

Called when the worker thread receives a message sent by the host thread through postMessage. The event handler is executed in the worker thread. In the callback function, this indicates the caller's DedicatedWorkerGlobalScope, and the ev type is MessageEvent, indicating the received message data.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorkerGlobalScope⁹⁺.onmessage⁹⁺.

System capability: SystemCapability.Utils.Lang

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.postMessage("hello world");

// worker.ets
import worker from '@ohos.worker';

const parentPort = worker.parentPort;
parentPort.onmessage = (e): void => {
    console.log("receive main thread message");
}

onmessageerror^(deprecated)

onmessageerror?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void

Called when the worker thread receives a message that cannot be deserialized. The event handler is executed in the worker thread. In the callback function, this indicates the caller's DedicatedWorkerGlobalScope, and the ev type is MessageEvent, indicating the received message data.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use ThreadWorkerGlobalScope⁹⁺.onmessageerror⁹⁺.

System capability: SystemCapability.Utils.Lang

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");

// worker.ets
import worker from '@ohos.worker';

const parentPort = worker.parentPort;
parentPort.onmessageerror = (e) => {
    console.log("worker.ets onmessageerror")
}

PostMessageOptions

Defines the object for which the ownership is to be transferred during data transfer. The object must be an ArrayBuffer instance. After the ownership is transferred, the object becomes unavailable in the sender and can be used only in the receiver.

System capability: SystemCapability.Utils.Lang

Event

Defines the event.

System capability: SystemCapability.Utils.Lang

EventListener^(deprecated)

(evt: Event): void | Promise<void>

Implements event listening.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use WorkerEventListener⁹⁺ instead.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Example

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})

ErrorEvent

Provides detailed information about the exception that occurs during worker execution. The ErrorEvent class inherits from Event.

System capability: SystemCapability.Utils.Lang

MessageEvent<T>

Holds the data transferred between worker threads.

System capability: SystemCapability.Utils.Lang

WorkerGlobalScope^(deprecated)

Implements the running environment of the worker thread. The WorkerGlobalScope class inherits from EventTarget.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use GlobalScope⁹⁺ instead.

Attributes

System capability: SystemCapability.Utils.Lang

onerror^(deprecated)

onerror?: (ev: ErrorEvent) => void

Called when an exception occurs during worker execution. The event handler is executed in the worker thread. In the callback function, the ev type is ErrorEvent, indicating the received abnormal data.

NOTE
This API is supported since API version 7 and deprecated since API version 9. You are advised to use GlobalScope⁹⁺.onerror⁹⁺.

System capability: SystemCapability.Utils.Lang

Example

// Main thread
import worker from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets")

// worker.ets
import worker, { ErrorEvent } from '@ohos.worker';

const parentPort = worker.parentPort
parentPort.onerror = (err: ErrorEvent) => {
    console.log("worker.ets onerror" + err.message)
}

More Information

Sequenceable Data Types

The following object types are supported: basic types except Symbol, Date, String, RegExp, Array, Map, Set, Object (simple objects only, for example, objects created using {} or new Object), ArrayBuffer, and typedArray. (Note that only attributes can be transferred for common objects. Prototypes and methods cannot be transferred.)

Exception: When an object created through a custom class is passed, no serialization error occurs. However, the attributes (such as Function) of the custom class cannot be passed through serialization.

NOTE
An FA project of API version 9 is used as an example.

// Main thread
import worker, { MessageEvents } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("workers/worker.ets");
workerInstance.postMessage("message from main thread to worker");
workerInstance.onmessage = (d: MessageEvents): void => {
  // When the worker thread passes obj2, data contains obj2, excluding the Init or SetName method.
  let data: string  = d.data;
}

// worker.ets
import worker, { MessageEvents, ErrorEvent } from '@ohos.worker';

const workerPort = worker.workerPort;
class MyModel {
    name = "undefined"
    Init() {
        this.name = "MyModel"
    }
}
workerPort.onmessage = (d: MessageEvents): void => {
  console.log("worker.ets onmessage");
  let data: string = d.data;
  let func1 = () => {
    console.log("post message is function");
  }
  // workerPort.postMessage(func1); A serialization error occurs when passing func1.
  // let obj1: obj | null = null;
  // if (obj1) {
  //   workerPort.postMessage(obj1 as obj);  // A serialization error occurs when passing obj1.
  // }
  let obj2 = new MyModel();
  workerPort.postMessage(obj2);     // No serialization error occurs when passing obj2.
}
workerPort.onmessageerror = () => {
    console.log("worker.ets onmessageerror");
}
workerPort.onerror = (err: ErrorEvent) => {
    console.log("worker.ets onerror" + err.message);
}

Memory Model

The worker thread is implemented based on the actor model. In the worker interaction process, the JS main thread can create multiple worker threads, each of which are isolated and transfer data through serialization. They complete computing tasks and return the result to the main thread.

Each actor concurrently processes tasks of the main thread. For each actor, there is a message queue and a single-thread execution module. The message queue receives requests from the main thread and other actors; the single-thread execution module serially processes requests, sends requests to other actors, and creates new actors. These isolated actors use the asynchronous mode and can run concurrently.

Sample Code

NOTE
Two projects of API version 9 are used as an example.
Only the FA model is supported in API version 8 and earlier versions. If you want to use API version 8 or earlier, change the API for constructing the Worker instance and the API for creating an object in the worker thread for communicating with the main thread.

FA Model

// Main thread (The following assumes that the workers directory and pages directory are at the same level.)
import worker, { MessageEvents, ErrorEvent } from '@ohos.worker';

// Create a Worker instance in the main thread.
const workerInstance = new worker.ThreadWorker("workers/worker.ets");

// The main thread transfers information to the worker thread.
workerInstance.postMessage("123");

// The main thread receives information from the worker thread.
workerInstance.onmessage = (e: MessageEvents): void => {
    // data carries the information sent by the worker thread.
    let data: string = e.data;
    console.log("main thread onmessage");

    // Terminate the Worker instance.
    workerInstance.terminate();
}

// Call onexit().
workerInstance.onexit = (code) => {
    console.log("main thread terminate");
}

workerInstance.onerror = (err: ErrorEvent) => {
    console.log("main error message " + err.message);
}

// worker.ets
import worker, { MessageEvents, ErrorEvent } from '@ohos.worker';

// Create an object in the worker thread for communicating with the main thread.
const workerPort = worker.workerPort

// The worker thread receives information from the main thread.
workerPort.onmessage = (e: MessageEvents): void => {
    // data carries the information sent by the main thread.
    let data: string = e.data;
    console.log("worker.ets onmessage");

    // The worker thread sends information to the main thread.
    workerPort.postMessage("123")
}

// Trigger a callback when an error occurs in the worker thread.
workerPort.onerror = (err: ErrorEvent) => {
    console.log("worker.ets onerror");
}

Configuration of the build-profile.json5 file:

  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/entryability/workers/worker.ets"
      ]
    }
  }

Stage Model

// Main thread (The following assumes that the workers directory and pages directory are at different levels.)
import worker, { MessageEvents, ErrorEvent } from '@ohos.worker';

// Create a Worker instance in the main thread.
const workerInstance = new worker.ThreadWorker("entry/ets/pages/workers/worker.ets");

// The main thread transfers information to the worker thread.
workerInstance.postMessage("123");

// The main thread receives information from the worker thread.
workerInstance.onmessage = (e: MessageEvents): void => {
    // data carries the information sent by the worker thread.
    let data: string = e.data;
    console.log("main thread onmessage");

    // Terminate the Worker instance.
    workerInstance.terminate();
}
// Call onexit().
workerInstance.onexit = (code) => {
    console.log("main thread terminate");
}

workerInstance.onerror = (err: ErrorEvent) => {
    console.log("main error message " + err.message);
}

// worker.ets
import worker, { MessageEvents, ErrorEvent } from '@ohos.worker';

// Create an object in the worker thread for communicating with the main thread.
const workerPort = worker.workerPort

// The worker thread receives information from the main thread.
workerPort.onmessage = (e: MessageEvents): void => {
    // data carries the information sent by the main thread.
    let data: string = e.data;
    console.log("worker.ets onmessage");

    // The worker thread sends information to the main thread.
    workerPort.postMessage("123")
}

// Trigger a callback when an error occurs in the worker thread.
workerPort.onerror = (err: ErrorEvent) => {
    console.log("worker.ets onerror" + err.message);
}

Configuration of the build-profile.json5 file:

  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/pages/workers/worker.ets"
      ]
    }
  }