harmony 鸿蒙@ohos.worker (Starting the Worker)

2022-08-09
浏览 (793)

@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.

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

Name	Type	Readable	Writable	Description
workerPort⁹⁺	ThreadWorkerGlobalScope	Yes	Yes	Object of the worker thread used to communicate with the host thread.
parentPort^(deprecated)	DedicatedWorkerGlobalScope	Yes	Yes	Object of the worker thread used to communicate with the host thread. This attribute is supported since API version 7 and deprecated since API version 9. You are advised to use workerPort⁹⁺ instead.

WorkerOptions

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

System capability: SystemCapability.Utils.Lang

Name	Type	Readable	Writable	Description
type	“classic” \|“module”	Yes	Yes	Mode in which the Worker instance executes the script. The module type is not supported yet. The default value is classic.
name	string	Yes	Yes	Name of the worker thread. The default value is undefined.
shared	boolean	Yes	Yes	Whether sharing of the Worker instance is enabled. Currently, sharing is not supported.

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

Name	Type	Mandatory	Description
scriptURL	string	Yes	Directory of the script to be executed by the Worker instance. In the FA or stage model, DevEco Studio creates a Worker project in either of the following scenarios: (a) The script directory is at the same level as the pages directory. (b) The script directory is at a different level from the pages directory.
options	WorkerOptions	No	Options that can be set for the Worker instance.

Return value

Type	Description
ThreadWorker	Returns the ThreadWorker instance created; returns undefined if the ThreadWorker instance fails to be created.

Error codes

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

ID	Error Message
10200003	Worker initialization failure.
10200007	The worker file patch is invalid path.

Example

import worker from '@ohos.worker';
// Create a Worker instance.

// In the FA model, the workers directory is at the same level as the pages directory in the entry module.
const workerFAModel01 = new worker.ThreadWorker("workers/worker.ts", {name:"first worker in FA model"});
// In the FA model, the workers directory is at the same level as the parent directory of the pages directory in the entry module.
const workerFAModel02 = new worker.ThreadWorker("../workers/worker.ts");

// In the stage model, the workers directory is at the same level as the pages directory in the entry module.
const workerStageModel01 = new worker.ThreadWorker('entry/ets/workers/worker.ts', {name:"first worker in Stage model"});
// In the stage model, the workers directory is a child directory of the pages directory in the entry module.
const workerStageModel02 = new worker.ThreadWorker('entry/ets/pages/workers/worker.ts');

// For the script URL "entry/ets/workers/worker.ts" in the stage model:
// entry is the value of the name attribute under module in the module.json5 file, and ets indicates the programming language in use.
// The script URL is related to the level of the workers directory where the worker file is located and is irrelevant to the file where the new worker is located.

// In the esmodule build scenario of the stage model, the script URL specification @bundle:bundlename/entryname/ets/workerdir/workerfile is added.
// @bundle is a fixed label, bundlename indicates the bundle name, entryname indicates the module name, and ets indicates the programming language in use.
// workerdir indicates the directory where the worker file is located, and workerfile indicates the worker file name.
// In the stage model, the workers directory is at the same level as the pages directory in the entry module, and bundlename is com.example.workerdemo.
const workerStageModel03 = new worker.ThreadWorker('@bundle:com.example.workerdemo/entry/ets/workers/worker');
// In the stage model, the workers directory is a child directory of the pages directory in the entry module, and bundlename is com.example.workerdemo.
const workerStageModel04 = new worker.ThreadWorker('@bundle:com.example.workerdemo/entry/ets/pages/workers/worker');

Depending on whether the workers directory and pages directory are at the same level, you may need to configure the buildOption attribute in the build-profile.json5 file.

(1) The workers directory and pages directory are at the same level.

In the FA model:

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

In the stage model:

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

(2) The workers directory and pages directory are at different levels.

In the FA model:

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

In the stage model:

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

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

Name	Type	Mandatory	Description
message	Object	Yes	Data to be sent to the worker thread. The data object must be sequenceable. For details about the supported parameter types, see Sequenceable Data Types.
transfer	ArrayBuffer[]	Yes	ArrayBuffer instance holding an array of objects for which the ownership is transferred to the worker thread. After the transfer, the objects are available only in the worker thread. The array cannot be null.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200006	An exception occurred during serialization.

Example

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

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

