1# js_worker_module 2 3### Introduction 4 5Worker enables JS to have the ability of multithreading, and completes the communication between worker thread and host thread through PostMessage. 6 7### Interface description 8For interface implementation, see: js_worker_module/jsapi/worker 9 10#### Worker object description 11 12The object object used by the host thread to communicate with the worker thread. 13 14##### Interface 15 161. 17 18- name 19 20|constructor(scriptURL:string, options? WorkerOptions) | worker constructor to Creates a worker instance | 21|---|---| 22 23- example 24 25``` 26import worker from "@ohos.worker" 27const worker = new worker.Worker("workers/worker.js"); 28``` 29 302. 31 32- name 33 34| postMessage(message:Object, options?:PostMessageOptions) | Sends a message to the worker thread | 35|---|---| 36| postMessage(message:Object, transfer:ArrayBuffer[]) | Sends a message to the worker thread | 37 38- example 39 40``` 41// example 1 42import worker from "@ohos.worker" 43const worker = new worker.Worker("workers/worker.js"); 44worker.postMessage("hello world"); 45 46// example 2 47import worker from "@ohos.worker" 48const worker = new worker.Worker("workers/worker.js"); 49var buffer = new ArrayBuffer(8); 50worker.postMessage(buffer, [buffer]); 51``` 52 533. 54 55- name 56 57| on(type:string, listener:EventListener) | Adds an event listener to the worker | 58|---|---| 59 60- example 61 62``` 63import worker from "@ohos.worker" 64const worker = new worker.Worker("workers/worker.js"); 65worker.on("alert", (e)=>{ 66 console.log("worker on..."); 67}) 68``` 69 704. 71 72- name 73 74| once(type:string, listener:EventListener) | Adds an event listener to the worker and removes the event listener automically after it is invoked once | 75|---|---| 76 77- example 78 79``` 80import worker from "@ohos.worker" 81const worker = new worker.Worker("workers/worker.js"); 82worker.once("alert", (e)=>{ 83 console.log("worker on..."); 84}) 85``` 86 875. 88 89- name 90 91| off(type:string, listener?:EventListener) | Removes an event listener to the worker | 92|---|---| 93 94- example 95 96``` 97import worker from "@ohos.worker" 98const worker = new worker.Worker("workers/worker.js"); 99worker.off("alert"); 100``` 101 1026. 103 104- name 105 106| terminate() | Terminates the worker thread to stop the worker from receiving messages | 107|---|---| 108 109- example 110 111``` 112import worker from "@ohos.worker" 113const worker = new worker.Worker("workers/worker.js"); 114worker.terminate(); 115``` 116 1177. 118 119- name 120 121| removeEventListener(type:string, listener?:EventListener) | Removes an event defined for the worker | 122|---|---| 123 124- example 125 126``` 127import worker from "@ohos.worker" 128const worker = new worker.Worker("workers/worker.js"); 129worker.removeEventListener("alert"); 130``` 131 1328. 133 134- name 135 136| dispatchEvent(event: Event) | Dispatches the event defined for the worker | 137|---|---| 138 139- example 140 141``` 142import worker from "@ohos.worker" 143const worker = new worker.Worker("workers/worker.js"); 144worker.dispatchEvent({type:"alert"}); 145``` 146 1479. 148 149- name 150 151| removeAllListener() | Removes all event listeners for the worker | 152|---|---| 153 154- example 155 156``` 157import worker from "@ohos.worker" 158const worker = new worker.Worker("workers/worker.js"); 159worker.removeAllListener(); 160``` 161 162##### Attribute 163 1641. 165 166- name 167 168| onexit?:(code:number)=>void | The onexit attribute of the worker specifies the event handler to be called when the worker exits. The handler is executed in the host thread | 169|---|---| 170 171- example 172 173``` 174import worker from "@ohos.worker" 175const worker = new worker.Worker("workers/worker.js"); 176worker.onexit = function(e) { 177 console.log("onexit..."); 178} 179``` 180 1812. 182 183- name 184 185| onerror?:(ev:ErrorEvent)=>void | The onerror attribute of the worker specifies the event handler to be called when an exception occurs during worker execution. The event handler is executed in the host thread | 186|---|---| 187 188- example 189 190``` 191import worker from "@ohos.worker" 192const worker = new worker.Worker("workers/worker.js"); 193worker.onerror = function(e) { 194 console.log("onerror..."); 195} 196``` 197 1983. 199 200- name 201 202| onmessage?:(ev:MessageEvent)=>void | The onmessage attribute of the worker specifies the event handler to be called then the host thread receives a message created by itself and sent by the worker through the parentPort.postMessage. The event handler is executed in the host thread | 203|---|---| 204 205- example 206 207``` 208import worker from "@ohos.worker" 209const worker = new worker.Worker("workers/worker.js"); 210worker.onmessage = function(e) { 211 console.log("onmessage..."); 212} 213``` 214 2154. 216 217- name 218 219| onmessageerror?:(event:MessageEvent)=>void | The onmessage attribute of the worker specifies the event handler when the worker receives a message that cannot be serialized. The event handler is executed in the host thread | 220|---|---| 221 222- example 223 224``` 225import worker from "@ohos.worker" 226const worker = new worker.Worker("workers/worker.js"); 227worker.onmessageerror = function(e) { 228 console.log("onmessageerror..."); 229} 230``` 231 232#### parentPort object description 233 234Object of the worker thread used to communicate with the host thread 235 236##### Interface 237 2381. 239 240- name 241 242| postMessage(message:Object, options?:PostMessageOptions) | Send a message to host thread | 243|---|---| 244| postMessage(message:Object, transfer:ArrayBuffer[]) | Send a message to host thread | 245 246- example 247 248``` 249// main.js 250import worker from "@ohos.worker" 251const worker = new worker.Worker("workers/worker.js"); 252worker.postMessage("hello world"); 253 254// worker.js 255import worker from "@ohos.worker" 256const parentPort = worker.parentPort; 257parentPort.onmessage = function(e) { 258 parentPort.postMessage("hello world from worker.js"); 259} 260``` 261 2622. 263 264- name 265 266| close() | Close the worker thread to stop the worker from receiving messages | 267|---|---| 268 269- example 270 271``` 272// main.js 273import worker from "@ohos.worker" 274const worker = new worker.Worker("workers/worker.js"); 275worker.postMessage("hello world"); 276 277// worker.js 278import worker from "@ohos.worker" 279const parentPort = worker.parentPort; 280parentPort.onmessage = function(e) { 281 parentPort.close(); 282} 283``` 284 285##### Attribute 286 2871. 288 289- name 290 291| onmessage?:(event:MessageEvent)=>void | The onmessage attribute of parentPort specifies the event handler to be called then the worker thread receives a message sent by the host thread through worker postMessage. The event handler is executed in the worker thread | 292|---|---| 293 294- example 295 296``` 297// main.js 298import worker from "@ohos.worker" 299const worker = new worker.Worker("workers/worker.js"); 300worker.postMessage("hello world"); 301 302// worker.js 303import worker from "@ohos.worker" 304const parentPort = worker.parentPort; 305parentPort.onmessage = function(e) { 306 console.log("receive main.js message"); 307} 308``` 309 3102. 311 312- name 313 314| onerror?:(ev: ErrorEvent)=>void | The onerror attribute of parentPort specifies the event handler to be called when an exception occurs during worker execution. The event handler is executed in the worker thread | 315|---|---| 316 317- example 318 319``` 320// main.js 321import worker from "@ohos.worker" 322const worker = new worker.Worker("workers/worker.js"); 323worker.postMessage("hello world"); 324 325// worker.js 326import worker from "@ohos.worker" 327const parentPort = worker.parentPort; 328parentPort.onerror = function(e) { 329 console.log("onerror..."); 330} 331 332``` 333 3343. 335 336- name 337 338| onmessageerror?:(event: MessageEvent)=>void | The onmessage attribute of parentPort specifies the event handler to be called then the worker receives a message that cannot be deserialized. The event handler is executed in the worker thread. | 339|---|---| 340 341- example 342 343``` 344// main.js 345import worker from "@ohos.worker" 346const worker = new worker.Worker("workers/worker.js"); 347worker.postMessage("hello world"); 348 349// worker.js 350import worker from "@ohos.worker" 351const parentPort = worker.parentPort; 352parentPort.onmessageerror = function(e) { 353 console.log("onmessageerror..."); 354} 355``` 356 357### Repositories Involved 358 359- ace_ace_engine(foundation/ace/ace_engine-readme.md) 360- ace_napi(foundation/ace/napi-readme.md) 361 362## Related warehouse 363[js_worker_module Subsystem](base/compileruntime/js_worker_module-readme.md) 364 365### License 366 367Worker is available under [Mozilla license](https://www.mozilla.org/en-US/MPL/), and the documentation is detailed in [documentation](https://gitee.com/openharmony/js_worker_module/blob/master/mozilla_docs.txt). See [LICENSE](https://gitee.com/openharmony/js_worker_module/blob/master/LICENSE) for the full license text.