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