Name	Type	Mandatory	Description
message	Object	Yes	Data to be sent to the worker thread. The data object must be sequenceable. For details about the supported parameter types, see Sequenceable Data Types.
options	PostMessageOptions	No	If this parameter is specified, it functions the same as ArrayBuffer[]. Specifically, the ownership of the objects in the array is transferred to the worker thread and becomes unavailable in the host thread. The objects are available only in the worker thread. If this parameter is not specified, the default value undefined is used, and information is transferred to the worker thread by copying data.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200006	An exception occurred during serialization.

Example

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

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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to listen for.
listener	WorkerEventListener	Yes	Callback to invoke when an event of the specified type occurs. Callback to invoke when an event of the specified type occurs.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to listen for.
listener	WorkerEventListener	Yes	Callback to invoke when an event of the specified type occurs. Callback to invoke when an event of the specified type occurs.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event for which the event listener is to be removed.
listener	WorkerEventListener	No	Callback to invoke when an event of the specified type occurs. Callback of the event listener to remove.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

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

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.

ID	Error Message
10200004	Worker instance is not running.

Example

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

onexit⁹⁺

onexit?: (code: number) => void

Defines the event handler to be called when the worker thread exits. The handler is executed in the host thread.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
code	number	Yes	Code indicating the worker thread exit state.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.onexit = () => {
 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

Defines the event handler to be called when an exception occurs during worker execution. The event handler is executed in the host thread.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
err	ErrorEvent	Yes	Error data.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

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

onmessage⁹⁺

onmessage?: (event: MessageEvents) => void

Defines the event handler to be 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.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
event	MessageEvents	Yes	Message received.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

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

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

onmessageerror⁹⁺

onmessageerror?: (event: MessageEvents) => void

Defines the event handler to be called when the worker thread receives a message that cannot be serialized. The event handler is executed in the host thread.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
event	MessageEvents	Yes	Error data.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.onmessageerror= () => {
    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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to listen for.
listener	WorkerEventListener	Yes	Callback to invoke when an event of the specified type occurs.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event for which the event listener is to be removed.
callback	WorkerEventListener	No	Callback to invoke when an event of the specified type occurs. Callback of the event listener to remove.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
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

Name	Type	Mandatory	Description
event	Event	Yes	Event to dispatch.

Return value

Type	Description
boolean	Returns true if the event is dispatched successfully; returns false otherwise.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.

Example

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

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.ts");

// 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.

ID	Error Message
10200004	Worker instance is not running.

Example

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

WorkerEventTarget⁹⁺

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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to listen for.
listener	WorkerEventListener	Yes	Callback to invoke when an event of the specified type occurs.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event for which the event listener is to be removed.
callback	WorkerEventListener	No	Callback to invoke when an event of the specified type occurs. Callback of the event listener to remove.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
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

Name	Type	Mandatory	Description
event	Event	Yes	Event to dispatch.

Return value

Type	Description
boolean	Returns true if the event is dispatched successfully; returns false otherwise.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.

Example

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

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.ts");

// 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.

ID	Error Message
10200004	Worker instance is not running.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
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

Name	Type	Mandatory	Description
message	Object	Yes	Data to be sent to the host thread. The data object must be sequenceable. For details about the supported parameter types, see Sequenceable Data Types.
transfer	ArrayBuffer[]	Yes	ArrayBuffer instance holding an array of objects for which the ownership is transferred to the host thread. After the transfer, the objects are available only in the host thread. The array cannot be null.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200006	An exception occurred during serialization.

Example

// Main thread
import worker, { MessageEvents } from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("receive data from worker.ts");
}

// worker.ts
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

Name	Type	Mandatory	Description
message	Object	Yes	Data to be sent to the host thread. The data object must be sequenceable. For details about the supported parameter types, see Sequenceable Data Types.
options	PostMessageOptions	No	If this parameter is specified, it functions the same as ArrayBuffer[]. Specifically, the ownership of the objects in the array is transferred to the host thread and becomes unavailable in the worker thread. The objects are available only in the host thread. If this parameter is not specified, the default value undefined is used, and information is transferred to the host thread by copying data.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200006	An exception occurred during serialization.

Example

// Main thread
import worker, { MessageEvents } from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("receive data from worker.ts");
}

