# @ohos.taskpool (启动任务池)

> phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+

任务池（taskpool）为应用程序提供多线程运行环境，降低资源消耗并提升系统性能，开发者无需关心线程的生命周期。使用任务池API可创建后台任务（Task），执行或取消任务等操作。理论上，任务池API允许创建的任务数量不受限制，但由于内存限制，不建议无限制地创建大量任务。此外，不建议在任务中执行阻塞操作，尤其是无限期阻塞操作，因为阻塞操作会占用工作线程，影响其他任务的调度和应用性能。

创建同一优先级的任务时，可以自行决定其执行顺序。任务的实际执行顺序与任务提交到任务池的顺序一致。任务的默认优先级为MEDIUM。

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

任务池API返回错误码。如需了解各错误码的详细信息，请参阅文档[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

请查阅[TaskPool注意事项](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#taskpool注意事项)，了解使用TaskPool时的相关注意点。

文档中涉及以下任务概念：

* 任务组任务：对应为[TaskGroup](#taskgroup10)任务。
* 串行队列任务：对应为[SequenceRunner](#sequencerunner11)任务。
* 异步队列任务：对应为[AsyncRunner](#asyncrunner18)任务。
* 周期任务：由[executePeriodically](#taskpoolexecuteperiodically12)执行的任务。

> 说明
>
> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

## 导入模块

```ts
import { taskpool } from '@kit.ArkTS';
```

## taskpool.execute

execute(func: Function, ...args: Object[]): Promise<Object>

将待执行的函数放入taskpool的内部任务队列，函数不会立即执行，而是等待分发到工作线程执行。在当前执行模式下，不支持取消任务。使用Promise异步回调。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-------|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
|func|Function|是|待执行的函数，必须使用[@Concurrent装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#concurrent装饰器)装饰。支持的函数返回值类型请参考[序列化支持类型](#序列化支持类型)。|
|args|Object[]|否|任务执行函数的入参，支持的参数类型请参考[序列化支持类型](#序列化支持类型)。默认值为undefined。|

**返回值：**

|类型|说明|
|:--------------|:---------------------|
|Promise<Object>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------|
|10200003|Worker initialization failed. 适用版本：9-11|
|10200006|An exception occurred during serialization.|
|10200014|The function is not marked as concurrent.|

**示例：**

```ts
@Concurrent
function printArgs(args: number): number {
    console.info("printArgs: " + args);
    return args;
}

taskpool.execute(printArgs, 100).then((value: Object) => { // 100: test number
  console.info("taskpool result: " + value);
});
```

## taskpool.execute^13+^

execute<A extends Array<Object>, R>(func: (...args: A) => R | Promise<R>, ...args: A): Promise<R>

校验并发函数的参数类型和返回类型后，将函数添加到taskpool的任务队列。在当前执行模式下，不支持取消任务。使用Promise异步回调。

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

**元服务API：** 从API version 13开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-----------------------------|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
|func|(...args: A) => R | Promise<R>|是|待执行的函数，必须使用[@Concurrent装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#concurrent装饰器)装饰，支持的函数返回值类型请参考[序列化支持类型](#序列化支持类型)。|
|args|A|否|任务执行函数的入参，支持的参数类型请参考[序列化支持类型](#序列化支持类型)。默认值为undefined。|

**返回值：**

|类型|说明|
|:---------|:---------------------|
|Promise<R>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200014|The function is not marked as concurrent.|

**示例：**

```ts
@Concurrent
function printArgs(args: number): number {
  console.info("printArgs: " + args);
  return args;
}

@Concurrent
function testWithThreeParams(a: number, b: string, c: number): string {
  return b;
}

@Concurrent
function testWithArray(args: [number, string]): string {
  return "success";
}

taskpool.execute<[number], number>(printArgs, 100).then((value: number) => { // 100: test number
  console.info("taskpool result: " + value); // "taskpool result: 100"
});

taskpool.execute<[number, string, number], string>(testWithThreeParams, 100, "test", 100).then((value: string) => {
  console.info("taskpool result: " + value); // "taskpool result: test"
});

taskpool.execute<[[number, string]], string>(testWithArray, [100, "test"]).then((value: string) => {
  console.info("taskpool result: " + value); // "taskpool result: success"
});
```

## taskpool.execute

execute(task: Task, priority?: Priority): Promise<Object>

将创建好的任务添加到taskpool的内部任务队列中，任务不会立即执行，而是等待分发到工作线程执行。当前模式支持设置任务优先级和通过cancel取消任务。使用Promise异步回调。
> 说明
>
> * 任务不能是任务组任务、串行队列任务或异步队列任务。
> * 长时任务只能调用一次，非长时任务可以多次调用执行。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

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

**返回值：**

|类型|说明|
|:--------------|:---------------------|
|Promise<Object>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:---------------------------------------------------|
|10200003|Worker initialization failed. 适用版本：9-17|
|10200006|An exception occurred during serialization.|
|10200014|The function is not marked as concurrent.|
|10200051|The periodic task cannot be executed again. 适用版本：12+|
|10200057|The task cannot be executed by two APIs. 适用版本：18+|

**示例：**

```ts
@Concurrent
function printArgs(args: number): number {
    console.info("printArgs: " + args);
    return args;
}

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
taskpool.execute(task1, taskpool.Priority.LOW).then((value: Object) => {
  console.info("taskpool result1: " + value);
});
taskpool.execute(task2, taskpool.Priority.MEDIUM).then((value: Object) => {
  console.info("taskpool result2: " + value);
});
taskpool.execute(task3, taskpool.Priority.HIGH).then((value: Object) => {
  console.info("taskpool result3: " + value);
});
```

## taskpool.execute^24+^

execute(task: Task, configs: Configs): Promise<Object>

将创建好的任务添加到taskpool的内部任务队列中，任务不会立即执行，而是等待分发到工作线程执行。当前模式支持设置任务优先级、设置超时时间和通过cancel取消任务。使用Promise异步回调。
> 说明
>
> * 不支持执行任务组任务。
> * 不支持执行串行队列任务。
> * 不支持执行异步队列任务。
> * 不支持执行周期性任务。
> * 不支持执行延时任务。
> * 不支持执行存在依赖的任务。
> * 不支持任务重复执行。
> * 设置过超时的任务无法被其他任务依赖，也无法依赖其他任务。
> * 如果任务设置了失败监听，任务执行超时了，失败监听不会被触发。
> * 如果任务使用sendData向宿主线程发消息，任务超时之后，宿主线程不再接收到消息。
> * 在抛出超时异常信息之后，执行中的任务还是会在线程中继续执行，但是最终不会返回执行结果。

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

**元服务API：** 从API version 24开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:------|:--------------------|:-|:-----------------|
|task|[Task](#task)|是|需要在任务池中执行的任务。|
|configs|[Configs](#configs24)|是|该参数可以设置超时时间和任务优先级。|

**返回值：**

|类型|说明|
|:--------------|:---------------------|
|Promise<Object>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200014|The function is not marked as concurrent.|
|10200051|The periodic task cannot be executed again.|
|10200057|The task cannot be executed by two APIs.|
|10200058|Task timed out.|

**示例：**

```ts
@Concurrent
function printArgs(args: number, time: number): number {
  let start = Date.now();
  while (Date.now() - start < time) {
    continue;
  }
  return args;
}

let task: taskpool.Task = new taskpool.Task(printArgs, 100, 1000);
let config: taskpool.Configs = { timeout: 500, priority: taskpool.Priority.HIGH };
taskpool.execute(task, config).catch((e: BusinessError) => {
  // Failed to execute task. Code: 10200058, message: Task timed out.
  console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
})
try {
  taskpool.execute(task, { timeout: 500 });
} catch (e) {
  // Failed to execute task. Code: 10200057, message: The task cannot be executed by two APIs, the timeout task cannot be executed again.
  console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
}
```

## taskpool.execute^13+^

execute<A extends Array<Object>, R>(task: GenericsTask<A, R>, priority?: Priority): Promise<R>

将创建好的泛型任务放入taskpool的内部任务队列，校验任务的参数类型和返回值类型。使用Promise异步回调。

execute任务的类型校验与GenericsTask的构造类型相关联，参数类型和返回值类型需与new GenericsTask时指定的类型保持一致。

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

**元服务API：** 从API version 13开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:------------------------------------|:-|:----------------------------------------|
|task|[GenericsTask](#genericstask13)<A, R>|是|需要在任务池中执行的泛型任务。|
|priority|[Priority](#priority)|否|等待执行的任务的优先级，默认值为taskpool.Priority.MEDIUM。|

**返回值：**

|类型|说明|
|:---------|:---------------------|
|Promise<R>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200014|The function is not marked as concurrent.|
|10200051|The periodic task cannot be executed again.|
|10200057|The task cannot be executed by two APIs. 适用版本：18+|

**示例：**

```ts
@Concurrent
function printArgs(args: number): number {
    console.info("printArgs: " + args);
    return args;
}

let task1: taskpool.Task = new taskpool.GenericsTask<[number], number>(printArgs, 100); // 100: test number
let task2: taskpool.Task = new taskpool.GenericsTask<[number], number>(printArgs, 200); // 200: test number
let task3: taskpool.Task = new taskpool.GenericsTask<[number], number>(printArgs, 300); // 300: test number
taskpool.execute<[number], number>(task1, taskpool.Priority.LOW).then((value: number) => {
  console.info("taskpool result1: " + value);
});
taskpool.execute<[number], number>(task2, taskpool.Priority.MEDIUM).then((value: number) => {
  console.info("taskpool result2: " + value);
});
taskpool.execute<[number], number>(task3, taskpool.Priority.HIGH).then((value: number) => {
  console.info("taskpool result3: " + value);
});
```

## taskpool.execute^24+^

execute<A extends Array<Object>, R>(task: GenericsTask<A, R>, configs: Configs): Promise<R>

将创建好的泛型任务放入taskpool的内部任务队列，使用Promise异步回调。

execute任务的类型校验与GenericsTask的构造类型相关联，参数类型和返回值类型需与new GenericsTask时指定的类型保持一致。
> 说明
>
> * 不支持执行任务组任务。
> * 不支持执行串行队列任务。
> * 不支持执行异步队列任务。
> * 不支持执行周期性任务。
> * 不支持执行延时任务。
> * 不支持执行存在依赖的任务。
> * 不支持任务重复执行。
> * 设置过超时的任务无法被其他任务依赖，也无法依赖其他任务。
> * 如果任务设置了失败监听，任务执行超时了，失败监听不会被触发。
> * 如果任务使用sendData来往宿主线程发消息，任务超时之后，宿主线程不再接收到消息。
> * 在抛出超时异常信息之后，执行中的任务还是会在线程中继续执行，但是最终不会返回执行结果。

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

**元服务API：** 从API version 24开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:------|:------------------------------------|:-|:-----------------|
|task|[GenericsTask](#genericstask13)<A, R>|是|需要在任务池中执行的泛型任务。|
|configs|[Configs](#configs24)|是|该参数可以设置超时时间和任务优先级。|

**返回值：**

|类型|说明|
|:---------|:---------------------|
|Promise<R>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200014|The function is not marked as concurrent.|
|10200051|The periodic task cannot be executed again.|
|10200057|The task cannot be executed by two APIs.|
|10200058|Task timed out.|

**示例：**

```ts
@Concurrent
function printArgs(args: number, time: number): number {
  let start = Date.now();
  while (Date.now() - start < time) {
    continue;
  }
  return args;
}

let task: taskpool.Task = new taskpool.GenericsTask<[number, number], number>(printArgs, 100, 1000);
let config: taskpool.Configs = { timeout: 500, priority: taskpool.Priority.MEDIUM };
taskpool.execute<[number, number], number>(task, config).catch((e: BusinessError) => {
  // Failed to execute task. Code: 10200058, message: Task timed out.
  console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
})
try {
  taskpool.execute<[number, number], number>(task, { timeout: 500 });
} catch (e) {
  // Failed to execute task. Code: 10200057, message: The task cannot be executed by two APIs, the timeout task cannot be executed again.
  console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
}
```

## taskpool.execute^10+^

execute(group: TaskGroup, priority?: Priority): Promise<Object[]>

将创建好的任务组放入taskpool内部任务队列，任务组中的任务不会立即执行，而是等待分发到工作线程执行。任务组中任务全部执行完成后，结果数组统一返回。此模式适用于执行关联任务。使用Promise异步回调。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

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

**返回值：**

|类型|说明|
|:----------------|:-----------------------|
|Promise<Object[]>|Promise对象数组，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200059|TaskGroup cannot be re-executed. 适用版本：24+|

**示例：**

```ts
@Concurrent
function printArgs(args: number): number {
    console.info("printArgs: " + args);
    return args;
}

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

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
taskGroup2.addTask(task1);
taskGroup2.addTask(task2);
taskGroup2.addTask(task3);
taskpool.execute(taskGroup1).then((res: Array<Object>) => {
  console.info("Succeeded in executing task, res is:" + res);
});
taskpool.execute(taskGroup2).then((res: Array<Object>) => {
  console.info("Succeeded in executing task, res is:" + res);
});
```

## taskpool.execute^24+^

execute(group: TaskGroup, configs: Configs): Promise<Object[]>

将创建好的任务组放入taskpool内部任务队列，任务组中的任务不会立即执行，而是等待分发到工作线程执行。任务组中任务全部执行完成后，结果数组统一返回。此模式适用于执行关联任务。使用Promise异步回调。

configs配置里可以指定任务组执行的超时时间和优先级。指定的超时时间到了，但是任务组还未完成，则会抛出任务组超时的异常信息。
> 说明
>
> * 不支持任务组重复执行。
> * 在抛出超时异常信息之后，执行中的任务还是会在线程中继续执行，但是最终不会返回执行结果。

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

**元服务API：** 从API version 24开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:------|:------------------------|:-|:-----------------|
|group|[TaskGroup](#taskgroup10)|是|需要在任务池中执行的任务组。|
|configs|[Configs](#configs24)|是|该参数可以设置超时时间和任务优先级。|

**返回值：**

|类型|说明|
|:----------------|:-----------------------|
|Promise<Object[]>|Promise对象数组，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200059|TaskGroup cannot be re-executed.|
|10200070|TaskGroup timed out.|

**示例：**

```ts
@Concurrent
function printArgs(args: number, time: number): number {
  let start = Date.now();
  while (Date.now() - start < time) {
    continue;
  }
  return args;
}

let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup();
taskGroup.addTask(printArgs, 10, 1000);
let config: taskpool.Configs = {timeout: 500, priority: taskpool.Priority.HIGH};
taskpool.execute(taskGroup, config).catch((e:BusinessError) => {
  // Failed to execute task. Code: 10200070, message: TaskGroup timed out.
  console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
})
try {
  taskpool.execute(taskGroup, config);
} catch (e) {
  // Failed to execute task. Code: 10200059, message: TaskGroup cannot be re-executed, taskGroup has already set timeout.
  console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
}
```

## taskpool.executeDelayed^11+^

executeDelayed(delayTime: number, task: Task, priority?: Priority): Promise<Object>

延时执行任务。当前执行模式可以设置任务优先级，可通过cancel取消任务。使用Promise异步回调。
> 说明
>
> * 该任务不能是任务组任务、串行队列任务、异步队列任务或周期任务。
> * 如果任务不是长时任务，可以多次调用executeDelayed执行。
> * 如果是长时任务，则仅支持执行一次。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:--------|:--------------------|:-|:-------------------------------------------|
|delayTime|number|是|延时时间。单位：ms。delayTime值必须要大于等于0。|
|task|[Task](#task)|是|需要延时执行的任务。|
|priority|[Priority](#priority)|否|延时执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。|

**返回值：**

|类型|说明|
|:--------------|:---------------------|
|Promise<Object>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:---------------------------------------------------|
|10200006|An exception occurred during serialization. 适用版本：12+|
|10200014|The function is not marked as concurrent. 适用版本：12+|
|10200028|The delayTime is less than zero.|
|10200051|The periodic task cannot be executed again. 适用版本：12+|
|10200057|The task cannot be executed by two APIs. 适用版本：18+|

**示例：**

```ts
// import BusinessError
import { BusinessError } from '@kit.BasicServicesKit';

@Concurrent
function printArgs(args: number): void {
    console.info("printArgs: " + args);
}

let t: number = Date.now();
console.info("taskpool start time is: " + t);
let task: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number
taskpool.executeDelayed(1000, task).then(() => { // 1000: delayTime is 1000ms
  console.info('Succeeded in executing task');
}).catch((e: BusinessError) => {
  console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
})
```

## taskpool.executeDelayed^13+^

executeDelayed<A extends Array<Object>, R>(delayTime: number, task: GenericsTask<A, R>, priority?: Priority): Promise<R>

延时执行泛型任务，使用Promise异步回调。

executeDelayed任务的类型校验与GenericsTask的构造类型相关联，参数类型和返回值类型需与new GenericsTask时指定的类型保持一致。

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

**元服务API：** 从API version 13开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:--------|:------------------------------------|:-|:----------------------------------------|
|delayTime|number|是|延时时间。单位：ms。delayTime值必须要大于等于0。|
|task|[GenericsTask](#genericstask13)<A, R>|是|需要延时执行的泛型任务。|
|priority|[Priority](#priority)|否|延时执行的任务的优先级，默认值为taskpool.Priority.MEDIUM。|

**返回值：**

|类型|说明|
|:---------|:---------------------|
|Promise<R>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------------|
|10200028|The delayTime is less than zero.|
|10200051|The periodic task cannot be executed again.|
|10200057|The task cannot be executed by two APIs. 适用版本：18+|

**示例：**

```ts
// import BusinessError
import { BusinessError } from '@kit.BasicServicesKit'

@Concurrent
function printArgs(args: number): string {
    console.info("printArgs: " + args);
    return "success";
}

let task: taskpool.Task = new taskpool.GenericsTask<[number], string>(printArgs, 100); // 100: test number
taskpool.executeDelayed<[number], string>(1000, task).then((res: string) => { // 1000: delayTime is 1000ms
  console.info('Succeeded in executing task');
}).catch((e: BusinessError) => {
  console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
})
```

## taskpool.executePeriodically^12+^

executePeriodically(period: number, task: Task, priority?: Priority): void

周期任务每隔period时长执行一次。当前执行模式支持设置任务优先级，可通过cancel取消任务。
> 说明
>
> * 周期任务不能是任务组任务、串行队列任务或异步队列任务。
> * 同一个周期任务不能多次调用该接口。
> * 执行的任务不能拥有依赖关系。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------|:-|:-------------------------------------------|
|period|number|是|周期时长。单位：ms。period值必须要大于等于0。|
|task|[Task](#task)|是|需要周期执行的任务。|
|priority|[Priority](#priority)|否|周期执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200014|The function is not marked as concurrent.|
|10200028|The period is less than zero.|
|10200050|The concurrent task has been executed and cannot be executed periodically.|
|10200057|The task cannot be executed by two APIs. 适用版本：18+|

**示例：**

```ts
@Concurrent
function printArgs(args: number): void {
  console.info("printArgs: " + args);
}

@Concurrent
function testExecutePeriodically(args: number): void {
  let t = Date.now();
  while ((Date.now() - t) < args) {
    continue;
  }
  taskpool.Task.sendData(args); // 向宿主线程发送消息
}

function printResult(data: number): void {
  console.info("taskpool: data is: " + data);
}

function taskpoolTest() {
  try {
    let task: taskpool.Task = new taskpool.Task(printArgs, 100); // 100: test number
    taskpool.executePeriodically(1000, task); // 1000: period is 1000ms
  } catch (e) {
    console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
  }

  try {
    let periodicTask: taskpool.Task = new taskpool.Task(testExecutePeriodically, 200); // 200: test number
    periodicTask.onReceiveData(printResult);
    taskpool.executePeriodically(1000, periodicTask); // 1000: period is 1000ms
  } catch (e) {
    console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
  }
}

taskpoolTest();
```

## taskpool.executePeriodically^13+^

executePeriodically<A extends Array<Object>, R>(period: number, task: GenericsTask<A, R>, priority?: Priority): void

周期执行泛型任务，每隔period时长执行一次。

executePeriodically任务的类型校验与GenericsTask的构造类型相关联，参数类型和返回值类型需与new GenericsTask时指定的类型保持一致。

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

**元服务API：** 从API version 13开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:------------------------------------|:-|:-------------------------------------------|
|period|number|是|周期时长。单位：ms。period值必须要大于等于0。|
|task|[GenericsTask](#genericstask13)<A, R>|是|需要周期执行的泛型任务。|
|priority|[Priority](#priority)|否|周期执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200014|The function is not marked as concurrent.|
|10200028|The period is less than zero.|
|10200050|The concurrent task has been executed and cannot be executed periodically.|
|10200057|The task cannot be executed by two APIs. 适用版本：18+|

**示例：**

```ts
@Concurrent
function printArgs(args: number): void {
  console.info("printArgs: " + args);
}

@Concurrent
function testExecutePeriodically(args: number): void {
  let t = Date.now();
  while ((Date.now() - t) < args) {
    continue;
  }
  taskpool.Task.sendData(args); // 向宿主线程发送消息
}

function printResult(data: number): void {
  console.info("taskpool: data is: " + data);
}

function taskpoolTest() {
  try {
    let task: taskpool.Task = new taskpool.GenericsTask<[number], void>(printArgs, 100); // 100: test number
    taskpool.executePeriodically<[number], void>(1000, task); // 1000: period is 1000ms
  } catch (e) {
    console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
  }

  try {
    let periodicTask: taskpool.Task = new taskpool.GenericsTask<[number], void>(testExecutePeriodically, 200); // 200: test number
    periodicTask.onReceiveData(printResult);
    taskpool.executePeriodically<[number], void>(1000, periodicTask); // 1000: period is 1000ms
  } catch (e) {
    console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
  }
}

taskpoolTest();
```

## taskpool.cancel

cancel(task: Task): void

取消任务池中的任务。

* 当任务在taskpool等待队列中，取消该任务后该任务将不再执行，并返回任务被取消的异常。
* 当任务已经在taskpool工作线程执行，取消该任务并不影响任务继续执行。执行结果在catch分支返回，开发者可搭配isCanceled方法对任务取消行为作出响应。
* taskpool.cancel对其之前的taskpool.execute、taskpool.executeDelayed或taskpool.executePeriodically生效。

从API version 20开始，支持在执行cancel操作后，在catch分支里使用BusinessError<[taskpool.TaskResult](#taskresult20)>的泛型标记，来获取任务中抛出的异常信息或最终的执行结果。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

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

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:-----------------------------------------------|
|10200015|The task to cancel does not exist.|
|10200016|The task to cancel is being executed. 适用版本：9-17|
|10200055|The asyncRunner task has been canceled. 适用版本：18+|

**正在执行的任务取消示例：**

```ts
import { BusinessError } from '@kit.BasicServicesKit';

@Concurrent
function inspectStatus(arg: number): number {
  // 第一次检查任务是否已经取消并作出响应
  if (taskpool.Task.isCanceled()) {
    console.info("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.info("task has been canceled after 2s sleep.");
    return arg + 3;
  }
  return arg + 1;
}

function concurrentFunc() {
  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: Object) => {
    console.info(`Succeeded in executing task. result: ` + res);
  }).catch((err: BusinessError) => {
    console.error(`Failed to execute task. Code: ${err.code}, message: ${err.message}`);
  });
  taskpool.execute(task2);
  taskpool.execute(task3);
  taskpool.execute(task4);
  taskpool.execute(task5);
  taskpool.execute(task6);
  // 1s后取消task
  setTimeout(() => {
    try {
      taskpool.cancel(task1);
    } catch (e) {
      console.error(`Failed to cancel task. Code: ${e.code}, message: ${e.message}`);
    }
  }, 1000);
}

concurrentFunc();
```

## taskpool.cancel^10+^

cancel(group: TaskGroup): void

取消任务池中的任务组。如果任务组中的任务未全部执行结束，则整个任务组的执行结果返回undefined。

从API version 20开始，支持在执行cancel操作后，在catch分支里使用BusinessError<[taskpool.TaskResult](#taskresult20)>的泛型标记，来获取任务中抛出的异常信息或最终的执行结果。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:----|:------------------------|:-|:----------|
|group|[TaskGroup](#taskgroup10)|是|需要取消执行的任务组。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:---------------------------------------|
|10200018|The task group to cancel does not exist.|

**示例：**

```ts
import { BusinessError } from '@kit.BasicServicesKit';

@Concurrent
function printArgs(args: number): number {
  let t: number = Date.now();
  while (Date.now() - t < 2000) {
    continue;
  }
  console.info("printArgs: " + args);
  return args;
}

function concurrentFunc() {
  let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup();
  taskGroup1.addTask(printArgs, 10); // 10: test number
  let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup();
  taskGroup2.addTask(printArgs, 100); // 100: test number
  taskpool.execute(taskGroup1).then((res: Array<Object>) => {
    console.info(`Succeeded in executing task. res is: ` + res);
  });
  taskpool.execute(taskGroup2).then((res: Array<Object>) => {
    console.info(`Succeeded in executing task. res is: ` + res);
  }).catch((err: BusinessError) => {
    console.error(`Failed to execute task. Code: ${err.code}, message: ${err.message}`);
  });
  setTimeout(() => {
    try {
      taskpool.cancel(taskGroup2);
    } catch (e) {
      console.error(`Failed to cancel task. Code: ${e.code}, message: ${e.message}`);
    }
  }, 1000);
}

concurrentFunc();
```

## taskpool.cancel^18+^

cancel(taskId: number): void

通过任务ID取消任务池中的任务。

* 如果任务在taskpool等待队列中，取消后任务将不再执行，并返回任务取消的异常。
* 当任务已经在taskpool工作线程执行，取消该任务并不影响任务继续执行。执行结果在catch分支返回，开发者可搭配isCanceled方法对任务取消行为作出响应。
* taskpool.cancel对其之前的taskpool.execute、taskpool.executeDelayed或taskpool.executePeriodically生效。
* 在其他线程调用taskpool.cancel时，需注意其行为是异步的，可能导致在cancel调用之后的taskpool.execute或taskpool.executeDelayed的任务被取消。

从API version 20开始，支持在执行cancel操作后，在catch分支里使用BusinessError<[taskpool.TaskResult](#taskresult20)>的泛型标记。这可以用来获取任务中抛出的异常信息或最终的执行结果。

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

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-----|:-----|:-|:------------|
|taskId|number|是|需要取消执行的任务的ID。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:--------------------------------------|
|10200015|The task to cancel does not exist.|
|10200055|The asyncRunner task has been canceled.|

**示例：**

```ts
import { BusinessError } from '@kit.BasicServicesKit';

@Concurrent
function printArgs(args: number): number {
  let t: number = Date.now();
  while (Date.now() - t < 2000) {
    continue;
  }
  if (taskpool.Task.isCanceled()) {
    console.info("task has been canceled after 2s sleep.");
    return args + 1;
  }
  console.info("printArgs: " + args);
  return args;
}

@Concurrent
function cancelFunction(taskId: number) {
  try {
    taskpool.cancel(taskId);
  } catch (e) {
    console.error(`Failed to cancel task. Code: ${e.code}, message: ${e.message}`);
  }
}

function concurrentFunc() {
  let task = new taskpool.Task(printArgs, 100); // 100: test number
  taskpool.execute(task).catch((err: BusinessError) => {
    console.error(`Failed to execute task. Code: ${err.code}, message: ${err.message}`);
  });
  setTimeout(() => {
    let cancelTask = new taskpool.Task(cancelFunction, task.taskId);
    taskpool.execute(cancelTask);
  }, 1000);
}

concurrentFunc();
```

## taskpool.terminateTask^12+^

terminateTask(longTask: LongTask): void

终止任务池中的长时任务，在长时任务执行完成后调用。终止后，执行长时任务的线程可能会被回收。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:----------------------|:-|:---------|
|longTask|[LongTask](#longtask12)|是|需要终止的长时任务。|

**示例：**

```ts
@Concurrent
function longTask(arg: number): number {
  let t: number = Date.now();
  while (Date.now() - t < arg) {
    continue;
  }
  console.info("longTask has been executed.");
  return arg;
}

function concurrentFunc() {
  let task1: taskpool.LongTask = new taskpool.LongTask(longTask, 1000); // 1000: sleep time
  taskpool.execute(task1).then((res: Object) => {
    taskpool.terminateTask(task1);
    console.info("taskpool longTask result: " + res);
  });
}

concurrentFunc();
```

## taskpool.isConcurrent^12+^

isConcurrent(func: Function): boolean

检查函数是否为并发函数。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-------|:-|:-------|
|func|Function|是|需要检查的函数。|

**返回值：**

|类型|说明|
|:------|:-----------------------------------------------------------------------------------------------------------------------------------------------|
|boolean|如果被检查函数标注了[@Concurrent装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#concurrent装饰器)，则返回true，否则返回false。|

**示例：**

```ts
@Concurrent
function emptyFunc(): void {}

let result: boolean = taskpool.isConcurrent(emptyFunc);
console.info("result is: " + result);
```

## taskpool.getTaskPoolInfo^10+^

getTaskPoolInfo(): TaskPoolInfo

获取任务池的线程信息和任务信息。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**返回值：**

|类型|说明|
|:------------------------------|:--------|
|[TaskPoolInfo](#taskpoolinfo10)|任务池的内部信息。|

**示例：**

```ts
let taskpoolInfo: taskpool.TaskPoolInfo = taskpool.getTaskPoolInfo();
```

## taskpool.getTask^22+^

getTask(taskId: number, taskName?: string): Task | undefined

通过taskId或taskId与taskName获取对应的Task实例。
> 说明
>
> * 如果传入的taskId查询不到对应的Task实例，则会返回undefined；
> * 如果传入的taskId能够查询到对应的Task实例，但是调用getTask方法的线程和创建Task实例的线程不一致，则会返回undefined；
> * 如果传入了taskId和taskName，通过taskId查询到的Task实例的name和传入的taskName不一致，则会返回undefined。

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

**元服务API：** 从API version 22开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:-----|:-|:------------------|
|taskId|number|是|任务ID。|
|taskName|string|否|任务名称。默认值为undefined。|

**返回值：**

|类型|说明|
|:------------------------|:------------------------------------|
|[Task](#task) | undefined|返回Task实例；当情况异常时，返回undefined，具体可见上文说明。|

**示例：**

```ts
import { taskpool } from '@kit.ArkTS';

@Concurrent
function addNum(num1: number, num2: number) {
  return num1 + num2;
}

function checkTask() {
  try {
    taskpool.getTask(null);
  } catch (e) {
    console.error("error:" + e);
    // error:BusinessError: Parameter error. The input parameters are invalid, the type of the first param must be number.
  }

  let task1:taskpool.Task = new taskpool.Task("addNum", addNum, 1, 2);
  let task2:taskpool.Task | undefined = taskpool.getTask(task1.taskId, "addNum"); // task2 is not undefined
  let task3:taskpool.Task | undefined = taskpool.getTask(task1.taskId, "add"); // task3 is undefined
  let task4:taskpool.Task | undefined = taskpool.getTask(0); // task4 is undefined
}

function dealTask() {
  let task1:taskpool.Task = new taskpool.Task(addNum, 1, 2);
  let task2:taskpool.Task | undefined = taskpool.getTask(task1.taskId);
  if (task2 === undefined) {
    return;
  }

  taskpool.execute(task2).then((result) => {
    console.info("task2 result: " + result); // task2 result: 3
  })
}
```

## Priority

表示所创建任务（Task）执行时的优先级。工作线程优先级跟随任务优先级更新，对应关系参考[QoS等级定义](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/qos-guidelines#qos等级定义)。

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

|名称|值|说明|
|:--------|:-|:---------------------------------------------------|
|HIGH|0|任务为高优先级。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|MEDIUM|1|任务为中优先级。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|LOW|2|任务为低优先级。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|IDLE^12+^|3|任务为后台任务。 **元服务API：** 从API version 12开始，该接口支持在元服务中使用。|

**示例：**

```ts
@Concurrent
function printArgs(args: number): number {
  let t: number = Date.now();
  while (Date.now() - t < 1000) { // 1000: delay 1s
    continue;
  }
  console.info("printArgs: " + args);
  return args;
}

let allCount = 100; // 100: test number
let taskArray: Array<taskpool.Task> = [];
// 创建400个任务并添加至taskArray
for (let i: number = 0; i < allCount; i++) {
  let task1: taskpool.Task = new taskpool.Task(printArgs, i);
  taskArray.push(task1);
  let task2: taskpool.Task = new taskpool.Task(printArgs, i * 10); // 10: test number
  taskArray.push(task2);
  let task3: taskpool.Task = new taskpool.Task(printArgs, i * 100); // 100: test number
  taskArray.push(task3);
  let task4: taskpool.Task = new taskpool.Task(printArgs, i * 1000); // 1000: test number
  taskArray.push(task4);
}

// 从taskArray中获取不同的任务并给定不同优先级执行
for (let i: number = 0; i < taskArray.length; i+=4) { // 4: 每次执行4个任务，循环取任务时需后移4项，确保执行的是不同的任务
  taskpool.execute(taskArray[i], taskpool.Priority.HIGH);
  taskpool.execute(taskArray[i + 1], taskpool.Priority.LOW);
  taskpool.execute(taskArray[i + 2], taskpool.Priority.MEDIUM);
  taskpool.execute(taskArray[i + 3], taskpool.Priority.IDLE);
}
```

## Task

调用Task中的任何接口前必须先使用构造函数创建Task对象。任务可以多次执行，也可以放入任务组、串行队列或异步队列执行，还支持添加依赖关系。

### 属性

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

|名称|类型|只读|可选|说明|
|:-----------------|:-------|:-|:-|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|function|Function|否|否|待执行的函数，必须使用[@Concurrent装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#concurrent装饰器)装饰，支持的函数返回值类型请参考[序列化支持类型](#序列化支持类型)。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|arguments|Object[]|否|是|创建任务传入函数所需的参数，支持的参数类型请参考[序列化支持类型](#序列化支持类型)。默认值为undefined。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|name^11+^|string|否|否|创建任务时指定的任务名称。不建议修改此值。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|taskId^18+^|number|否|否|任务的ID。系统默认提供全局唯一值，不建议修改此值。 **元服务API：** 从API version 18开始，该接口支持在元服务中使用。|
|totalDuration^11+^|number|否|否|执行任务总耗时。单位：ms。不建议修改此值。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|ioDuration^11+^|number|否|否|执行任务异步IO耗时。单位：ms。不建议修改此值。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|cpuDuration^11+^|number|否|否|执行任务CPU耗时。单位：ms。不建议修改此值。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|

### constructor

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

Task的构造函数。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-------|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
|func|Function|是|待执行的函数，必须使用[@Concurrent装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#concurrent装饰器)装饰，支持的函数返回值类型请参考[序列化支持类型](#序列化支持类型)。|
|args|Object[]|否|任务执行函数的入参，支持的参数类型请参考[序列化支持类型](#序列化支持类型)。默认值为undefined。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

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

**示例：**

```ts
@Concurrent
function printArgs(args: string): string {
  console.info("printArgs: " + args);
  return args;
}

let task: taskpool.Task = new taskpool.Task(printArgs, "this is my first Task");
```

### constructor^11+^

constructor(name: string, func: Function, ...args: Object[])

Task的构造函数用于创建任务，并可指定任务名称。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-------|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
|name|string|是|任务名称。|
|func|Function|是|待执行的函数，必须使用[@Concurrent装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#concurrent装饰器)装饰，支持的函数返回值类型请参考[序列化支持类型](#序列化支持类型)。|
|args|Object[]|否|任务执行函数的入参。支持的类型请参考[序列化支持类型](#序列化支持类型)。默认值为undefined。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

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

**示例：**

```ts
@Concurrent
function printArgs(args: string): string {
  console.info("printArgs: " + args);
  return args;
}

let taskName: string = "taskName";
let task: taskpool.Task = new taskpool.Task(taskName, printArgs, "this is my first Task");
let name: string = task.name;
```

### isCanceled^10+^

static isCanceled(): boolean

检查当前正在运行的任务是否已取消。使用此方法前，需要先创建一个Task对象。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**返回值：**

|类型|说明|
|:------|:------------------------------|
|boolean|如果当前正在运行的任务被取消返回true，否则返回false。|

**示例：**

```ts
@Concurrent
function inspectStatus(arg: number): number {
    // ...
    if (taskpool.Task.isCanceled()) {
      console.info("task has been canceled.");
      // ...
      return arg + 1;
    }
    // ...
    return arg;
}
```

> 说明
>
> isCanceled方法需要和taskpool.cancel方法搭配使用，如果不调用cancel方法，isCanceled方法默认返回false。

**示例：**

```ts
import { BusinessError } from '@kit.BasicServicesKit';

@Concurrent
function inspectStatus(arg: number): number {
  // 第一次检查任务是否已经取消并作出响应
  if (taskpool.Task.isCanceled()) {
    console.info("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.info("task has been canceled after 2s sleep.");
    return arg + 3;
  }
  return arg + 1;
}

let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number
taskpool.execute(task).then((res: Object) => {
  console.info("Succeeded in executing task, result: " + res);
}).catch((e: BusinessError) => {
  console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
});
// 不调用cancel，isCanceled()默认返回false，task执行的结果为101
```

### setTransferList^10+^

setTransferList(transfer?: ArrayBuffer[]): void

设置任务的传输列表。使用该方法前需要先构造Task对象。不调用该接口，则传给任务的数据中的ArrayBuffer默认transfer转移。
> 说明
>
> * 此接口与[setCloneList](#setclonelist11)互斥：同一个ArrayBuffer不能同时设置在transfer列表和clone列表中。
> * 此接口可以设置任务池中ArrayBuffer的transfer列表，transfer列表中的ArrayBuffer对象在传输时不会复制buffer内容到工作线程而是转移buffer控制权至工作线程，传输后当前的ArrayBuffer失效。若ArrayBuffer为空，则不会transfer转移。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:------------|:-|:-----------------------------|
|transfer|ArrayBuffer[]|否|可传输对象是ArrayBuffer的实例对象，默认为空数组。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------------------------------------------|
|10200029|An ArrayBuffer cannot be set as both a transfer list and a clone list. 适用版本：11+|

**示例：**

```ts
@Concurrent
function testTransfer(arg1: ArrayBuffer, arg2: ArrayBuffer): number {
  console.info("testTransfer arg1 byteLength: " + arg1.byteLength);
  console.info("testTransfer arg2 byteLength: " + arg2.byteLength);
  return 100;
}

let buffer: ArrayBuffer = new ArrayBuffer(8);
let view: Uint8Array = new Uint8Array(buffer);
let buffer1: ArrayBuffer = new ArrayBuffer(16);
let view1: Uint8Array = new Uint8Array(buffer1);

console.info("testTransfer view byteLength: " + view.byteLength);
console.info("testTransfer view1 byteLength: " + view1.byteLength);
// 执行结果为：
// testTransfer view byteLength: 8
// testTransfer view1 byteLength: 16

let task: taskpool.Task = new taskpool.Task(testTransfer, view, view1);
task.setTransferList([view.buffer, view1.buffer]);
taskpool.execute(task).then((res: Object) => {
  console.info("test result: " + res);
}).catch((e: string) => {
  console.error("test catch: " + e);
})
console.info("testTransfer view2 byteLength: " + view.byteLength);
console.info("testTransfer view3 byteLength: " + view1.byteLength);
// 经过transfer转移之后值为0，执行结果为：
// testTransfer view2 byteLength: 0
// testTransfer view3 byteLength: 0
```

### setCloneList^11+^

setCloneList(cloneList: Object[] | ArrayBuffer[]): void

设置任务的拷贝列表。在使用该方法前，需先构造Task对象。
> 说明
>
> * 此接口与[setTransferList](#settransferlist10)互斥：同一个ArrayBuffer不能同时设置在transfer列表和clone列表中。
> * 需搭配[@Sendable装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-sendable#sendable装饰器)使用，否则会抛异常。建议开发者使用该装饰器以避免异常。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:--------|:-----------------------|:-|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|cloneList|Object[] | ArrayBuffer[]|是|- 传入数组的类型必须为[Sendable支持的数据类型](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-sendable#sendable支持的数据类型)或ArrayBuffer。 - 所有传入cloneList的对象持有的[Sendable class](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-sendable#sendable-class)实例或ArrayBuffer类型对象，在线程间传输的行为都会变成拷贝传递，即修改传输后的对象不会对原有对象产生任何影响。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:---------------------------------------------------------------------|
|10200029|An ArrayBuffer cannot be set as both a transfer list and a clone list.|

**示例：**

```ts
// sendable.ets
// 定义两个Sendable class：BaseClass及其子类DeriveClass
@Sendable
export class BaseClass {
  private str: string = "sendable: BaseClass";
  static num :number = 10;
  str1: string = "sendable: this is BaseClass's string";
  num1: number = 5;
  isDone1: boolean = false;

  private fibonacciRecursive(n: number): number {
    if (n <= 1) {
      return n;
    } else {
      return this.fibonacciRecursive(n - 1) + this.fibonacciRecursive(n - 2);
    }
  }

  private privateFunc(num: number): number{
    let res: number = this.fibonacciRecursive(num);
    console.info("sendable: BaseClass privateFunc res is: " + res);
    return res;
  }

  publicFunc(num: number): number {
    return this.privateFunc(num);
  }

  get GetNum(): number {
    return this.num1;
  }
  set SetNum(num: number) {
    this.num1 = num;
  }

  constructor() {
    console.info(this.str);
    this.isDone1 = true;
  }
}

@Sendable
export class DeriveClass extends BaseClass {
  name: string = "sendable: this is DeriveClass";
  printName() {
    console.info(this.name);
  }
  constructor() {
    super();
  }
}
```

```ts
// index.ets
// 宿主线程（这里的宿主线程为UI主线程）调用taskpool，在taskpool线程中调用BaseClass和DeriveClass的方法、访问对应属性
import { taskpool } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { BaseClass, DeriveClass } from './sendable';

@Concurrent
function testFunc(arr: Array<BaseClass>, num: number): number {
  let baseInstance1 = arr[0];
  console.info("sendable: str1 is: " + baseInstance1.str1);
  baseInstance1.SetNum = 100;
  console.info("sendable: num1 is: " + baseInstance1.GetNum);
  console.info("sendable: isDone1 is: " + baseInstance1.isDone1);
  // 获取斐波那契数列第num项的结果
  let res: number = baseInstance1.publicFunc(num);
  return res;
}

@Concurrent
function printLog(arr: Array<DeriveClass>): void {
  let deriveInstance = arr[0];
  deriveInstance.printName();
}

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
        Button() {
          Text("TaskPool Test");
        }.onClick(() => {
          // task1访问调用BaseClass.str1/BaseClass.SetNum/BaseClass.GetNum/BaseClass.isDone1/BaseClass.publicFunc
          let baseInstance1: BaseClass = new BaseClass();
          let array1 = new Array<BaseClass>();
          array1.push(baseInstance1);
          let task1 = new taskpool.Task(testFunc, array1, 10);
          task1.setCloneList(array1);
          taskpool.execute(task1).then((res: Object) => {
            console.info("sendable: task1 res is: " + res);
          }).catch((e:BusinessError) => {
            console.error(`sendable: task1 execute Code is ${e.code}, message is ${e.message}`);
          })

          // task2调用DeriveClass.printName
          let deriveInstance: DeriveClass = new DeriveClass();
          let array2 = new Array<DeriveClass>();
          array2.push(deriveInstance);
          let task2 = new taskpool.Task(printLog, array2);
          task2.setCloneList(array2);
          taskpool.execute(task2).then(() => {
            console.info("sendable: task2 execute success");
          }).catch((e:BusinessError) => {
            console.error(`sendable: task2 execute Code is ${e.code}, message is ${e.message}`);
          })
        })
        .height('15%')
        .width('30%')
      }
      .width('100%')
    }
    .height('100%')
  }
}
```

### sendData^11+^

static sendData(...args: Object[]): void

任务执行过程中向宿主线程发送消息并触发回调。使用此方法前需构造Task。
> 说明
>
> * 该接口应在taskpool的线程中调用。
> * 避免在回调函数中调用该方法，否则可能导致消息无法传递到宿主线程。
> * 避免在异步函数中调用该方法，否则可能导致消息无法传递到宿主线程。如果在异步函数中使用，则需要使用await来确保该异步函数在任务中同步执行完成。
> * 调用该接口时，请确保处理数据的回调函数在宿主线程通过[onReceiveData](#onreceivedata11)注册。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-------|:-|:---------------------------------------------------------------|
|args|Object[]|否|可传输对象默认转移，作为回调函数的参数。支持的参数类型请参见[序列化支持类型](#序列化支持类型)，默认值为undefined。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:-----------------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200022|The function is not called in the TaskPool thread.|
|10200023|The function is not called in the concurrent function.|
|10200024|The callback is not registered on the host side.|

**示例：**

```ts
@Concurrent
function sendDataTest(num: number): number {
  let res: number = num * 10;
  taskpool.Task.sendData(res);
  return num;
}

function printLog(data: number): void {
  console.info("taskpool: data is: " + data);
}

async function taskpoolTest(): Promise<void> {
  try {
    let task: taskpool.Task = new taskpool.Task(sendDataTest, 1);
    task.onReceiveData(printLog);
    await taskpool.execute(task);
  } catch (e) {
    console.error(`taskpool: error code: ${e.code}, message: ${e.message}`);
  }
}

taskpoolTest();
```

```ts
// 异步函数中调用该方法
@Concurrent
async function sendDataTest(num: number) {
  let asyncSleepAndSendData = async () => {
    let asyncSleep = async (time: number): Promise<Object> => {
      return new Promise(resolve => setTimeout(resolve, time));
    }
    await asyncSleep(10000);
    let res: number = num * 10;
    taskpool.Task.sendData(res);
  }
  await asyncSleepAndSendData(); // 需要使用await来确保该异步函数在任务中同步执行完成。
}

function taskpoolTest() {
  try {
    let task: taskpool.Task = new taskpool.Task(sendDataTest, 10);
    task.onReceiveData((data: number) => {
      console.info("taskpool: data is: " + data);
    });
    taskpool.execute(task);
  } catch (e) {
    console.error(`taskpool: error code: ${e.code}, info: ${e.message}`);
  }
}

taskpoolTest();
```

### onReceiveData^11+^

onReceiveData(callback?: Function): void

为任务注册回调函数，接收并处理任务池工作线程的数据。使用此方法前，需构造Task。
> 说明
>
> * 该方法与[sendData](#senddata11)配对使用。
> * 不支持为同一任务定义多种回调函数。如果多次赋值，只有最后一次赋值的回调函数会生效。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:-------|:-|:------------------------------------------------|
|callback|Function|否|处理数据的回调函数，发送到宿主线程的数据将会作为入参传入该回调函数。不传参可以取消注册的回调函数。|

**示例：**

```ts
@Concurrent
function concurrentFunc(num: number): number {
  let res: number = num * 10;
  taskpool.Task.sendData(res);
  return num;
}

function printLog(data: number): void {
  console.info("taskpool: data is: " + data);
}

async function testFunc(): Promise<void> {
  try {
    let task: taskpool.Task = new taskpool.Task(concurrentFunc, 1);
    task.onReceiveData(printLog);
    await taskpool.execute(task);
  } catch (e) {
    console.error(`taskpool: error code: ${e.code}, message: ${e.message}`);
  }
}

testFunc();
```

### addDependency^11+^

addDependency(...tasks: Task[]): void

为当前任务添加对其他任务的依赖。使用该方法前需先构造Task。该任务和被依赖的任务不能是任务组任务、串行队列任务、异步队列任务、已执行任务或周期任务。存在依赖关系的任务（依赖其他任务的任务或被依赖的任务）执行后不可再次执行。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:----|:--------------|:-|:----------------------|
|tasks|[Task](#task)[]|否|被依赖的任务数组。默认值为undefined。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------------------|
|10200026|There is a circular dependency.|
|10200052|The periodic task cannot have a dependency. 适用版本：12+|
|10200056|The task has been executed by the AsyncRunner. 适用版本：18+|

**示例：**

```ts
@Concurrent
function delay(args: number): number {
  let t: number = Date.now();
  while ((Date.now() - t) < 1000) {
    continue;
  }
  return args;
}

let task1:taskpool.Task = new taskpool.Task(delay, 100);
let task2:taskpool.Task = new taskpool.Task(delay, 200);
let task3:taskpool.Task = new taskpool.Task(delay, 200);

console.info("dependency: add dependency start");
task1.addDependency(task2);
task2.addDependency(task3);
console.info("dependency: add dependency end");

console.info("dependency: start execute second");
taskpool.execute(task1).then(() => {
  console.info("dependency: second task1 success");
})
taskpool.execute(task2).then(() => {
  console.info("dependency: second task2 success");
})
taskpool.execute(task3).then(() => {
  console.info("dependency: second task3 success");
})
```

### removeDependency^11+^

removeDependency(...tasks: Task[]): void

删除当前任务对其他任务的依赖。在使用该方法之前，需要先构造Task对象。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:----|:--------------|:-|:----------------------|
|tasks|[Task](#task)[]|否|被依赖的任务数组。默认值为undefined。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------------------|
|10200027|The dependency does not exist.|
|10200052|The periodic task cannot have a dependency. 适用版本：12+|
|10200056|The task has been executed by the AsyncRunner. 适用版本：18+|

**示例：**

```ts
@Concurrent
function delay(args: number): number {
  let t: number = Date.now();
  while ((Date.now() - t) < 1000) {
    continue;
  }
  return args;
}

let task1:taskpool.Task = new taskpool.Task(delay, 100);
let task2:taskpool.Task = new taskpool.Task(delay, 200);
let task3:taskpool.Task = new taskpool.Task(delay, 200);

console.info("dependency: add dependency start");
task1.addDependency(task2);
task2.addDependency(task3);
console.info("dependency: add dependency end");
console.info("dependency: remove dependency start");
task1.removeDependency(task2);
task2.removeDependency(task3);
console.info("dependency: remove dependency end");

console.info("dependency: start execute");
taskpool.execute(task1).then(() => {
  console.info("dependency: task1 success");
})
taskpool.execute(task2).then(() => {
  console.info("dependency: task2 success");
})
taskpool.execute(task3).then(() => {
  console.info("dependency: task3 success");
})
```

### onEnqueued^12+^

onEnqueued(callback: CallbackFunction): void

注册回调函数，任务入队时将调用该函数。需在调用execute前注册，否则会抛异常。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------------------------|:-|:--------|
|callback|[CallbackFunction](#callbackfunction12)|是|需注册的回调函数。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:----------------------------------------------------------------|
|10200034|The executed task does not support the registration of listeners.|

**示例：**

```ts
import { taskpool } from '@kit.ArkTS';

@Concurrent
function delay(args: number): number {
  let t: number = Date.now();
  while ((Date.now() - t) < 1000) {
    continue;
  }
  return args;
}

let task: taskpool.Task = new taskpool.Task(delay, 1);
task.onEnqueued(() => {
  console.info("taskpool: onEnqueued");
});
taskpool.execute(task).then(() => {
  console.info("taskpool: execute task success");
});
```

### onStartExecution^12+^

onStartExecution(callback: CallbackFunction): void

注册回调函数，任务开始执行前将调用该函数。需在调用execute前注册，否则会抛异常。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------------------------|:-|:--------|
|callback|[CallbackFunction](#callbackfunction12)|是|需注册的回调函数。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:----------------------------------------------------------------|
|10200034|The executed task does not support the registration of listeners.|

**示例：**

```ts
import { taskpool } from '@kit.ArkTS';

@Concurrent
function delay(args: number): number {
  let t: number = Date.now();
  while ((Date.now() - t) < 1000) {
    continue;
  }
  return args;
}

let task: taskpool.Task = new taskpool.Task(delay, 1);
task.onStartExecution(() => {
  console.info("taskpool: onStartExecution");
});
taskpool.execute(task).then(() => {
  console.info("taskpool: execute task success");
});
```

### onExecutionFailed^12+^

onExecutionFailed(callback: CallbackFunctionWithError): void

注册回调函数，任务执行失败时调用该回调函数（周期任务不支持）。需在调用execute前注册，否则会抛异常。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------------------------------------------|:-|:--------|
|callback|[CallbackFunctionWithError](#callbackfunctionwitherror12)|是|需注册的回调函数。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:----------------------------------------------------------------|
|10200034|The executed task does not support the registration of listeners.|

**示例：**

```ts
import { taskpool } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { HashMap } from '@kit.ArkTS';

@Concurrent
function hashMapFunc(args: number) {
  let t = Date.now();
  while ((Date.now() - t) < 100) {
    continue;
  }
  return () => {};
}

let task2 = new taskpool.Task(hashMapFunc, 1);
task2.onExecutionFailed((e: Error) => {
  console.error("taskpool: onExecutionFailed error is " + e.message);
})
taskpool.execute(task2).then(() => {
  console.info("taskpool: execute task success");
}).catch((e:BusinessError) => {
  console.error(`taskpool: error code: ${e.code}, error message: ${e.message}`);
})
```

### onExecutionSucceeded^12+^

onExecutionSucceeded(callback: CallbackFunction): void

注册一个回调函数，并在任务执行成功时调用它（周期任务不支持）。需在调用execute前注册，否则会抛异常。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------------------------|:-|:--------|
|callback|[CallbackFunction](#callbackfunction12)|是|需注册的回调函数。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:----------------------------------------------------------------|
|10200034|The executed task does not support the registration of listeners.|

**示例：**

```ts
import { taskpool } from '@kit.ArkTS';

@Concurrent
function delay(args: number): number {
  let t: number = Date.now();
  while ((Date.now() - t) < 1000) {
    continue;
  }
  return args;
}

let task: taskpool.Task = new taskpool.Task(delay, 1);
task.onExecutionSucceeded(() => {
  console.info("taskpool: onExecutionSucceeded");
});
taskpool.execute(task).then(() => {
  console.info("taskpool: execute task success");
});
```

### isDone^12+^

isDone(): boolean

检查任务是否已完成。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**返回值：**

|类型|说明|
|:------|:-----------------------------|
|boolean|任务执行完成时返回true，任务未执行完成时返回false。|

**示例：**

```ts
import { BusinessError } from '@kit.BasicServicesKit';

@Concurrent
function inspectStatus(arg: number): number {
  // 1s sleep
  let t: number = Date.now();
  while (Date.now() - t < 1000) {
    continue;
  }
  return arg + 1;
}

async function taskpoolCancel(): Promise<void> {
  let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number
  taskpool.execute(task).then((res: Object) => {
    console.info("Succeeded in executing task, result: " + res);
  }).catch((e: BusinessError) => {
    console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
  });

  setTimeout(() => {
    if (!task.isDone()) {
      taskpool.cancel(task);
    }
  }, 3000); // 延时3s，确保任务已执行
}

taskpoolCancel();
```

## CallbackFunction^12+^

type CallbackFunction = () => void

注册的回调函数类型。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

## CallbackFunctionWithError^12+^

type CallbackFunctionWithError = (e: Error) => void

注册接收错误对象的回调函数类型。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:--|:----|:-|:------|
|e|Error|是|错误信息对象。|

## LongTask^12+^

表示长时任务。LongTask继承自[Task](#task)。

长时任务不设置执行时间上限，长时间运行不会触发超时异常，但不支持将同一任务多次执行或者将该任务加入任务组（TaskGroup）。

执行长时任务的线程会持续存在，直到任务完成并调用[terminateTask](#taskpoolterminatetask12)后，该线程在空闲时被回收。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**示例：**

```ts
@Concurrent
function printArgs(args: string): string {
  console.info("printArgs: " + args);
  return args;
}

let task: taskpool.LongTask = new taskpool.LongTask(printArgs, "this is my first LongTask");
```

## GenericsTask^13+^

表示泛型任务。GenericsTask继承自[Task](#task)。

相比创建Task，创建GenericsTask可以在编译阶段校验并发函数的传参和返回值类型。其余行为与Task相同。

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

### constructor^13+^

constructor(func: (...args: A) => R | Promise<R>, ...args: A)

GenericsTask的构造函数。

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

**元服务API：** 从API version 13开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-----------------------------|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
|func|(...args: A) => R | Promise<R>|是|待执行的函数，必须使用[@Concurrent装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#concurrent装饰器)装饰，支持的函数返回值类型请参考[序列化支持类型](#序列化支持类型)。|
|args|A|否|任务执行函数的入参，支持的参数类型请参考[序列化支持类型](#序列化支持类型)。默认值为undefined。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

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

**示例：**

```ts
@Concurrent
function printArgs(args: string): string {
  console.info("printArgs: " + args);
  return args;
}

@Concurrent
function testWithThreeParams(a: number, b: string, c: number): string {
  return b;
}

@Concurrent
function testWithArray(args: [number, string]): string {
  return "success";
}

let task1: taskpool.Task = new taskpool.GenericsTask<[string], string>(printArgs, "this is my first GenericsTask");

let task2: taskpool.Task = new taskpool.GenericsTask<[number, string, number], string>(testWithThreeParams, 100, "test", 100);

let task3: taskpool.Task = new taskpool.GenericsTask<[[number, string]], string>(testWithArray, [100, "test"]);
```

### constructor^13+^

constructor(name: string, func: (...args: A) => R | Promise<R>, ...args: A)

GenericsTask的构造函数，可以指定任务名称。

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

**元服务API：** 从API version 13开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-----------------------------|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
|name|string|是|泛型任务名称。|
|func|(...args: A) => R | Promise<R>|是|待执行的函数，必须使用[@Concurrent装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#concurrent装饰器)装饰，支持的函数返回值类型请参考[序列化支持类型](#序列化支持类型)。|
|args|A|否|任务执行传入函数的入参，支持的参数类型请参考[序列化支持类型](#序列化支持类型)。默认值为undefined。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

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

**示例：**

```ts
@Concurrent
function printArgs(args: string): string {
  console.info("printArgs: " + args);
  return args;
}

let taskName: string = "taskName";
let task: taskpool.Task = new taskpool.GenericsTask<[string], string>(taskName, printArgs, "this is my first Task");
let name: string = task.name;
```

## TaskGroup^10+^

表示任务组，一次执行一组任务，适用于执行一组有关联的任务。

* 如果所有任务正常执行，异步执行完毕后返回所有任务结果的数组，数组中元素的顺序与[addTask](#addtask10-1)的顺序相同。
* 如果任意任务失败，则会抛出对应异常。
* 如果任务组中存在多个任务失败的情况，则会抛出第一个失败任务的异常。
* 任务组可以多次执行，但执行后不能新增任务。

### constructor^10+^

constructor()

TaskGroup的构造函数。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**示例：**

```ts
let taskGroup = new taskpool.TaskGroup();
```

### constructor^11+^

constructor(name: string)

TaskGroup的构造函数，支持指定任务组名称。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-----|:-|:-----|
|name|string|是|任务组名称。|

**示例：**

```ts
let taskGroupName: string = "groupName";
let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup(taskGroupName);
let name: string = taskGroup.name;
```

### addTask^10+^

addTask(func: Function, ...args: Object[]): void

将待执行的函数添加到任务组中。使用该方法前需要先构造TaskGroup。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:-------|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
|func|Function|是|待执行的函数，必须使用[@Concurrent装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/taskpool-introduction#concurrent装饰器)装饰，支持的函数返回值类型请参考[序列化支持类型](#序列化支持类型)。|
|args|Object[]|否|任务执行函数的入参，支持的类型请参考[序列化支持类型](#序列化支持类型)，默认值为undefined。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

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

**示例：**

```ts
@Concurrent
function printArgs(args: number): number {
  console.info("printArgs: " + args);
  return args;
}

let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup();
taskGroup.addTask(printArgs, 100); // 100: test number
```

### addTask^10+^

addTask(task: Task): void

将创建好的任务添加到任务组中。使用此方法前需要先构造TaskGroup。任务组不能添加其他任务组中的任务、串行队列任务、异步队列任务、有依赖关系的任务、长时任务、周期任务和已执行的任务。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:------------|:-|:------------|
|task|[Task](#task)|是|需要添加到任务组中的任务。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:---------------------------------------------------|
|10200014|The function is not marked as concurrent.|
|10200051|The periodic task cannot be executed again. 适用版本：12+|
|10200057|The task cannot be executed by two APIs. 适用版本：18+|

**示例：**

```ts
@Concurrent
function printArgs(args: number): number {
  console.info("printArgs: " + args);
  return args;
}

let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup();
let task: taskpool.Task = new taskpool.Task(printArgs, 200); // 200: test number
taskGroup.addTask(task);
```

### 属性

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

|名称|类型|只读|可选|说明|
|:--------|:-----|:-|:-|:--------------|
|name^11+^|string|否|否|创建任务组时指定的任务组名称。|

## SequenceRunner^11+^

表示串行队列的任务，用于执行一组需要串行执行的任务。

### constructor^11+^

constructor(priority?: Priority)

SequenceRunner的构造函数。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------|:-|:----------------------------------------|
|priority|[Priority](#priority)|否|指定任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。|

**示例：**

```ts
let runner: taskpool.SequenceRunner = new taskpool.SequenceRunner();
```

### constructor^12+^

constructor(name: string, priority?: Priority)

SequenceRunner的构造函数。构造一个全局串行队列，如果名字相同，将返回同一个串行队列。
> 说明
>
> * 底层通过单例模式保证了：创建同名串行队列时，获取到同一个实例。
> * 无法修改串行队列的优先级。

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

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------|:-|:----------------------------------------|
|name|string|是|串行队列的名字。|
|priority|[Priority](#priority)|否|指定任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。|

**示例：**

```ts
let runner:taskpool.SequenceRunner = new taskpool.SequenceRunner("runner1", taskpool.Priority.LOW);
```

### execute^11+^

execute(task: Task): Promise<Object>

执行串行任务。使用该方法前需先构造SequenceRunner。串行队列不能执行任务组任务、其他串行队列任务、异步队列任务、有依赖关系的任务和已执行的任务。使用Promise异步回调。
> 说明
>
> * 不支持加入存在依赖的任务。
> * 前面的任务执行失败或取消不会影响后续任务的执行。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:---|:------------|:-|:---------------|
|task|[Task](#task)|是|需要添加到串行任务队列中的任务。|

**返回值：**

|类型|说明|
|:--------------|:---------------------|
|Promise<Object>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:---------------------------------------------------|
|10200003|Worker initialization failed. 适用版本：11-17|
|10200006|An exception occurred during serialization.|
|10200025|dependent task not allowed.|
|10200051|The periodic task cannot be executed again. 适用版本：12+|
|10200057|The task cannot be executed by two APIs. 适用版本：18+|

**示例：**

```ts
@Concurrent
function additionDelay(delay: number): void {
  let start: number = new Date().getTime();
  while (new Date().getTime() - start < delay) {
    continue;
  }
}
@Concurrent
function waitForRunner(finalString: string): string {
  return finalString;
}
async function seqRunner() {
  let finalString:string = "";
  let task1:taskpool.Task = new taskpool.Task(additionDelay, 3000);
  let task2:taskpool.Task = new taskpool.Task(additionDelay, 2000);
  let task3:taskpool.Task = new taskpool.Task(additionDelay, 1000);
  let task4:taskpool.Task = new taskpool.Task(waitForRunner, finalString);

  let runner:taskpool.SequenceRunner = new taskpool.SequenceRunner();
  runner.execute(task1).then(() => {
    finalString += 'a';
    console.info("seqrunner: task1 done.");
  });
  runner.execute(task2).then(() => {
    finalString += 'b';
    console.info("seqrunner: task2 done");
  });
  runner.execute(task3).then(() => {
    finalString += 'c';
    console.info("seqrunner: task3 done");
  });
  await runner.execute(task4);
  console.info("seqrunner: task4 done, finalString is " + finalString);
}
```

## AsyncRunner^18+^

表示异步队列。可以指定任务执行的并发度和排队策略。

### constructor^18+^

constructor(runningCapacity: number, waitingCapacity?: number)

AsyncRunner的构造函数。构造一个非全局的异步队列，即使参数相同，每次调用也会返回不同的异步队列实例。

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

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:--------------|:-----|:-|:------------------------------------------------------------------------------------------------------------------|
|runningCapacity|number|是|指定任务执行的最大并发度，该参数应为正整数，负数时报错，非整数时会向下取整。|
|waitingCapacity|number|否|指定等待任务的列表容量，取值需大于等于0，负数时报错，输入非整数时会向下取整。默认值为0，表示等待任务列表的容量没有限制。如果设置大于0的值，则表示排队策略为丢弃策略，当加入的任务数量超过该值时，等待列表中处于队头的任务会被丢弃。|

**示例：**

```ts
let runner: taskpool.AsyncRunner = new taskpool.AsyncRunner(5);
```

### constructor^18+^

constructor(name: string, runningCapacity: number, waitingCapacity?: number)

AsyncRunner的构造函数用于构造一个全局异步队列。如果队列名称相同，将返回同一个异步队列实例。
> 说明
>
> * 底层通过单例模式确保创建同名的异步队列时，获取同一个实例。
> * 无法修改并发度和等待任务列表容量。

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

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:--------------|:-----|:-|:----------------------------------------------------------------------------------------------------------------|
|name|string|是|异步队列的名字。|
|runningCapacity|number|是|指定任务执行的最大并发度，该参数应为正整数。负数时报错，非整数会向下取整。|
|waitingCapacity|number|否|指定等待任务的列表容量，取值需大于等于0，负数时报错，非整数时会向下取整。默认值为0，表示等待任务列表的容量没有限制。如果设置大于0的值，则表示排队策略为丢弃策略，当加入的任务数量超过该值时，等待列表中处于队头的任务会被丢弃。|

**示例：**

```ts
let runner:taskpool.AsyncRunner = new taskpool.AsyncRunner("runner1", 5, 5);
```

### execute^18+^

execute(task: Task, priority?: Priority): Promise<Object>

执行异步任务。使用该方法前需要先构造AsyncRunner。使用Promise异步回调。
> 说明
>
> * 不支持执行任务组中的任务。
> * 不支持执行串行队列中的任务。
> * 不支持执行其他异步队列任务。
> * 不支持执行周期性任务。
> * 不支持执行延时任务。
> * 不支持执行存在依赖的任务。
> * 不支持执行已执行过的任务。

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

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------|:-|:----------------------------------------|
|task|[Task](#task)|是|需要添加到异步队列中的任务。|
|priority|[Priority](#priority)|否|指定任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。|

**返回值：**

|类型|说明|
|:--------------|:---------------------|
|Promise<Object>|Promise对象，返回任务函数的执行结果。|

**错误码：**

以下错误码的详细介绍请参见[语言基础类库错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-utils)。

|错误码ID|错误信息|
|:-------|:------------------------------------------|
|10200006|An exception occurred during serialization.|
|10200025|dependent task not allowed.|
|10200051|The periodic task cannot be executed again.|
|10200054|The asyncRunner task is discarded.|
|10200057|The task cannot be executed by two APIs.|

**示例：**

```ts
import { taskpool } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

@Concurrent
function additionDelay(delay: number): void {
  let start: number = new Date().getTime();
  while (new Date().getTime() - start < delay) {
    continue;
  }
}
async function asyncRunner() {
  let runner:taskpool.AsyncRunner = new taskpool.AsyncRunner("runner1", 5, 5);
  for (let i = 0; i < 30; i++) {
    let task:taskpool.Task = new taskpool.Task(additionDelay, 1000);
    runner.execute(task).then(() => {
      console.info("asyncRunner: task" + i + " done.");
    }).catch((e: BusinessError) => {
      console.error("asyncRunner: task" + i + " error." + e.code + "-" + e.message);
    });
  }
}

async function asyncRunner2() {
  let runner:taskpool.AsyncRunner = new taskpool.AsyncRunner(5);
  for (let i = 0; i < 20; i++) {
    let task:taskpool.Task = new taskpool.Task(additionDelay, 1000);
    runner.execute(task).then(() => {
      console.info("asyncRunner: task" + i + " done.");
    });
  }
}
```

## State^10+^

表示任务（Task）状态的枚举。

状态转换规则如下：

* 当任务创建成功后，调用execute，任务进入taskpool等待队列，状态设置为WAITING。
* 任务从等待队列出来进入taskpool工作线程中，任务状态更新为RUNNING。
* 当任务执行完成，返回结果后，如果任务再次被执行，则状态重置为WAITING。
* 当主动cancel任务时，将任务状态更新为CANCELED。

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

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

## TaskInfo^10+^

任务的内部信息。

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

### 属性

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

|名称|类型|只读|可选|说明|
|:--------|:----------------|:-|:-|:---------------------------------------------------------------------------------------------------------|
|name^12+^|string|否|否|任务的名字，不建议修改此值。 **元服务API：** 从API version 12开始，该接口支持在元服务中使用。|
|taskId|number|否|否|任务的ID。系统默认提供全局唯一值，不建议修改此值。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|state|[State](#state10)|否|否|任务的状态。state标识任务的当前状态，不建议修改此值。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|
|duration|number|否|是|任务执行至当前所用的时间，默认为0，单位：ms。当返回为0时，表示任务未执行；返回为空时，表示没有任务执行。不建议修改此值。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。|

## ThreadInfo^10+^

工作线程的内部信息。

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

### 属性

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

|名称|类型|只读|可选|说明|
|:-------|:--------------------|:-|:-|:--------------------------------------|
|tid|number|否|否|工作线程的标识符。如果返回为空，表示当前没有任务执行。不建议修改此值。|
|taskIds|number[]|否|是|在当前线程上运行的任务ID列表。返回为空时，代表没有任务执行。不建议修改此值。|
|priority|[Priority](#priority)|否|是|当前线程的优先级。返回为空时，代表没有任务执行。 不建议修改此值。|

## TaskPoolInfo^10+^

任务池的内部信息。

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

### 属性

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

|名称|类型|只读|可选|说明|
|:----------|:----------------------------|:-|:-|:-----------------|
|threadInfos|[ThreadInfo](#threadinfo10)[]|否|否|工作线程的内部信息。不建议修改此值。|
|taskInfos|[TaskInfo](#taskinfo10)[]|否|否|任务的内部信息。不建议修改此值。|

## TaskResult^20+^

对处于等待或执行过程中的任务执行取消操作后，在catch分支里捕获到BusinessError里的补充信息。其他场景下该信息为undefined。

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

### 属性

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

**元服务API：** 从API version 20开始，该接口支持在元服务中使用。

|名称|类型|只读|可选|说明|
|:-----|:-------------|:-|:-|:-----------------------------------------|
|result|Object|否|是|任务执行结果。默认为undefined。 不建议修改此值。|
|error|Error | Object|否|是|错误信息。默认和BusinessError的message字段一致。不建议修改此值。|

> 说明
>
> 任务被取消后，有如下两种情况：
>
> * 如果当前任务是处于等待阶段，则result的值为undefined，error的值和BusinessError的message字段一致；
> * 如果当前任务正在运行，有异常抛出的情况下result的值为undefined，error的值为抛出的异常信息；没有异常的情况下，result为任务执行完成后的结果，error的值和BusinessError的message字段一致。

**示例：**

```ts
import { taskpool } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit'

@Concurrent
function loop(): Error | number {
  let start: number = Date.now();
  while (Date.now() - start < 1500) {
  }
  if (taskpool.Task.isCanceled()) {
    return 0;
  }
  while (Date.now() - start < 3000) {
  }
  if (taskpool.Task.isCanceled()) {
    throw new Error("this is loop error");
  }
  return 1;
}

// 执行前取消
function waitingCancel() {
  let task = new taskpool.Task(loop);
  taskpool.executeDelayed(2000, task).catch((e:BusinessError<taskpool.TaskResult>) => {
    console.error(`waitingCancel task catch code: ${e.code}, message: ${e.message}`);
    // waitingCancel task catch code: 0, message: taskpool:: task has been canceled
    if (e.data !== undefined) {
      console.error(`waitingCancel task catch data: result: ${e.data.result}, error: ${e.data.error}`);
      // waitingCancel task catch data: result: undefined, error: taskpool:: task has been canceled
    }
  })
  setTimeout(() => {
    taskpool.cancel(task);
  }, 1000);
}

// 执行过程中取消
function runningCancel() {
  let task = new taskpool.Task(loop);
  taskpool.execute(task).catch((e:BusinessError<taskpool.TaskResult>) => {
    console.error(`runningCancel task catch code: ${e.code}, message: ${e.message}`);
    // runningCancel task catch code: 0, message: taskpool:: task has been canceled
    if (e.data !== undefined) {
      console.error(`runningCancel task catch data: result: ${e.data.result}, error: ${e.data.error}`);
      // runningCancel task catch data: result: 0, error: taskpool:: task has been canceled
    }
  })
  setTimeout(() => {
    taskpool.cancel(task);
  }, 1000);
}

// 执行过程中抛异常
function runningCancelError() {
  let task = new taskpool.Task(loop);
  taskpool.execute(task).catch((e:BusinessError<taskpool.TaskResult>) => {
    console.error(`runningCancelError task catch code: ${e.code}, message: ${e.message}`);
    // runningCancelError task catch code: 0, message: taskpool:: task has been canceled
    if (e.data !== undefined) {
      console.error(`runningCancelError task catch data: result: ${e.data.result}, error: ${e.data.error}`);
      // runningCancelError task catch data: result: undefined, error: Error: this is loop error
    }
  })
  setTimeout(() => {
    taskpool.cancel(task);
  }, 2000);
}
```

## Configs^24+^

任务或任务组的配置项。

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

**元服务API：** 从API version 24开始，该接口支持在元服务中使用。

|名称|类型|只读|可选|说明|
|:-------|:--------------------|:-|:-|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|timeout|number|否|是|超时时间，单位：ms。建议传入整数，若传入小数，会被向下取整。 如果省略该参数，timeout取默认值0，不执行超时逻辑。 **注意**： 1. 该超时时间非精准时间，受线程调度影响，实际超时触发时间可能与设定值存在偏差。 2. 如果值小于1，会被默认取0。 3. timeout值受系统限制，超出2^31 - 1时会溢出，timeout值为0。|
|priority|[Priority](#priority)|否|是|任务的优先级。默认值为taskpool.Priority.MEDIUM。|

## 其他说明

### 序列化支持类型

序列化支持类型参考[线程间通信对象概述](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/serializable-overview)里的介绍。

### 简单使用

**示例一**

```ts
// 支持普通函数、引用入参传递
@Concurrent
function printArgs(args: string): string {
  console.info("func: " + args);
  return args;
}

async function taskpoolExecute(): Promise<void> {
  // taskpool.execute(task)
  let task: taskpool.Task = new taskpool.Task(printArgs, "create task, then execute");
  console.info("taskpool.execute(task) result: " + await taskpool.execute(task));
  // taskpool.execute(function)
  console.info("taskpool.execute(function) result: " + await taskpool.execute(printArgs, "execute task by func"));
}

taskpoolExecute();
```

**示例二**

```ts
// b.ets
export let sharedString: string = "hello";
```

```ts
// 引用import变量
// a.ets(与b.ets位于同一目录中)
import { sharedString } from "./b";

@Concurrent
function printArgs(str: string): string {
  console.info(str);
  console.info(sharedString);
  return str;
}

async function taskpoolExecute(): Promise<void> {
  // taskpool.execute(task)
  let task: taskpool.Task = new taskpool.Task(printArgs, "create task, then execute");
  console.info("taskpool.execute(task) result: " + await taskpool.execute(task));

  // taskpool.execute(function)
  console.info("taskpool.execute(function) result: " + await taskpool.execute(printArgs, "execute task by func"));
}

taskpoolExecute();
```

**示例三**

```ts
import { BusinessError } from '@kit.BasicServicesKit';

// 支持async函数
@Concurrent
async function delayExecute(): Promise<Array<Object>> {
  let resolvedResults = await Promise.all<Object>([
    new Promise<Object>(resolve => setTimeout(resolve, 1000, "resolved"))
  ]);
  return resolvedResults;
}

async function taskpoolExecute(): Promise<void> {
  taskpool.execute(delayExecute).then((result: Object) => {
    console.info("Succeeded in executing task, result: " + result);
  }).catch((e: BusinessError) => {
    console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
  });
}

taskpoolExecute();
```

**示例四**

```ts
// c.ets
import { BusinessError } from '@kit.BasicServicesKit';

@Concurrent
function strSort(inputArr: Array<string>): Array<string> {
  let newArr = inputArr.sort();
  return newArr;
}

export async function executeByTaskObject(): Promise<void> {
  console.info("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.info("func1 result:" + await taskpool.execute(task));
}

export async function executeByFunction(): Promise<void> {
  console.info("taskpoolTest2 start");
  let strArray: Array<string> = ['c test string', 'b test string', 'a test string'];
  taskpool.execute(strSort, strArray).then((result: Object) => {
    console.info("Succeeded in executing task, result: " + result);
  }).catch((e: BusinessError) => {
    console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
  });
}
```

```ts
// index.ets
import { executeByTaskObject, executeByFunction } from "./c";

executeByTaskObject();
executeByFunction();
```

**示例五**

```ts
import { BusinessError } from '@kit.BasicServicesKit';

// 任务取消成功
@Concurrent
function inspectStatus(arg: number): number {
  // 第一次检查任务是否已经取消并作出响应
  if (taskpool.Task.isCanceled()) {
    console.info("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.info("task has been canceled after 2s sleep.");
    return arg + 3;
  }
  return arg + 1;
}

async function taskpoolCancel(): Promise<void> {
  let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number
  taskpool.execute(task).then((res: Object) => {
    console.info("Succeeded in executing task, result: " + res);
  }).catch((e: BusinessError) => {
    console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
  });
  // 1s后取消task
  setTimeout(() => {
    try {
      taskpool.cancel(task);
    } catch (e) {
      console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`);
    }
  }, 1000);
}

taskpoolCancel();
```

**示例六**

```ts
import { BusinessError } from '@kit.BasicServicesKit';

// 已执行的任务取消失败
@Concurrent
function inspectStatus(arg: number): number {
  // 第一次检查任务是否已经取消并作出响应
  if (taskpool.Task.isCanceled()) {
    return arg + 2;
  }
  // 延时0.5s
  let t: number = Date.now();
  while (Date.now() - t < 500) {
    continue;
  }
  // 第二次检查任务是否已经取消并作出响应
  if (taskpool.Task.isCanceled()) {
    return arg + 3;
  }
  return arg + 1;
}

async function taskpoolCancel(): Promise<void> {
  let task: taskpool.Task = new taskpool.Task(inspectStatus, 100); // 100: test number
  taskpool.execute(task).then((res: Object) => {
    console.info("Succeeded in executing task, result: " + res);
  }).catch((e: BusinessError) => {
    console.error(`Failed to execute task. Code: ${e.code}, message: ${e.message}`);
  });

  setTimeout(() => {
    try {
      taskpool.cancel(task); // 任务已执行,取消失败
    } catch (e) {
      console.error(`taskpool: cancel error code: ${e.code}, info: ${e.message}`);
    }
  }, 3000); // 延时3s，确保任务已执行
}

taskpoolCancel();
```

**示例七**

```ts
// 待执行的任务组取消成功
@Concurrent
function printArgs(args: number): number {
  let t: number = Date.now();
  while (Date.now() - t < 1000) {
    continue;
  }
  console.info("printArgs: " + args);
  return args;
}

async function taskpoolGroupCancelTest(): Promise<void> {
  let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup();
  taskGroup1.addTask(printArgs, 10); // 10: test number
  taskGroup1.addTask(printArgs, 20); // 20: test number
  taskGroup1.addTask(printArgs, 30); // 30: test number
  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
  taskGroup2.addTask(task1);
  taskGroup2.addTask(task2);
  taskGroup2.addTask(task3);
  taskpool.execute(taskGroup1).then((res: Array<Object>) => {
    console.info("taskpool execute res is:" + res);
  }).catch((e: string) => {
    console.error("taskpool execute error is:" + e);
  });
  taskpool.execute(taskGroup2).then((res: Array<Object>) => {
    console.info("taskpool execute res is:" + res);
  }).catch((e: string) => {
    console.error("taskpool execute error is:" + e);
  });

  try {
    taskpool.cancel(taskGroup2);
  } catch (e) {
    console.error(`Failed to cancel task. Code: ${e.code}, message: ${e.message}`);
  }
}

taskpoolGroupCancelTest()
```

**示例八**

```ts
// 分别创建执行100个高、中、低优先级的任务，查看其各项信息
@Concurrent
function delay(): void {
  let start: number = new Date().getTime();
  while (new Date().getTime() - start < 500) {
    continue;
  }
}

let highCount: number = 0;
let mediumCount: number = 0;
let lowCount: number = 0;
let allCount: number = 100;
for (let i = 0; i < allCount; i++) {
  let task1: taskpool.Task = new taskpool.Task(delay);
  let task2: taskpool.Task = new taskpool.Task(delay);
  let task3: taskpool.Task = new taskpool.Task(delay);
  taskpool.execute(task1, taskpool.Priority.LOW).then(() => {
    lowCount++;
  }).catch((e: string) => {
    console.error("low task error: " + e);
  })
  taskpool.execute(task2, taskpool.Priority.MEDIUM).then(() => {
    mediumCount++;
  }).catch((e: string) => {
    console.error("medium task error: " + e);
  })
  taskpool.execute(task3, taskpool.Priority.HIGH).then(() => {
    highCount++;
  }).catch((e: string) => {
    console.error("high task error: " + e);
  })
}
let start: number = new Date().getTime();
while (new Date().getTime() - start < 1000) {
  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;
let name: string = "";
let threadInfos = Array.from(taskpoolInfo.threadInfos);
for (let threadInfo of threadInfos) {
  tid = threadInfo.tid;
  if (threadInfo.taskIds != undefined && threadInfo.priority != undefined) {
    taskIds.length = threadInfo.taskIds.length;
    priority = threadInfo.priority;
  }
  console.info("taskpool---tid is:" + tid + ", taskIds is:" + taskIds + ", priority is:" + priority);
}
let taskInfos = Array.from(taskpoolInfo.taskInfos);
for (let taskInfo of taskInfos) {
  taskId = taskInfo.taskId;
  state = taskInfo.state;
  if (taskInfo.duration != undefined) {
    duration = taskInfo.duration;
    name = taskInfo.name;
  }
  console.info("taskpool---taskId is:" + taskId + ", state is:" + state + ", duration is:" + duration + ", name is:" + name);
}
```

**示例九**

```ts
// 获取执行过程中主动抛的异常信息
@Concurrent
function taskpoolThrow() {
  throw new Error('execute error');
}

taskpool.execute(taskpoolThrow).catch((e: ESObject) => {
  if (e.error) {
    let errorMessage = e.error as Error;
    console.error(`Failed to execute task. Error name: ${errorMessage.name}, error message: ${errorMessage.message}`);
  } else {
    console.error(`Failed to execute task. Error name: ${e.name}, error message: ${e.message}`);
  }
});
```