1# @ohos.taskpool（启动任务池） 2<!--Kit: ArkTS--> 3<!--Subsystem: CommonLibrary--> 4<!--Owner: @lijiamin2025--> 5<!--Designer: @weng-changcheng--> 6<!--Tester: @kirl75; @zsw_zhushiwei--> 7<!--Adviser: @ge-yafang--> 8 9任务池（taskpool）的作用是为应用程序提供多线程运行环境，降低资源消耗并提升系统性能，且您无需关心线程的生命周期。您可以使用任务池API创建后台任务（Task），并进行如执行任务或取消任务等操作。理论上，任务池API允许创建的任务数量不受限制，但由于内存限制，不建议这样做。此外，不建议在任务中执行阻塞操作，尤其是无限期阻塞操作，因为长时间的阻塞操作会占用工作线程，可能阻塞其他任务的调度，影响应用性能。 10 11创建同一优先级的任务时，可以自行决定其执行顺序。任务的实际执行顺序与调用任务池API提供的任务执行接口的顺序一致。任务的默认优先级为MEDIUM。 12 13当同一时间待执行的任务数量大于任务池工作线程数量，任务池会根据负载均衡机制进行扩容，增加工作线程数量，减少整体等待时长。同样，当执行的任务数量减少，工作线程数量大于执行任务数量，部分工作线程处于空闲状态，任务池会根据负载均衡机制进行缩容，减少工作线程数量。 14 15任务池API返回错误码。如需了解各错误码的详细信息，请参阅文档[语言基础类库错误码](errorcode-utils.md)。 16 17请查阅[TaskPool注意事项](../../arkts-utils/taskpool-introduction.md#taskpool注意事项)，了解使用TaskPool时的相关注意点。 18 19文档中涉及以下任务概念： 20- 任务组任务：对应为[TaskGroup](#taskgroup10)任务。 21- 串行队列任务：对应为[SequenceRunner](#sequencerunner-11)任务。 22- 异步队列任务：对应为[AsyncRunner](#asyncrunner18)任务。 23- 周期任务：由[executePeriodically](#taskpoolexecuteperiodically12)执行的任务。 24 25> **说明：** 26> 27> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 28 29## 导入模块 30 31```ts 32import { taskpool } from '@kit.ArkTS'; 33``` 34## taskpool.execute 35 36execute(func: Function, ...args: Object[]): Promise\<Object> 37 38将待执行的函数放入taskpool的内部任务队列，函数不会立即执行，而是等待分发到工作线程执行。在当前执行模式下，不支持取消任务。使用Promise异步回调。 39 40**系统能力：** SystemCapability.Utils.Lang 41 42**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 43 44**参数：** 45 46| 参数名 | 类型 | 必填 | 说明 | 47| ------ | --------- | ---- | ---------------------------------------------------------------------- | 48| func | Function | 是 | 执行的逻辑需要传入一个函数，该函数必须使用[@Concurrent装饰器](../../arkts-utils/taskpool-introduction.md#concurrent装饰器)装饰。支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 49| args | Object[] | 否 | 执行逻辑的函数所需要的入参，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 50 51**返回值：** 52 53| 类型 | 说明 | 54| ----------------- | ------------------------------------ | 55| Promise\<Object> | Promise对象，返回任务函数的执行结果。 | 56 57**错误码：** 58 59以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 60 61| 错误码ID | 错误信息 | 62| -------- | -------------------------------------------- | 63| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 64| 10200006 | An exception occurred during serialization. | 65| 10200014 | The function is not marked as concurrent. | 66 67**示例：** 68 69```ts 70@Concurrent 71function printArgs(args: number): number { 72 console.info("printArgs: " + args); 73 return args; 74} 75 76taskpool.execute(printArgs, 100).then((value: Object) => { // 100: test number 77 console.info("taskpool result: " + value); 78}); 79``` 80 81 82## taskpool.execute<sup>13+</sup> 83 84execute<A extends Array\<Object>, R>(func: (...args: A) => R | Promise\<R>, ...args: A): Promise\<R> 85 86校验并发函数的参数类型和返回类型后，将函数添加到taskpool的任务队列。使用Promise异步回调。 87 88**系统能力：** SystemCapability.Utils.Lang 89 90**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 91 92**参数：** 93 94| 参数名 | 类型 | 必填 | 说明 | 95| ------ | --------- | ---- | ---------------------------------------------------------------------- | 96| func | (...args: A) => R \| Promise\<R> | 是 | 执行的逻辑需要传入函数，必须使用[@Concurrent装饰器](../../arkts-utils/taskpool-introduction.md#concurrent装饰器)装饰，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 97| args | A | 否 | 执行逻辑的函数所需要的入参，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 98 99**返回值：** 100 101| 类型 | 说明 | 102| ----------------- | ------------------------------------ | 103| Promise\<R> | Promise对象，返回任务函数的执行结果。 | 104 105**错误码：** 106 107以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 108 109| 错误码ID | 错误信息 | 110| -------- | -------------------------------------------- | 111| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. | 112| 10200006 | An exception occurred during serialization. | 113| 10200014 | The function is not marked as concurrent. | 114 115**示例：** 116 117```ts 118@Concurrent 119function printArgs(args: number): number { 120 console.info("printArgs: " + args); 121 return args; 122} 123 124@Concurrent 125function testWithThreeParams(a: number, b: string, c: number): string { 126 return b; 127} 128 129@Concurrent 130function testWithArray(args: [number, string]): string { 131 return "success"; 132} 133 134taskpool.execute<[number], number>(printArgs, 100).then((value: number) => { // 100: test number 135 console.info("taskpool result: " + value); // "taskpool result: 100" 136}); 137 138taskpool.execute<[number, string, number], string>(testWithThreeParams, 100, "test", 100).then((value: string) => { 139 console.info("taskpool result: " + value); // "taskpool result: test" 140}); 141 142taskpool.execute<[[number, string]], string>(testWithArray, [100, "test"]).then((value: string) => { 143 console.info("taskpool result: " + value); // "taskpool result: success" 144}); 145``` 146 147 148## taskpool.execute 149 150execute(task: Task, priority?: Priority): Promise\<Object> 151 152将创建好的任务添加到taskpool的内部任务队列中，任务不会立即执行，而是等待分发到工作线程执行。当前模式支持设置任务优先级和通过cancel取消任务。任务不能是任务组任务、串行队列任务或异步队列任务。非长时任务可以多次调用执行。使用Promise异步回调。 153 154**系统能力：** SystemCapability.Utils.Lang 155 156**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 157 158**参数：** 159 160| 参数名 | 类型 | 必填 | 说明 | 161| -------- | --------------------- | ---- | ---------------------------------------- | 162| task | [Task](#task) | 是 | 需要在任务池中执行的任务。 | 163| priority | [Priority](#priority) | 否 | 该参数表示等待执行的任务的优先级，默认值为taskpool.Priority.MEDIUM。 | 164 165**返回值：** 166 167| 类型 | 说明 | 168| ---------------- | ---------------- | 169| Promise\<Object> | Promise对象，返回任务函数的执行结果。 | 170 171**错误码：** 172 173以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 174 175| 错误码ID | 错误信息 | 176| -------- | ------------------------------------------- | 177| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 178| 10200006 | An exception occurred during serialization. | 179| 10200014 | The function is not marked as concurrent. | 180| 10200051 | The periodic task cannot be executed again. | 181| 10200057 | The task cannot be executed by two APIs. | 182 183**示例：** 184 185```ts 186@Concurrent 187function printArgs(args: number): number { 188 console.info("printArgs: " + args); 189 return args; 190} 191 192let task1: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number 193let task2: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number 194let task3: taskpool.Task = new taskpool.Task(printArgs, 300); // 300: test number 195taskpool.execute(task1, taskpool.Priority.LOW).then((value: Object) => { 196 console.info("taskpool result1: " + value); 197}); 198taskpool.execute(task2, taskpool.Priority.MEDIUM).then((value: Object) => { 199 console.info("taskpool result2: " + value); 200}); 201taskpool.execute(task3, taskpool.Priority.HIGH).then((value: Object) => { 202 console.info("taskpool result3: " + value); 203}); 204``` 205 206 207## taskpool.execute<sup>13+</sup> 208 209execute<A extends Array\<Object>, R>(task: GenericsTask<A, R>, priority?: Priority): Promise\<R> 210 211将创建好的泛型任务放入taskpool的内部任务队列，不校验任务的参数类型和返回值类型。使用Promise异步回调。 212 213execute任务的校验是结合new GenericsTask一起用的，参数、返回值类型需与new GenericsTask中的类型保持一致。 214 215**系统能力：** SystemCapability.Utils.Lang 216 217**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 218 219**参数：** 220 221| 参数名 | 类型 | 必填 | 说明 | 222| -------- | --------------------- | ---- | ---------------------------------------- | 223| task | [GenericsTask<A, R>](#genericstask13) | 是 | 需要在任务池中执行的泛型任务。 | 224| priority | [Priority](#priority) | 否 | 等待执行的任务的优先级，默认值为taskpool.Priority.MEDIUM。 | 225 226**返回值：** 227 228| 类型 | 说明 | 229| ---------------- | ---------------- | 230| Promise\<R> | Promise对象，返回任务函数的执行结果。 | 231 232**错误码：** 233 234以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 235 236| 错误码ID | 错误信息 | 237| -------- | ------------------------------------------- | 238| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. | 239| 10200006 | An exception occurred during serialization. | 240| 10200014 | The function is not marked as concurrent. | 241| 10200051 | The periodic task cannot be executed again. | 242| 10200057 | The task cannot be executed by two APIs. | 243 244**示例：** 245 246```ts 247@Concurrent 248function printArgs(args: number): number { 249 console.info("printArgs: " + args); 250 return args; 251} 252 253let task1: taskpool.Task = new taskpool.GenericsTask<[number], number>(printArgs, 100); // 100: test number 254let task2: taskpool.Task = new taskpool.GenericsTask<[number], number>(printArgs, 200); // 200: test number 255let task3: taskpool.Task = new taskpool.GenericsTask<[number], number>(printArgs, 300); // 300: test number 256taskpool.execute<[number], number>(task1, taskpool.Priority.LOW).then((value: number) => { 257 console.info("taskpool result1: " + value); 258}); 259taskpool.execute<[number], number>(task2, taskpool.Priority.MEDIUM).then((value: number) => { 260 console.info("taskpool result2: " + value); 261}); 262taskpool.execute<[number], number>(task3, taskpool.Priority.HIGH).then((value: number) => { 263 console.info("taskpool result3: " + value); 264}); 265``` 266 267 268## taskpool.execute<sup>10+</sup> 269 270execute(group: TaskGroup, priority?: Priority): Promise<Object[]> 271 272将创建好的任务组放入taskpool内部任务队列，任务组中的任务不会立即执行，而是等待分发到工作线程执行。任务组中任务全部执行完成后，结果数组统一返回。此模式适用于执行关联任务。使用Promise异步回调。 273 274**系统能力：** SystemCapability.Utils.Lang 275 276**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 277 278**参数：** 279 280| 参数名 | 类型 | 必填 | 说明 | 281| --------- | --------------------------- | ---- | -------------------------------------------------------------- | 282| group | [TaskGroup](#taskgroup10) | 是 | 需要在任务池中执行的任务组。 | 283| priority | [Priority](#priority) | 否 | 等待执行的任务组的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | 284 285**返回值：** 286 287| 类型 | 说明 | 288| ---------------- | ---------------------------------- | 289| Promise\<Object[]> | Promise对象数组，返回任务函数的执行结果。 | 290 291**错误码：** 292 293以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 294 295| 错误码ID | 错误信息 | 296| -------- | ------------------------------------------- | 297| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 298| 10200006 | An exception occurred during serialization. | 299 300**示例：** 301 302```ts 303@Concurrent 304function printArgs(args: number): number { 305 console.info("printArgs: " + args); 306 return args; 307} 308 309let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup(); 310taskGroup1.addTask(printArgs, 10); // 10: test number 311taskGroup1.addTask(printArgs, 20); // 20: test number 312taskGroup1.addTask(printArgs, 30); // 30: test number 313 314let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup(); 315let task1: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number 316let task2: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number 317let task3: taskpool.Task = new taskpool.Task(printArgs, 300); // 300: test number 318taskGroup2.addTask(task1); 319taskGroup2.addTask(task2); 320taskGroup2.addTask(task3); 321taskpool.execute(taskGroup1).then((res: Array<Object>) => { 322 console.info("taskpool execute res is:" + res); 323}); 324taskpool.execute(taskGroup2).then((res: Array<Object>) => { 325 console.info("taskpool execute res is:" + res); 326}); 327``` 328 329## taskpool.executeDelayed<sup>11+</sup> 330 331executeDelayed(delayTime: number, task: Task, priority?: Priority): Promise\<Object> 332 333延时执行任务。当前执行模式可以设置任务优先级，并且可以尝试调用cancel取消任务。该任务不能是任务组任务、串行队列任务、异步队列任务或周期任务。如果任务不是长时任务，可以多次调用executeDelayed执行；如果是长时任务，则仅支持执行一次。使用Promise异步回调。 334 335**系统能力：** SystemCapability.Utils.Lang 336 337**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 338 339**参数：** 340 341| 参数名 | 类型 | 必填 | 说明 | 342| ----------- | ------------- | ---- | -------------------- | 343| delayTime | number | 是 | 延时时间。单位为ms。delayTime值必须要大于等于0。 | 344| task | [Task](#task) | 是 | 需要延时执行的任务。 | 345| priority | [Priority](#priority) | 否 | 延时执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | 346 347**返回值：** 348 349| 类型 | 说明 | 350| ---------------- | ---------------------------------- | 351| Promise\<Object> | Promise对象，返回任务函数的执行结果。 | 352 353**错误码：** 354 355以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 356 357| 错误码ID | 错误信息 | 358| --------- | -------------------------------- | 359| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 360| 10200006 | An exception occurred during serialization. | 361| 10200014 | The function is not marked as concurrent. | 362| 10200028 | The delayTime is less than zero. | 363| 10200051 | The periodic task cannot be executed again. | 364| 10200057 | The task cannot be executed by two APIs. | 365 366**示例：** 367 368```ts 369// import BusinessError 370import { BusinessError } from '@kit.BasicServicesKit'; 371 372@Concurrent 373function printArgs(args: number): void { 374 console.info("printArgs: " + args); 375} 376 377let t: number = Date.now(); 378console.info("taskpool start time is: " + t); 379let task: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number 380taskpool.executeDelayed(1000, task).then(() => { // 1000: delayTime is 1000ms 381 console.info("taskpool execute success"); 382}).catch((e: BusinessError) => { 383 console.error(`taskpool execute: Code: ${e.code}, message: ${e.message}`); 384}) 385``` 386 387 388## taskpool.executeDelayed<sup>13+</sup> 389 390executeDelayed<A extends Array\<Object>, R>(delayTime: number, task: GenericsTask\<A, R>, priority?: Priority): Promise\<R> 391 392延时执行泛型任务，不校验任务的参数类型和返回值类型。使用Promise异步回调。 393 394executeDelayed任务的校验是结合new GenericsTask一起用的，参数、返回值类型需与new GenericsTask中的类型保持一致。 395 396**系统能力：** SystemCapability.Utils.Lang 397 398**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 399 400**参数：** 401 402| 参数名 | 类型 | 必填 | 说明 | 403| ----------- | ------------- | ---- | -------------------- | 404| delayTime | number | 是 | 延时时间。单位为ms。delayTime值必须要大于等于0。 | 405| task | [GenericsTask\<A, R>](#genericstask13) | 是 | 需要延时执行的泛型任务。 | 406| priority | [Priority](#priority) | 否 | 延时执行的任务的优先级，默认值为taskpool.Priority.MEDIUM。 | 407 408**返回值：** 409 410| 类型 | 说明 | 411| ---------------- | ---------------------------------- | 412| Promise\<R> | Promise对象，返回任务函数的执行结果。 | 413 414**错误码：** 415 416以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 417 418| 错误码ID | 错误信息 | 419| --------- | -------------------------------- | 420| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. | 421| 10200028 | The delayTime is less than zero. | 422| 10200051 | The periodic task cannot be executed again. | 423| 10200057 | The task cannot be executed by two APIs. | 424 425**示例：** 426 427```ts 428// import BusinessError 429import { BusinessError } from '@kit.BasicServicesKit' 430 431@Concurrent 432function printArgs(args: number): string { 433 console.info("printArgs: " + args); 434 return "success"; 435} 436 437let task: taskpool.Task = new taskpool.GenericsTask<[number], string>(printArgs, 100); // 100: test number 438taskpool.executeDelayed<[number], string>(1000, task).then((res: string) => { // 1000: delayTime is 1000ms 439 console.info("taskpool execute success"); 440}).catch((e: BusinessError) => { 441 console.error(`taskpool execute: Code: ${e.code}, message: ${e.message}`); 442}) 443``` 444 445 446## taskpool.executePeriodically<sup>12+</sup> 447 448executePeriodically(period: number, task: Task, priority?: Priority): void 449 450周期任务每隔period时长执行一次。当前执行模式支持设置任务优先级，并可以通过调用cancel取消周期任务的执行。周期任务不能是任务组任务、串行队列任务或异步队列任务，不能再次调用执行接口，且执行的任务不能拥有依赖关系。 451 452 453**系统能力：** SystemCapability.Utils.Lang 454 455**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 456 457**参数：** 458 459| 参数名 | 类型 | 必填 | 说明 | 460| ----------- | ------------- | ----- | -------------------- | 461| period | number | 是 | 周期时长。单位为ms。period值必须要大于等于0。 | 462| task | [Task](#task) | 是 | 需要周期执行的任务。 | 463| priority | [Priority](#priority) | 否 | 周期执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | 464 465 466**错误码：** 467 468以下错误码的详细介绍，请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 469 470| 错误码ID | 错误信息 | 471| ---------- | -------------------------------- | 472| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 473| 10200006 | An exception occurred during serialization. | 474| 10200014 | The function is not marked as concurrent. | 475| 10200028 | The period is less than zero. | 476| 10200050 | The concurrent task has been executed and cannot be executed periodically. | 477| 10200057 | The task cannot be executed by two APIs. | 478 479 480**示例：** 481 482```ts 483@Concurrent 484function printArgs(args: number): void { 485 console.info("printArgs: " + args); 486} 487 488@Concurrent 489function testExecutePeriodically(args: number): void { 490 let t = Date.now(); 491 while ((Date.now() - t) < args) { 492 continue; 493 } 494 taskpool.Task.sendData(args); // 向宿主线程发送消息 495} 496 497function printResult(data: number): void { 498 console.info("taskpool: data is: " + data); 499} 500 501function taskpoolTest() { 502 try { 503 let task: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number 504 taskpool.executePeriodically(1000, task); // 1000: period is 1000ms 505 } catch (e) { 506 console.error(`taskpool execute-1: Code: ${e.code}, message: ${e.message}`); 507 } 508 509 try { 510 let periodicTask: taskpool.Task = new taskpool.Task(testExecutePeriodically, 200); // 200: test number 511 periodicTask.onReceiveData(printResult); 512 taskpool.executePeriodically(1000, periodicTask); // 1000: period is 1000ms 513 } catch (e) { 514 console.error(`taskpool execute-2: Code: ${e.code}, message: ${e.message}`); 515 } 516} 517 518taskpoolTest(); 519``` 520 521 522## taskpool.executePeriodically<sup>13+</sup> 523 524executePeriodically<A extends Array\<Object>, R>(period: number, task: GenericsTask\<A, R>, priority?: Priority): void 525 526周期执行泛型任务，每隔period时长执行一次。不校验任务的参数类型和返回值类型。 527 528executePeriodically任务的校验是结合new GenericsTask一起用的，参数、返回值类型需与new GenericsTask中的类型保持一致。 529 530**系统能力：** SystemCapability.Utils.Lang 531 532**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 533 534**参数：** 535 536| 参数名 | 类型 | 必填 | 说明 | 537| ----------- | ------------- | ----- | -------------------- | 538| period | number | 是 | 周期时长。单位为ms。period值必须要大于等于0。 | 539| task | [GenericsTask\<A, R>](#genericstask13) | 是 | 需要周期执行的泛型任务。 | 540| priority | [Priority](#priority) | 否 | 周期执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | 541 542 543**错误码：** 544 545以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 546 547| 错误码ID | 错误信息 | 548| ---------- | -------------------------------- | 549| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. | 550| 10200006 | An exception occurred during serialization. | 551| 10200014 | The function is not marked as concurrent. | 552| 10200028 | The period is less than zero. | 553| 10200050 | The concurrent task has been executed and cannot be executed periodically. | 554| 10200057 | The task cannot be executed by two APIs. | 555 556 557**示例：** 558 559```ts 560@Concurrent 561function printArgs(args: number): void { 562 console.info("printArgs: " + args); 563} 564 565@Concurrent 566function testExecutePeriodically(args: number): void { 567 let t = Date.now(); 568 while ((Date.now() - t) < args) { 569 continue; 570 } 571 taskpool.Task.sendData(args); // 向宿主线程发送消息 572} 573 574function printResult(data: number): void { 575 console.info("taskpool: data is: " + data); 576} 577 578function taskpoolTest() { 579 try { 580 let task: taskpool.Task = new taskpool.GenericsTask<[number], void>(printArgs, 100); // 100: test number 581 taskpool.executePeriodically<[number], void>(1000, task); // 1000: period is 1000ms 582 } catch (e) { 583 console.error(`taskpool execute-1: Code: ${e.code}, message: ${e.message}`); 584 } 585 586 try { 587 let periodicTask: taskpool.Task = new taskpool.GenericsTask<[number], void>(testExecutePeriodically, 200); // 200: test number 588 periodicTask.onReceiveData(printResult); 589 taskpool.executePeriodically<[number], void>(1000, periodicTask); // 1000: period is 1000ms 590 } catch (e) { 591 console.error(`taskpool execute-2: Code: ${e.code}, message: ${e.message}`); 592 } 593} 594 595taskpoolTest(); 596``` 597 598 599## taskpool.cancel 600 601cancel(task: Task): void 602 603取消任务池中的任务。当任务在taskpool等待队列中，取消该任务后该任务将不再执行，并返回任务被取消的异常；当任务已经在taskpool工作线程执行，取消该任务并不影响任务继续执行，执行结果在catch分支返回，搭配isCanceled使用可以对任务取消行为作出响应。taskpool.cancel对其之前的taskpool.execute、taskpool.executeDelayed或taskpool.executePeriodically生效。 604 605从API version 20开始，支持在执行cancel操作后，在catch分支里使用BusinessError<[taskpool.TaskResult](#taskresult20)>的泛型标记，来获取任务中抛出的异常信息或最终的执行结果。 606 607**系统能力：** SystemCapability.Utils.Lang 608 609**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 610 611**参数：** 612 613| 参数名 | 类型 | 必填 | 说明 | 614| ------ | ------------- | ---- | -------------------- | 615| task | [Task](#task) | 是 | 需要取消执行的任务。 | 616 617**错误码：** 618 619以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 620 621| 错误码ID | 错误信息 | 622| -------- | -------------------------------------------- | 623| 10200015 | The task to cancel does not exist. | 624| 10200055 | The asyncRunner task has been canceled. | 625 626从API version 10开始，此接口调用时不再涉及上报错误码10200016。 627 628**正在执行的任务取消示例：** 629 630```ts 631@Concurrent 632function inspectStatus(arg: number): number { 633 // 第一次检查任务是否已经取消并作出响应 634 if (taskpool.Task.isCanceled()) { 635 console.info("task has been canceled before 2s sleep."); 636 return arg + 2; 637 } 638 // 2s sleep 639 let t: number = Date.now(); 640 while (Date.now() - t < 2000) { 641 continue; 642 } 643 // 第二次检查任务是否已经取消并作出响应 644 if (taskpool.Task.isCanceled()) { 645 console.info("task has been canceled after 2s sleep."); 646 return arg + 3; 647 } 648 return arg + 1; 649} 650 651function concurrentFunc() { 652 let task1: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number 653 let task2: taskpool.Task = new taskpool.Task(inspectStatus, 200); // 200: test number 654 let task3: taskpool.Task = new taskpool.Task(inspectStatus, 300); // 300: test number 655 let task4: taskpool.Task = new taskpool.Task(inspectStatus, 400); // 400: test number 656 let task5: taskpool.Task = new taskpool.Task(inspectStatus, 500); // 500: test number 657 let task6: taskpool.Task = new taskpool.Task(inspectStatus, 600); // 600: test number 658 taskpool.execute(task1).then((res: Object) => { 659 console.info("taskpool test result: " + res); 660 }); 661 taskpool.execute(task2); 662 taskpool.execute(task3); 663 taskpool.execute(task4); 664 taskpool.execute(task5); 665 taskpool.execute(task6); 666 // 1s后取消task 667 setTimeout(() => { 668 try { 669 taskpool.cancel(task1); 670 } catch (e) { 671 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 672 } 673 }, 1000); 674} 675 676concurrentFunc(); 677``` 678 679## taskpool.cancel<sup>10+</sup> 680 681cancel(group: TaskGroup): void 682 683取消任务池中的任务组。如果任务组中的任务未全部执行结束，返回undefined作为任务组结果。 684 685从API version 20开始，支持在执行cancel操作后，在catch分支里使用BusinessError<[taskpool.TaskResult](#taskresult20)>的泛型标记，来获取任务中抛出的异常信息或最终的执行结果。 686 687**系统能力：** SystemCapability.Utils.Lang 688 689**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 690 691**参数：** 692 693| 参数名 | 类型 | 必填 | 说明 | 694| ------- | ----------------------- | ---- | -------------------- | 695| group | [TaskGroup](#taskgroup10) | 是 | 需要取消执行的任务组。 | 696 697**错误码：** 698 699以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 700 701| 错误码ID | 错误信息 | 702| -------- | ------------------------------------------------------- | 703| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 704| 10200018 | The task group to cancel does not exist. | 705 706**示例：** 707 708```ts 709@Concurrent 710function printArgs(args: number): number { 711 let t: number = Date.now(); 712 while (Date.now() - t < 2000) { 713 continue; 714 } 715 console.info("printArgs: " + args); 716 return args; 717} 718 719function concurrentFunc() { 720 let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup(); 721 taskGroup1.addTask(printArgs, 10); // 10: test number 722 let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup(); 723 taskGroup2.addTask(printArgs, 100); // 100: test number 724 taskpool.execute(taskGroup1).then((res: Array<Object>) => { 725 console.info("taskGroup1 res is:" + res); 726 }); 727 taskpool.execute(taskGroup2).then((res: Array<Object>) => { 728 console.info("taskGroup2 res is:" + res); 729 }); 730 setTimeout(() => { 731 try { 732 taskpool.cancel(taskGroup2); 733 } catch (e) { 734 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 735 } 736 }, 1000); 737} 738 739concurrentFunc(); 740``` 741 742## taskpool.cancel<sup>18+</sup> 743 744cancel(taskId: number): void 745 746通过任务ID取消任务池中的任务。如果任务在taskpool等待队列中，取消后任务将不再执行，并返回任务取消的异常。如果任务已在taskpool工作线程中执行，取消不影响任务继续执行，执行结果在catch分支返回。使用isCanceled可以对任务取消行为作出响应。taskpool.cancel对其之前的taskpool.execute或taskpool.executeDelayed生效。在其他线程调用taskpool.cancel时，需注意其行为是异步的，可能影响之后的taskpool.execute或taskpool.executeDelayed。 747 748从API version 20开始，支持在执行cancel操作后，在catch分支里使用BusinessError<[taskpool.TaskResult](#taskresult20)>的泛型标记。这可以用来获取任务中抛出的异常信息或最终的执行结果。 749 750**系统能力：** SystemCapability.Utils.Lang 751 752**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 753 754**参数：** 755 756| 参数名 | 类型 | 必填 | 说明 | 757| ------- | ----------------------- | ---- | -------------------- | 758| taskId | number | 是 | 需要取消执行的任务的ID。 | 759 760**错误码：** 761 762以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 763 764| 错误码ID | 错误信息 | 765| -------- | -------------------------------------------- | 766| 10200015 | The task to cancel does not exist. | 767| 10200055 | The asyncRunner task has been canceled. | 768 769**示例：** 770 771```ts 772@Concurrent 773function printArgs(args: number): number { 774 let t: number = Date.now(); 775 while (Date.now() - t < 2000) { 776 continue; 777 } 778 if (taskpool.Task.isCanceled()) { 779 console.info("task has been canceled after 2s sleep."); 780 return args + 1; 781 } 782 console.info("printArgs: " + args); 783 return args; 784} 785 786@Concurrent 787function cancelFunction(taskId: number) { 788 try { 789 taskpool.cancel(taskId); 790 } catch (e) { 791 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 792 } 793} 794 795function concurrentFunc() { 796 let task = new taskpool.Task(printArgs, 100); // 100: test number 797 taskpool.execute(task); 798 setTimeout(() => { 799 let cancelTask = new taskpool.Task(cancelFunction, task.taskId); 800 taskpool.execute(cancelTask); 801 }, 1000); 802} 803 804concurrentFunc(); 805``` 806 807## taskpool.terminateTask<sup>12+</sup> 808 809terminateTask(longTask: LongTask): void 810 811中止任务池中的长时任务，在长时任务执行完成后调用。中止后，执行长时任务的线程可能会被回收。 812 813**系统能力：** SystemCapability.Utils.Lang 814 815**原子化服务API**： 从API version 12开始，该接口支持在原子化服务中使用。 816 817**参数：** 818 819| 参数名 | 类型 | 必填 | 说明 | 820| ------ | ------------- | ---- | -------------------- | 821| longTask | [LongTask](#longtask12) | 是 | 需要中止的长时任务。 | 822 823**错误码：** 824 825以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 826 827| 错误码ID | 错误信息 | 828| -------- | -------- | 829| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 830 831**示例：** 832 833```ts 834@Concurrent 835function longTask(arg: number): number { 836 let t: number = Date.now(); 837 while (Date.now() - t < arg) { 838 continue; 839 } 840 console.info("longTask has been executed."); 841 return arg; 842} 843 844function concurrentFunc() { 845 let task1: taskpool.LongTask = new taskpool.LongTask(longTask, 1000); // 1000: sleep time 846 taskpool.execute(task1).then((res: Object) => { 847 taskpool.terminateTask(task1); 848 console.info("taskpool longTask result: " + res); 849 }); 850} 851 852concurrentFunc(); 853``` 854 855## taskpool.isConcurrent<sup>12+</sup> 856 857isConcurrent(func: Function): boolean 858 859检查函数是否为并发函数。 860 861**系统能力：** SystemCapability.Utils.Lang 862 863**原子化服务API**： 从API version 12开始，该接口支持在原子化服务中使用。 864 865**参数：** 866 867| 参数名 | 类型 | 必填 | 说明 | 868| ------ | ------------- | ---- | -------------------- | 869| func | Function | 是 | 需要检查的函数。 | 870 871**返回值：** 872 873| 类型 | 说明 | 874| ------- | ------------------------------------ | 875| boolean | 如果被检查函数标注了[@Concurrent装饰器](../../arkts-utils/taskpool-introduction.md#concurrent装饰器)，则返回true，否则返回false。 | 876 877**错误码：** 878 879以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 880 881| 错误码ID | 错误信息 | 882| -------- | -------- | 883| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 884 885**示例：** 886 887```ts 888@Concurrent 889function test() {} 890 891let result: Boolean = taskpool.isConcurrent(test); 892console.info("result is: " + result); 893``` 894 895## taskpool.getTaskPoolInfo<sup>10+</sup> 896 897getTaskPoolInfo(): TaskPoolInfo 898 899获取任务池的线程信息和任务信息。 900 901**系统能力：** SystemCapability.Utils.Lang 902 903**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 904 905**返回值：** 906 907| 类型 | 说明 | 908| ----------------------------------- | ------------------ | 909| [TaskPoolInfo](#taskpoolinfo10) | 任务池的内部信息。 | 910 911**示例：** 912 913```ts 914let taskpoolInfo: taskpool.TaskPoolInfo = taskpool.getTaskPoolInfo(); 915``` 916 917## Priority 918 919表示所创建任务（Task）执行时的优先级。工作线程优先级跟随任务优先级更新，对应关系参考[QoS等级定义](../../napi/qos-guidelines.md#qos等级定义)。 920 921**系统能力：** SystemCapability.Utils.Lang 922 923| 名称 | 值 | 说明 | 924| -------- | -------- | -------- | 925| HIGH | 0 | 任务为高优先级。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 926| MEDIUM | 1 | 任务为中优先级。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 927| LOW | 2 | 任务为低优先级。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 928| IDLE<sup>12+</sup> | 3 | 任务为后台任务。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 929 930**示例：** 931 932```ts 933@Concurrent 934function printArgs(args: number): number { 935 let t: number = Date.now(); 936 while (Date.now() - t < 1000) { // 1000: delay 1s 937 continue; 938 } 939 console.info("printArgs: " + args); 940 return args; 941} 942 943let allCount = 100; // 100: test number 944let taskArray: Array<taskpool.Task> = []; 945// 创建400个任务并添加至taskArray 946for (let i: number = 0; i < allCount; i++) { 947 let task1: taskpool.Task = new taskpool.Task(printArgs, i); 948 taskArray.push(task1); 949 let task2: taskpool.Task = new taskpool.Task(printArgs, i * 10); // 10: test number 950 taskArray.push(task2); 951 let task3: taskpool.Task = new taskpool.Task(printArgs, i * 100); // 100: test number 952 taskArray.push(task3); 953 let task4: taskpool.Task = new taskpool.Task(printArgs, i * 1000); // 1000: test number 954 taskArray.push(task4); 955} 956 957// 从taskArray中获取不同的任务并给定不同优先级执行 958for (let i: number = 0; i < taskArray.length; i+=4) { // 4: 每次执行4个任务，循环取任务时需后移4项，确保执行的是不同的任务 959 taskpool.execute(taskArray[i], taskpool.Priority.HIGH); 960 taskpool.execute(taskArray[i + 1], taskpool.Priority.LOW); 961 taskpool.execute(taskArray[i + 2], taskpool.Priority.MEDIUM); 962 taskpool.execute(taskArray[i + 3], taskpool.Priority.IDLE); 963} 964``` 965 966## Task 967 968任务可以多次执行，也可以放入任务组、串行队列或异步队列执行，还支持添加依赖关系。 969 970### 属性 971 972**系统能力：** SystemCapability.Utils.Lang 973 974| 名称 | 类型 | 只读 | 可选 | 说明 | 975| -------------------- | --------- | ---- | ---- | ------------------------------------------------------------ | 976| function | Function | 否 | 否 | 创建任务时需要传入的函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 977| arguments | Object[] | 否 | 是 | 创建任务传入函数所需的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 978| name<sup>11+</sup> | string | 是 | 否 | 创建任务时指定的任务名称。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 979| taskId<sup>18+</sup> | number | 是 | 否 | 任务的ID。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。| 980| totalDuration<sup>11+</sup> | number | 是 | 否 | 执行任务总耗时。单位为ms。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 981| ioDuration<sup>11+</sup> | number | 是 | 否 | 执行任务异步IO耗时。单位为ms。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 982| cpuDuration<sup>11+</sup> | number | 是 | 否 | 执行任务CPU耗时。单位为ms。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 983 984### constructor 985 986constructor(func: Function, ...args: Object[]) 987 988Task的构造函数。 989 990**系统能力：** SystemCapability.Utils.Lang 991 992**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 993 994**参数：** 995 996| 参数名 | 类型 | 必填 | 说明 | 997| ------ | --------- | ---- | -------------------------------------------------------------------- | 998| func | Function | 是 | 执行的逻辑需要传入函数，必须使用[@Concurrent装饰器](../../arkts-utils/taskpool-introduction.md#concurrent装饰器)装饰，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 999| args | Object[] | 否 | 任务执行传入函数的入参，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 1000 1001**错误码：** 1002 1003以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1004 1005| 错误码ID | 错误信息 | 1006| -------- | --------------------------------------- | 1007| 401 | The input parameters are invalid. | 1008| 10200014 | The function is not marked as concurrent. | 1009 1010**示例：** 1011 1012```ts 1013@Concurrent 1014function printArgs(args: number): number { 1015 console.info("printArgs: " + args); 1016 return args; 1017} 1018 1019let task: taskpool.Task = new taskpool.Task(printArgs, "this is my first Task"); 1020``` 1021 1022### constructor<sup>11+</sup> 1023 1024constructor(name: string, func: Function, ...args: Object[]) 1025 1026Task的构造函数用于创建任务，并可指定任务名称。 1027 1028**系统能力：** SystemCapability.Utils.Lang 1029 1030**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1031 1032**参数：** 1033 1034| 参数名 | 类型 | 必填 | 说明 | 1035| ------ | -------- | ---- | ------------------------------------------------------------ | 1036| name | string | 是 | 任务名称。 | 1037| func | Function | 是 | 执行的逻辑需要传入函数，必须使用[@Concurrent装饰器](../../arkts-utils/taskpool-introduction.md#concurrent装饰器)装饰，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 1038| args | Object[] | 否 | 任务执行时传入函数的参数。支持的类型请参考[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 1039 1040**错误码：** 1041 1042以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1043 1044| 错误码ID | 错误信息 | 1045| -------- | --------------------------------------- | 1046| 401 | The input parameters are invalid. | 1047| 10200014 | The function is not marked as concurrent. | 1048 1049**示例：** 1050 1051```ts 1052@Concurrent 1053function printArgs(args: string): string { 1054 console.info("printArgs: " + args); 1055 return args; 1056} 1057 1058let taskName: string = "taskName"; 1059let task: taskpool.Task = new taskpool.Task(taskName, printArgs, "this is my first Task"); 1060let name: string = task.name; 1061``` 1062 1063### isCanceled<sup>10+</sup> 1064 1065static isCanceled(): boolean 1066 1067检查当前正在运行的任务是否已取消。使用此方法前，需要先创建一个Task对象。 1068 1069**系统能力：** SystemCapability.Utils.Lang 1070 1071**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1072 1073**返回值：** 1074 1075| 类型 | 说明 | 1076| ------- | ------------------------------------ | 1077| boolean | 如果当前正在运行的任务被取消返回true，否则返回false。| 1078 1079**示例：** 1080 1081```ts 1082@Concurrent 1083function inspectStatus(arg: number): number { 1084 // do something 1085 if (taskpool.Task.isCanceled()) { 1086 console.info("task has been canceled."); 1087 // do something 1088 return arg + 1; 1089 } 1090 // do something 1091 return arg; 1092} 1093``` 1094 1095> **说明：** 1096> 1097> isCanceled方法需要和taskpool.cancel方法搭配使用，如果不调用cancel方法，isCanceled方法默认返回false。 1098 1099**示例：** 1100 1101```ts 1102@Concurrent 1103function inspectStatus(arg: number): number { 1104 // 第一次检查任务是否已经取消并作出响应 1105 if (taskpool.Task.isCanceled()) { 1106 console.info("task has been canceled before 2s sleep."); 1107 return arg + 2; 1108 } 1109 // 延时2s 1110 let t: number = Date.now(); 1111 while (Date.now() - t < 2000) { 1112 continue; 1113 } 1114 // 第二次检查任务是否已经取消并作出响应 1115 if (taskpool.Task.isCanceled()) { 1116 console.info("task has been canceled after 2s sleep."); 1117 return arg + 3; 1118 } 1119 return arg + 1; 1120} 1121 1122let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number 1123taskpool.execute(task).then((res: Object) => { 1124 console.info("taskpool test result: " + res); 1125}).catch((err: string) => { 1126 console.error("taskpool test occur error: " + err); 1127}); 1128// 不调用cancel，isCanceled()默认返回false，task执行的结果为101 1129``` 1130 1131### setTransferList<sup>10+</sup> 1132 1133setTransferList(transfer?: ArrayBuffer[]): void 1134 1135设置任务的传输列表。使用该方法前需要先构造Task。不调用该接口，则传给任务的数据中的ArrayBuffer默认transfer转移。 1136 1137> **说明：** 1138> 1139> 此接口可以设置任务池中ArrayBuffer的transfer列表，transfer列表中的ArrayBuffer对象在传输时不会复制buffer内容到工作线程而是转移buffer控制权至工作线程，传输后当前的ArrayBuffer失效。若ArrayBuffer为空，则不会transfer转移。 1140 1141**系统能力：** SystemCapability.Utils.Lang 1142 1143**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1144 1145**参数：** 1146 1147| 参数名 | 类型 | 必填 | 说明 | 1148| -------- | ------------- | ---- | --------------------------------------------- | 1149| transfer | ArrayBuffer[] | 否 | 可传输对象是ArrayBuffer的实例对象，默认为空数组。 | 1150 1151**错误码：** 1152 1153以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1154 1155| 错误码ID | 错误信息 | 1156| -------- | -------------------------------------------------------------- | 1157| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed. | 1158| 10200029 | An ArrayBuffer cannot be set as both a transfer list and a clone list. | 1159 1160**示例：** 1161 1162```ts 1163@Concurrent 1164function testTransfer(arg1: ArrayBuffer, arg2: ArrayBuffer): number { 1165 console.info("testTransfer arg1 byteLength: " + arg1.byteLength); 1166 console.info("testTransfer arg2 byteLength: " + arg2.byteLength); 1167 return 100; 1168} 1169 1170let buffer: ArrayBuffer = new ArrayBuffer(8); 1171let view: Uint8Array = new Uint8Array(buffer); 1172let buffer1: ArrayBuffer = new ArrayBuffer(16); 1173let view1: Uint8Array = new Uint8Array(buffer1); 1174 1175console.info("testTransfer view byteLength: " + view.byteLength); 1176console.info("testTransfer view1 byteLength: " + view1.byteLength); 1177// 执行结果为： 1178// testTransfer view byteLength: 8 1179// testTransfer view1 byteLength: 16 1180 1181let task: taskpool.Task = new taskpool.Task(testTransfer, view, view1); 1182task.setTransferList([view.buffer, view1.buffer]); 1183taskpool.execute(task).then((res: Object) => { 1184 console.info("test result: " + res); 1185}).catch((e: string) => { 1186 console.error("test catch: " + e); 1187}) 1188console.info("testTransfer view2 byteLength: " + view.byteLength); 1189console.info("testTransfer view3 byteLength: " + view1.byteLength); 1190// 经过transfer转移之后值为0，执行结果为： 1191// testTransfer view2 byteLength: 0 1192// testTransfer view3 byteLength: 0 1193``` 1194 1195 1196### setCloneList<sup>11+</sup> 1197 1198setCloneList(cloneList: Object[] | ArrayBuffer[]): void 1199 1200设置任务的拷贝列表。在使用该方法前，需先构造Task对象。 1201 1202> **说明：** 1203> 1204> 需搭配[@Sendable装饰器](../../arkts-utils/arkts-sendable.md#sendable装饰器)使用，否则会抛异常。建议开发者使用该装饰器以避免异常。 1205 1206**系统能力：** SystemCapability.Utils.Lang 1207 1208**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1209 1210**参数：** 1211 1212| 参数名 | 类型 | 必填 | 说明 | 1213| --------- | ------------------------ | ---- | --------------------------------------------- | 1214| cloneList | Object[] \| ArrayBuffer[] | 是 | - 传入数组的类型必须为[Sendable支持的数据类型](../../arkts-utils/arkts-sendable.md#sendable支持的数据类型)或ArrayBuffer。<br/>- 所有传入cloneList的对象持有的[Sendable class](../../arkts-utils/arkts-sendable.md#sendable-class)实例或ArrayBuffer类型对象，在线程间传输的行为都会变成拷贝传递，即修改传输后的对象不会对原有对象产生任何影响。 | 1215 1216**错误码：** 1217 1218以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1219 1220| 错误码ID | 错误信息 | 1221| -------- | -------------------------------------------------------------- | 1222| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1223| 10200029 | An ArrayBuffer cannot be set as both a transfer list and a clone list. | 1224 1225**示例：** 1226 1227```ts 1228// sendable.ets 1229// 定义两个Sendable class：BaseClass及其子类DeriveClass 1230@Sendable 1231export class BaseClass { 1232 private str: string = "sendable: BaseClass"; 1233 static num :number = 10; 1234 str1: string = "sendable: this is BaseClass's string"; 1235 num1: number = 5; 1236 isDone1: boolean = false; 1237 1238 private fibonacciRecursive(n: number): number { 1239 if (n <= 1) { 1240 return n; 1241 } else { 1242 return this.fibonacciRecursive(n - 1) + this.fibonacciRecursive(n - 2); 1243 } 1244 } 1245 1246 private privateFunc(num: number): number{ 1247 let res: number = this.fibonacciRecursive(num); 1248 console.info("sendable: BaseClass privateFunc res is: " + res); 1249 return res; 1250 } 1251 1252 publicFunc(num: number): number { 1253 return this.privateFunc(num); 1254 } 1255 1256 get GetNum(): number { 1257 return this.num1; 1258 } 1259 set SetNum(num: number) { 1260 this.num1 = num; 1261 } 1262 1263 constructor() { 1264 console.info(this.str); 1265 this.isDone1 = true; 1266 } 1267} 1268 1269@Sendable 1270export class DeriveClass extends BaseClass { 1271 name: string = "sendable: this is DeriveClass"; 1272 printName() { 1273 console.info(this.name); 1274 } 1275 constructor() { 1276 super(); 1277 } 1278} 1279``` 1280 1281<!--code_no_check--> 1282```ts 1283// index.ets 1284// 宿主线程（这里的宿主线程为UI主线程）调用taskpool，在taskpool线程中调用BaseClass和DeriveClass的方法、访问对应属性 1285import { taskpool } from '@kit.ArkTS'; 1286import { BusinessError } from '@kit.BasicServicesKit'; 1287import { BaseClass, DeriveClass } from './sendable'; 1288 1289@Concurrent 1290function testFunc(arr: Array<BaseClass>, num: number): number { 1291 let baseInstance1 = arr[0]; 1292 console.info("sendable: str1 is: " + baseInstance1.str1); 1293 baseInstance1.SetNum = 100; 1294 console.info("sendable: num1 is: " + baseInstance1.GetNum); 1295 console.info("sendable: isDone1 is: " + baseInstance1.isDone1); 1296 // 获取斐波那契数列第num项的结果 1297 let res: number = baseInstance1.publicFunc(num); 1298 return res; 1299} 1300 1301@Concurrent 1302function printLog(arr: Array<DeriveClass>): void { 1303 let deriveInstance = arr[0]; 1304 deriveInstance.printName(); 1305} 1306 1307@Entry 1308@Component 1309struct Index { 1310 @State message: string = 'Hello World'; 1311 1312 build() { 1313 Row() { 1314 Column() { 1315 Text(this.message) 1316 .fontSize(50) 1317 .fontWeight(FontWeight.Bold) 1318 Button() { 1319 Text("TaskPool Test"); 1320 }.onClick(() => { 1321 // task1访问调用BaseClass.str1/BaseClass.SetNum/BaseClass.GetNum/BaseClass.isDone1/BaseClass.publicFunc 1322 let baseInstance1: BaseClass = new BaseClass(); 1323 let array1 = new Array<BaseClass>(); 1324 array1.push(baseInstance1); 1325 let task1 = new taskpool.Task(testFunc, array1, 10); 1326 task1.setCloneList(array1); 1327 taskpool.execute(task1).then((res: Object) => { 1328 console.info("sendable: task1 res is: " + res); 1329 }).catch((e:BusinessError) => { 1330 console.error(`sendable: task1 execute Code is ${e.code}, message is ${e.message}`); 1331 }) 1332 1333 // task2调用DeriveClass.printName 1334 let deriveInstance: DeriveClass = new DeriveClass(); 1335 let array2 = new Array<DeriveClass>(); 1336 array2.push(deriveInstance); 1337 let task2 = new taskpool.Task(printLog, array2); 1338 task2.setCloneList(array2); 1339 taskpool.execute(task2).then(() => { 1340 console.info("sendable: task2 execute success"); 1341 }).catch((e:BusinessError) => { 1342 console.error(`sendable: task2 execute Code is ${e.code}, message is ${e.message}`); 1343 }) 1344 }) 1345 .height('15%') 1346 .width('30%') 1347 } 1348 .width('100%') 1349 } 1350 .height('100%') 1351 } 1352} 1353``` 1354 1355 1356### sendData<sup>11+</sup> 1357 1358static sendData(...args: Object[]): void 1359 1360任务执行过程中向宿主线程发送消息并触发回调。使用此方法前需构造Task。 1361 1362> **说明：** 1363> 1364> - 该接口应在taskpool的线程中调用。 1365> - 避免在回调函数中调用该方法，否则可能导致消息无法传递到宿主线程。 1366> - 调用该接口时，请确保处理数据的回调函数已在宿主线程注册。 1367 1368**系统能力：** SystemCapability.Utils.Lang 1369 1370**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1371 1372**参数：** 1373 1374| 参数名 | 类型 | 必填 | 说明 | 1375| -------- | ------------- | ---- | ------------------------------------------------- | 1376| args | Object[] | 否 | 可传输对象默认转移，作为回调函数的参数。支持的参数类型请参见[序列化支持类型](#序列化支持类型)，默认值为undefined。 | 1377 1378**错误码：** 1379 1380以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1381 1382| 错误码ID | 错误信息 | 1383| -------- | --------------------------------------- | 1384| 401 | The input parameters are invalid. | 1385| 10200006 | An exception occurred during serialization. | 1386| 10200022 | The function is not called in the TaskPool thread. | 1387| 10200023 | The function is not called in the concurrent function. | 1388| 10200024 | The callback is not registered on the host side. | 1389 1390**示例：** 1391 1392```ts 1393@Concurrent 1394function sendDataTest(num: number): number { 1395 let res: number = num * 10; 1396 taskpool.Task.sendData(res); 1397 return num; 1398} 1399 1400function printLog(data: number): void { 1401 console.info("taskpool: data is: " + data); 1402} 1403 1404async function taskpoolTest(): Promise<void> { 1405 try { 1406 let task: taskpool.Task = new taskpool.Task(sendDataTest, 1); 1407 task.onReceiveData(printLog); 1408 await taskpool.execute(task); 1409 } catch (e) { 1410 console.error(`taskpool: error code: ${e.code}, info: ${e.message}`); 1411 } 1412} 1413 1414taskpoolTest(); 1415``` 1416 1417 1418### onReceiveData<sup>11+</sup> 1419 1420onReceiveData(callback?: Function): void 1421 1422为任务注册回调函数，接收并处理任务池工作线程的数据。使用此方法前，需构造Task。 1423 1424> **说明：** 1425> 1426> 不支持为同一任务定义多种回调函数。如果多次赋值，只有最后一次赋值的回调函数会生效。 1427 1428**系统能力：** SystemCapability.Utils.Lang 1429 1430**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1431 1432**参数：** 1433 1434| 参数名 | 类型 | 必填 | 说明 | 1435| -------- | -------- | ---- | ------------------------------------------------------------ | 1436| callback | Function | 否 | 处理数据的回调函数，发送到宿主线程的数据将会作为入参传入该回调函数。不传参可以取消注册的回调函数。 | 1437 1438**错误码：** 1439 1440以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1441 1442| 错误码ID | 错误信息 | 1443| -------- | -------- | 1444| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed. | 1445 1446**示例：** 1447 1448```ts 1449@Concurrent 1450function ConcurrentFunc(num: number): number { 1451 let res: number = num * 10; 1452 taskpool.Task.sendData(res); 1453 return num; 1454} 1455 1456function printLog(data: number): void { 1457 console.info("taskpool: data is: " + data); 1458} 1459 1460async function testFunc(): Promise<void> { 1461 try { 1462 let task: taskpool.Task = new taskpool.Task(ConcurrentFunc, 1); 1463 task.onReceiveData(printLog); 1464 await taskpool.execute(task); 1465 } catch (e) { 1466 console.error(`taskpool: error code: ${e.code}, info: ${e.message}`); 1467 } 1468} 1469 1470testFunc(); 1471``` 1472 1473### addDependency<sup>11+</sup> 1474 1475addDependency(...tasks: Task[]): void 1476 1477为当前任务添加对其他任务的依赖。使用该方法前需先构造Task。该任务和被依赖的任务不能是任务组任务、串行队列任务、异步队列任务、已执行任务或周期任务。存在依赖关系的任务（依赖其他任务的任务或被依赖的任务）执行后不可再次执行。 1478 1479**系统能力：** SystemCapability.Utils.Lang 1480 1481**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1482 1483**参数：** 1484 1485| 参数名 | 类型 | 必填 | 说明 | 1486| ------ | --------------- | ---- | ------------------ | 1487| tasks | [Task](#task)[] | 否 | 被依赖的任务数组。默认值为undefined。 | 1488 1489**错误码：** 1490 1491以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1492 1493| 错误码ID | 错误信息 | 1494| -------- | ------------------------------- | 1495| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1496| 10200026 | There is a circular dependency. | 1497| 10200052 | The periodic task cannot have a dependency. | 1498| 10200056 | The task has been executed by the AsyncRunner. | 1499 1500**示例：** 1501 1502```ts 1503@Concurrent 1504function delay(args: number): number { 1505 let t: number = Date.now(); 1506 while ((Date.now() - t) < 1000) { 1507 continue; 1508 } 1509 return args; 1510} 1511 1512let task1:taskpool.Task = new taskpool.Task(delay, 100); 1513let task2:taskpool.Task = new taskpool.Task(delay, 200); 1514let task3:taskpool.Task = new taskpool.Task(delay, 200); 1515 1516console.info("dependency: add dependency start"); 1517task1.addDependency(task2); 1518task2.addDependency(task3); 1519console.info("dependency: add dependency end"); 1520 1521console.info("dependency: start execute second"); 1522taskpool.execute(task1).then(() => { 1523 console.info("dependency: second task1 success"); 1524}) 1525taskpool.execute(task2).then(() => { 1526 console.info("dependency: second task2 success"); 1527}) 1528taskpool.execute(task3).then(() => { 1529 console.info("dependency: second task3 success"); 1530}) 1531``` 1532 1533### removeDependency<sup>11+</sup> 1534 1535removeDependency(...tasks: Task[]): void 1536 1537删除当前任务对其他任务的依赖。在使用该方法之前，需要先构造Task对象。 1538 1539**系统能力：** SystemCapability.Utils.Lang 1540 1541**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1542 1543**参数：** 1544 1545| 参数名 | 类型 | 必填 | 说明 | 1546| ------ | ------ | ---- | ------------------ | 1547| tasks | [Task](#task)[] | 否 | 被依赖的任务数组。默认值为undefined。 | 1548 1549**错误码：** 1550 1551以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1552 1553| 错误码ID | 错误信息 | 1554| -------- | ------------------------------ | 1555| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1556| 10200027 | The dependency does not exist. | 1557| 10200052 | The periodic task cannot have a dependency. | 1558| 10200056 | The task has been executed by the AsyncRunner. | 1559 1560**示例：** 1561 1562```ts 1563@Concurrent 1564function delay(args: number): number { 1565 let t: number = Date.now(); 1566 while ((Date.now() - t) < 1000) { 1567 continue; 1568 } 1569 return args; 1570} 1571 1572let task1:taskpool.Task = new taskpool.Task(delay, 100); 1573let task2:taskpool.Task = new taskpool.Task(delay, 200); 1574let task3:taskpool.Task = new taskpool.Task(delay, 200); 1575 1576console.info("dependency: add dependency start"); 1577task1.addDependency(task2); 1578task2.addDependency(task3); 1579console.info("dependency: add dependency end"); 1580console.info("dependency: remove dependency start"); 1581task1.removeDependency(task2); 1582task2.removeDependency(task3); 1583console.info("dependency: remove dependency end"); 1584 1585console.info("dependency: start execute"); 1586taskpool.execute(task1).then(() => { 1587 console.info("dependency: task1 success"); 1588}) 1589taskpool.execute(task2).then(() => { 1590 console.info("dependency: task2 success"); 1591}) 1592taskpool.execute(task3).then(() => { 1593 console.info("dependency: task3 success"); 1594}) 1595``` 1596 1597 1598### onEnqueued<sup>12+</sup> 1599 1600onEnqueued(callback: CallbackFunction): void 1601 1602注册回调函数，任务入队时将调用该函数。若任务执行前未注册回调函数，将抛出异常。 1603 1604**系统能力：** SystemCapability.Utils.Lang 1605 1606**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1607 1608**参数：** 1609 1610| 参数名 | 类型 | 必填 | 说明 | 1611| ------ | ------ | ---- | ------------------ | 1612| callback | [CallbackFunction](#callbackfunction12) | 是 | 需注册的回调函数。 | 1613 1614**错误码：** 1615 1616以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1617 1618| 错误码ID | 错误信息 | 1619| -------- | ------------------------------ | 1620| 401 | The input parameters are invalid. | 1621| 10200034 | The executed task does not support the registration of listeners. | 1622 1623**示例：** 1624 1625```ts 1626import { taskpool } from '@kit.ArkTS'; 1627 1628@Concurrent 1629function delay(args: number): number { 1630 let t: number = Date.now(); 1631 while ((Date.now() - t) < 1000) { 1632 continue; 1633 } 1634 return args; 1635} 1636 1637let task: taskpool.Task = new taskpool.Task(delay, 1); 1638task.onEnqueued(() => { 1639 console.info("taskpool: onEnqueued"); 1640}); 1641taskpool.execute(task).then(() => { 1642 console.info("taskpool: execute task success"); 1643}); 1644``` 1645 1646 1647### onStartExecution<sup>12+</sup> 1648 1649onStartExecution(callback: CallbackFunction): void 1650 1651注册回调函数，任务执行前将调用该函数。若任务执行前未注册回调函数，将抛出异常。 1652 1653**系统能力：** SystemCapability.Utils.Lang 1654 1655**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1656 1657**参数：** 1658 1659| 参数名 | 类型 | 必填 | 说明 | 1660| ------ | ------ | ---- | ------------------ | 1661| callback | [CallbackFunction](#callbackfunction12) | 是 | 需注册的回调函数。 | 1662 1663**错误码：** 1664 1665以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1666 1667| 错误码ID | 错误信息 | 1668| -------- | ------------------------------ | 1669| 401 | The input parameters are invalid. | 1670| 10200034 | The executed task does not support the registration of listeners. | 1671 1672**示例：** 1673 1674```ts 1675import { taskpool } from '@kit.ArkTS'; 1676 1677@Concurrent 1678function delay(args: number): number { 1679 let t: number = Date.now(); 1680 while ((Date.now() - t) < 1000) { 1681 continue; 1682 } 1683 return args; 1684} 1685 1686let task: taskpool.Task = new taskpool.Task(delay, 1); 1687task.onStartExecution(() => { 1688 console.info("taskpool: onStartExecution"); 1689}); 1690taskpool.execute(task).then(() => { 1691 console.info("taskpool: execute task success"); 1692}); 1693``` 1694 1695### onExecutionFailed<sup>12+</sup> 1696 1697onExecutionFailed(callback: CallbackFunctionWithError): void 1698 1699注册一个回调函数，并在任务执行失败时调用它（周期任务不支持）。需在任务执行前注册，否则会抛异常。 1700 1701**系统能力：** SystemCapability.Utils.Lang 1702 1703**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1704 1705**参数：** 1706 1707| 参数名 | 类型 | 必填 | 说明 | 1708| ------ | ------ | ---- | ------------------ | 1709| callback | [CallbackFunctionWithError](#callbackfunctionwitherror12) | 是 | 需注册的回调函数。 | 1710 1711**错误码：** 1712 1713以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1714 1715| 错误码ID | 错误信息 | 1716| -------- | ------------------------------ | 1717| 401 | The input parameters are invalid. | 1718| 10200034 | The executed task does not support the registration of listeners. | 1719 1720**示例：** 1721 1722```ts 1723import { taskpool } from '@kit.ArkTS'; 1724import { BusinessError } from '@kit.BasicServicesKit'; 1725import { HashMap } from '@kit.ArkTS'; 1726 1727@Concurrent 1728function test(args: number) { 1729 let t = Date.now(); 1730 while ((Date.now() - t) < 100) { 1731 continue; 1732 } 1733 let hashMap1: HashMap<string, number> = new HashMap(); 1734 hashMap1.set('a', args); 1735 return hashMap1; 1736} 1737 1738let task2 = new taskpool.Task(test, 1); 1739task2.onExecutionFailed((e: Error) => { 1740 console.info("taskpool: onExecutionFailed error is " + e); 1741}) 1742taskpool.execute(task2).then(() => { 1743 console.info("taskpool: execute task success"); 1744}).catch((e:BusinessError) => { 1745 console.error(`taskpool: error code: ${e.code}, error info: ${e.message}`); 1746}) 1747``` 1748 1749### onExecutionSucceeded<sup>12+</sup> 1750 1751onExecutionSucceeded(callback: CallbackFunction): void 1752 1753注册一个回调函数，并在任务执行成功时调用它（周期任务不支持）。需在任务执行前注册，否则会抛异常。 1754 1755**系统能力：** SystemCapability.Utils.Lang 1756 1757**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1758 1759**参数：** 1760 1761| 参数名 | 类型 | 必填 | 说明 | 1762| ------ | ------ | ---- | ------------------ | 1763| callback | [CallbackFunction](#callbackfunction12) | 是 | 需注册的回调函数。 | 1764 1765**错误码：** 1766 1767以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1768 1769| 错误码ID | 错误信息 | 1770| -------- | ------------------------------ | 1771| 401 | The input parameters are invalid. | 1772| 10200034 | The executed task does not support the registration of listeners. | 1773 1774**示例：** 1775 1776```ts 1777import { taskpool } from '@kit.ArkTS'; 1778 1779@Concurrent 1780function delay(args: number): number { 1781 let t: number = Date.now(); 1782 while ((Date.now() - t) < 1000) { 1783 continue; 1784 } 1785 return args; 1786} 1787 1788let task: taskpool.Task = new taskpool.Task(delay, 1); 1789task.onExecutionSucceeded(() => { 1790 console.info("taskpool: onExecutionSucceeded"); 1791}); 1792taskpool.execute(task).then(() => { 1793 console.info("taskpool: execute task success"); 1794}); 1795``` 1796 1797### isDone<sup>12+</sup> 1798 1799isDone(): boolean 1800 1801检查任务是否已完成。 1802 1803**系统能力：** SystemCapability.Utils.Lang 1804 1805**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1806 1807**返回值：** 1808 1809| 类型 | 说明 | 1810| ------- | ------------------------------------ | 1811| boolean | 任务执行完成时返回true，任务未执行完成时返回false。 | 1812 1813**示例：** 1814 1815```ts 1816@Concurrent 1817function inspectStatus(arg: number): number { 1818 // 1s sleep 1819 let t: number = Date.now(); 1820 while (Date.now() - t < 1000) { 1821 continue; 1822 } 1823 return arg + 1; 1824} 1825 1826async function taskpoolCancel(): Promise<void> { 1827 let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number 1828 taskpool.execute(task).then((res: Object) => { 1829 console.info("taskpool test result: " + res); 1830 }).catch((err: string) => { 1831 console.error("taskpool test occur error: " + err); 1832 }); 1833 1834 setTimeout(() => { 1835 if (!task.isDone()) { 1836 taskpool.cancel(task); 1837 } 1838 }, 3000); // 延时3s，确保任务已执行 1839} 1840 1841taskpoolCancel(); 1842``` 1843 1844## CallbackFunction<sup>12+</sup> 1845 1846type CallbackFunction = () => void 1847 1848注册的回调函数类型。 1849 1850**系统能力：** SystemCapability.Utils.Lang 1851 1852**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1853 1854 1855## CallbackFunctionWithError<sup>12+</sup> 1856 1857type CallbackFunctionWithError = (e: Error) => void 1858 1859注册带有错误码的回调函数类型。 1860 1861**系统能力：** SystemCapability.Utils.Lang 1862 1863**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1864 1865**参数：** 1866 1867| 参数名 | 类型 | 必填 | 说明 | 1868| ------ | ------ | ---- | ------------------ | 1869| e | Error | 是 | 错误信息。 | 1870 1871 1872## LongTask<sup>12+</sup> 1873 1874**系统能力：** SystemCapability.Utils.Lang 1875 1876表示长时任务。LongTask继承自[Task](#task)。 1877长时任务不设置执行时间上限，长时间运行不会触发超时异常，但不支持将同一任务多次执行或者将该任务加入任务组（TaskGroup）。 1878执行长时任务的线程会持续存在，直到任务完成并调用[terminateTask](#taskpoolterminatetask12)后，该线程在空闲时被回收。 1879 1880**示例：** 1881 1882```ts 1883@Concurrent 1884function printArgs(args: string): string { 1885 console.info("printArgs: " + args); 1886 return args; 1887} 1888 1889let task: taskpool.LongTask = new taskpool.LongTask(printArgs, "this is my first LongTask"); 1890``` 1891 1892 1893## GenericsTask<sup>13+</sup> 1894 1895**系统能力：** SystemCapability.Utils.Lang 1896 1897表示泛型任务。GenericsTask继承自[Task](#task)。 1898相比创建Task，创建GenericsTask可以在编译阶段校验并发函数的传参和返回值类型。其余行为与Task相同。 1899 1900### constructor<sup>13+</sup> 1901 1902constructor(func: (...args: A) => R | Promise\<R>, ...args: A) 1903 1904GenericsTask的构造函数。 1905 1906**系统能力：** SystemCapability.Utils.Lang 1907 1908**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 1909 1910**参数：** 1911 1912| 参数名 | 类型 | 必填 | 说明 | 1913| ------ | --------- | ---- | -------------------------------------------------------------------- | 1914| func | (...args: A) => R \| Promise\<R> | 是 | 执行的逻辑需要传入函数，必须使用[@Concurrent装饰器](../../arkts-utils/taskpool-introduction.md#concurrent装饰器)装饰，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 1915| args | A | 否 | 任务执行传入函数的入参，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 1916 1917**错误码：** 1918 1919以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1920 1921| 错误码ID | 错误信息 | 1922| -------- | --------------------------------------- | 1923| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. | 1924| 10200014 | The function is not marked as concurrent. | 1925 1926**示例：** 1927 1928```ts 1929@Concurrent 1930function printArgs(args: string): string { 1931 console.info("printArgs: " + args); 1932 return args; 1933} 1934 1935@Concurrent 1936function testWithThreeParams(a: number, b: string, c: number): string { 1937 return b; 1938} 1939 1940@Concurrent 1941function testWithArray(args: [number, string]): string { 1942 return "success"; 1943} 1944 1945let task1: taskpool.Task = new taskpool.GenericsTask<[string], string>(printArgs, "this is my first LongTask"); 1946 1947let task2: taskpool.Task = new taskpool.GenericsTask<[number, string, number], string>(testWithThreeParams, 100, "test", 100); 1948 1949let task3: taskpool.Task = new taskpool.GenericsTask<[[number, string]], string>(testWithArray, [100, "test"]); 1950``` 1951 1952### constructor<sup>13+</sup> 1953 1954constructor(name: string, func: (...args: A) => R | Promise\<R>, ...args: A) 1955 1956GenericsTask的构造函数，可以指定任务名称。 1957 1958**系统能力：** SystemCapability.Utils.Lang 1959 1960**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 1961 1962**参数：** 1963 1964| 参数名 | 类型 | 必填 | 说明 | 1965| ------ | -------- | ---- | ------------------------------------------------------------ | 1966| name | string | 是 | 泛型任务名称。 | 1967| func | (...args: A) => R \| Promise\<R> | 是 | 执行的逻辑需要传入函数，必须使用[@Concurrent装饰器](../../arkts-utils/taskpool-introduction.md#concurrent装饰器)装饰，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 1968| args | A | 否 | 任务执行传入函数的入参，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 1969 1970**错误码：** 1971 1972以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1973 1974| 错误码ID | 错误信息 | 1975| -------- | --------------------------------------- | 1976| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. | 1977| 10200014 | The function is not marked as concurrent. | 1978 1979**示例：** 1980 1981```ts 1982@Concurrent 1983function printArgs(args: string): string { 1984 console.info("printArgs: " + args); 1985 return args; 1986} 1987 1988let taskName: string = "taskName"; 1989let task: taskpool.Task = new taskpool.GenericsTask<[string], string>(taskName, printArgs, "this is my first Task"); 1990let name: string = task.name; 1991``` 1992 1993## TaskGroup<sup>10+</sup> 1994 1995表示任务组，一次执行一组任务，适用于执行一组有关联的任务。如果所有任务正常执行，异步执行完毕后返回所有任务结果的数组，数组中元素的顺序与[addTask](#addtask10-1)的顺序相同；如果任意任务失败，则会抛出对应异常。如果任务组中存在多个任务失败的情况，则会抛出第一个失败任务的异常。任务组可以多次执行，但执行后不能新增任务。 1996 1997### constructor<sup>10+</sup> 1998 1999constructor() 2000 2001TaskGroup的构造函数。 2002 2003**系统能力：** SystemCapability.Utils.Lang 2004 2005**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2006 2007**示例：** 2008 2009```ts 2010let taskGroup = new taskpool.TaskGroup(); 2011``` 2012 2013### constructor<sup>11+</sup> 2014 2015constructor(name: string) 2016 2017TaskGroup的构造函数，支持指定任务组名称。 2018 2019**系统能力：** SystemCapability.Utils.Lang 2020 2021**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2022 2023**参数：** 2024 2025| 参数名 | 类型 | 必填 | 说明 | 2026| ------ | ------ | ---- | ------------ | 2027| name | string | 是 | 任务组名称。 | 2028 2029**错误码：** 2030 2031以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2032 2033| 错误码ID | 错误信息 | 2034| -------- | -------- | 2035| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2036 2037**示例：** 2038 2039```ts 2040let taskGroupName: string = "groupName"; 2041let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup(taskGroupName); 2042let name: string = taskGroup.name; 2043``` 2044 2045### addTask<sup>10+</sup> 2046 2047addTask(func: Function, ...args: Object[]): void 2048 2049将待执行的函数添加到任务组中。使用该方法前需要先构造TaskGroup。 2050 2051**系统能力：** SystemCapability.Utils.Lang 2052 2053**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2054 2055**参数：** 2056 2057| 参数名 | 类型 | 必填 | 说明 | 2058| ------ | --------- | ---- | ---------------------------------------------------------------------- | 2059| func | Function | 是 | 需要传入使用[@Concurrent装饰器](../../arkts-utils/taskpool-introduction.md#concurrent装饰器)装饰的函数。支持的返回值类型请查[序列化支持类型](#序列化支持类型)。 | 2060| args | Object[] | 否 | 任务执行函数的入参，支持的类型请查[序列化支持类型](#序列化支持类型)，默认值为undefined。 | 2061 2062**错误码：** 2063 2064以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 2065 2066| 错误码ID | 错误信息 | 2067| -------- | --------------------------------------- | 2068| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2069| 10200014 | The function is not marked as concurrent. | 2070 2071**示例：** 2072 2073```ts 2074@Concurrent 2075function printArgs(args: number): number { 2076 console.info("printArgs: " + args); 2077 return args; 2078} 2079 2080let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup(); 2081taskGroup.addTask(printArgs, 100); // 100: test number 2082``` 2083 2084### addTask<sup>10+</sup> 2085 2086addTask(task: Task): void 2087 2088将创建好的任务添加到任务组中。使用此方法前需要先构造TaskGroup。任务组不能添加其他任务组中的任务、串行队列任务、异步队列任务、有依赖关系的任务、长时任务、周期任务和已执行的任务。 2089 2090**系统能力：** SystemCapability.Utils.Lang 2091 2092**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2093 2094**参数：** 2095 2096| 参数名 | 类型 | 必填 | 说明 | 2097| -------- | --------------------- | ---- | ---------------------------------------- | 2098| task | [Task](#task) | 是 | 需要添加到任务组中的任务。 | 2099 2100**错误码：** 2101 2102以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 2103 2104| 错误码ID | 错误信息 | 2105| -------- | --------------------------------------- | 2106| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2107| 10200014 | The function is not marked as concurrent. | 2108| 10200051 | The periodic task cannot be executed again. | 2109| 10200057 | The task cannot be executed by two APIs. | 2110 2111**示例：** 2112 2113```ts 2114@Concurrent 2115function printArgs(args: number): number { 2116 console.info("printArgs: " + args); 2117 return args; 2118} 2119 2120let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup(); 2121let task: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number 2122taskGroup.addTask(task); 2123``` 2124 2125### 属性 2126 2127**系统能力：** SystemCapability.Utils.Lang 2128 2129**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2130 2131| 名称 | 类型 | 只读 | 可选 | 说明 | 2132| ---- | ------ | ---- | ---- | ---------------------------- | 2133| name<sup>11+</sup> | string | 否 | 否 | 创建任务组时指定的任务组名称。 | 2134 2135## SequenceRunner <sup>11+</sup> 2136 2137表示串行队列的任务，用于执行一组需要串行执行的任务。 2138 2139### constructor<sup>11+</sup> 2140 2141constructor(priority?: Priority) 2142 2143SequenceRunner的构造函数。 2144 2145**系统能力：** SystemCapability.Utils.Lang 2146 2147**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2148 2149**参数：** 2150 2151| 参数名 | 类型 | 必填 | 说明 | 2152| -------- | --------------------- | ---- | ---------------------------------------------------------- | 2153| priority | [Priority](#priority) | 否 | 指定任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | 2154 2155**错误码：** 2156 2157以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2158 2159| 错误码ID | 错误信息 | 2160| -------- | -------- | 2161| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed. | 2162 2163**示例：** 2164 2165```ts 2166let runner: taskpool.SequenceRunner = new taskpool.SequenceRunner(); 2167``` 2168 2169### constructor<sup>12+</sup> 2170 2171constructor(name: string, priority?: Priority) 2172 2173SequenceRunner的构造函数。构造一个全局串行队列，如果名字相同，将返回同一个串行队列。 2174 2175> **说明：** 2176> 2177> - 底层通过单例模式保证了：创建同名串行队列时，获取到同一个实例。 2178> - 无法修改串行队列的优先级。 2179 2180**系统能力：** SystemCapability.Utils.Lang 2181 2182**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2183 2184**参数：** 2185 2186| 参数名 | 类型 | 必填 | 说明 | 2187| -------- | --------------------- | ---- | ---------------------------------------------------------- | 2188| name | string | 是 | 串行队列的名字。 | 2189| priority | [Priority](#priority) | 否 | 指定任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | 2190 2191**错误码：** 2192 2193以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2194 2195| 错误码ID | 错误信息 | 2196| -------- | -------- | 2197| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2198 2199**示例：** 2200 2201```ts 2202let runner:taskpool.SequenceRunner = new taskpool.SequenceRunner("runner1", taskpool.Priority.LOW); 2203``` 2204 2205### execute<sup>11+</sup> 2206 2207execute(task: Task): Promise\<Object> 2208 2209执行串行任务。使用该方法前需先构造SequenceRunner。串行队列不能执行任务组任务、其他串行队列任务、异步队列任务、有依赖关系的任务和已执行的任务。使用Promise异步回调。 2210 2211> **说明：** 2212> 2213> - 不支持加入存在依赖的任务。 2214> - 前面的任务执行失败或取消不会影响后续任务的执行。 2215 2216**系统能力：** SystemCapability.Utils.Lang 2217 2218**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2219 2220**参数：** 2221 2222| 参数名 | 类型 | 必填 | 说明 | 2223| ------ | ------------- | ---- | -------------------------------- | 2224| task | [Task](#task) | 是 | 需要添加到串行任务队列中的任务。 | 2225 2226**返回值：** 2227 2228| 类型 | 说明 | 2229| ---------------- | --------------------------------- | 2230| Promise\<Object> | Promise对象，返回任务执行的结果。 | 2231 2232**错误码：** 2233 2234以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 2235 2236| 错误码ID | 错误信息 | 2237| -------- | ------------------------------------------- | 2238| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2239| 10200006 | An exception occurred during serialization. | 2240| 10200025 | dependent task not allowed. | 2241| 10200051 | The periodic task cannot be executed again. | 2242| 10200057 | The task cannot be executed by two APIs. | 2243 2244**示例：** 2245 2246```ts 2247@Concurrent 2248function additionDelay(delay: number): void { 2249 let start: number = new Date().getTime(); 2250 while (new Date().getTime() - start < delay) { 2251 continue; 2252 } 2253} 2254@Concurrent 2255function waitForRunner(finalString: string): string { 2256 return finalString; 2257} 2258async function seqRunner() { 2259 let finalString:string = ""; 2260 let task1:taskpool.Task = new taskpool.Task(additionDelay, 3000); 2261 let task2:taskpool.Task = new taskpool.Task(additionDelay, 2000); 2262 let task3:taskpool.Task = new taskpool.Task(additionDelay, 1000); 2263 let task4:taskpool.Task = new taskpool.Task(waitForRunner, finalString); 2264 2265 let runner:taskpool.SequenceRunner = new taskpool.SequenceRunner(); 2266 runner.execute(task1).then(() => { 2267 finalString += 'a'; 2268 console.info("seqrunner: task1 done."); 2269 }); 2270 runner.execute(task2).then(() => { 2271 finalString += 'b'; 2272 console.info("seqrunner: task2 done"); 2273 }); 2274 runner.execute(task3).then(() => { 2275 finalString += 'c'; 2276 console.info("seqrunner: task3 done"); 2277 }); 2278 await runner.execute(task4); 2279 console.info("seqrunner: task4 done, finalString is " + finalString); 2280} 2281``` 2282 2283## AsyncRunner<sup>18+</sup> 2284 2285表示异步队列。可以指定任务执行的并发度和排队策略。 2286 2287### constructor<sup>18+</sup> 2288 2289constructor(runningCapacity: number, waitingCapacity?: number) 2290 2291AsyncRunner的构造函数。构造一个非全局的异步队列，如果参数相同，返回的是不同的异步队列。 2292 2293**系统能力：** SystemCapability.Utils.Lang 2294 2295**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2296 2297**参数：** 2298 2299| 参数名 | 类型 | 必填 | 说明 | 2300| -------- | --------------------- | ---- | ---------------------------------------------------------- | 2301| runningCapacity | number | 是 | 指定任务执行的最大并发度，该参数应为正整数，负数时报错，非整数时会向下取整。 | 2302| waitingCapacity | number | 否 | 指定等待任务的列表容量，取值需大于等于0，负数时报错，输入非整数时会向下取整。默认值为0，表示等待任务列表的容量没有限制。如果设置大于0的值，则表示排队策略为丢弃策略，当加入的任务数量超过该值时，等待列表中处于队头的任务会被丢弃。 | 2303 2304**错误码：** 2305 2306以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2307 2308| 错误码ID | 错误信息 | 2309| -------- | -------- | 2310| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2311 2312**示例：** 2313 2314```ts 2315let runner: taskpool.AsyncRunner = new taskpool.AsyncRunner(5); 2316``` 2317 2318### constructor<sup>18+</sup> 2319 2320constructor(name: string, runningCapacity: number, waitingCapacity?: number) 2321 2322AsyncRunner的构造函数用于构造一个全局异步队列。如果队列名称相同，将返回同一个异步队列实例。 2323 2324> **说明：** 2325> 2326> - 底层通过单例模式确保创建同名的异步队列时，获取同一个实例。 2327> - 无法修改并发度和等待任务列表容量。 2328 2329**系统能力：** SystemCapability.Utils.Lang 2330 2331**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2332 2333**参数：** 2334 2335| 参数名 | 类型 | 必填 | 说明 | 2336| -------- | --------------------- | ---- | ---------------------------------------------------------- | 2337| name | string | 是 | 异步队列的名字。 | 2338| runningCapacity | number | 是 | 指定任务执行的最大并发度，该参数应为正整数。负数时报错，非整数会向下取整。 | 2339| waitingCapacity | number | 否 | 指定等待任务的列表容量，取值需大于等于0，负数时报错，非整数时会向下取整。默认值为0，表示等待任务列表的容量没有限制。如果设置大于0的值，则表示排队策略为丢弃策略，当加入的任务数量超过该值时，等待列表中处于队头的任务会被丢弃。 | 2340 2341**错误码：** 2342 2343以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2344 2345| 错误码ID | 错误信息 | 2346| -------- | -------- | 2347| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2348 2349**示例：** 2350 2351```ts 2352let runner:taskpool.AsyncRunner = new taskpool.AsyncRunner("runner1", 5, 5); 2353``` 2354 2355### execute<sup>18+</sup> 2356 2357execute(task: Task, priority?: Priority): Promise\<Object> 2358 2359执行异步任务。使用该方法前需要先构造AsyncRunner。使用Promise异步回调。 2360 2361> **说明：** 2362> 2363> - 不支持执行任务组中的任务。 2364> - 不支持执行串行队列中的任务。 2365> - 不支持执行其他异步队列任务。 2366> - 不支持执行周期性任务。 2367> - 不支持执行延迟任务。 2368> - 不支持执行存在依赖的任务。 2369> - 不支持执行已执行过的任务。 2370 2371**系统能力：** SystemCapability.Utils.Lang 2372 2373**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2374 2375**参数：** 2376 2377| 参数名 | 类型 | 必填 | 说明 | 2378| ------ | ------------- | ---- | -------------------------------- | 2379| task | [Task](#task) | 是 | 需要添加到异步队列中的任务。 | 2380| priority | [Priority](#priority) | 否 | 指定任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | 2381 2382**返回值：** 2383 2384| 类型 | 说明 | 2385| ---------------- | --------------------------------- | 2386| Promise\<Object> | Promise对象，返回任务执行的结果。 | 2387 2388**错误码：** 2389 2390以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 2391 2392| 错误码ID | 错误信息 | 2393| -------- | ------------------------------------------- | 2394| 10200006 | An exception occurred during serialization. | 2395| 10200025 | dependent task not allowed. | 2396| 10200051 | The periodic task cannot be executed again. | 2397| 10200054 | The asyncRunner task is discarded. | 2398| 10200057 | The task cannot be executed by two APIs. | 2399 2400**示例：** 2401 2402```ts 2403import { taskpool } from '@kit.ArkTS'; 2404import { BusinessError } from '@kit.BasicServicesKit'; 2405 2406@Concurrent 2407function additionDelay(delay: number): void { 2408 let start: number = new Date().getTime(); 2409 while (new Date().getTime() - start < delay) { 2410 continue; 2411 } 2412} 2413async function asyRunner() { 2414 let runner:taskpool.AsyncRunner = new taskpool.AsyncRunner("runner1", 5, 5); 2415 for (let i = 0; i < 30; i++) { 2416 let task:taskpool.Task = new taskpool.Task(additionDelay, 1000); 2417 runner.execute(task).then(() => { 2418 console.info("asyncRunner: task" + i + " done."); 2419 }).catch((e: BusinessError) => { 2420 console.error("asyncRunner: task" + i + " error." + e.code + "-" + e.message); 2421 }); 2422 } 2423} 2424 2425async function asyRunner2() { 2426 let runner:taskpool.AsyncRunner = new taskpool.AsyncRunner(5); 2427 for (let i = 0; i < 20; i++) { 2428 let task:taskpool.Task = new taskpool.Task(additionDelay, 1000); 2429 runner.execute(task).then(() => { 2430 console.info("asyncRunner: task" + i + " done."); 2431 }); 2432 } 2433} 2434``` 2435 2436## State<sup>10+</sup> 2437 2438表示任务（Task）状态的枚举。当任务创建成功后，调用execute，任务进入taskpool等待队列，状态设置为WAITING；任务从等待队列出来进入taskpool工作线程中，任务状态更新为RUNNING；当任务执行完成，返回结果后任务状态重置为WAITING；当主动cancel任务时，将任务状态更新为CANCELED。 2439 2440**系统能力：** SystemCapability.Utils.Lang 2441 2442**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2443 2444| 名称 | 值 | 说明 | 2445| --------- | -------- | ------------- | 2446| WAITING | 1 | 任务正在等待。 | 2447| RUNNING | 2 | 任务正在执行。 | 2448| CANCELED | 3 | 任务已被取消。 | 2449 2450 2451## TaskInfo<sup>10+</sup> 2452 2453任务的内部信息。 2454 2455**系统能力：** SystemCapability.Utils.Lang 2456 2457### 属性 2458 2459**系统能力：** SystemCapability.Utils.Lang 2460 2461| 名称 | 类型 | 只读 | 可选 | 说明 | 2462| -------- | ------------------ | ---- | ---- | ------------------------------------------------------------- | 2463| name<sup>12+</sup> | string | 否 | 否 | 任务的名字。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2464| taskId | number | 否 | 否 | 任务的ID。任务的标识符，系统默认提供全局唯一值，不建议修改此值。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2465| state | [State](#state10) | 否 | 否 | 任务的状态。state标识任务的当前状态，不建议修改此值。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2466| duration | number | 否 | 是 | 任务执行至当前所用的时间，默认为0，单位为ms。当返回为0时，表示任务未执行；返回为空时，表示没有任务执行。不建议修改此值。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2467 2468 2469## ThreadInfo<sup>10+</sup> 2470 2471工作线程的内部信息。 2472 2473**系统能力：** SystemCapability.Utils.Lang 2474 2475### 属性 2476 2477**系统能力：** SystemCapability.Utils.Lang 2478 2479**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2480 2481| 名称 | 类型 | 只读 | 可选 | 说明 | 2482| -------- | ---------------------- | ---- | ---- | -------------------------------------------------------- | 2483| tid | number | 否 | 否 | 工作线程的标识符。如果返回为空，表示当前没有任务执行。不建议修改此值。 | 2484| taskIds | number[] | 否 | 是 | 在当前线程上运行的任务id列表。返回为空时，代表没有任务执行。不建议修改此值。 | 2485| priority | [Priority](#priority) | 否 | 是 | 当前线程的优先级。返回为空时，代表没有任务执行。 不建议修改此值。 | 2486 2487## TaskPoolInfo<sup>10+</sup> 2488 2489任务池的内部信息。 2490 2491**系统能力：** SystemCapability.Utils.Lang 2492 2493### 属性 2494 2495**系统能力：** SystemCapability.Utils.Lang 2496 2497**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2498 2499| 名称 | 类型 | 只读 | 可选 | 说明 | 2500| ------------- | -------------------------------- | ---- | ---- | -------------------- | 2501| threadInfos | [ThreadInfo[]](#threadinfo10) | 否 | 否 | 工作线程的内部信息。不建议修改此值。| 2502| taskInfos | [TaskInfo[]](#taskinfo10) | 否 | 否 | 任务的内部信息。不建议修改此值。 | 2503 2504## TaskResult<sup>20+</sup> 2505 2506处于等待或执行过程中的任务进行取消操作后，在catch分支里捕获到BusinessError里的补充信息。其他场景下该信息为undefined。 2507 2508**系统能力：** SystemCapability.Utils.Lang 2509 2510### 属性 2511 2512**系统能力：** SystemCapability.Utils.Lang 2513 2514**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2515 2516| 名称 | 类型 | 只读 | 可选 | 说明 | 2517| -------- | ------------------ | ---- | ---- | ------------------------------------------------------------- | 2518| result | Object | 否 | 是 | 任务执行结果。默认为undefined。 不建议修改此值。 | 2519| error | Error \| Object | 否 | 是 | 错误信息。默认和BusinessError的message字段一致。不建议修改此值。 | 2520 2521> **说明：** 2522> 2523> 任务被取消后，有如下两种情况： 2524> - 如果当前任务是处于等待阶段，则result的值为undefined，error的值和BusinessError的message字段一致； 2525> - 如果当前任务正在运行，有异常抛出的情况下result的值为undefined，error的值为抛出的异常信息；没有异常的情况下，result为任务执行完成后的结果，error的值和BusinessError的message字段一致。 2526> 2527 2528**示例** 2529 2530```ts 2531import { taskpool } from '@kit.ArkTS'; 2532import { BusinessError } from '@kit.BasicServicesKit' 2533 2534@Concurrent 2535function loop(): Error | number { 2536 let start: number = Date.now(); 2537 while (Date.now() - start < 1500) { 2538 } 2539 if (taskpool.Task.isCanceled()) { 2540 return 0; 2541 } 2542 while (Date.now() - start < 3000) { 2543 } 2544 if (taskpool.Task.isCanceled()) { 2545 throw new Error("this is loop error"); 2546 } 2547 return 1; 2548} 2549 2550// 执行前取消 2551function waitingCancel() { 2552 let task = new taskpool.Task(loop); 2553 taskpool.executeDelayed(2000, task).catch((e:BusinessError<taskpool.TaskResult>) => { 2554 console.error(`waitingCancel task catch code: ${e.code}, message: ${e.message}`); 2555 // waitingCancel task catch code: 0, message: taskpool:: task has been canceled 2556 if (e.data !== undefined) { 2557 console.error(`waitingCancel task catch data: result: ${e.data.result}, error: ${e.data.error}`); 2558 // waitingCancel task catch data: result: undefined, error: taskpool:: task has been canceled 2559 } 2560 }) 2561 setTimeout(() => { 2562 taskpool.cancel(task); 2563 }, 1000); 2564} 2565 2566// 执行过程中取消 2567function runningCancel() { 2568 let task = new taskpool.Task(loop); 2569 taskpool.execute(task).catch((e:BusinessError<taskpool.TaskResult>) => { 2570 console.error(`runningCancel task catch code: ${e.code}, message: ${e.message}`); 2571 // runningCancel task catch code: 0, message: taskpool:: task has been canceled 2572 if (e.data !== undefined) { 2573 console.error(`runningCancel task catch data: result: ${e.data.result}, error: ${e.data.error}`); 2574 // runningCancel task catch data: result: 0, error: taskpool:: task has been canceled 2575 } 2576 }) 2577 setTimeout(() => { 2578 taskpool.cancel(task); 2579 }, 1000); 2580} 2581 2582// 执行过程中抛异常 2583function runningCancelError() { 2584 let task = new taskpool.Task(loop); 2585 taskpool.execute(task).catch((e:BusinessError<taskpool.TaskResult>) => { 2586 console.error(`runningCancelError task catch code: ${e.code}, message: ${e.message}`); 2587 // runningCancelError task catch code: 0, message: taskpool:: task has been canceled 2588 if (e.data !== undefined) { 2589 console.error(`runningCancelError task catch data: result: ${e.data.result}, error: ${e.data.error}`); 2590 // runningCancelError task catch data: result: undefined, error: Error: this is loop error 2591 } 2592 }) 2593 setTimeout(() => { 2594 taskpool.cancel(task); 2595 }, 2000); 2596} 2597``` 2598 2599## 其他说明 2600 2601### 序列化支持类型 2602序列化支持类型包括：目前支持的数据类型有[普通对象](../../arkts-utils/normal-object.md)、[ArrayBuffer对象](../../arkts-utils/arraybuffer-object.md)、[SharedArrayBuffer对象](../../arkts-utils/shared-arraybuffer-object.md)、[Transferable对象（NativeBinding对象）](../../arkts-utils/transferabled-object.md)、[Sendable对象](../../arkts-utils/arkts-sendable.md)五种。 2603 2604### 简单使用 2605 2606**示例一** 2607 2608```ts 2609// 支持普通函数、引用入参传递 2610@Concurrent 2611function printArgs(args: string): string { 2612 console.info("func: " + args); 2613 return args; 2614} 2615 2616async function taskpoolExecute(): Promise<void> { 2617 // taskpool.execute(task) 2618 let task: taskpool.Task = new taskpool.Task(printArgs, "create task, then execute"); 2619 console.info("taskpool.execute(task) result: " + await taskpool.execute(task)); 2620 // taskpool.execute(function) 2621 console.info("taskpool.execute(function) result: " + await taskpool.execute(printArgs, "execute task by func")); 2622} 2623 2624taskpoolExecute(); 2625``` 2626 2627**示例二** 2628 2629```ts 2630// b.ets 2631export let c: string = "hello"; 2632``` 2633<!--code_no_check--> 2634```ts 2635// 引用import变量 2636// a.ets(与b.ets位于同一目录中) 2637import { c } from "./b"; 2638 2639@Concurrent 2640function printArgs(a: string): string { 2641 console.info(a); 2642 console.info(c); 2643 return a; 2644} 2645 2646async function taskpoolExecute(): Promise<void> { 2647 // taskpool.execute(task) 2648 let task: taskpool.Task = new taskpool.Task(printArgs, "create task, then execute"); 2649 console.info("taskpool.execute(task) result: " + await taskpool.execute(task)); 2650 2651 // taskpool.execute(function) 2652 console.info("taskpool.execute(function) result: " + await taskpool.execute(printArgs, "execute task by func")); 2653} 2654 2655taskpoolExecute(); 2656``` 2657 2658**示例三** 2659 2660```ts 2661// 支持async函数 2662@Concurrent 2663async function delayExecute(): Promise<Object> { 2664 let ret = await Promise.all<Object>([ 2665 new Promise<Object>(resolve => setTimeout(resolve, 1000, "resolved")) 2666 ]); 2667 return ret; 2668} 2669 2670async function taskpoolExecute(): Promise<void> { 2671 taskpool.execute(delayExecute).then((result: Object) => { 2672 console.info("taskPoolTest task result: " + result); 2673 }).catch((err: string) => { 2674 console.error("taskpool test occur error: " + err); 2675 }); 2676} 2677 2678taskpoolExecute(); 2679``` 2680 2681**示例四** 2682 2683```ts 2684// c.ets 2685@Concurrent 2686function strSort(inPutArr: Array<string>): Array<string> { 2687 let newArr = inPutArr.sort(); 2688 return newArr; 2689} 2690 2691export async function func1(): Promise<void> { 2692 console.info("taskpoolTest start"); 2693 let strArray: Array<string> = ['c test string', 'b test string', 'a test string']; 2694 let task: taskpool.Task = new taskpool.Task(strSort, strArray); 2695 console.info("func1 result:" + await taskpool.execute(task)); 2696} 2697 2698export async function func2(): Promise<void> { 2699 console.info("taskpoolTest2 start"); 2700 let strArray: Array<string> = ['c test string', 'b test string', 'a test string']; 2701 taskpool.execute(strSort, strArray).then((result: Object) => { 2702 console.info("func2 result: " + result); 2703 }).catch((err: string) => { 2704 console.error("taskpool test occur error: " + err); 2705 }); 2706} 2707``` 2708<!--code_no_check--> 2709```ts 2710// index.ets 2711import { func1, func2 } from "./c"; 2712 2713func1(); 2714func2(); 2715``` 2716 2717**示例五** 2718 2719```ts 2720// 任务取消成功 2721@Concurrent 2722function inspectStatus(arg: number): number { 2723 // 第一次检查任务是否已经取消并作出响应 2724 if (taskpool.Task.isCanceled()) { 2725 console.info("task has been canceled before 2s sleep."); 2726 return arg + 2; 2727 } 2728 // 2s sleep 2729 let t: number = Date.now(); 2730 while (Date.now() - t < 2000) { 2731 continue; 2732 } 2733 // 第二次检查任务是否已经取消并作出响应 2734 if (taskpool.Task.isCanceled()) { 2735 console.info("task has been canceled after 2s sleep."); 2736 return arg + 3; 2737 } 2738 return arg + 1; 2739} 2740 2741async function taskpoolCancel(): Promise<void> { 2742 let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number 2743 taskpool.execute(task).then((res: Object) => { 2744 console.info("taskpool test result: " + res); 2745 }).catch((err: string) => { 2746 console.error("taskpool test occur error: " + err); 2747 }); 2748 // 1s后取消task 2749 setTimeout(() => { 2750 try { 2751 taskpool.cancel(task); 2752 } catch (e) { 2753 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 2754 } 2755 }, 1000); 2756} 2757 2758taskpoolCancel(); 2759``` 2760 2761**示例六** 2762 2763```ts 2764// 已执行的任务取消失败 2765@Concurrent 2766function inspectStatus(arg: number): number { 2767 // 第一次检查任务是否已经取消并作出响应 2768 if (taskpool.Task.isCanceled()) { 2769 return arg + 2; 2770 } 2771 // 延时0.5s 2772 let t: number = Date.now(); 2773 while (Date.now() - t < 500) { 2774 continue; 2775 } 2776 // 第二次检查任务是否已经取消并作出响应 2777 if (taskpool.Task.isCanceled()) { 2778 return arg + 3; 2779 } 2780 return arg + 1; 2781} 2782 2783async function taskpoolCancel(): Promise<void> { 2784 let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number 2785 taskpool.execute(task).then((res: Object) => { 2786 console.info("taskpool test result: " + res); 2787 }).catch((err: string) => { 2788 console.error("taskpool test occur error: " + err); 2789 }); 2790 2791 setTimeout(() => { 2792 try { 2793 taskpool.cancel(task); // 任务已执行,取消失败 2794 } catch (e) { 2795 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 2796 } 2797 }, 3000); // 延时3s，确保任务已执行 2798} 2799 2800taskpoolCancel(); 2801``` 2802 2803**示例七** 2804 2805```ts 2806// 待执行的任务组取消成功 2807@Concurrent 2808function printArgs(args: number): number { 2809 let t: number = Date.now(); 2810 while (Date.now() - t < 1000) { 2811 continue; 2812 } 2813 console.info("printArgs: " + args); 2814 return args; 2815} 2816 2817async function taskpoolGroupCancelTest(): Promise<void> { 2818 let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup(); 2819 taskGroup1.addTask(printArgs, 10); // 10: test number 2820 taskGroup1.addTask(printArgs, 20); // 20: test number 2821 taskGroup1.addTask(printArgs, 30); // 30: test number 2822 let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup(); 2823 let task1: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number 2824 let task2: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number 2825 let task3: taskpool.Task = new taskpool.Task(printArgs, 300); // 300: test number 2826 taskGroup2.addTask(task1); 2827 taskGroup2.addTask(task2); 2828 taskGroup2.addTask(task3); 2829 taskpool.execute(taskGroup1).then((res: Array<Object>) => { 2830 console.info("taskpool execute res is:" + res); 2831 }).catch((e: string) => { 2832 console.error("taskpool execute error is:" + e); 2833 }); 2834 taskpool.execute(taskGroup2).then((res: Array<Object>) => { 2835 console.info("taskpool execute res is:" + res); 2836 }).catch((e: string) => { 2837 console.error("taskpool execute error is:" + e); 2838 }); 2839 2840 try { 2841 taskpool.cancel(taskGroup2); 2842 } catch (e) { 2843 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 2844 } 2845} 2846 2847taskpoolGroupCancelTest() 2848``` 2849 2850**示例八** 2851 2852```ts 2853// 分别创建执行100个高、中、低优先级的任务，查看其各项信息 2854@Concurrent 2855function delay(): void { 2856 let start: number = new Date().getTime(); 2857 while (new Date().getTime() - start < 500) { 2858 continue; 2859 } 2860} 2861 2862let highCount: number = 0; 2863let mediumCount: number = 0; 2864let lowCount: number = 0; 2865let allCount: number = 100; 2866for (let i = 0; i < allCount; i++) { 2867 let task1: taskpool.Task = new taskpool.Task(delay); 2868 let task2: taskpool.Task = new taskpool.Task(delay); 2869 let task3: taskpool.Task = new taskpool.Task(delay); 2870 taskpool.execute(task1, taskpool.Priority.LOW).then(() => { 2871 lowCount++; 2872 }).catch((e: string) => { 2873 console.error("low task error: " + e); 2874 }) 2875 taskpool.execute(task2, taskpool.Priority.MEDIUM).then(() => { 2876 mediumCount++; 2877 }).catch((e: string) => { 2878 console.error("medium task error: " + e); 2879 }) 2880 taskpool.execute(task3, taskpool.Priority.HIGH).then(() => { 2881 highCount++; 2882 }).catch((e: string) => { 2883 console.error("high task error: " + e); 2884 }) 2885} 2886let start: number = new Date().getTime(); 2887while (new Date().getTime() - start < 1000) { 2888 continue; 2889} 2890let taskpoolInfo: taskpool.TaskPoolInfo = taskpool.getTaskPoolInfo(); 2891let tid: number = 0; 2892let taskIds: Array<number> = []; 2893let priority: number = 0; 2894let taskId: number = 0; 2895let state: number = 0; 2896let duration: number = 0; 2897let name: string = ""; 2898let threadIS = Array.from(taskpoolInfo.threadInfos); 2899for (let threadInfo of threadIS) { 2900 tid = threadInfo.tid; 2901 if (threadInfo.taskIds != undefined && threadInfo.priority != undefined) { 2902 taskIds.length = threadInfo.taskIds.length; 2903 priority = threadInfo.priority; 2904 } 2905 console.info("taskpool---tid is:" + tid + ", taskIds is:" + taskIds + ", priority is:" + priority); 2906} 2907let taskIS = Array.from(taskpoolInfo.taskInfos); 2908for (let taskInfo of taskIS) { 2909 taskId = taskInfo.taskId; 2910 state = taskInfo.state; 2911 if (taskInfo.duration != undefined) { 2912 duration = taskInfo.duration; 2913 name = taskInfo.name; 2914 } 2915 console.info("taskpool---taskId is:" + taskId + ", state is:" + state + ", duration is:" + duration + ", name is:" + name); 2916} 2917```