// worker.ts
import worker, { MessageEvents } from '@ohos.worker';
const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    workerPort.postMessage("receive data from main thread");
}

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.

ID	Error Message
10200004	Worker instance is not running.

Example

// Main thread
import worker from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");

// worker.ts
import worker, { MessageEvents } from '@ohos.worker';
const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    workerPort.close()
}

onmessage⁹⁺

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

Defines the event handler to be called when the worker thread receives a message sent by the host thread through postMessage. The event handler is executed in the worker thread.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
this	ThreadWorkerGlobalScope	Yes	Caller.
ev	MessageEvents	Yes	Message received.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

// Main thread
import worker from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.postMessage("hello world");

// worker.ts
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

Defines the event handler to be called when the worker thread receives a message that cannot be deserialized. The event handler is executed in the worker thread.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
this	ThreadWorkerGlobalScope	Yes	Caller.
ev	MessageEvents	Yes	Error data.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

// Main thread
import worker from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");

// worker.ts
import worker from '@ohos.worker';
const workerPort = worker.workerPort;
workerPort.onmessageerror = () => {
    console.log("worker.ts onmessageerror")
}

WorkerEventListener⁹⁺

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

Implements event listening.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
event	Event	Yes	Event class for the callback to invoke.

Return value

Type	Description
void \| Promise<void>	Returns no value or returns a Promise.

Error codes

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

ID	Error Message
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

