1/* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17* Provides options that can be set for the worker to create. 18* @since 7 19* @syscap SystemCapability.Utils.Lang 20*/ 21export interface WorkerOptions { 22 /** 23 * Mode in which the worker executes the script. 24 * @since 7 25 * @syscap SystemCapability.Utils.Lang 26 */ 27 type?: "classic" | "module"; 28 29 /** 30 * Name of the worker. 31 * @since 7 32 * @syscap SystemCapability.Utils.Lang 33 */ 34 name?: string; 35 36 /** 37 * Whether the worker is shared. 38 * @since 7 39 * @syscap SystemCapability.Utils.Lang 40 */ 41 shared?: boolean; 42} 43 44/** 45 * Defines the event. 46 * @since 7 47 * @syscap SystemCapability.Utils.Lang 48 */ 49export interface Event { 50 /** 51 * Type of the Event. 52 * @since 7 53 * @syscap SystemCapability.Utils.Lang 54 */ 55 readonly type: string; 56 57 /** 58 * Timestamp(accurate to millisecond) when the event is created. 59 * @since 7 60 * @syscap SystemCapability.Utils.Lang 61 */ 62 readonly timeStamp: number; 63} 64 65/** 66 * Provides detailed information about the exception occurred during worker execution. 67 * @since 7 68 * @syscap SystemCapability.Utils.Lang 69 */ 70 export interface ErrorEvent extends Event { 71 /** 72 * Information about the exception. 73 * @since 7 74 * @syscap SystemCapability.Utils.Lang 75 */ 76 readonly message: string; 77 78 /** 79 * File where the exception is located. 80 * @since 7 81 * @syscap SystemCapability.Utils.Lang 82 */ 83 readonly filename: string; 84 85 /** 86 * Number of the line where the exception is located. 87 * @since 7 88 * @syscap SystemCapability.Utils.Lang 89 */ 90 readonly lineno: number; 91 92 /** 93 * Number of the column where the exception is located. 94 * @since 7 95 * @syscap SystemCapability.Utils.Lang 96 */ 97 readonly colno: number; 98 99 /** 100 * Type of the exception. 101 * @since 7 102 * @syscap SystemCapability.Utils.Lang 103 */ 104 readonly error: Object; 105} 106 107/** 108 * Holds the data transferred between worker threads. 109 * @since 7 110 * @syscap SystemCapability.Utils.Lang 111 */ 112 export interface MessageEvent<T> extends Event { 113 /** 114 * Data transferred when an exception occurs. 115 * @since 7 116 * @syscap SystemCapability.Utils.Lang 117 */ 118 readonly data: T; 119} 120 121/** 122 * Specifies the object whose ownership need to be transferred during data transfer. 123 * The object must be ArrayBuffer. 124 * @since 7 125 * @syscap SystemCapability.Utils.Lang 126 */ 127export interface PostMessageOptions { 128 /** 129 * ArrayBuffer array used to transfer the ownership. 130 * @since 7 131 * @syscap SystemCapability.Utils.Lang 132 */ 133 transfer?: Object[]; 134} 135 136/** 137 * Implements evemt listening. 138 * @since 7 139 * @syscap SystemCapability.Utils.Lang 140 */ 141export interface EventListener { 142 /** 143 * Specifies the callback to invoke. 144 * @param evt Event class for the callback to invoke. 145 * @since 7 146 * @syscap SystemCapability.Utils.Lang 147 */ 148 (evt: Event): void | Promise<void>; 149} 150 151/** 152 * Type of message, only "message" and "messageerror". 153 * @since 7 154 * @syscap SystemCapability.Utils.Lang 155 */ 156type MessageType = "message" | "messageerror"; 157 158/** 159 * Specific event features. 160 * @since 7 161 * @syscap SystemCapability.Utils.Lang 162 */ 163 export interface EventTarget { 164 /** 165 * Adds an event listener to the worker. 166 * @param type Type of the event to listen for. 167 * @param listener Callback to invoke when an event of the specified type occurs. 168 * @since 7 169 * @syscap SystemCapability.Utils.Lang 170 */ 171 addEventListener( 172 type: string, 173 listener: EventListener 174 ): void; 175 176 /** 177 * Dispatches the event defined for the worker. 178 * @param event Event to dispatch. 179 * @since 7 180 * @syscap SystemCapability.Utils.Lang 181 */ 182 dispatchEvent(event: Event): boolean; 183 184 /** 185 * Removes an event defined for the worker. 186 * @param type Type of the event for which the event listener is removed. 187 * @param callback Callback of the event listener to remove. 188 * @since 7 189 * @syscap SystemCapability.Utils.Lang 190 */ 191 removeEventListener( 192 type: string, 193 callback?: EventListener 194 ): void; 195 196 /** 197 * Removes all event listeners for the worker. 198 * @since 7 199 * @syscap SystemCapability.Utils.Lang 200 */ 201 removeAllListener(): void; 202} 203 204/** 205 * Specifies the worker thread running environment, which is isolated from the host thread environment. 206 * @since 7 207 * @syscap SystemCapability.Utils.Lang 208 */ 209declare interface WorkerGlobalScope extends EventTarget { 210 /** 211 * Worker name specified when there is a new worker. 212 * @since 7 213 * @syscap SystemCapability.Utils.Lang 214 */ 215 readonly name: string; 216 217 /** 218 * The onerror attribute of parentPort specifies 219 * the event handler to be called when an exception occurs during worker execution. 220 * The event handler is executed in the worker thread. 221 * @param ev Error data. 222 * @since 7 223 * @syscap SystemCapability.Utils.Lang 224 */ 225 onerror?: (ev: ErrorEvent) => void; 226 readonly self: WorkerGlobalScope & typeof globalThis; 227} 228 229/** 230 * Specifies the worker thread running environment, which is isolated from the host thread environment 231 * @since 7 232 * @syscap SystemCapability.Utils.Lang 233 */ 234 export interface DedicatedWorkerGlobalScope extends WorkerGlobalScope { 235 /** 236 * The onmessage attribute of parentPort specifies the event handler 237 * to be called then the worker thread receives a message sent by 238 * the host thread through worker postMessage. 239 * The event handler is executed in the worker thread. 240 * @param ev Message received. 241 * @since 7 242 * @syscap SystemCapability.Utils.Lang 243 */ 244 onmessage?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent<T>) => void; 245 246 /** 247 * The onmessage attribute of parentPort specifies the event handler 248 * to be called then the worker receives a message that cannot be deserialized. 249 * The event handler is executed in the worker thread. 250 * @param ev Error data. 251 * @since 7 252 * @syscap SystemCapability.Utils.Lang 253 */ 254 onmessageerror?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent<T>) => void; 255 256 /** 257 * Close the worker thread to stop the worker from receiving messages 258 * @since 7 259 * @syscap SystemCapability.Utils.Lang 260 */ 261 close(): void; 262 263 /** 264 * Send a message to be host thread from the worker 265 * @param messageObject Data to be sent to the worker 266 * @param transfer array cannot contain null. 267 * @since 7 268 * @deprecated since 9 269 * @syscap SystemCapability.Utils.Lang 270 */ 271 postMessage(messageObject: Object, transfer: Transferable[]): void; 272 postMessage(messageObject: Object, options?: PostMessageOptions): void; 273 274 /** 275 * Send a message to host thread from the worker 276 * @param messageObject Data to be sent to the worker 277 * @param transfer array cannot contain null. 278 * @since 9 279 * @syscap SystemCapability.Utils.Lang 280 */ 281 postMessage(messageObject: Object, transfer: ArrayBuffer[]): void; 282} 283 284/** 285 * JS cross-thread communication tool 286 * @since 7 287 * @syscap SystemCapability.Utils.Lang 288 */ 289declare namespace worker { 290 class Worker implements EventTarget { 291 /** 292 * Creates a worker instance 293 * @param scriptURL URL of the script to be executed by the worker 294 * @param options Options that can be set for the worker 295 * @since 7 296 * @syscap SystemCapability.Utils.Lang 297 */ 298 constructor(scriptURL: string, options?: WorkerOptions); 299 300 /** 301 * The onexit attribute of the worker specifies the event handler to be called 302 * when the worker exits. The handler is executed in the host thread. 303 * @param code Code indicating the worker exit state 304 * @since 7 305 * @syscap SystemCapability.Utils.Lang 306 */ 307 onexit?: (code: number) => void; 308 309 /** 310 * The onerror attribute of the worker specifies the event handler to be called 311 * when an exception occurs during worker execution. 312 * The event handler is executed in the host thread. 313 * @since 7 314 * @syscap SystemCapability.Utils.Lang 315 */ 316 onerror?: (err: ErrorEvent) => void; 317 318 /** 319 * The onmessage attribute of the worker specifies the event handler 320 * to be called then the host thread receives a message created by itself 321 * and sent by the worker through the parentPort.postMessage. 322 * The event handler is executed in the host thread. 323 * @param event Message received. 324 * @since 7 325 * @syscap SystemCapability.Utils.Lang 326 */ 327 onmessage?: (event: MessageEvent<T>) => void; 328 329 /** 330 * The onmessage attribute of the worker specifies the event handler 331 * when the worker receives a message that cannot be serialized. 332 * The event handler is executed in the host thread. 333 * @since 7 334 * @syscap SystemCapability.Utils.Lang 335 */ 336 onmessageerror?: (event: MessageEvent<T>) => void; 337 338 /** 339 * Sends a message to the worker thread. 340 * The data is transferred using the structured clone algorithm. 341 * @param message Data to be sent to the worker 342 * @param transfer ArrayBuffer instance that can be transferred. 343 * The transferList array cannot contain null. 344 * @since 7 345 * @syscap SystemCapability.Utils.Lang 346 */ 347 postMessage(message: Object, transfer: ArrayBuffer[]): void; 348 postMessage(message: Object, options?: PostMessageOptions): void; 349 350 /** 351 * Adds an event listener to the worker. 352 * @param type Adds an event listener to the worker. 353 * @param listener Callback to invoke when an event of the specified type occurs. 354 * @since 7 355 * @syscap SystemCapability.Utils.Lang 356 */ 357 on(type: string, listener: EventListener): void; 358 359 /** 360 * Adds an event listener to the worker 361 * and removes the event listener automatically after it is invoked once. 362 * @param type Type of the event to listen for 363 * @param listener Callback to invoke when an event of the specified type occurs 364 * @since 7 365 * @syscap SystemCapability.Utils.Lang 366 */ 367 once(type: string, listener: EventListener): void; 368 369 /** 370 * Removes an event listener to the worker. 371 * @param type Type of the event for which the event listener is removed. 372 * @param listener Callback of the event listener to remove. 373 * @since 7 374 * @syscap SystemCapability.Utils.Lang 375 */ 376 off(type: string, listener?: EventListener): void; 377 378 /** 379 * Terminates the worker thread to stop the worker from receiving messages 380 * @since 7 381 * @syscap SystemCapability.Utils.Lang 382 */ 383 terminate(): void; 384 } 385 const parentPort: DedicatedWorkerGlobalScope; 386} 387 388export default worker;