js-apis-taskpool.md 30.7 KB
Newer Older
1
# @ohos.taskpool(启动任务池)
W
wangzhaoyong 已提交
2

W
wangzhaoyong 已提交
3 4
任务池(taskpool)作用是为应用程序提供一个多线程的运行环境,降低整体资源的消耗、提高系统的整体性能,且您无需关心线程实例的生命周期。您可以使用任务池API创建后台任务(Task),并对所创建的任务进行如任务执行、任务取消的操作。理论上您可以使用任务池API创建数量不受限制的任务,但是出于内存因素不建议您这样做。此外,不建议您在任务中执行阻塞操作,特别是无限期阻塞操作,长时间的阻塞操作占据工作线程,可能会阻塞其他任务调度,影响您的应用性能。

B
buzhuyu 已提交
5
您所创建的同一优先级任务的执行顺序可以由您决定,任务真实执行的顺序与您调用任务池API提供的任务执行接口顺序一致。任务默认优先级是MEDIUM。
W
wangzhaoyong 已提交
6

B
buzhuyu 已提交
7
当同一时间待执行的任务数量大于任务池工作线程数量,任务池会根据负载均衡机制进行扩容,增加工作线程数量,减少整体等待时长。同样,当执行的任务数量减少,工作线程数量大于执行任务数量,部分工作线程处于空闲状态,任务池会根据负载均衡机制进行缩容,减少工作线程数量。
W
wangzhaoyong 已提交
8 9

任务池API以数字形式返回错误码。有关各个错误码的更多信息,请参阅文档[语言基础类库错误码](../errorcodes/errorcode-utils.md)
W
wangzhaoyong 已提交
10

W
wangzhaoyong 已提交
11 12 13
> **说明:**<br/>
> 本模块首批接口从API version 9 开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

W
wangzhaoyong 已提交
14 15
## 导入模块

W
wangzhaoyong 已提交
16
```ts
W
wangzhaoyong 已提交
17 18
import taskpool from '@ohos.taskpool';
```
19
## taskpool.execute
W
wangzhaoyong 已提交
20

21
execute(func: Function, ...args: unknown[]): Promise\<unknown>
W
wangzhaoyong 已提交
22

23
将待执行的函数放入taskpool内部任务队列等待,等待分发到工作线程执行。当前执行模式不可取消任务。
W
wangzhaoyong 已提交
24

25
**系统能力:** SystemCapability.Utils.Lang
W
wangzhaoyong 已提交
26

27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
**参数:**

| 参数名 | 类型      | 必填 | 说明                                                                   |
| ------ | --------- | ---- | ---------------------------------------------------------------------- |
| func   | Function  | 是   | 执行的逻辑需要传入函数,支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。     |
| args   | unknown[] | 否   | 执行逻辑的函数所需要的参数,支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 |

**返回值:**

| 类型              | 说明                                 |
| ----------------- | ------------------------------------ |
| Promise\<unknown> | execute是异步方法,返回Promise对象。 |

**错误码:**

以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)

| 错误码ID | 错误信息                                      |
| -------- | -------------------------------------------- |
| 10200003 | Worker initialization failure.               |
| 10200006 | An exception occurred during serialization.  |
| 10200014 | The function is not mark as concurrent.      |
W
wangzhaoyong 已提交
49

B
buzhuyu 已提交
50 51 52
**示例:**

```ts
B
buzhuyu 已提交
53
@Concurrent
54
function printArgs(args: number): number {
B
buzhuyu 已提交
55
    console.log("printArgs: " + args);
B
buzhuyu 已提交
56 57
    return args;
}
B
buzhuyu 已提交
58

59
taskpool.execute(printArgs, 100).then((value: number) => { // 100: test number
60 61
  console.log("taskpool result: " + value);
});
B
buzhuyu 已提交
62 63
```

64
## taskpool.execute
W
wangzhaoyong 已提交
65

66
execute(task: Task, priority?: Priority): Promise\<unknown>
W
wangzhaoyong 已提交
67

68
将创建好的任务放入taskpool内部任务队列等待,等待分发到工作线程执行。当前执行模式可尝试调用cancel进行任务取消。
W
wangzhaoyong 已提交
69 70 71 72 73

**系统能力:** SystemCapability.Utils.Lang

**参数:**