Example

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.addEventListener("alert", ()=>{
    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

Name	Type	Readable	Writable	Description
name	string	Yes	No	Worker instance specified when there is a new Worker instance.
self	GlobalScope & typeof globalThis	Yes	No	GlobalScope itself.

onerror⁹⁺

onerror?: (ev: ErrorEvent) => void

Defines the event handler to be called when an exception occurs during worker execution. The event handler is executed in the worker thread.

System capability: SystemCapability.Utils.Lang

Parameters

Name	Type	Mandatory	Description
ev	ErrorEvent	Yes	Error data.

Example

// Main thread
import worker from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts")

// worker.ts
import worker from '@ohos.worker';
const workerPort = worker.workerPort
workerPort.onerror = () => {
    console.log("worker.ts onerror")
}

MessageEvents⁹⁺

Holds the data transferred between worker threads.

System capability: SystemCapability.Utils.Lang

Name	Type	Readable	Writable	Description
data	any	Yes	No	Data transferred between threads.

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

Name	Type	Mandatory	Description
scriptURL	string	Yes	Directory of the script to be executed by the Worker instance. In the FA or stage model, DevEco Studio creates a Worker project in either of the following scenarios: (a) The script directory is at the same level as the pages directory. (b) The script directory is at a different level from the pages directory.
options	WorkerOptions	No	Options that can be set for the Worker instance.

Return value

Type	Description
Worker	Returns the Worker instance created; returns undefined if the Worker instance fails to be created.

Example

import worker from '@ohos.worker';
// Create a Worker instance.

// In the FA model, the workers directory is at the same level as the pages directory.
const workerFAModel01 = new worker.Worker("workers/worker.ts", {name:"first worker in FA model"});
// In the FA model, the workers directory is at the same level as the parent directory of the pages directory.
const workerFAModel02 = new worker.Worker("../workers/worker.ts");

// In the stage model, the workers directory is at the same level as the pages directory.
const workerStageModel01 = new worker.Worker('entry/ets/workers/worker.ts', {name:"first worker in Stage model"});
// In the stage model, the workers directory is a child directory of the pages directory.
const workerStageModel02 = new worker.Worker('entry/ets/pages/workers/worker.ts');

// For the script URL "entry/ets/workers/worker.ts" in the stage model:
// entry is the value of the name attribute under module in the module.json5 file.
// ets indicates the programming language in use.

Depending on whether the workers directory and pages directory are at the same level, you may need to configure the buildOption attribute in the build-profile.json5 file.

(1) The workers directory and pages directory are at the same level.

In the FA model:

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

In the stage model:

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

(2) The workers directory and pages directory are at different levels.

In the FA model:

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

In the stage model:

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

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

Name	Type	Mandatory	Description
message	Object	Yes	Data to be sent to the worker thread. The data object must be sequenceable. For details about the supported parameter types, see Sequenceable Data Types.
transfer	ArrayBuffer[]	Yes	ArrayBuffer instance holding an array of objects for which the ownership is transferred to the worker thread. After the transfer, the objects are available only in the worker thread. The array cannot be null.

Example

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

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

Name	Type	Mandatory	Description
message	Object	Yes	Data to be sent to the worker thread. The data object must be sequenceable. For details about the supported parameter types, see Sequenceable Data Types.
options	PostMessageOptions	No	If this parameter is specified, it functions the same as ArrayBuffer[]. Specifically, the ownership of the objects in the array is transferred to the worker thread and becomes unavailable in the host thread. The objects are available only in the worker thread. If this parameter is not specified, the default value undefined is used, and information is transferred to the worker thread by copying data.

Example

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

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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to listen for.
listener	EventListener	Yes	Callback to invoke when an event of the specified type occurs.

Example

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.on("alert", ()=>{
    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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to listen for.
listener	EventListener	Yes	Callback to invoke when an event of the specified type occurs.

Example

const workerInstance = new worker.Worker("workers/worker.ts");
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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event for which the event listener is to be removed.
listener	EventListener	No	Callback of the event listener to remove.

Example

const workerInstance = new worker.Worker("workers/worker.ts");
// 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.ts");
workerInstance.terminate();

onexit^(deprecated)

onexit?: (code: number) => void

Defines the event handler to be called when the worker thread exits. The handler is executed in the host thread.

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

Parameters

Name	Type	Mandatory	Description
code	number	Yes	Code indicating the worker thread exit state.

Example

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.onexit = () => {
    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

Defines the event handler to be called when an exception occurs during worker execution. The event handler is executed in the host thread.

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

Parameters

Name	Type	Mandatory	Description
err	ErrorEvent	Yes	Error data.

Example

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.onerror = function() {
    console.log("onerror");
}

onmessage^(deprecated)

onmessage?: (event: MessageEvent) => void

Defines the event handler to be called when the host thread receives a message sent by the worker thread through parentPort.postMessage. The event handler is executed in the host thread.

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

Parameters

Name	Type	Mandatory	Description
event	MessageEvent<T>	Yes	Message received.

Example

import worker, { MessageEvents } from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("onmessage");
}

onmessageerror^(deprecated)

onmessageerror?: (event: MessageEvent) => void

Defines the event handler to be called when the worker thread receives a message that cannot be serialized. The event handler is executed in the host thread.

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

Parameters

Name	Type	Mandatory	Description
event	MessageEvent<T>	Yes	Error data.

Example

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.onmessageerror= () => {
    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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to listen for.
listener	EventListener	Yes	Callback to invoke when an event of the specified type occurs.

Example

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.addEventListener("alert", ()=>{
    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

Name	Type	Mandatory	Description
type	string	Yes	Type of the event for which the event listener is to be removed.
callback	EventListener	No	Callback of the event listener to remove.

Example

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.addEventListener("alert", ()=>{
    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

Name	Type	Mandatory	Description
event	Event	Yes	Event to dispatch.

Return value

Type	Description
boolean	Returns true if the event is dispatched successfully; returns false otherwise.

Example

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

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.ts");

// 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.ts");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})
workerInstance.removeAllListener();

DedicatedWorkerGlobalScope^(deprecated)

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

Name	Type	Mandatory	Description
messageObject	Object	Yes	Data to be sent to the host thread. The data object must be sequenceable. For details about the supported parameter types, see Sequenceable Data Types.
transfer	Transferable[]	Yes	Currently, this parameter is not supported.

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

Name	Type	Mandatory	Description
message	Object	Yes	Data to be sent to the host thread. The data object must be sequenceable. For details about the supported parameter types, see Sequenceable Data Types.
transfer	ArrayBuffer[]	Yes	ArrayBuffer instance holding an array of objects for which the ownership is transferred to the host thread. After the transfer, the objects are available only in the host thread. The array cannot be null.

Example

// Main thread
import worker, { MessageEvents } from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    // let data = e.data;
    console.log("receive data from worker.ts");
}

// worker.ts
import worker, { MessageEvents } from '@ohos.worker';
const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): 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

Name	Type	Mandatory	Description
message	Object	Yes	Data to be sent to the host thread. The data object must be sequenceable. For details about the supported parameter types, see Sequenceable Data Types.
options	PostMessageOptions	No	If this parameter is specified, it functions the same as ArrayBuffer[]. Specifically, the ownership of the objects in the array is transferred to the host thread and becomes unavailable in the worker thread. The objects are available only in the host thread. If this parameter is not specified, the default value undefined is used, and information is transferred to the host thread by copying data.

Example

// Main thread
import worker, { MessageEvents } from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    // let data = e.data;
    console.log("receive data from worker.ts");
}

// worker.ts
import worker, { MessageEvents } from '@ohos.worker';
const parentPort = worker.parentPort;
parentPort.onmessage = (e: MessageEvents): 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.ts");

// worker.ts
import worker, { MessageEvents } from '@ohos.worker';
const parentPort = worker.parentPort;
parentPort.onmessage = (e: MessageEvents): void => {
    parentPort.close()
}

onmessage^(deprecated)

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

Defines the event handler to be called when the worker thread receives a message sent by the host thread through postMessage. The event handler is executed in the worker thread.

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

Parameters

Name	Type	Mandatory	Description
this	DedicatedWorkerGlobalScope	Yes	Caller.
ev	MessageEvent<T>	Yes	Message received.

Example

// Main thread
import worker from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.postMessage("hello world");

// worker.ts
import worker, { MessageEvents } from '@ohos.worker';
const parentPort = worker.parentPort;
parentPort.onmessage = (e: MessageEvents): void => {
    console.log("receive main thread message");
}

onmessageerror^(deprecated)

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

Defines the event handler to be called when the worker thread receives a message that cannot be deserialized. The event handler is executed in the worker thread.

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

Parameters

Name	Type	Mandatory	Description
this	DedicatedWorkerGlobalScope	Yes	Caller.
ev	MessageEvent<T>	Yes	Error data.

Example

// Main thread
import worker from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.ts");

// worker.ts
import worker from '@ohos.worker';
const parentPort = worker.parentPort;
parentPort.onmessageerror = () => {
    console.log("worker.ts 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

Name	Type	Readable	Writable	Description
transfer	Object[]	Yes	Yes	ArrayBuffer array used to transfer the ownership. The array cannot contain null.

Event

Defines the event.

System capability: SystemCapability.Utils.Lang

Name	Type	Readable	Writable	Description
type	string	Yes	No	Type of the event.
timeStamp	number	Yes	No	Timestamp (accurate to millisecond) when the event is created. This parameter is not supported yet.

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

Name	Type	Mandatory	Description
evt	Event	Yes	Event class for the callback to invoke.

Return value

Type	Description
void \| Promise<void>	Returns no value or returns a Promise.

Example

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.addEventListener("alert", ()=>{
    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

Name	Type	Readable	Writable	Description
message	string	Yes	No	Information about the exception.
filename	string	Yes	No	File where the exception is located.
lineno	number	Yes	No	Serial number of the line where the exception is located.
colno	number	Yes	No	Serial number of the column where the exception is located.
error	Object	Yes	No	Type of the exception.

MessageEvent<T>

Holds the data transferred between worker threads.

System capability: SystemCapability.Utils.Lang

Name	Type	Readable	Writable	Description
data	T	Yes	No	Data transferred between threads.

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

Name	Type	Readable	Writable	Description
name	string	Yes	No	Worker instance specified when there is a new Worker instance.
self	WorkerGlobalScope & typeof globalThis	Yes	No	WorkerGlobalScope.

onerror^(deprecated)

onerror?: (ev: ErrorEvent) => void

Defines the event handler to be called when an exception occurs during worker execution. The event handler is executed in the worker thread.

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

Parameters

Name	Type	Mandatory	Description
ev	ErrorEvent	Yes	Error data.

Example

// Main thread
import worker from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.ts")

// worker.ts
import worker from '@ohos.worker';
const parentPort = worker.parentPort
parentPort.onerror = () => {
    console.log("worker.ts onerror")
}

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.ts");
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.ts
import worker, { MessageEvents } from '@ohos.worker';
const workerPort = worker.workerPort;
class MyModel {
    name = "undefined"
    Init() {
        this.name = "MyModel"
    }
}
workerPort.onmessage = (d: MessageEvents): void => {
    console.log("worker.ts onmessage");
    let data: string = d.data;
    let func1 = () => {
        console.log("post message is function");
    }
    let obj1 = {
        "index": 2,
        "name1": "zhangshan",
        setName() {
            this.index = 3;
        }
    }
    let obj2 = new MyModel();
    // workerPort.postMessage(func1); A serialization error occurs when passing func1.
    // workerPort.postMessage(obj1); A serialization error occurs when passing obj1.
    workerPort.postMessage(obj2);     // No serialization error occurs when passing obj2.
}
workerPort.onmessageerror = () => {
    console.log("worker.ts onmessageerror");
}
workerPort.onerror = () => {
    console.log("worker.ts onerror");
}

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 } from '@ohos.worker';
// Create a Worker instance in the main thread.
const workerInstance = new worker.ThreadWorker("workers/worker.ts");

// 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 = () => {
    console.log("main thread terminate");
}

// worker.ts
import worker, { MessageEvents } 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.ts 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= () => {
    console.log("worker.ts onerror");
}

Configuration of the build-profile.json5 file:

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

Stage Model

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

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

// 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 = () => {
    console.log("main thread terminate");
}

// worker.ts
import worker, { MessageEvents } 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.ts 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= () => {
    console.log("worker.ts onerror");
}

Configuration of the build-profile.json5 file:

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/222fcf22e25044fa9e7620c80272388e

harmony 鸿蒙@ohos.worker (Starting the Worker)

@ohos.worker (Starting the Worker)

Modules to Import

Attributes

WorkerOptions

ThreadWorker9+

constructor9+

postMessage9+

postMessage9+

on9+

once9+

off9+

terminate9+

onexit9+

onerror9+

onmessage9+

onmessageerror9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

WorkerEventTarget9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

ThreadWorkerGlobalScope9+

postMessage9+

postMessage9+

close9+

onmessage9+

onmessageerror9+

WorkerEventListener9+

GlobalScope9+

Attributes

onerror9+

MessageEvents9+

Worker(deprecated)

constructor(deprecated)

postMessage(deprecated)

postMessage(deprecated)

on(deprecated)

once(deprecated)

off(deprecated)

terminate(deprecated)

onexit(deprecated)

onerror(deprecated)

onmessage(deprecated)

onmessageerror(deprecated)

EventTarget(deprecated)

addEventListener(deprecated)

removeEventListener(deprecated)

dispatchEvent(deprecated)

removeAllListener(deprecated)

DedicatedWorkerGlobalScope(deprecated)

postMessage(deprecated)

postMessage9+

postMessage(deprecated)

close(deprecated)

onmessage(deprecated)

onmessageerror(deprecated)

PostMessageOptions

Event

EventListener(deprecated)

ErrorEvent

MessageEvent<T>

WorkerGlobalScope(deprecated)

Attributes

onerror(deprecated)

More Information

Sequenceable Data Types

Memory Model

Sample Code

FA Model

Stage Model

你可能感兴趣的鸿蒙文章

热门推荐

标签云

最新文章

本文目录

ThreadWorker⁹⁺

constructor⁹⁺

postMessage⁹⁺

postMessage⁹⁺

on⁹⁺

once⁹⁺

off⁹⁺

terminate⁹⁺

onexit⁹⁺

onerror⁹⁺

onmessage⁹⁺

onmessageerror⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

WorkerEventTarget⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

ThreadWorkerGlobalScope⁹⁺

postMessage⁹⁺

postMessage⁹⁺

close⁹⁺

onmessage⁹⁺

onmessageerror⁹⁺

WorkerEventListener⁹⁺

GlobalScope⁹⁺

onerror⁹⁺

MessageEvents⁹⁺

Worker^(deprecated)

constructor^(deprecated)

postMessage^(deprecated)

postMessage^(deprecated)

on^(deprecated)

once^(deprecated)

off^(deprecated)

terminate^(deprecated)

onexit^(deprecated)

onerror^(deprecated)

onmessage^(deprecated)

onmessageerror^(deprecated)

EventTarget^(deprecated)

addEventListener^(deprecated)

removeEventListener^(deprecated)

dispatchEvent^(deprecated)

removeAllListener^(deprecated)

DedicatedWorkerGlobalScope^(deprecated)

postMessage^(deprecated)

postMessage⁹⁺

postMessage^(deprecated)

close^(deprecated)

onmessage^(deprecated)

onmessageerror^(deprecated)

EventListener^(deprecated)

WorkerGlobalScope^(deprecated)

onerror^(deprecated)