1/* 2 * Copyright (c) 2022 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 * JS cross-thread task executor. 18 * 19 * @namespace taskpool 20 * @syscap SystemCapability.Utils.Lang 21 * @since 9 22 */ 23/** 24 * JS cross-thread task executor. 25 * 26 * @namespace taskpool 27 * @syscap SystemCapability.Utils.Lang 28 * @crossplatform 29 * @since 10 30 */ 31declare namespace taskpool { 32 /** 33 * The Priority defines the task priority. 34 * 35 * @enum { number } Priority 36 * @syscap SystemCapability.Utils.Lang 37 * @since 9 38 */ 39 /** 40 * The Priority defines the task priority. 41 * 42 * @enum { number } Priority 43 * @syscap SystemCapability.Utils.Lang 44 * @crossplatform 45 * @since 10 46 */ 47 enum Priority { 48 /** 49 * set task priority to high. 50 * 51 * @syscap SystemCapability.Utils.Lang 52 * @since 9 53 */ 54 /** 55 * set task priority to high. 56 * 57 * @syscap SystemCapability.Utils.Lang 58 * @crossplatform 59 * @since 10 60 */ 61 HIGH = 0, 62 63 /** 64 * set task priority to medium. 65 * 66 * @syscap SystemCapability.Utils.Lang 67 * @since 9 68 */ 69 /** 70 * set task priority to medium. 71 * 72 * @syscap SystemCapability.Utils.Lang 73 * @crossplatform 74 * @since 10 75 */ 76 MEDIUM = 1, 77 78 /** 79 * set task priority to low. 80 * 81 * @syscap SystemCapability.Utils.Lang 82 * @since 9 83 */ 84 /** 85 * set task priority to low. 86 * 87 * @syscap SystemCapability.Utils.Lang 88 * @crossplatform 89 * @since 10 90 */ 91 LOW = 2 92 } 93 94 /** 95 * The Task class provides an interface to create a task. 96 * 97 * @syscap SystemCapability.Utils.Lang 98 * @since 9 99 */ 100 /** 101 * The Task class provides an interface to create a task. 102 * 103 * @syscap SystemCapability.Utils.Lang 104 * @crossplatform 105 * @since 10 106 */ 107 class Task { 108 /** 109 * Create a Task instance. 110 * 111 * @param { Function } func - func func Concurrent function to execute in taskpool. 112 * @param { unknown[] } args - args args The concurrent function arguments. 113 * @throws { BusinessError } 401 - The input parameters are invalid. 114 * @throws { BusinessError } 10200014 - The function is not mark as concurrent. 115 * @syscap SystemCapability.Utils.Lang 116 * @since 9 117 */ 118 /** 119 * Create a Task instance. 120 * 121 * @param { Function } func - func func Concurrent function to execute in taskpool. 122 * @param { unknown[] } args - args args The concurrent function arguments. 123 * @throws { BusinessError } 401 - The input parameters are invalid. 124 * @throws { BusinessError } 10200014 - The function is not mark as concurrent. 125 * @syscap SystemCapability.Utils.Lang 126 * @crossplatform 127 * @since 10 128 */ 129 constructor(func: Function, ...args: unknown[]); 130 131 /** 132 * Check current running Task is canceled or not. 133 * 134 * @returns { boolean } Returns {@code true} if current running task is canceled; returns {@code false} otherwise. 135 * @static 136 * @syscap SystemCapability.Utils.Lang 137 * @crossplatform 138 * @since 10 139 */ 140 static isCanceled(): boolean; 141 142 /** 143 * Set transfer list for this task. 144 * 145 * @param { ArrayBuffer[] } transfer - transfer Transfer list of this task, empty array is default. 146 * @throws { BusinessError } 401 - The input parameters are invalid. 147 * @syscap SystemCapability.Utils.Lang 148 * @crossplatform 149 * @since 10 150 */ 151 setTransferList(transfer?: ArrayBuffer[]): void; 152 153 /** 154 * Concurrent function to execute in taskpool. 155 * 156 * @syscap SystemCapability.Utils.Lang 157 * @since 9 158 */ 159 /** 160 * Concurrent function to execute in taskpool. 161 * 162 * @syscap SystemCapability.Utils.Lang 163 * @crossplatform 164 * @since 10 165 */ 166 function: Function; 167 168 /** 169 * The concurrent function arguments. 170 * 171 * @syscap SystemCapability.Utils.Lang 172 * @since 9 173 */ 174 /** 175 * The concurrent function arguments. 176 * 177 * @type { ?unknown[] } 178 * @syscap SystemCapability.Utils.Lang 179 * @crossplatform 180 * @since 10 181 */ 182 arguments?: unknown[]; 183 } 184 185 /** 186 * The TaskGroup class provides an interface to create a task group. 187 * 188 * @syscap SystemCapability.Utils.Lang 189 * @crossplatform 190 * @since 10 191 */ 192 class TaskGroup { 193 /** 194 * Create a TaskGroup instance. 195 * 196 * @syscap SystemCapability.Utils.Lang 197 * @crossplatform 198 * @since 10 199 */ 200 constructor(); 201 202 /** 203 * Add a Concurrent function into task group. 204 * 205 * @param { Function } func - func func Concurrent function to add in task group. 206 * @param { unknown[] } args - args args The concurrent function arguments. 207 * @throws { BusinessError } 401 - The input parameters are invalid. 208 * @throws { BusinessError } 10200014 - The function is not mark as concurrent. 209 * @syscap SystemCapability.Utils.Lang 210 * @crossplatform 211 * @since 10 212 */ 213 addTask(func: Function, ...args: unknown[]): void; 214 215 /** 216 * Add a Task into TaskGroup. 217 * 218 * @param { Task } task - task task The task want to add in task group. 219 * @throws { BusinessError } 401 - The input parameters are invalid. 220 * @throws { BusinessError } 10200014 - The function is not mark as concurrent. 221 * @syscap SystemCapability.Utils.Lang 222 * @crossplatform 223 * @since 10 224 */ 225 addTask(task: Task): void; 226 } 227 228 /** 229 * The State defines the task state. 230 * 231 * @enum { number } State 232 * @syscap SystemCapability.Utils.Lang 233 * @crossplatform 234 * @since 10 235 */ 236 enum State { 237 /** 238 * the task state is waiting. 239 * 240 * @syscap SystemCapability.Utils.Lang 241 * @crossplatform 242 * @since 10 243 */ 244 WAITING = 1, 245 246 /** 247 * the task state is running. 248 * 249 * @syscap SystemCapability.Utils.Lang 250 * @crossplatform 251 * @since 10 252 */ 253 RUNNING = 2, 254 255 /** 256 * the task state is canceled. 257 * 258 * @syscap SystemCapability.Utils.Lang 259 * @crossplatform 260 * @since 10 261 */ 262 CANCELED = 3 263 } 264 265 /** 266 * Indicates the internal information of the worker thread. 267 * 268 * @syscap SystemCapability.Utils.Lang 269 * @crossplatform 270 * @since 10 271 */ 272 class TaskInfo { 273 /** 274 * Task identity. 275 * 276 * @type { number } 277 * @default 0 278 * @syscap SystemCapability.Utils.Lang 279 * @crossplatform 280 * @since 10 281 */ 282 taskId: number; 283 284 /** 285 * Task state. 286 * 287 * @type { State } 288 * @default State::WAITING 289 * @syscap SystemCapability.Utils.Lang 290 * @crossplatform 291 * @since 10 292 */ 293 state: State; 294 295 /** 296 * Duration of task execution. 297 * 298 * @type { ?number } 299 * @syscap SystemCapability.Utils.Lang 300 * @crossplatform 301 * @since 10 302 */ 303 duration?: number; 304 } 305 306 /** 307 * Indicates the internal information of the worker thread. 308 * 309 * @syscap SystemCapability.Utils.Lang 310 * @crossplatform 311 * @since 10 312 */ 313 class ThreadInfo { 314 /** 315 * Thread id. 316 * 317 * @type { number } 318 * @default 0 319 * @syscap SystemCapability.Utils.Lang 320 * @crossplatform 321 * @since 10 322 */ 323 tid: number; 324 325 /** 326 * Task id list that running on current thread. 327 * 328 * @type { ?number[] } 329 * @syscap SystemCapability.Utils.Lang 330 * @crossplatform 331 * @since 10 332 */ 333 taskIds?: number[]; 334 335 /** 336 * Thread priority. 337 * 338 * @type { ?Priority } 339 * @syscap SystemCapability.Utils.Lang 340 * @crossplatform 341 * @since 10 342 */ 343 priority?: Priority; 344 } 345 346 /** 347 * Indicates the internal information of the taskpool. 348 * 349 * @syscap SystemCapability.Utils.Lang 350 * @crossplatform 351 * @since 10 352 */ 353 class TaskPoolInfo { 354 /** 355 * An array of taskpool thread information. 356 * 357 * @type { ThreadInfo[] } 358 * @syscap SystemCapability.Utils.Lang 359 * @crossplatform 360 * @since 10 361 */ 362 threadInfos: ThreadInfo[]; 363 364 /** 365 * An array of taskpool task information. 366 * 367 * @type { TaskInfo[] } 368 * @syscap SystemCapability.Utils.Lang 369 * @crossplatform 370 * @since 10 371 */ 372 taskInfos: TaskInfo[]; 373 } 374 375 /** 376 * Execute a concurrent function. 377 * 378 * @param { Function } func - func func Concurrent function want to execute. 379 * @param { unknown[] } args - args args The concurrent function arguments. 380 * @returns { Promise<unknown> } 381 * @throws { BusinessError } 401 - The input parameters are invalid. 382 * @throws { BusinessError } 10200003 - Worker initialization failure. 383 * @throws { BusinessError } 10200006 - An exception occurred during serialization. 384 * @throws { BusinessError } 10200014 - The function is not mark as concurrent. 385 * @syscap SystemCapability.Utils.Lang 386 * @since 9 387 */ 388 /** 389 * Execute a concurrent function. 390 * 391 * @param { Function } func - func func Concurrent function want to execute. 392 * @param { unknown[] } args - args args The concurrent function arguments. 393 * @returns { Promise<unknown> } 394 * @throws { BusinessError } 401 - The input parameters are invalid. 395 * @throws { BusinessError } 10200003 - Worker initialization failure. 396 * @throws { BusinessError } 10200006 - An exception occurred during serialization. 397 * @throws { BusinessError } 10200014 - The function is not mark as concurrent. 398 * @syscap SystemCapability.Utils.Lang 399 * @crossplatform 400 * @since 10 401 */ 402 function execute(func: Function, ...args: unknown[]): Promise<unknown>; 403 404 /** 405 * Execute a concurrent task. 406 * 407 * @param { Task } task - task task The task want to execute. 408 * @param { Priority } priority - priority priority Task priority, MEDIUM is default. 409 * @returns { Promise<unknown> } 410 * @throws { BusinessError } 401 - The input parameters are invalid. 411 * @throws { BusinessError } 10200003 - Worker initialization failure. 412 * @throws { BusinessError } 10200006 - An exception occurred during serialization. 413 * @throws { BusinessError } 10200014 - The function is not mark as concurrent. 414 * @syscap SystemCapability.Utils.Lang 415 * @since 9 416 */ 417 /** 418 * Execute a concurrent task. 419 * 420 * @param { Task } task - task task The task want to execute. 421 * @param { Priority } priority - priority priority Task priority, MEDIUM is default. 422 * @returns { Promise<unknown> } 423 * @throws { BusinessError } 401 - The input parameters are invalid. 424 * @throws { BusinessError } 10200003 - Worker initialization failure. 425 * @throws { BusinessError } 10200006 - An exception occurred during serialization. 426 * @throws { BusinessError } 10200014 - The function is not mark as concurrent. 427 * @syscap SystemCapability.Utils.Lang 428 * @crossplatform 429 * @since 10 430 */ 431 function execute(task: Task, priority?: Priority): Promise<unknown>; 432 433 /** 434 * Execute a concurrent task group. 435 * 436 * @param { TaskGroup } group - group group The task group want to execute. 437 * @param { Priority } priority - priority priority Task group priority, MEDIUM is default. 438 * @returns { Promise<unknown[]> } 439 * @throws { BusinessError } 401 - The input parameters are invalid. 440 * @throws { BusinessError } 10200006 - An exception occurred during serialization. 441 * @syscap SystemCapability.Utils.Lang 442 * @crossplatform 443 * @since 10 444 */ 445 function execute(group: TaskGroup, priority?: Priority): Promise<unknown[]>; 446 447 /** 448 * Cancel a concurrent task. 449 * 450 * @param { Task } task - task task The task want to cancel. 451 * @throws { BusinessError } 401 - The input parameters are invalid. 452 * @throws { BusinessError } 10200015 - The task does not exist when it is canceled. 453 * @throws { BusinessError } 10200016 - The task is executing when it is canceled. 454 * @syscap SystemCapability.Utils.Lang 455 * @since 9 456 */ 457 /** 458 * Cancel a concurrent task. 459 * 460 * @param { Task } task - task task The task want to cancel. 461 * @throws { BusinessError } 401 - The input parameters are invalid. 462 * @throws { BusinessError } 10200015 - The task does not exist when it is canceled. 463 * @syscap SystemCapability.Utils.Lang 464 * @crossplatform 465 * @since 10 466 */ 467 function cancel(task: Task): void; 468 469 /** 470 * Cancel a concurrent task group. 471 * 472 * @param { TaskGroup } group - group group The task group want to cancel. 473 * @throws { BusinessError } 401 - The input parameters are invalid. 474 * @throws { BusinessError } 10200018 - The task group does not exist when it is canceled. 475 * @syscap SystemCapability.Utils.Lang 476 * @crossplatform 477 * @since 10 478 */ 479 function cancel(group: TaskGroup): void; 480 481 /** 482 * Get task pool internal information. 483 * 484 * @returns { TaskPoolInfo } 485 * @syscap SystemCapability.Utils.Lang 486 * @crossplatform 487 * @since 10 488 */ 489 function getTaskPoolInfo(): TaskPoolInfo; 490} 491 492export default taskpool; 493