74 75 76 77 78 79 80 81 82 83
| 参数名   | 类型                  | 必填 | 说明                                       |
| -------- | --------------------- | ---- | ---------------------------------------- |
| task     | [Task](#task)         | 是   | 需要在任务池中执行的任务。                  |
| priority | [Priority](#priority) | 否   | 等待执行的任务的优先级,该参数默认值为taskpool.Priority.MEDIUM。 |

**返回值:**

| 类型              | 说明              |
| ----------------  | ---------------- |
| Promise\<unknown> | 返回Promise对象。 |
W
wangzhaoyong 已提交
84 85 86

**错误码:**

W
wangzhaoyong 已提交
87 88
以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)

89 90 91 92 93
| 错误码ID | 错误信息                                     |
| -------- | ------------------------------------------- |
| 10200003 | Worker initialization failure.              |
| 10200006 | An exception occurred during serialization. |
| 10200014 | The function is not mark as concurrent.     |
W
wangzhaoyong 已提交
94 95 96

**示例:**

W
wangzhaoyong 已提交
97 98
```ts
@Concurrent
99
function printArgs(args: number): number {
B
buzhuyu 已提交
100
    console.log("printArgs: " + args);
W
wangzhaoyong 已提交
101 102
    return args;
}
103

104 105
let task: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number
taskpool.execute(task).then((value: number) => {
106 107
  console.log("taskpool result: " + value);
});
W
wangzhaoyong 已提交
108 109
```

110
## taskpool.execute<sup>10+</sup>
B
buzhuyu 已提交
111

112
execute(group: TaskGroup, priority?: Priority): Promise<unknown[]>
B
buzhuyu 已提交
113

114
将创建好的任务组放入taskpool内部任务队列等待,等待分发到工作线程执行。
B
buzhuyu 已提交
115 116 117

**系统能力:** SystemCapability.Utils.Lang

118 119 120 121 122 123 124
**参数:**

| 参数名     | 类型                        | 必填 | 说明                                                           |
| --------- | --------------------------- | ---- | -------------------------------------------------------------- |
| group     | [TaskGroup](#taskgroup)     | 是   | 需要在任务池中执行的任务组。                                      |
| priority  | [Priority](#priority)       | 否   | 等待执行的任务组的优先级,该参数默认值为taskpool.Priority.MEDIUM。 |

B
buzhuyu 已提交
125 126
**返回值:**

127 128 129 130 131 132 133 134 135 136 137
| 类型                 | 说明                               |
| ----------------    | ---------------------------------- |
| Promise\<unknown[]> | execute是异步方法,返回Promise对象。 |

**错误码:**

以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)

| 错误码ID | 错误信息                                     |
| -------- | ------------------------------------------- |
| 10200006 | An exception occurred during serialization. |
B
buzhuyu 已提交
138 139 140 141 142

**示例:**

```ts
@Concurrent
143
function printArgs(args: number): number {
144 145
    console.log("printArgs: " + args);
    return args;
B
buzhuyu 已提交
146
}
147

148
let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup();
149 150 151 152
taskGroup1.addTask(printArgs, 10); // 10: test number
taskGroup1.addTask(printArgs, 20); // 20: test number
taskGroup1.addTask(printArgs, 30); // 30: test number

153 154 155 156
let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup();
let task1: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number
let task2: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number
let task3: taskpool.Task = new taskpool.Task(printArgs, 300); // 300: test number
157 158 159
taskGroup2.addTask(task1);
taskGroup2.addTask(task2);
taskGroup2.addTask(task3);
160
taskpool.execute(taskGroup1).then((res: Array<number>) => {
161 162
  console.info("taskpool execute res is:" + res);
});
163
taskpool.execute(taskGroup2).then((res: Array<number>) => {
164 165
  console.info("taskpool execute res is:" + res);
});
B
buzhuyu 已提交
166 167
```

168
## taskpool.cancel
B
buzhuyu 已提交
169

170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193
cancel(task: Task): void

取消任务池中的任务。

**系统能力:** SystemCapability.Utils.Lang

**参数:**

| 参数名 | 类型          | 必填 | 说明                 |
| ------ | ------------- | ---- | -------------------- |
| task   | [Task](#task) | 是   | 需要取消执行的任务。 |

**错误码:**

以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)

| 错误码ID | 错误信息                                      |
| -------- | -------------------------------------------- |
| 10200015 | The task does not exist when it is canceled. |
| 10200016 | The task is executing when it is canceled.   |

从API version10开始,此接口调用时不再涉及上报错误码10200016。

**正在执行的任务取消示例:**
B
buzhuyu 已提交
194 195 196

```ts
@Concurrent
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
function inspectStatus(arg: number): number {
  // 第一时间检查取消并回复
  if (taskpool.Task.isCanceled()) {
    console.log("task has been canceled before 2s sleep.");
    return arg + 2;
  }
  // 2s sleep
  let t: number = Date.now();
  while (Date.now() - t < 2000) {
    continue;
  }
  // 第二次检查取消并作出响应
  if (taskpool.Task.isCanceled()) {
    console.log("task has been canceled after 2s sleep.");
    return arg + 3;
  }
  return arg + 1;
B
buzhuyu 已提交
214 215
}

216 217 218 219 220 221 222
let task1: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number
let task2: taskpool.Task = new taskpool.Task(inspectStatus, 200); // 200: test number
let task3: taskpool.Task = new taskpool.Task(inspectStatus, 300); // 300: test number
let task4: taskpool.Task = new taskpool.Task(inspectStatus, 400); // 400: test number
let task5: taskpool.Task = new taskpool.Task(inspectStatus, 500); // 500: test number
let task6: taskpool.Task = new taskpool.Task(inspectStatus, 600); // 600: test number
taskpool.execute(task1).then((res: number)=>{
B
buzhuyu 已提交
223 224
  console.log("taskpool test result: " + res);
});
225 226 227 228 229
taskpool.execute(task2);
taskpool.execute(task3);
taskpool.execute(task4);
taskpool.execute(task5);
taskpool.execute(task6);
230 231 232
// 1s后取消task
setTimeout(()=>{
  taskpool.cancel(task1);}, 1000);
B
buzhuyu 已提交
233 234
```

235
## taskpool.cancel<sup>10+</sup>
B
buzhuyu 已提交
236

237
cancel(group: TaskGroup): void
B
buzhuyu 已提交
238

239
取消任务池中的任务组。
B
buzhuyu 已提交
240 241 242 243 244

**系统能力:** SystemCapability.Utils.Lang

**参数:**

245 246 247 248 249 250 251 252 253 254 255
| 参数名   | 类型                    | 必填 | 说明                 |
| ------- | ----------------------- | ---- | -------------------- |
| group   | [TaskGroup](#taskgroup) | 是   | 需要取消执行的任务组。 |

**错误码:**

以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)

| 错误码ID | 错误信息                                                 |
| -------- | ------------------------------------------------------- |
| 10200018 | The task group does not exist when it is canceled.      |
B
buzhuyu 已提交
256 257 258 259 260

**示例:**

```ts
@Concurrent
261 262 263 264 265 266 267
function printArgs(args: number): number {
  let t: number = Date.now();
  while (Date.now() - t < 2000) {
    continue;
  }
  console.log("printArgs: " + args);
  return args;
B
buzhuyu 已提交
268 269
}

270
let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup();
271
taskGroup1.addTask(printArgs, 10); // 10: test number
272
let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup();
273
taskGroup2.addTask(printArgs, 100); // 100: test number
274
taskpool.execute(taskGroup1).then((res: Array<number>)=>{
275 276
  console.info("taskGroup1 res is:" + res)
});
277
taskpool.execute(taskGroup2).then((res: Array<number>)=>{
278 279 280 281 282 283 284 285 286 287
  console.info("taskGroup2 res is:" + res)
});
setTimeout(()=>{
  try {
    taskpool.cancel(taskGroup2);
  } catch (e) {
    console.log("taskGroup.cancel occur error:" + e);
  }
}, 1000);
```
W
wangzhaoyong 已提交
288 289


290
## taskpool.getTaskPoolInfo<sup>10+</sup>
W
wangzhaoyong 已提交
291

292
getTaskPoolInfo(): TaskPoolInfo
B
buzhuyu 已提交
293

294
获取任务池内部信息。
B
buzhuyu 已提交
295

296
**系统能力:** SystemCapability.Utils.Lang
B
buzhuyu 已提交
297

298
**返回值:**
B
buzhuyu 已提交
299

300 301 302
| 类型                                | 说明                |
| ----------------------------------- | ------------------ |
| [TaskPoolInfo](#taskpoolinfo10)   | 任务池的内部信息。   |
B
buzhuyu 已提交
303 304 305 306

**示例:**

```ts
307
let taskpoolInfo: taskpool.TaskPoolInfo = taskpool.getTaskPoolInfo();
B
buzhuyu 已提交
308 309
```

310
## Priority
B
buzhuyu 已提交
311

312
表示所创建任务(Task)的优先级。
B
buzhuyu 已提交
313

314
**系统能力:**  SystemCapability.Utils.Lang
B
buzhuyu 已提交
315

316 317 318 319 320
| 名称 | 值 | 说明 |
| -------- | -------- | -------- |
| HIGH   | 0    | 任务为高优先级。 |
| MEDIUM | 1 | 任务为中优先级。 |
| LOW | 2 | 任务为低优先级。 |
B
buzhuyu 已提交
321 322 323 324 325

**示例:**

```ts
@Concurrent
326 327 328
function printArgs(args: number): number {
  console.log("printArgs: " + args);
  return args;
B
buzhuyu 已提交
329 330
}

331
let task: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number
332 333 334 335
let highCount = 0;
let mediumCount = 0;
let lowCount = 0;
let allCount = 100;
336
for (let i: number = 0; i < allCount; i++) {
337 338 339
  taskpool.execute(task, taskpool.Priority.LOW).then((res: number) => {
    lowCount++;
    console.log("taskpool lowCount is :" + lowCount);
340
  });
341 342 343
  taskpool.execute(task, taskpool.Priority.MEDIUM).then((res: number) => {
    mediumCount++;
    console.log("taskpool mediumCount is :" + mediumCount);
344
  });
345 346 347
  taskpool.execute(task, taskpool.Priority.HIGH).then((res: number) => {
    highCount++;
    console.log("taskpool highCount is :" + highCount);
348
  });
349
}
B
buzhuyu 已提交
350 351
```

352
## Task
B
buzhuyu 已提交
353

354
表示任务。使用[constructor](#constructor)方法构造Task。
B
buzhuyu 已提交
355

356 357 358 359 360
### constructor

constructor(func: Function, ...args: unknown[])

Task的构造函数。
B
buzhuyu 已提交
361 362 363 364 365

**系统能力:** SystemCapability.Utils.Lang

**参数:**

366 367 368 369
| 参数名 | 类型      | 必填 | 说明                                                                  |
| ------ | --------- | ---- | -------------------------------------------------------------------- |
| func   | Function  | 是   | 任务执行需要传入函数,支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。   |
| args   | unknown[] | 否   | 任务执行传入函数的参数,支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 |
B
buzhuyu 已提交
370 371 372 373 374 375 376 377 378 379 380 381 382

**错误码:**

以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)

| 错误码ID | 错误信息                                 |
| -------- | --------------------------------------- |
| 10200014 | The function is not mark as concurrent. |

**示例:**

```ts
@Concurrent
383 384 385
function printArgs(args: number): number {
  console.log("printArgs: " + args);
  return args;
B
buzhuyu 已提交
386 387
}

388
let task: taskpool.Task = new taskpool.Task(printArgs, "this is my first Task");
B
buzhuyu 已提交
389 390
```

391
### isCanceled<sup>10+</sup>
W
wangzhaoyong 已提交
392

393
static isCanceled(): boolean
W
wangzhaoyong 已提交
394

395
检查当前正在运行的任务是否已取消。使用该方法前需要先构造Task。
W
wangzhaoyong 已提交
396 397 398 399 400

**系统能力:** SystemCapability.Utils.Lang

**返回值:**

401 402 403
| 类型    | 说明                                 |
| ------- | ------------------------------------ |
| boolean | 如果当前正在运行的任务被取消返回true,未被取消返回false。|
W
wangzhaoyong 已提交
404

405
**示例:**
W
wangzhaoyong 已提交
406

407 408
```ts
@Concurrent
409
function inspectStatus(arg: number): number {
410 411 412 413 414 415 416 417 418 419
    // do something
    if (taskpool.Task.isCanceled()) {
      console.log("task has been canceled.");
      // do something
      return arg + 1;
    }
    // do something
    return arg;
}
```
W
wangzhaoyong 已提交
420

421 422
> **说明:**<br/>
> isCanceled方法需要和taskpool.cancel方法搭配使用,如果不调用cancel方法,isCanceled方法默认返回false。
W
wangzhaoyong 已提交
423 424 425

**示例:**

W
wangzhaoyong 已提交
426 427
```ts
@Concurrent
428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443
function inspectStatus(arg: number): number {
  // 第一时间检查取消并回复
  if (taskpool.Task.isCanceled()) {
    console.log("task has been canceled before 2s sleep.");
    return arg + 2;
  }
  // 延时2s
  let t: number = Date.now();
  while (Date.now() - t < 2000) {
    continue;
  }
  // 第二次检查取消并作出响应
  if (taskpool.Task.isCanceled()) {
    console.log("task has been canceled after 2s sleep.");
    return arg + 3;
  }
444
  return arg + 1;
W
wangzhaoyong 已提交
445
}
W
wangzhaoyong 已提交
446

447 448
let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number
taskpool.execute(task).then((res: number)=>{
449
  console.log("taskpool test result: " + res);
450
}).catch((err: string) => {
451
  console.log("taskpool test occur error: " + err);
B
buzhuyu 已提交
452
});
453
// 不调用cancel,isCanceled()默认返回false,task执行的结果为101
W
wangzhaoyong 已提交
454 455
```

456
### setTransferList<sup>10+</sup>
W
wangzhaoyong 已提交
457

458
setTransferList(transfer?: ArrayBuffer[]): void
W
wangzhaoyong 已提交
459

460
设置任务的传输列表。使用该方法前需要先构造Task。
461 462 463

> **说明:**<br/>
> 此接口可以设置任务池中ArrayBuffer的transfer列表,transfer列表中的ArrayBuffer对象在传输时不会复制buffer内容到工作线程而是转移buffer控制权至工作线程,传输后当前的ArrayBuffer失效。
W
wangzhaoyong 已提交
464 465 466 467 468

**系统能力:** SystemCapability.Utils.Lang

**参数:**

469 470 471
| 参数名   | 类型           | 必填 | 说明                                          |
| -------- | ------------- | ---- | --------------------------------------------- |
| transfer | ArrayBuffer[] | 否   | 可传输对象是ArrayBuffer的实例对象,默认为空数组。 |
W
wangzhaoyong 已提交
472 473 474

**示例:**

W
wangzhaoyong 已提交
475
```ts
476 477 478 479
let buffer: ArrayBuffer = new ArrayBuffer(8);
let view: Uint8Array = new Uint8Array(buffer);
let buffer1: ArrayBuffer = new ArrayBuffer(16);
let view1: Uint8Array = new Uint8Array(buffer1);
480 481 482

console.info("testTransfer view byteLength: " + view.byteLength);
console.info("testTransfer view1 byteLength: " + view1.byteLength);
W
wangzhaoyong 已提交
483
@Concurrent
484
function testTransfer(arg1: ArrayBuffer, arg2: ArrayBuffer): number {
485 486 487
  console.info("testTransfer arg1 byteLength: " + arg1.byteLength);
  console.info("testTransfer arg2 byteLength: " + arg2.byteLength);
  return 100;
W
wangzhaoyong 已提交
488
}
489
let task: taskpool.Task = new taskpool.Task(testTransfer, view, view1);
490
task.setTransferList([view.buffer, view1.buffer]);
491
taskpool.execute(task).then((res: number)=>{
492
  console.info("test result: " + res);
493
}).catch((e: string)=>{
494 495 496 497
  console.error("test catch: " + e);
})
console.info("testTransfer view byteLength: " + view.byteLength);
console.info("testTransfer view1 byteLength: " + view1.byteLength);
W
wangzhaoyong 已提交
498 499
```

500
### 属性
B
buzhuyu 已提交
501 502 503

**系统能力:** SystemCapability.Utils.Lang

504 505 506 507
| 名称      | 类型      | 可读 | 可写 | 说明                                                                       |
| --------- | --------- | ---- | ---- | ------------------------------------------------------------------------- |
| function  | Function  | 是   | 是   | 创建任务时需要传入的函数,支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。   |
| arguments | unknown[] | 是   | 是   | 创建任务传入函数所需的参数,支持的参数类型请查[序列化支持类型](#序列化支持类型)。 |
B
buzhuyu 已提交
508

509
## TaskGroup<sup>10+</sup>
510 511

表示任务组。使用[constructor](#constructor10)方法构造TaskGroup。
B
buzhuyu 已提交
512

513
### constructor<sup>10+</sup>
B
buzhuyu 已提交
514

515
constructor()
B
buzhuyu 已提交
516

517
TaskGroup的构造函数。
B
buzhuyu 已提交
518

519
**系统能力:** SystemCapability.Utils.Lang
B
buzhuyu 已提交
520 521 522 523

**示例:**

```ts
524
let taskGroup = new taskpool.TaskGroup();
B
buzhuyu 已提交
525 526
```

527
### addTask<sup>10+</sup>
W
wangzhaoyong 已提交
528

529
addTask(func: Function, ...args: unknown[]): void
W
wangzhaoyong 已提交
530

531
将待执行的函数添加到任务组中。使用该方法前需要先构造TaskGroup。
W
wangzhaoyong 已提交
532

W
wangzhaoyong 已提交
533 534 535 536
**系统能力:** SystemCapability.Utils.Lang

**参数:**

537 538 539 540
| 参数名 | 类型      | 必填 | 说明                                                                   |
| ------ | --------- | ---- | ---------------------------------------------------------------------- |
| func   | Function  | 是   | 任务执行需要传入函数,支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。     |
| args   | unknown[] | 否   | 任务执行函数所需要的参数,支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 |
W
wangzhaoyong 已提交
541 542 543

**错误码:**

W
wangzhaoyong 已提交
544 545
以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)

546 547 548
| 错误码ID | 错误信息                                 |
| -------- | --------------------------------------- |
| 10200014 | The function is not mark as concurrent. |
B
buzhuyu 已提交
549

550
**示例:**
W
wangzhaoyong 已提交
551

W
wangzhaoyong 已提交
552
```ts
B
buzhuyu 已提交
553
@Concurrent
554 555 556
function printArgs(args: number): number {
  console.log("printArgs: " + args);
  return args;
557 558
}

559
let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup();
560
taskGroup.addTask(printArgs, 100); // 100: test number
B
buzhuyu 已提交
561 562
```

563
### addTask<sup>10+</sup>
B
buzhuyu 已提交
564

565
addTask(task: Task): void
B
buzhuyu 已提交
566

567
将创建好的任务添加到任务组中。使用该方法前需要先构造TaskGroup。
B
buzhuyu 已提交
568 569 570 571 572

**系统能力:** SystemCapability.Utils.Lang

**参数:**

573 574 575
| 参数名   | 类型                  | 必填 | 说明                                       |
| -------- | --------------------- | ---- | ---------------------------------------- |
| task     | [Task](#task)         | 是   | 需要添加到任务组中的任务。                  |
B
buzhuyu 已提交
576 577 578 579 580

**错误码:**

以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)

581 582 583
| 错误码ID | 错误信息                                 |
| -------- | --------------------------------------- |
| 10200014 | The function is not mark as concurrent. |
B
buzhuyu 已提交
584 585 586 587 588

**示例:**

```ts
@Concurrent
589 590 591
function printArgs(args: number): number {
  console.log("printArgs: " + args);
  return args;
B
buzhuyu 已提交
592 593
}

594 595
let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup();
let task: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number
596
taskGroup.addTask(task);
B
buzhuyu 已提交
597 598
```

599

B
buzhuyu 已提交
600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660
## State<sup>10+</sup>

表示任务(Task)状态的枚举。

**系统能力:**  SystemCapability.Utils.Lang

| 名称      | 值        | 说明          |
| --------- | -------- | ------------- |
| WAITING   | 1        | 任务正在等待。 |
| RUNNING   | 2        | 任务正在执行。 |
| CANCELED  | 3        | 任务已被取消。 |


## TaskInfo<sup>10+</sup>

任务的内部信息。

**系统能力:** SystemCapability.Utils.Lang

### 属性

**系统能力:** SystemCapability.Utils.Lang

| 名称     | 类型                | 可读 | 可写 | 说明                                                           |
| -------- | ------------------ | ---- | ---- | ------------------------------------------------------------- |
| taskId   | number             | 是   | 否   | 任务的ID。                                                     |
| state    | [State](#state10)  | 是   | 否   | 任务的状态。                                                    |
| duration | number             | 是   | 否   | 任务执行至当前所用的时间,单位为ms。当返回为0时,表示任务未执行;返回为空时,表示没有任务执行  |

## ThreadInfo<sup>10+</sup>

工作线程的内部信息。

**系统能力:** SystemCapability.Utils.Lang

### 属性

**系统能力:** SystemCapability.Utils.Lang

| 名称     | 类型                    | 可读 | 可写 | 说明                                                      |
| -------- | ---------------------- | ---- | ---- | -------------------------------------------------------- |
| tid      | number                 | 是   | 否   | 工作线程的标识符。返回为空时,代表没有任务执行。              |
| taskIds  | number[]               | 是   | 否   | 在当前线程上运行的任务id列表。返回为空时,代表没有任务执行。   |
| priority | [Priority](#priority)  | 是   | 否   | 当前线程的优先级。返回为空时,代表没有任务执行。              |

## TaskPoolInfo<sup>10+</sup>

任务池的内部信息。

**系统能力:** SystemCapability.Utils.Lang

### 属性

**系统能力:** SystemCapability.Utils.Lang

| 名称          | 类型                              | 可读 | 可写 | 说明                  |
| ------------- | -------------------------------- | ---- | ---- | -------------------- |
| threadInfos   | [ThreadInfo[]](#threadinfo10)    | 是   | 否   | 工作线程的内部信息。   |
| taskInfos     | [TaskInfo[]](#taskinfo10)        | 是   | 否   | 任务的内部信息。       |


W
wangzhaoyong 已提交
661 662 663 664 665
## 其他说明

### 序列化支持类型
序列化支持类型包括:All Primitive Type(不包括symbol)、Date、String、RegExp、Array、Map、Set、Object、ArrayBuffer、TypedArray。

W
wangzhaoyong 已提交
666 667 668 669 670 671 672
### 简单使用

**示例一**

```ts
// 支持普通函数、引用入参传递
@Concurrent
673 674 675
function printArgs(args: number): number {
  console.log("func: " + args);
  return args;
W
wangzhaoyong 已提交
676
}
677
async function taskpoolExecute(): Promise<void> {
678
  // taskpool.execute(task)
679 680
  let task: taskpool.Task = new taskpool.Task(printArgs, "create task, then execute");
  console.log("taskpool.execute(task) result: " + await taskpool.execute(task));
681
  // taskpool.execute(function)
682
  console.log("taskpool.execute(function) result: " + await taskpool.execute(printArgs, "execute task by func"));
683
}
B
buzhuyu 已提交
684
taskpoolExecute();
W
wangzhaoyong 已提交
685 686
```

W
wangzhaoyong 已提交
687
**示例二**
W
wangzhaoyong 已提交
688

W
wangzhaoyong 已提交
689 690
```ts
// b.ets
691
export let c: string = "hello";
W
wangzhaoyong 已提交
692 693 694 695 696
```
```ts
// 引用import变量
// a.ets(与b.ets位于同一目录中)
import { c } from "./b";
W
wangzhaoyong 已提交
697

W
wangzhaoyong 已提交
698
@Concurrent
699
function printArgs(a: string): string {
W
wangzhaoyong 已提交
700 701 702 703 704
    console.log(a);
    console.log(c);
    return a;
}

B
buzhuyu 已提交
705
async function taskpoolExecute() {
706
  // taskpool.execute(task)
707 708
  let task: taskpool.Task = new taskpool.Task(printArgs, "create task, then execute");
  console.log("taskpool.execute(task) result: " + await taskpool.execute(task));
709 710

  // taskpool.execute(function)
711
  console.log("taskpool.execute(function) result: " + await taskpool.execute(printArgs, "execute task by func"));
712
}
W
wangzhaoyong 已提交
713

B
buzhuyu 已提交
714
taskpoolExecute();
W
wangzhaoyong 已提交
715 716 717 718 719 720 721
```

**示例三**

```ts
// 支持async函数
@Concurrent
B
buzhuyu 已提交
722
async function delayExcute() {
W
wangzhaoyong 已提交
723 724 725 726 727 728
  let ret = await Promise.all([
    new Promise(resolve => setTimeout(resolve, 1000, "resolved"))
  ]);
  return ret;
}

B
buzhuyu 已提交
729
async function taskpoolExecute() {
730 731 732 733
  taskpool.execute(delayExcute).then((result: string) => {
    console.log("taskPoolTest task result: " + result);
  }).catch((err: string) => {
    console.log("taskpool test occur error: " + err);
W
wangzhaoyong 已提交
734 735 736
  });
}

B
buzhuyu 已提交
737
taskpoolExecute();
W
wangzhaoyong 已提交
738 739 740 741 742
```

**示例四**

```ts
B
buzhuyu 已提交
743 744
// c.ets
@Concurrent
745
function strSort(inPutArr: Array<string>): Array<string> {
B
buzhuyu 已提交
746 747
  let newArr = inPutArr.sort();
  return newArr;
W
wangzhaoyong 已提交
748
}
B
buzhuyu 已提交
749
export async function func1() {
750 751 752 753
  console.log("taskpoolTest start");
  let strArray: Array<string> = ['c test string', 'b test string', 'a test string'];
  let task: taskpool.Task = new taskpool.Task(strSort, strArray);
  console.log("func1 result:" + await taskpool.execute(task));
W
wangzhaoyong 已提交
754 755
}

B
buzhuyu 已提交
756
export async function func2() {
757 758 759 760 761 762 763
  console.log("taskpoolTest2 start");
  let strArray: Array<string> = ['c test string', 'b test string', 'a test string'];
  taskpool.execute(strSort, strArray).then((result: Array<string>) => {
    console.log("func2 result: " + result);
  }).catch((err: string) => {
    console.log("taskpool test occur error: " + err);
  });
W
wangzhaoyong 已提交
764 765 766 767
}
```

```ts
B
buzhuyu 已提交
768
// a.ets(与c.ets在同一目录中)
W
wangzhaoyong 已提交
769 770
import { taskpoolTest1, taskpoolTest2 } from "./c";

B
buzhuyu 已提交
771 772
func1();
func2();
B
buzhuyu 已提交
773 774 775 776 777 778 779
```

**示例五**

```ts
// 任务取消成功
@Concurrent
780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796
function inspectStatus(arg: number): number {
  // 第一时间检查取消并回复
  if (taskpool.Task.isCanceled()) {
    console.log("task has been canceled before 2s sleep.");
    return arg + 2;
  }
  // 2s sleep
  let t: number = Date.now();
  while (Date.now() - t < 2000) {
    continue;
  }
  // 第二次检查取消并作出响应
  if (taskpool.Task.isCanceled()) {
    console.log("task has been canceled after 2s sleep.");
    return arg + 3;
  }
  return arg + 1;
B
buzhuyu 已提交
797 798
}

799 800 801 802 803 804 805 806 807 808
async function taskpoolCancel(): Promise<void> {
  let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number
  taskpool.execute(task).then((res: number)=>{
    console.log("taskpool test result: " + res);
  }).catch((err: string) => {
    console.log("taskpool test occur error: " + err);
  });
  // 1s后取消task
  setTimeout(()=>{
    taskpool.cancel(task);}, 1000);
B
buzhuyu 已提交
809 810 811 812 813 814 815 816 817 818
}

taskpoolCancel();
```

**示例六**

```ts
// 已执行的任务取消失败
@Concurrent
819 820 821 822 823 824 825 826 827 828 829 830 831 832 833
function inspectStatus(arg: number): number {
  // 第一时间检查取消并回复
  if (taskpool.Task.isCanceled()) {
    return arg + 2;
  }
  // 延时2s
  let t: number = Date.now();
  while (Date.now() - t < 500) {
    continue;
  }
  // 第二次检查取消并作出响应
  if (taskpool.Task.isCanceled()) {
    return arg + 3;
  }
  return arg + 1;
B
buzhuyu 已提交
834 835
}

836 837 838 839 840 841 842 843 844 845 846 847 848 849 850
async function taskpoolCancel(): Promise<void> {
  let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number
  taskpool.execute(task).then((res: number)=>{
    console.log("taskpool test result: " + res);
  }).catch((err: string) => {
    console.log("taskpool test occur error: " + err);
  });

  setTimeout(()=>{
    try {
      taskpool.cancel(task); // 任务已执行,取消失败
    } catch (e) {
      console.log("taskpool.cancel occur error:" + e);
    }
  }, 3000); // 延时3s,确保任务已执行
B
buzhuyu 已提交
851 852 853
}

taskpoolCancel();
B
buzhuyu 已提交
854 855 856 857 858 859 860
```

**示例七**

```ts
// 待执行的任务组取消成功
@Concurrent
861 862
function printArgs(args: number): number {
  let t: number = Date.now();
B
buzhuyu 已提交
863 864 865 866 867 868 869
  while (Date.now() - t < 1000) {
    continue;
  }
  console.log("printArgs: " + args);
  return args;
}

870 871
async function taskpoolGroupCancelTest(): Promise<void> {
  let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup();
B
buzhuyu 已提交
872 873 874
  taskGroup1.addTask(printArgs, 10); // 10: test number
  taskGroup1.addTask(printArgs, 20); // 20: test number
  taskGroup1.addTask(printArgs, 30); // 30: test number
875 876 877 878
  let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup();
  let task1: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number
  let task2: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number
  let task3: taskpool.Task = new taskpool.Task(printArgs, 300); // 300: test number
B
buzhuyu 已提交
879 880 881
  taskGroup2.addTask(task1);
  taskGroup2.addTask(task2);
  taskGroup2.addTask(task3);
882
  taskpool.execute(taskGroup1).then((res: Array<number>) => {
B
buzhuyu 已提交
883
    console.info("taskpool execute res is:" + res);
884
  }).catch((e: string) => {
B
buzhuyu 已提交
885 886
    console.error("taskpool execute error is:" + e);
  });
887
  taskpool.execute(taskGroup2).then((res: Array<number>) => {
B
buzhuyu 已提交
888
    console.info("taskpool execute res is:" + res);
889
  }).catch((e: string) => {
B
buzhuyu 已提交
890 891 892 893 894 895 896
    console.error("taskpool execute error is:" + e);
  });

  taskpool.cancel(taskGroup2);
}

taskpoolGroupCancelTest()
B
buzhuyu 已提交
897 898 899 900 901 902 903
```

**示例八**

```ts
// 分别创建执行100个高、中、低优先级的任务,查看其各项信息
@Concurrent
904 905
function delay(): void {
  let start: number = new Date().getTime();
B
buzhuyu 已提交
906 907 908 909 910
  while (new Date().getTime() - start < 500) {
    continue;
  }
}

911 912 913 914
let highCount: number = 0;
let mediumCount: number = 0;
let lowCount: number = 0;
let allCount: number = 100;
B
buzhuyu 已提交
915
for (let i = 0; i < allCount; i++) {
916 917 918
  let task1: taskpool.Task = new taskpool.Task(delay);
  let task2: taskpool.Task = new taskpool.Task(delay);
  let task3: taskpool.Task = new taskpool.Task(delay);
B
buzhuyu 已提交
919 920
  taskpool.execute(task1, taskpool.Priority.LOW).then(() => {
    lowCount++;
921
  }).catch((e: string) => {
B
buzhuyu 已提交
922 923 924 925
    console.error("low task error: " + e);
  })
  taskpool.execute(task2, taskpool.Priority.MEDIUM).then(() => {
    mediumCount++;
926
  }).catch((e: string) => {
B
buzhuyu 已提交
927 928 929 930
    console.error("medium task error: " + e);
  })
  taskpool.execute(task3, taskpool.Priority.HIGH).then(() => {
    highCount++;
931
  }).catch((e: string) => {
B
buzhuyu 已提交
932 933 934
    console.error("high task error: " + e);
  })
}
935
let start: number = new Date().getTime();
B
buzhuyu 已提交
936
while (new Date().getTime() - start < 1000) {
937 938 939 940 941 942 943 944 945
  continue;
}
let taskpoolInfo: taskpool.TaskPoolInfo = taskpool.getTaskPoolInfo();
let tid: number = 0;
let taskIds: Array<number> = [];
let priority: number = 0;
let taskId: number = 0;
let state: number = 0;
let duration: number = 0;
B
buzhuyu 已提交
946 947 948 949 950 951 952 953 954 955 956 957
for(let threadInfo of taskpoolInfo.threadInfos) {
  tid = threadInfo.tid;
  taskIds.length = threadInfo.taskIds.length;
  priority = threadInfo.priority;
  console.info("taskpool---tid is:" + tid + ", taskIds is:" + taskIds + ", priority is:" + priority);
}
for(let taskInfo of taskpoolInfo.taskInfos) {
  taskId = taskInfo.taskId;
  state = taskInfo.state;
  duration = taskInfo.duration;
  console.info("taskpool---taskId is:" + taskId + ", state is:" + state + ", duration is:" + duration);
}
W
wangzhaoyong 已提交
958
```