diff --git a/en/application-dev/reference/apis/js-apis-worker.md b/en/application-dev/reference/apis/js-apis-worker.md index a9bb769b0eccd89631f4747bcce6deba03c4533a..1b269ea33508c427b9480641ee08210b7906eddc 100644 --- a/en/application-dev/reference/apis/js-apis-worker.md +++ b/en/application-dev/reference/apis/js-apis-worker.md @@ -1,11 +1,13 @@ -# Worker Startup +# @ohos.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. > **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. -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. - ## Modules to Import ```js @@ -17,10 +19,10 @@ import worker from '@ohos.worker'; **System capability**: SystemCapability.Utils.Lang -| Name | Type | Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | --------------------------------- | --------------------------------------------------------- | ---- | ---- | ------------------------------------------------------------ | | workerPort9+ | [ThreadWorkerGlobalScope](#threadworkerglobalscope9) | Yes | Yes | Object of the worker thread used to communicate with the host thread. | -| parentPort(deprecated) | [DedicatedWorkerGlobalScope](#dedicatedworkerglobalscope) | Yes | Yes | Object of the worker thread used to communicate with the host thread.
This attribute is deprecated since API version 9. You are advised to use **workerPort9+** instead.| +| parentPort(deprecated) | [DedicatedWorkerGlobalScope](#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 **workerPort9+** instead.| ## WorkerOptions @@ -31,7 +33,9 @@ Provides options that can be set for the **Worker** instance to create. | Name| Type| Readable| Writable| Description | | ---- | -------- | ---- | ---- | -------------- | +| type | "classic" \| "module" | Yes | Yes | Mode in which the **Worker** instance executes the script. The default value is **classic**. The module **type** is not supported yet.| | name | string | Yes | Yes | Name of the worker thread.| +| shared | boolean | Yes | Yes | Sharing of the **Worker** instance is not supported yet.| ## ThreadWorker9+ @@ -166,7 +170,7 @@ workerInstance.postMessage(buffer, [buffer]); on(type: string, listener: WorkerEventListener): void -Adds an event listener for the worker thread. +Adds an event listener for the worker thread. This API provides the same functionality as [addEventListener9+](#addeventlistener9). **System capability**: SystemCapability.Utils.Lang @@ -216,7 +220,7 @@ workerInstance.once("alert", (e)=>{ off(type: string, listener?: WorkerEventListener): void -Removes an event listener for the worker thread. +Removes an event listener for the worker thread. This API provides the same functionality as [removeEventListener9+](#removeeventlistener9). **System capability**: SystemCapability.Utils.Lang @@ -231,6 +235,7 @@ Removes an event listener for the worker thread. ```js const workerInstance = new worker.ThreadWorker("workers/worker.js"); +// Use on, once, or addEventListener to add a listener for the "alert" event, and use off to remove the listener. workerInstance.off("alert"); ``` @@ -263,7 +268,7 @@ Defines the event handler to be called when the worker thread exits. The handler | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------ | -| code | number | No | Code indicating the worker thread exit state.| +| code | number | Yes | Code indicating the worker thread exit state.| **Example** @@ -272,6 +277,13 @@ const workerInstance = new worker.ThreadWorker("workers/worker.js"); workerInstance.onexit = function(e) { console.log("onexit"); } + +// onexit is executed in either of the following ways: +// Main thread: +workerInstance.terminate(); + +// Worker thread: +//parentPort.close() ``` @@ -287,7 +299,7 @@ Defines the event handler to be called when an exception occurs during worker ex | Name| Type | Mandatory| Description | | ------ | ------------------------- | ---- | ---------- | -| err | [ErrorEvent](#errorevent) | No | Error data.| +| err | [ErrorEvent](#errorevent) | Yes | Error data.| **Example** @@ -301,7 +313,7 @@ workerInstance.onerror = function(e) { ### onmessage9+ -onmessage?: (event: MessageEvent\) => void +onmessage?: (event: MessageEvents) => 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. @@ -309,16 +321,16 @@ Defines the event handler to be called when the host thread receives a message s **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----------------------------- | ---- | ---------------------- | -| event | [MessageEvent](#messageevent) | No | Message received.| +| Name| Type | Mandatory| Description | +| ------ | -------------------------------- | ---- | ---------------------- | +| event | [MessageEvents](#messageevents9) | Yes | Message received.| **Example** ```js const workerInstance = new worker.ThreadWorker("workers/worker.js"); workerInstance.onmessage = function(e) { - // e: MessageEvent. The usage is as follows: + // e: MessageEvents. The usage is as follows: // let data = e.data; console.log("onmessage"); } @@ -327,7 +339,7 @@ workerInstance.onmessage = function(e) { ### onmessageerror9+ -onmessageerror?: (event: MessageEvent\) => void +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. @@ -335,9 +347,9 @@ Defines the event handler to be called when the worker thread receives a message **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----------------------------- | ---- | ---------- | -| event | [MessageEvent](#messageevent) | No | Error data.| +| Name| Type | Mandatory| Description | +| ------ | -------------------------------- | ---- | ---------- | +| event | [MessageEvents](#messageevents9) | Yes | Error data.| **Example** @@ -355,7 +367,7 @@ workerInstance.onmessageerror= function(e) { addEventListener(type: string, listener: WorkerEventListener): void -Adds an event listener for the worker thread. +Adds an event listener for the worker thread. This API provides the same functionality as [on9+](#on9). **System capability**: SystemCapability.Utils.Lang @@ -380,7 +392,7 @@ workerInstance.addEventListener("alert", (e)=>{ removeEventListener(type: string, callback?: WorkerEventListener): void -Removes an event listener for the worker thread. +Removes an event listener for the worker thread. This API provides the same functionality as [off9+](#off9). **System capability**: SystemCapability.Utils.Lang @@ -395,6 +407,9 @@ Removes an event listener for the worker thread. ```js const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.addEventListener("alert", (e)=>{ + console.log("alert listener callback"); +}) workerInstance.removeEventListener("alert"); ``` @@ -423,7 +438,41 @@ Dispatches the event defined for the worker thread. ```js const workerInstance = new worker.ThreadWorker("workers/worker.js"); -workerInstance.dispatchEvent({type:"alert"}); +// 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}); +// The event listener created by on will be always valid and 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 be always valid and 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}); ``` @@ -439,13 +488,16 @@ Removes all event listeners for the worker thread. ```js const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.addEventListener("alert", (e)=>{ + console.log("alert listener callback"); +}) workerInstance.removeAllListener(); ``` ## ThreadWorkerGlobalScope9+ -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 **DedicatedWorkerGlobalScope** class inherits from [GlobalScope9+](#globalscope9). +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 [GlobalScope9+](#globalscope9). ### postMessage9+ @@ -515,7 +567,7 @@ parentPort.onmessage = function(e) { ### onmessage9+ -onmessage?: (event: MessageEvent\) => void +onmessage?: (this: ThreadWorkerGlobalScope, event: 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. @@ -523,9 +575,10 @@ Defines the event handler to be called when the worker thread receives a message **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----------------------------- | ---- | ------------------------ | -| event | [MessageEvent](#messageevent) | No | Message received.| +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------------------------- | ---- | ------------------------ | +| this | [ThreadWorkerGlobalScope](#threadworkerglobalscope9) | Yes | Caller. | +| event | [MessageEvents](#messageevents9) | Yes | Message received.| **Example** @@ -548,7 +601,7 @@ parentPort.onmessage = function(e) { ### onmessageerror9+ -onmessageerror?: (event: MessageEvent\) => void +onmessageerror?: (this: ThreadWorkerGlobalScope, event: 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. @@ -556,9 +609,10 @@ Defines the event handler to be called when the worker thread receives a message **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----------------------------- | ---- | ---------- | -| event | [MessageEvent](#messageevent) | No | Error data.| +| Name| Type | Mandatory| Description | +| ------ | -------------------------------- | ---- | ---------- | +| this | [ThreadWorkerGlobalScope](#threadworkerglobalscope9) | Yes | Caller. | +| event | [MessageEvents](#messageevents9) | Yes | Error data.| **Example** @@ -572,7 +626,7 @@ const workerInstance = new worker.ThreadWorker("workers/worker.js"); // worker.js import worker from '@ohos.worker'; const parentPort = worker.workerPort; -parentPort.onmessageerror= function(e) { +parentPort.onmessageerror = function(e) { console.log("worker.js onmessageerror") } ``` @@ -610,13 +664,13 @@ workerInstance.addEventListener("alert", (e)=>{ ## GlobalScope9+ -Implements the running environment of the worker thread. The **WorkerGlobalScope** class inherits from [WorkerEventTarget](#workereventtarget9). +Implements the running environment of the worker thread. The **GlobalScope** class inherits from [WorkerEventTarget](#workereventtarget9). ### Attributes **System capability**: SystemCapability.Utils.Lang -| Name| Type | Readable| Writable| Description | +| Name| Type | Readable| Writable| Description | | ---- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------- | | name | string | Yes | No | **Worker** instance specified when there is a new **Worker** instance.| | self | [GlobalScope](#globalscope9) & typeof globalThis | Yes | No | **GlobalScope** itself. | @@ -634,7 +688,7 @@ Defines the event handler to be called when an exception occurs during worker ex | Name| Type | Mandatory| Description | | ------ | ------------------------- | ---- | ---------- | -| ev | [ErrorEvent](#errorevent) | No | Error data.| +| ev | [ErrorEvent](#errorevent) | Yes | Error data.| **Example** @@ -653,22 +707,33 @@ parentPort.onerror = function(e){ } ``` +## MessageEvents9+ + +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) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker9+](#threadworker9) instead. Before using the following APIs, you must create a **Worker** instance. The **Worker** class inherits from [EventTarget](#eventtarget). -### constructor(deprecated) > **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.constructor9+](#constructor9) instead. +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [ThreadWorker9+](#threadworker9) 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.constructor9+](#constructor9) instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** @@ -753,13 +818,13 @@ In the stage model: ``` ### postMessage(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.postMessage9+](#postmessage9) instead. - postMessage(message: Object, options?: PostMessageOptions): void Sends a message to the worker thread. The data type of the message must be sequenceable. For details about the sequenceable data types, see [More Information](#more-information). +> **NOTE**
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [ThreadWorker.postMessage9+](#postmessage9) instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** @@ -783,12 +848,12 @@ workerInstance.postMessage(buffer, [buffer]); ### on(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.on9+](#on9) instead. - on(type: string, listener: EventListener): void -Adds an event listener for the worker thread. +Adds an event listener for the worker thread. This API provides the same functionality as [addEventListener(deprecated)](#addeventlistenerdeprecated). + +> **NOTE**
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [ThreadWorker.on9+](#on9) instead. **System capability**: SystemCapability.Utils.Lang @@ -811,13 +876,13 @@ workerInstance.on("alert", (e)=>{ ### once(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.once9+](#once9) instead. - 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.once9+](#once9) instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** @@ -839,12 +904,12 @@ workerInstance.once("alert", (e)=>{ ### off(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.off9+](#off9) instead. - off(type: string, listener?: EventListener): void -Removes an event listener for the worker thread. +Removes an event listener for the worker thread. This API provides the same functionality as [removeEventListener(deprecated)](#removeeventlistenerdeprecated). + +> **NOTE**
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [ThreadWorker.off9+](#off9) instead. **System capability**: SystemCapability.Utils.Lang @@ -859,19 +924,20 @@ Removes an event listener for the worker thread. ```js const workerInstance = new worker.Worker("workers/worker.js"); +// 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) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.terminate9+](#terminate9) instead. - 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.terminate9+](#terminate9) instead. + **System capability**: SystemCapability.Utils.Lang **Example** @@ -884,20 +950,20 @@ workerInstance.terminate(); ### onexit(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.onexit9+](#onexit9) instead. - 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.onexit9+](#onexit9) instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------ | -| code | number | No | Code indicating the worker thread exit state.| +| code | number | Yes | Code indicating the worker thread exit state.| **Example** @@ -906,25 +972,32 @@ const workerInstance = new worker.Worker("workers/worker.js"); workerInstance.onexit = function(e) { console.log("onexit"); } + +// onexit is executed in either of the following ways: +// Main thread: +workerInstance.terminate(); + +// Worker thread: +//parentPort.close() ``` ### onerror(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.onerror9+](#onerror9) instead. - 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.onerror9+](#onerror9) instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** | Name| Type | Mandatory| Description | | ------ | ------------------------- | ---- | ---------- | -| err | [ErrorEvent](#errorevent) | No | Error data.| +| err | [ErrorEvent](#errorevent) | Yes | Error data.| **Example** @@ -938,27 +1011,27 @@ workerInstance.onerror = function(e) { ### onmessage(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.onmessage9+](#onmessage9) instead. - -onmessage?: (event: MessageEvent\) => void +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.onmessage9+](#onmessage9) instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----------------------------- | ---- | ---------------------- | -| event | [MessageEvent](#messageevent) | No | Message received.| +| Name| Type | Mandatory| Description | +| ------ | ------------------------------ | ---- | ---------------------- | +| event | [MessageEvent](#messageeventt) | Yes | Message received.| **Example** ```js const workerInstance = new worker.Worker("workers/worker.js"); workerInstance.onmessage = function(e) { - // e: MessageEvent. The usage is as follows: + // e: MessageEvent. The usage is as follows: // let data = e.data; console.log("onmessage"); } @@ -967,20 +1040,20 @@ workerInstance.onmessage = function(e) { ### onmessageerror(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorker.onmessageerror9+](#onmessageerror9) instead. - -onmessageerror?: (event: MessageEvent\) => void +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.onmessageerror9+](#onmessageerror9) instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----------------------------- | ---- | ---------- | -| event | [MessageEvent](#messageevent) | No | Error data.| +| Name| Type | Mandatory| Description | +| ------ | ------------------------------ | ---- | ---------- | +| event | [MessageEvent](#messageeventt) | Yes | Error data.| **Example** @@ -994,16 +1067,16 @@ workerInstance.onmessageerror= function(e) { ## EventTarget(deprecated) > **NOTE**
-> This API is deprecated since API version 9. You are advised to use [WorkerEventTarget9+](#workereventtarget9) instead. +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [WorkerEventTarget9+](#workereventtarget9) instead. ### addEventListener(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [addEventListener9+](#addeventlistener9) instead. - addEventListener(type: string, listener: EventListener): void -Adds an event listener for the worker thread. +Adds an event listener for the worker thread. This API provides the same functionality as [on(deprecated)](#ondeprecated). + +> **NOTE**
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addEventListener9+](#addeventlistener9) instead. **System capability**: SystemCapability.Utils.Lang @@ -1026,12 +1099,12 @@ workerInstance.addEventListener("alert", (e)=>{ ### removeEventListener(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [removeEventListener9+](#removeeventlistener9) instead. - removeEventListener(type: string, callback?: EventListener): void -Removes an event listener for the worker thread. +Removes an event listener for the worker thread. This API provides the same functionality as [off(deprecated)](#offdeprecated). + +> **NOTE**
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [removeEventListener9+](#removeeventlistener9) instead. **System capability**: SystemCapability.Utils.Lang @@ -1046,19 +1119,22 @@ Removes an event listener for the worker thread. ```js const workerInstance = new worker.Worker("workers/worker.js"); +workerInstance.addEventListener("alert", (e)=>{ + console.log("alert listener callback"); +}) workerInstance.removeEventListener("alert"); ``` ### dispatchEvent(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [dispatchEvent9+](#dispatchevent9) instead. - 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 [dispatchEvent9+](#dispatchevent9) instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** @@ -1077,46 +1153,81 @@ Dispatches the event defined for the worker thread. ```js const workerInstance = new worker.Worker("workers/worker.js"); -workerInstance.dispatchEvent({type:"alert"}); -``` +// 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}); +// 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) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [removeAllListener9+](#removealllistener9) instead. - 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 [removeAllListener9+](#removealllistener9) instead. + **System capability**: SystemCapability.Utils.Lang **Example** ```js const workerInstance = new worker.Worker("workers/worker.js"); +workerInstance.addEventListener("alert", (e)=>{ + console.log("alert listener callback"); +}) workerInstance.removeAllListener(); ``` ## DedicatedWorkerGlobalScope(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9) instead. - 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](#workerglobalscope). +> **NOTE**
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9) instead. ### postMessage(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).postMessage9+ instead. - postMessage(messageObject: Object, options?: PostMessageOptions): void Sends a message to the host thread from the worker thread. +> **NOTE**
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).postMessage9+ instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** @@ -1151,13 +1262,13 @@ parentPort.onmessage = function(e){ ### close(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).close9+ instead. - 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 [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).close9+ instead. + **System capability**: SystemCapability.Utils.Lang **Example** @@ -1179,20 +1290,21 @@ parentPort.onmessage = function(e) { ### onmessage(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).onmessage9+ instead. - -onmessage?: (event: MessageEvent\) => void +onmessage?: (this: DedicatedWorkerGlobalScope, event: 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 [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).onmessage9+ instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----------------------------- | ---- | ------------------------ | -| event | [MessageEvent](#messageevent) | No | Message received.| +| Name| Type | Mandatory| Description | +| ------ | ------------------------------------------------------------ | ---- | ------------------------ | +| this | [DedicatedWorkerGlobalScope](#dedicatedworkerglobalscopedeprecated) | Yes | Caller. | +| event | [MessageEvent](#messageeventt) | Yes | Message received.| **Example** @@ -1214,20 +1326,21 @@ parentPort.onmessage = function(e) { ### onmessageerror(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).onmessageerror9+ instead. - -onmessageerror?: (event: MessageEvent\) => void +onmessageerror?: (this: DedicatedWorkerGlobalScope, event: 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 [ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).onmessageerror9+ instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----------------------------- | ---- | ---------- | -| event | [MessageEvent](#messageevent) | No | Error data.| +| Name| Type | Mandatory| Description | +| ------ | ------------------------------ | ---- | ---------- | +| this | [DedicatedWorkerGlobalScope](#dedicatedworkerglobalscopedeprecated) | Yes | Caller.| +| event | [MessageEvent](#messageeventt) | Yes | Error data.| **Example** @@ -1240,7 +1353,7 @@ const workerInstance = new worker.Worker("workers/worker.js"); // worker.js import worker from '@ohos.worker'; const parentPort = worker.parentPort; -parentPort.onmessageerror= function(e) { +parentPort.onmessageerror = function(e) { console.log("worker.js onmessageerror") } ``` @@ -1252,7 +1365,7 @@ Specifies the object whose ownership needs to be transferred during data transfe **System capability**: SystemCapability.Utils.Lang -| Name | Type| Readable| Writable| Description | +| Name | Type | Readable| Writable| Description | | -------- | -------- | ---- | ---- | --------------------------------- | | transfer | Object[] | Yes | Yes | **ArrayBuffer** array used to transfer the ownership.| @@ -1263,21 +1376,21 @@ 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.| +| 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.| ## EventListener(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [WorkerEventListener9+](#workereventlistener9) instead. - (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 [WorkerEventListener9+](#workereventlistener9) instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** @@ -1308,38 +1421,38 @@ Provides detailed information about the exception that occurs during worker exec **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. | +| 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 +## MessageEvent\ 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.| +| ---- | ---- | ---- | ---- | ------------------ | +| data | T | Yes | No | Data transferred between threads.| ## WorkerGlobalScope(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [GlobalScope9+](#globalscope9) instead. - Implements the running environment of the worker thread. The **WorkerGlobalScope** class inherits from [EventTarget](#eventtarget). +> **NOTE**
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [GlobalScope9+](#globalscope9) instead. + ### Attributes **System capability**: SystemCapability.Utils.Lang -| Name| Type | Readable| Writable| Description | +| Name| Type | Readable| Writable| Description | | ---- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------- | | name | string | Yes | No | **Worker** instance specified when there is a new **Worker** instance.| | self | [WorkerGlobalScope](#workerglobalscope) & typeof globalThis | Yes | No | **WorkerGlobalScope**. | @@ -1347,20 +1460,20 @@ Implements the running environment of the worker thread. The **WorkerGlobalScope ### onerror(deprecated) -> **NOTE**
-> This API is deprecated since API version 9. You are advised to use [GlobalScope9+](#globalscope9).onerror instead. - 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 [GlobalScope9+](#globalscope9).onerror instead. + **System capability**: SystemCapability.Utils.Lang **Parameters** | Name| Type | Mandatory| Description | | ------ | ------------------------- | ---- | ---------- | -| ev | [ErrorEvent](#errorevent) | No | Error data.| +| ev | [ErrorEvent](#errorevent) | Yes | Error data.| **Example** @@ -1402,7 +1515,7 @@ Exception: When an object created through a custom class is passed, no serializa ```js // main.js import worker from '@ohos.worker'; -const workerInstance = new worker.Thread("workers/worker.js"); +const workerInstance = new worker.ThreadWorker("workers/worker.js"); workerInstance.postMessage("message from main to worker"); workerInstance.onmessage = function(d) { // When the worker thread passes obj2, data contains obj2, excluding the Init or SetName method. @@ -1414,12 +1527,9 @@ workerInstance.onmessage = function(d) { import worker from '@ohos.worker'; const parentPort = worker.workerPort; class MyModel { + name = "undefined" Init() { - this.name = "wzy" - this.age = 18 - } - SetName() { - this.name = "WZY" + this.name = "MyModel" } } parentPort.onmessage = function(d) { @@ -1460,6 +1570,7 @@ Each actor concurrently processes tasks of the main thread. For each actor, ther - To proactively destroy a worker thread, you can call **terminate()** or **parentPort.close()** of the newly created **Worker** instance. - Since API version 9, if a **Worker** instance in a non-running state (such as destroyed or being destroyed) calls an API, a business error is thrown. - Creating and terminating worker threads consume performance. Therefore, you are advised to manage available workers and reuse them. +- Do not use both **new worker.Worker** and **new worker.ThreadWorker** to create a **Worker** project. Otherwise, **Worker** functions abnormally. Since API version 9, you are advised to use [new worker.ThreadWorker](#constructor9). In API version 8 and earlier versions, you are advised to use [new worker.Worker](#constructordeprecated). ## Sample Code > **NOTE**
@@ -1589,3 +1700,4 @@ Configuration of the **build-profile.json5** file: } } ``` +