1# @ohos.taskpool（启动任务池） 2 3任务池（taskpool）作用是为应用程序提供一个多线程的运行环境，降低整体资源的消耗、提高系统的整体性能，且您无需关心线程实例的生命周期。您可以使用任务池API创建后台任务（Task），并对所创建的任务进行如任务执行、任务取消的操作。理论上您可以使用任务池API创建数量不受限制的任务，但是出于内存因素不建议您这样做。此外，不建议您在任务中执行阻塞操作，特别是无限期阻塞操作，长时间的阻塞操作占据工作线程，可能会阻塞其他任务调度，影响您的应用性能。 4 5您所创建的同一优先级任务的执行顺序可以由您决定，任务真实执行的顺序与您调用任务池API提供的任务执行接口顺序一致。任务默认优先级是MEDIUM。 6 7当同一时间待执行的任务数量大于任务池工作线程数量，任务池会根据负载均衡机制进行扩容，增加工作线程数量，减少整体等待时长。同样，当执行的任务数量减少，工作线程数量大于执行任务数量，部分工作线程处于空闲状态，任务池会根据负载均衡机制进行缩容，减少工作线程数量。 8 9任务池API以数字形式返回错误码。有关各个错误码的更多信息，请参阅文档[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 10 11taskpool使用过程中的相关注意点请查[TaskPool注意事项](../../arkts-utils/taskpool-introduction.md#taskpool注意事项)。 12 13> **说明：**<br/> 14> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16## 导入模块 17 18```ts 19import taskpool from '@ohos.taskpool'; 20``` 21## taskpool.execute 22 23execute(func: Function, ...args: unknown[]): Promise\<unknown> 24 25将待执行的函数放入taskpool内部任务队列等待，等待分发到工作线程执行。当前执行模式不可取消任务。 26 27**系统能力：** SystemCapability.Utils.Lang 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ------ | --------- | ---- | ---------------------------------------------------------------------- | 33| func | Function | 是 | 执行的逻辑需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 34| args | unknown[] | 否 | 执行逻辑的函数所需要的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 35 36**返回值：** 37 38| 类型 | 说明 | 39| ----------------- | ------------------------------------ | 40| Promise\<unknown> | execute是异步方法，返回Promise对象。 | 41 42**错误码：** 43 44以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 45 46| 错误码ID | 错误信息 | 47| -------- | -------------------------------------------- | 48| 10200003 | Worker initialization failure. | 49| 10200006 | An exception occurred during serialization. | 50| 10200014 | The function is not mark as concurrent. | 51 52**示例：** 53 54```ts 55@Concurrent 56function printArgs(args: number): number { 57 console.log("printArgs: " + args); 58 return args; 59} 60 61taskpool.execute(printArgs, 100).then((value: number) => { // 100: test number 62 console.log("taskpool result: " + value); 63}); 64``` 65 66## taskpool.execute 67 68execute(task: Task, priority?: Priority): Promise\<unknown> 69 70将创建好的任务放入taskpool内部任务队列等待，等待分发到工作线程执行。当前执行模式可尝试调用cancel进行任务取消。 71 72**系统能力：** SystemCapability.Utils.Lang 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| -------- | --------------------- | ---- | ---------------------------------------- | 78| task | [Task](#task) | 是 | 需要在任务池中执行的任务。 | 79| priority | [Priority](#priority) | 否 | 等待执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | 80 81**返回值：** 82 83| 类型 | 说明 | 84| ---------------- | ---------------- | 85| Promise\<unknown> | 返回Promise对象。 | 86 87**错误码：** 88 89以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 90 91| 错误码ID | 错误信息 | 92| -------- | ------------------------------------------- | 93| 10200003 | Worker initialization failure. | 94| 10200006 | An exception occurred during serialization. | 95| 10200014 | The function is not mark as concurrent. | 96 97**示例：** 98 99```ts 100@Concurrent 101function printArgs(args: number): number { 102 console.log("printArgs: " + args); 103 return args; 104} 105 106let task: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number 107taskpool.execute(task).then((value: number) => { 108 console.log("taskpool result: " + value); 109}); 110``` 111 112## taskpool.execute<sup>10+</sup> 113 114execute(group: TaskGroup, priority?: Priority): Promise<unknown[]> 115 116将创建好的任务组放入taskpool内部任务队列等待，等待分发到工作线程执行。 117 118**系统能力：** SystemCapability.Utils.Lang 119 120**参数：** 121 122| 参数名 | 类型 | 必填 | 说明 | 123| --------- | --------------------------- | ---- | -------------------------------------------------------------- | 124| group | [TaskGroup](#taskgroup10) | 是 | 需要在任务池中执行的任务组。 | 125| priority | [Priority](#priority) | 否 | 等待执行的任务组的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | 126 127**返回值：** 128 129| 类型 | 说明 | 130| ---------------- | ---------------------------------- | 131| Promise\<unknown[]> | execute是异步方法，返回Promise对象。 | 132 133**错误码：** 134 135以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 136 137| 错误码ID | 错误信息 | 138| -------- | ------------------------------------------- | 139| 10200006 | An exception occurred during serialization. | 140 141**示例：** 142 143```ts 144@Concurrent 145function printArgs(args: number): number { 146 console.log("printArgs: " + args); 147 return args; 148} 149 150let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup(); 151taskGroup1.addTask(printArgs, 10); // 10: test number 152taskGroup1.addTask(printArgs, 20); // 20: test number 153taskGroup1.addTask(printArgs, 30); // 30: test number 154 155let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup(); 156let task1: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number 157let task2: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number 158let task3: taskpool.Task = new taskpool.Task(printArgs, 300); // 300: test number 159taskGroup2.addTask(task1); 160taskGroup2.addTask(task2); 161taskGroup2.addTask(task3); 162taskpool.execute(taskGroup1).then((res: Array<number>) => { 163 console.info("taskpool execute res is:" + res); 164}); 165taskpool.execute(taskGroup2).then((res: Array<number>) => { 166 console.info("taskpool execute res is:" + res); 167}); 168``` 169 170## taskpool.cancel 171 172cancel(task: Task): void 173 174取消任务池中的任务。 175 176**系统能力：** SystemCapability.Utils.Lang 177 178**参数：** 179 180| 参数名 | 类型 | 必填 | 说明 | 181| ------ | ------------- | ---- | -------------------- | 182| task | [Task](#task) | 是 | 需要取消执行的任务。 | 183 184**错误码：** 185 186以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 187 188| 错误码ID | 错误信息 | 189| -------- | -------------------------------------------- | 190| 10200015 | The task does not exist when it is canceled. | 191| 10200016 | The task is executing when it is canceled. | 192 193从API version10开始，此接口调用时不再涉及上报错误码10200016。 194 195**正在执行的任务取消示例：** 196 197```ts 198@Concurrent 199function inspectStatus(arg: number): number { 200 // 第一次检查任务是否已经取消并作出响应 201 if (taskpool.Task.isCanceled()) { 202 console.info("task has been canceled before 2s sleep."); 203 return arg + 2; 204 } 205 // 2s sleep 206 let t: number = Date.now(); 207 while (Date.now() - t < 2000) { 208 continue; 209 } 210 // 第二次检查任务是否已经取消并作出响应 211 if (taskpool.Task.isCanceled()) { 212 console.info("task has been canceled after 2s sleep."); 213 return arg + 3; 214 } 215 return arg + 1; 216} 217 218function concurrntFunc() { 219 let task1: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number 220 let task2: taskpool.Task = new taskpool.Task(inspectStatus, 200); // 200: test number 221 let task3: taskpool.Task = new taskpool.Task(inspectStatus, 300); // 300: test number 222 let task4: taskpool.Task = new taskpool.Task(inspectStatus, 400); // 400: test number 223 let task5: taskpool.Task = new taskpool.Task(inspectStatus, 500); // 500: test number 224 let task6: taskpool.Task = new taskpool.Task(inspectStatus, 600); // 600: test number 225 taskpool.execute(task1).then((res: Object)=>{ 226 console.info("taskpool test result: " + res); 227 }); 228 taskpool.execute(task2); 229 taskpool.execute(task3); 230 taskpool.execute(task4); 231 taskpool.execute(task5); 232 taskpool.execute(task6); 233 // 1s后取消task 234 setTimeout(()=>{ 235 try { 236 taskpool.cancel(task1); 237 } catch (e) { 238 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 239 } 240 }, 1000); 241} 242 243concurrntFunc(); 244``` 245 246## taskpool.cancel<sup>10+</sup> 247 248cancel(group: TaskGroup): void 249 250取消任务池中的任务组。 251 252**系统能力：** SystemCapability.Utils.Lang 253 254**参数：** 255 256| 参数名 | 类型 | 必填 | 说明 | 257| ------- | ----------------------- | ---- | -------------------- | 258| group | [TaskGroup](#taskgroup10) | 是 | 需要取消执行的任务组。 | 259 260**错误码：** 261 262以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 263 264| 错误码ID | 错误信息 | 265| -------- | ------------------------------------------------------- | 266| 10200018 | The task group does not exist when it is canceled. | 267 268**示例：** 269 270```ts 271@Concurrent 272function printArgs(args: number): number { 273 let t: number = Date.now(); 274 while (Date.now() - t < 2000) { 275 continue; 276 } 277 console.info("printArgs: " + args); 278 return args; 279} 280 281function concurrntFunc() { 282 let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup(); 283 taskGroup1.addTask(printArgs, 10); // 10: test number 284 let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup(); 285 taskGroup2.addTask(printArgs, 100); // 100: test number 286 taskpool.execute(taskGroup1).then((res: Array<Object>)=>{ 287 console.info("taskGroup1 res is:" + res); 288 }); 289 taskpool.execute(taskGroup2).then((res: Array<Object>)=>{ 290 console.info("taskGroup2 res is:" + res); 291 }); 292 setTimeout(()=>{ 293 try { 294 taskpool.cancel(taskGroup2); 295 } catch (e) { 296 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 297 } 298 }, 1000); 299} 300 301concurrntFunc(); 302``` 303 304 305## taskpool.getTaskPoolInfo<sup>10+</sup> 306 307getTaskPoolInfo(): TaskPoolInfo 308 309获取任务池内部信息。 310 311**系统能力：** SystemCapability.Utils.Lang 312 313**返回值：** 314 315| 类型 | 说明 | 316| ----------------------------------- | ------------------ | 317| [TaskPoolInfo](#taskpoolinfo10) | 任务池的内部信息。 | 318 319**示例：** 320 321```ts 322let taskpoolInfo: taskpool.TaskPoolInfo = taskpool.getTaskPoolInfo(); 323``` 324 325## Priority 326 327表示所创建任务（Task）的优先级。 328 329**系统能力：** SystemCapability.Utils.Lang 330 331| 名称 | 值 | 说明 | 332| -------- | -------- | -------- | 333| HIGH | 0 | 任务为高优先级。 | 334| MEDIUM | 1 | 任务为中优先级。 | 335| LOW | 2 | 任务为低优先级。 | 336 337**示例：** 338 339```ts 340@Concurrent 341function printArgs(args: number): number { 342 console.log("printArgs: " + args); 343 return args; 344} 345 346let task: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number 347let highCount = 0; 348let mediumCount = 0; 349let lowCount = 0; 350let allCount = 100; 351for (let i: number = 0; i < allCount; i++) { 352 taskpool.execute(task, taskpool.Priority.LOW).then((res: number) => { 353 lowCount++; 354 console.log("taskpool lowCount is :" + lowCount); 355 }); 356 taskpool.execute(task, taskpool.Priority.MEDIUM).then((res: number) => { 357 mediumCount++; 358 console.log("taskpool mediumCount is :" + mediumCount); 359 }); 360 taskpool.execute(task, taskpool.Priority.HIGH).then((res: number) => { 361 highCount++; 362 console.log("taskpool highCount is :" + highCount); 363 }); 364} 365``` 366 367## Task 368 369表示任务。使用[constructor](#constructor)方法构造Task。 370 371### constructor 372 373constructor(func: Function, ...args: unknown[]) 374 375Task的构造函数。 376 377**系统能力：** SystemCapability.Utils.Lang 378 379**参数：** 380 381| 参数名 | 类型 | 必填 | 说明 | 382| ------ | --------- | ---- | -------------------------------------------------------------------- | 383| func | Function | 是 | 任务执行需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 384| args | unknown[] | 否 | 任务执行传入函数的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 385 386**错误码：** 387 388以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 389 390| 错误码ID | 错误信息 | 391| -------- | --------------------------------------- | 392| 10200014 | The function is not mark as concurrent. | 393 394**示例：** 395 396```ts 397@Concurrent 398function printArgs(args: number): number { 399 console.log("printArgs: " + args); 400 return args; 401} 402 403let task: taskpool.Task = new taskpool.Task(printArgs, "this is my first Task"); 404``` 405 406### isCanceled<sup>10+</sup> 407 408static isCanceled(): boolean 409 410检查当前正在运行的任务是否已取消。使用该方法前需要先构造Task。 411 412**系统能力：** SystemCapability.Utils.Lang 413 414**返回值：** 415 416| 类型 | 说明 | 417| ------- | ------------------------------------ | 418| boolean | 如果当前正在运行的任务被取消返回true，未被取消返回false。| 419 420**示例：** 421 422```ts 423@Concurrent 424function inspectStatus(arg: number): number { 425 // do something 426 if (taskpool.Task.isCanceled()) { 427 console.log("task has been canceled."); 428 // do something 429 return arg + 1; 430 } 431 // do something 432 return arg; 433} 434``` 435 436> **说明：**<br/> 437> isCanceled方法需要和taskpool.cancel方法搭配使用，如果不调用cancel方法，isCanceled方法默认返回false。 438 439**示例：** 440 441```ts 442@Concurrent 443function inspectStatus(arg: number): number { 444 // 第一时间检查取消并回复 445 if (taskpool.Task.isCanceled()) { 446 console.log("task has been canceled before 2s sleep."); 447 return arg + 2; 448 } 449 // 延时2s 450 let t: number = Date.now(); 451 while (Date.now() - t < 2000) { 452 continue; 453 } 454 // 第二次检查取消并作出响应 455 if (taskpool.Task.isCanceled()) { 456 console.log("task has been canceled after 2s sleep."); 457 return arg + 3; 458 } 459 return arg + 1; 460} 461 462let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number 463taskpool.execute(task).then((res: number)=>{ 464 console.log("taskpool test result: " + res); 465}).catch((err: string) => { 466 console.log("taskpool test occur error: " + err); 467}); 468// 不调用cancel，isCanceled()默认返回false，task执行的结果为101 469``` 470 471### setTransferList<sup>10+</sup> 472 473setTransferList(transfer?: ArrayBuffer[]): void 474 475设置任务的传输列表。使用该方法前需要先构造Task。 476 477> **说明：**<br/> 478> 此接口可以设置任务池中ArrayBuffer的transfer列表，transfer列表中的ArrayBuffer对象在传输时不会复制buffer内容到工作线程而是转移buffer控制权至工作线程，传输后当前的ArrayBuffer失效。若ArrayBuffer为空，则不会transfer转移。 479 480**系统能力：** SystemCapability.Utils.Lang 481 482**参数：** 483 484| 参数名 | 类型 | 必填 | 说明 | 485| -------- | ------------- | ---- | --------------------------------------------- | 486| transfer | ArrayBuffer[] | 否 | 可传输对象是ArrayBuffer的实例对象，默认为空数组。 | 487 488**示例：** 489 490```ts 491let buffer: ArrayBuffer = new ArrayBuffer(8); 492let view: Uint8Array = new Uint8Array(buffer); 493let buffer1: ArrayBuffer = new ArrayBuffer(16); 494let view1: Uint8Array = new Uint8Array(buffer1); 495 496console.info("testTransfer view byteLength: " + view.byteLength); 497console.info("testTransfer view1 byteLength: " + view1.byteLength); 498@Concurrent 499function testTransfer(arg1: ArrayBuffer, arg2: ArrayBuffer): number { 500 console.info("testTransfer arg1 byteLength: " + arg1.byteLength); 501 console.info("testTransfer arg2 byteLength: " + arg2.byteLength); 502 return 100; 503} 504let task: taskpool.Task = new taskpool.Task(testTransfer, view, view1); 505task.setTransferList([view.buffer, view1.buffer]); 506taskpool.execute(task).then((res: number)=>{ 507 console.info("test result: " + res); 508}).catch((e: string)=>{ 509 console.error("test catch: " + e); 510}) 511console.info("testTransfer view byteLength: " + view.byteLength); 512console.info("testTransfer view1 byteLength: " + view1.byteLength); 513``` 514 515### 属性 516 517**系统能力：** SystemCapability.Utils.Lang 518 519| 名称 | 类型 | 可读 | 可写 | 说明 | 520| --------- | --------- | ---- | ---- | ------------------------------------------------------------------------- | 521| function | Function | 是 | 是 | 创建任务时需要传入的函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 522| arguments | unknown[] | 是 | 是 | 创建任务传入函数所需的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。 | 523 524## TaskGroup<sup>10+</sup> 525 526表示任务组，一次执行一组任务，如果所有任务正常执行，异步执行完毕后返回所有任务结果的数组，数组中元素的顺序与[addTask](#addtask10-1)的顺序相同；如果任意任务失败，则会抛出对应异常。任务组可以多次执行，但执行后不能新增任务。使用[constructor](#constructor10)方法构造TaskGroup。 527 528### constructor<sup>10+</sup> 529 530constructor() 531 532TaskGroup的构造函数。 533 534**系统能力：** SystemCapability.Utils.Lang 535 536**示例：** 537 538```ts 539let taskGroup = new taskpool.TaskGroup(); 540``` 541 542### addTask<sup>10+</sup> 543 544addTask(func: Function, ...args: unknown[]): void 545 546将待执行的函数添加到任务组中。使用该方法前需要先构造TaskGroup。 547 548**系统能力：** SystemCapability.Utils.Lang 549 550**参数：** 551 552| 参数名 | 类型 | 必填 | 说明 | 553| ------ | --------- | ---- | ---------------------------------------------------------------------- | 554| func | Function | 是 | 任务执行需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 555| args | unknown[] | 否 | 任务执行函数所需要的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 556 557**错误码：** 558 559以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 560 561| 错误码ID | 错误信息 | 562| -------- | --------------------------------------- | 563| 10200014 | The function is not mark as concurrent. | 564 565**示例：** 566 567```ts 568@Concurrent 569function printArgs(args: number): number { 570 console.log("printArgs: " + args); 571 return args; 572} 573 574let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup(); 575taskGroup.addTask(printArgs, 100); // 100: test number 576``` 577 578### addTask<sup>10+</sup> 579 580addTask(task: Task): void 581 582将创建好的任务添加到任务组中。使用该方法前需要先构造TaskGroup。 583 584**系统能力：** SystemCapability.Utils.Lang 585 586**参数：** 587 588| 参数名 | 类型 | 必填 | 说明 | 589| -------- | --------------------- | ---- | ---------------------------------------- | 590| task | [Task](#task) | 是 | 需要添加到任务组中的任务。 | 591 592**错误码：** 593 594以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 595 596| 错误码ID | 错误信息 | 597| -------- | --------------------------------------- | 598| 10200014 | The function is not mark as concurrent. | 599 600**示例：** 601 602```ts 603@Concurrent 604function printArgs(args: number): number { 605 console.log("printArgs: " + args); 606 return args; 607} 608 609let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup(); 610let task: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number 611taskGroup.addTask(task); 612``` 613 614 615## State<sup>10+</sup> 616 617表示任务（Task）状态的枚举。 618 619**系统能力：** SystemCapability.Utils.Lang 620 621| 名称 | 值 | 说明 | 622| --------- | -------- | ------------- | 623| WAITING | 1 | 任务正在等待。 | 624| RUNNING | 2 | 任务正在执行。 | 625| CANCELED | 3 | 任务已被取消。 | 626 627 628## TaskInfo<sup>10+</sup> 629 630任务的内部信息。 631 632**系统能力：** SystemCapability.Utils.Lang 633 634### 属性 635 636**系统能力：** SystemCapability.Utils.Lang 637 638| 名称 | 类型 | 可读 | 可写 | 说明 | 639| -------- | ------------------ | ---- | ---- | ------------------------------------------------------------- | 640| taskId | number | 是 | 否 | 任务的ID。 | 641| state | [State](#state10) | 是 | 否 | 任务的状态。 | 642| duration | number | 是 | 否 | 任务执行至当前所用的时间，单位为ms。当返回为0时，表示任务未执行；返回为空时，表示没有任务执行。 | 643 644## ThreadInfo<sup>10+</sup> 645 646工作线程的内部信息。 647 648**系统能力：** SystemCapability.Utils.Lang 649 650### 属性 651 652**系统能力：** SystemCapability.Utils.Lang 653 654| 名称 | 类型 | 可读 | 可写 | 说明 | 655| -------- | ---------------------- | ---- | ---- | -------------------------------------------------------- | 656| tid | number | 是 | 否 | 工作线程的标识符。返回为空时，代表没有任务执行。 | 657| taskIds | number[] | 是 | 否 | 在当前线程上运行的任务id列表。返回为空时，代表没有任务执行。 | 658| priority | [Priority](#priority) | 是 | 否 | 当前线程的优先级。返回为空时，代表没有任务执行。 | 659 660## TaskPoolInfo<sup>10+</sup> 661 662任务池的内部信息。 663 664**系统能力：** SystemCapability.Utils.Lang 665 666### 属性 667 668**系统能力：** SystemCapability.Utils.Lang 669 670| 名称 | 类型 | 可读 | 可写 | 说明 | 671| ------------- | -------------------------------- | ---- | ---- | -------------------- | 672| threadInfos | [ThreadInfo[]](#threadinfo10) | 是 | 否 | 工作线程的内部信息。 | 673| taskInfos | [TaskInfo[]](#taskinfo10) | 是 | 否 | 任务的内部信息。 | 674 675 676## 其他说明 677 678### 序列化支持类型 679序列化支持类型包括：All Primitive Type(不包括symbol)、Date、String、RegExp、Array、Map、Set、Object、ArrayBuffer、TypedArray。 680 681### 简单使用 682 683**示例一** 684 685```ts 686// 支持普通函数、引用入参传递 687@Concurrent 688function printArgs(args: string): string { 689 console.log("func: " + args); 690 return args; 691} 692async function taskpoolExecute(): Promise<void> { 693 // taskpool.execute(task) 694 let task: taskpool.Task = new taskpool.Task(printArgs, "create task, then execute"); 695 console.log("taskpool.execute(task) result: " + await taskpool.execute(task)); 696 // taskpool.execute(function) 697 console.log("taskpool.execute(function) result: " + await taskpool.execute(printArgs, "execute task by func")); 698} 699taskpoolExecute(); 700``` 701 702**示例二** 703 704```ts 705// b.ets 706export let c: string = "hello"; 707``` 708```ts 709// 引用import变量 710// a.ets(与b.ets位于同一目录中) 711import { c } from "./b"; 712 713@Concurrent 714function printArgs(a: string): string { 715 console.log(a); 716 console.log(c); 717 return a; 718} 719 720async function taskpoolExecute(): Promise<void> { 721 // taskpool.execute(task) 722 let task: taskpool.Task = new taskpool.Task(printArgs, "create task, then execute"); 723 console.log("taskpool.execute(task) result: " + await taskpool.execute(task)); 724 725 // taskpool.execute(function) 726 console.log("taskpool.execute(function) result: " + await taskpool.execute(printArgs, "execute task by func")); 727} 728 729taskpoolExecute(); 730``` 731 732**示例三** 733 734```ts 735// 支持async函数 736@Concurrent 737async function delayExcute(): Promise<Object> { 738 let ret = await Promise.all<Object>([ 739 new Promise<Object>(resolve => setTimeout(resolve, 1000, "resolved")) 740 ]); 741 return ret; 742} 743 744async function taskpoolExecute(): Promise<void> { 745 taskpool.execute(delayExcute).then((result: string) => { 746 console.log("taskPoolTest task result: " + result); 747 }).catch((err: string) => { 748 console.log("taskpool test occur error: " + err); 749 }); 750} 751 752taskpoolExecute(); 753``` 754 755**示例四** 756 757```ts 758// c.ets 759@Concurrent 760function strSort(inPutArr: Array<string>): Array<string> { 761 let newArr = inPutArr.sort(); 762 return newArr; 763} 764export async function func1(): Promise<void> { 765 console.log("taskpoolTest start"); 766 let strArray: Array<string> = ['c test string', 'b test string', 'a test string']; 767 let task: taskpool.Task = new taskpool.Task(strSort, strArray); 768 console.log("func1 result:" + await taskpool.execute(task)); 769} 770 771export async function func2(): Promise<void> { 772 console.log("taskpoolTest2 start"); 773 let strArray: Array<string> = ['c test string', 'b test string', 'a test string']; 774 taskpool.execute(strSort, strArray).then((result: Array<string>) => { 775 console.log("func2 result: " + result); 776 }).catch((err: string) => { 777 console.log("taskpool test occur error: " + err); 778 }); 779} 780``` 781 782```ts 783// a.ets(与c.ets在同一目录中) 784import { func1, func2 } from "./c"; 785 786func1(); 787func2(); 788``` 789 790**示例五** 791 792```ts 793// 任务取消成功 794@Concurrent 795function inspectStatus(arg: number): number { 796 // 第一次检查任务是否已经取消并作出响应 797 if (taskpool.Task.isCanceled()) { 798 console.info("task has been canceled before 2s sleep."); 799 return arg + 2; 800 } 801 // 2s sleep 802 let t: number = Date.now(); 803 while (Date.now() - t < 2000) { 804 continue; 805 } 806 // 第二次检查任务是否已经取消并作出响应 807 if (taskpool.Task.isCanceled()) { 808 console.info("task has been canceled after 2s sleep."); 809 return arg + 3; 810 } 811 return arg + 1; 812} 813 814async function taskpoolCancel(): Promise<void> { 815 let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number 816 taskpool.execute(task).then((res: Object)=>{ 817 console.info("taskpool test result: " + res); 818 }).catch((err: string) => { 819 console.error("taskpool test occur error: " + err); 820 }); 821 // 1s后取消task 822 setTimeout(()=>{ 823 try { 824 taskpool.cancel(task); 825 } catch (e) { 826 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 827 } 828 }, 1000); 829} 830 831taskpoolCancel(); 832``` 833 834**示例六** 835 836```ts 837// 已执行的任务取消失败 838@Concurrent 839function inspectStatus(arg: number): number { 840 // 第一次检查任务是否已经取消并作出响应 841 if (taskpool.Task.isCanceled()) { 842 return arg + 2; 843 } 844 // 延时2s 845 let t: number = Date.now(); 846 while (Date.now() - t < 500) { 847 continue; 848 } 849 // 第二次检查任务是否已经取消并作出响应 850 if (taskpool.Task.isCanceled()) { 851 return arg + 3; 852 } 853 return arg + 1; 854} 855 856async function taskpoolCancel(): Promise<void> { 857 let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number 858 taskpool.execute(task).then((res: Object)=>{ 859 console.info("taskpool test result: " + res); 860 }).catch((err: string) => { 861 console.error("taskpool test occur error: " + err); 862 }); 863 864 setTimeout(()=>{ 865 try { 866 taskpool.cancel(task); // 任务已执行,取消失败 867 } catch (e) { 868 console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`); 869 } 870 }, 3000); // 延时3s，确保任务已执行 871} 872 873taskpoolCancel(); 874``` 875 876**示例七** 877 878```ts 879// 待执行的任务组取消成功 880@Concurrent 881function printArgs(args: number): number { 882 let t: number = Date.now(); 883 while (Date.now() - t < 1000) { 884 continue; 885 } 886 console.log("printArgs: " + args); 887 return args; 888} 889 890async function taskpoolGroupCancelTest(): Promise<void> { 891 let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup(); 892 taskGroup1.addTask(printArgs, 10); // 10: test number 893 taskGroup1.addTask(printArgs, 20); // 20: test number 894 taskGroup1.addTask(printArgs, 30); // 30: test number 895 let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup(); 896 let task1: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number 897 let task2: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number 898 let task3: taskpool.Task = new taskpool.Task(printArgs, 300); // 300: test number 899 taskGroup2.addTask(task1); 900 taskGroup2.addTask(task2); 901 taskGroup2.addTask(task3); 902 taskpool.execute(taskGroup1).then((res: Array<number>) => { 903 console.info("taskpool execute res is:" + res); 904 }).catch((e: string) => { 905 console.error("taskpool execute error is:" + e); 906 }); 907 taskpool.execute(taskGroup2).then((res: Array<number>) => { 908 console.info("taskpool execute res is:" + res); 909 }).catch((e: string) => { 910 console.error("taskpool execute error is:" + e); 911 }); 912 913 taskpool.cancel(taskGroup2); 914} 915 916taskpoolGroupCancelTest() 917``` 918 919**示例八** 920 921```ts 922// 分别创建执行100个高、中、低优先级的任务，查看其各项信息 923@Concurrent 924function delay(): void { 925 let start: number = new Date().getTime(); 926 while (new Date().getTime() - start < 500) { 927 continue; 928 } 929} 930 931let highCount: number = 0; 932let mediumCount: number = 0; 933let lowCount: number = 0; 934let allCount: number = 100; 935for (let i = 0; i < allCount; i++) { 936 let task1: taskpool.Task = new taskpool.Task(delay); 937 let task2: taskpool.Task = new taskpool.Task(delay); 938 let task3: taskpool.Task = new taskpool.Task(delay); 939 taskpool.execute(task1, taskpool.Priority.LOW).then(() => { 940 lowCount++; 941 }).catch((e: string) => { 942 console.error("low task error: " + e); 943 }) 944 taskpool.execute(task2, taskpool.Priority.MEDIUM).then(() => { 945 mediumCount++; 946 }).catch((e: string) => { 947 console.error("medium task error: " + e); 948 }) 949 taskpool.execute(task3, taskpool.Priority.HIGH).then(() => { 950 highCount++; 951 }).catch((e: string) => { 952 console.error("high task error: " + e); 953 }) 954} 955let start: number = new Date().getTime(); 956while (new Date().getTime() - start < 1000) { 957 continue; 958} 959let taskpoolInfo: taskpool.TaskPoolInfo = taskpool.getTaskPoolInfo(); 960let tid: number = 0; 961let taskIds: Array<number> = []; 962let priority: number = 0; 963let taskId: number = 0; 964let state: number = 0; 965let duration: number = 0; 966let threadIS = Array.from(taskpoolInfo.threadInfos) 967for(let threadInfo of threadIS) { 968 tid = threadInfo.tid; 969 if (threadInfo.taskIds != undefined && threadInfo.priority != undefined ) 970 { 971 taskIds.length = threadInfo.taskIds.length; 972 priority = threadInfo.priority; 973 } 974 console.info("taskpool---tid is:" + tid + ", taskIds is:" + taskIds + ", priority is:" + priority); 975} 976let taskIS = Array.from(taskpoolInfo.taskInfos) 977for(let taskInfo of taskIS) { 978 taskId = taskInfo.taskId; 979 state = taskInfo.state; 980 if (taskInfo.duration != undefined ) 981 { 982 duration = taskInfo.duration; 983 } 984 console.info("taskpool---taskId is:" + taskId + ", state is:" + state + ", duration is:" + duration); 985} 986```