diff --git a/zh-cn/application-dev/reference/apis/Readme-CN.md b/zh-cn/application-dev/reference/apis/Readme-CN.md index 7686d5db5b412b801c02f38acfd147661f56024f..2a22588070d6e53c21c0a967fdd538bd7fa610e0 100755 --- a/zh-cn/application-dev/reference/apis/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis/Readme-CN.md @@ -342,6 +342,7 @@ - [@ohos.buffer (Buffer)](js-apis-buffer.md) - [@ohos.convertxml (xml转换JavaScript)](js-apis-convertxml.md) - [@ohos.process (获取进程相关的信息)](js-apis-process.md) + - [@ohos.taskpool (启动任务池)](js-apis-taskpool.md) - [@ohos.uri (URI字符串解析)](js-apis-uri.md) - [@ohos.url (URL字符串解析)](js-apis-url.md) - [@ohos.util (util工具函数)](js-apis-util.md) diff --git a/zh-cn/application-dev/reference/apis/js-apis-taskpool.md b/zh-cn/application-dev/reference/apis/js-apis-taskpool.md new file mode 100644 index 0000000000000000000000000000000000000000..3add4b31bc7a98cb81029334d4e6ae31461a3f40 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-taskpool.md @@ -0,0 +1,193 @@ +# @ohos.taskpool(使用任务池) + +taskpool作用是为应用程序提供一个多线程的运行环境,可以降低整体资源的消耗、提高系统的整体性能,且用户无需关心线程实例的生命周期。 + +> **说明:**
+> 本模块首批接口从API version 9 开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```js +import taskpool from '@ohos.taskpool'; +``` + +## Priority + +表示所创建任务(Task)的优先级。(暂未支持) + +**系统能力:** SystemCapability.Utils.Lang + +| 名称 | 值 | 说明 | +| -------- | -------- | -------- | +| HIGH | 0 | 任务为高优先级。 | +| MEDIUM | 1 | 任务为中优先级。 | +| LOW | 2 | 任务为低优先级。 | + +## Task + +表示任务。使用以下方法前,需要先构造Task。 + +### constructor + +constructor(func: Function, ...args: unknown[]) + +Task的构造函数。 + +**系统能力:** SystemCapability.Utils.Lang + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ------------------------ | +| func | Function | 是 | 任务执行需要传入函数。 | +| args | unknown[] | 否 | 任务执行传入函数的参数。 | + +**错误码:** + +以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------- | +| 10200014 | The function is not mark as concurrent. | + +**示例:** + +```js +function func(args) { + "use concurrent" + console.log("func: " + args); + return args; +} +let task = new taskpool.Task(func, "this is my first Task"); +``` + +### 属性 + +**系统能力:** SystemCapability.Utils.Lang + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| --------- | --------- | ---- | ---- | ---------------------------- | +| function | Function | 是 | 是 | 创建任务时需要传入的函数。 | +| arguments | unknown[] | 是 | 是 | 创建任务传入函数所需的参数。 | + +## taskpool.execute + +execute(func: Function, ...args: unknown[]): Promise\ + +任务池执行任务,需要传入待执行的函数和函数所需的参数,此执行模式不可取消任务。 + +**系统能力:** SystemCapability.Utils.Lang + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ---------------------------- | +| func | Function | 是 | 执行的逻辑需要传入函数。 | +| args | unknown[] | 否 | 执行逻辑的函数所需要的参数。 | + +**返回值:** + +| 类型 | 说明 | +| ----------------- | ------------------------------------ | +| Promise\ | execute是异步方法,返回Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 + +| 错误码ID | 错误信息 | +| -------- | ----------------------------------------- | +| 10200003 | Worker initialization failure. | +| 10200006 | Serializing an uncaught exception failed. | +| 10200014 | The function is not mark as concurrent. | + +**示例:** + +```js +function func(args) { + "use concurrent" + console.log("func: " + args); + return args; +} + +let value = taskpool.execute(func, 100); +``` + +## taskpool.execute + +execute(task: Task, priority?: Priority): Promise\ + +任务池执行任务,需要传入已创建的任务,此执行模式可取消任务。 + +**系统能力:** SystemCapability.Utils.Lang + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ------------------------------------ | +| task | [Task](#task) | 是 | 需要在任务池中执行的任务。 | +| priority | [Priority](#priority) | 否 | 等待执行的任务的优先级(暂未支持)。 | + +**返回值:** + +| 类型 | 说明 | +| ---------------- | ------------------------------ | +| Promise\ | execute是异步方法,返回Promise对象。 | + +**错误码:** + +以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 + +| 错误码ID | 错误信息 | +| -------- | ----------------------------------------- | +| 10200003 | Worker initialization failure. | +| 10200006 | Serializing an uncaught exception failed. | +| 10200014 | The function is not mark as concurrent. | + +**示例:** + +```js +function func(args) { + "use concurrent" + console.log("func: " + args); + return args; +} +let task = new taskpool.Task(func, "this is my first Task"); +let value = taskpool.execute(task); +``` + +## taskpool.cancel + +cancel(task: Task): void + +取消任务池中的任务。 + +**系统能力:** SystemCapability.Utils.Lang + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------- | ---- | -------------------- | +| task | [Task](#task) | 是 | 需要取消执行的任务。 | + +**错误码:** + +以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------- | +| 10200015 | If the task is not exist. | +| 10200016 | If the task is running. | + +**示例:** + +```js +function func(args) { + "use concurrent" + console.log("func: " + args); + return args; +} +let task = new taskpool.Task(func, "this is first Task"); +let value = taskpool.execute(task); +taskpool.cancel(task); +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-utils.md b/zh-cn/application-dev/reference/errorcodes/errorcode-utils.md index 8423abf9d2543cd01fcbe33526bf47ad6cf5a71d..9dd0d2ccf0650a53e9cb60f9db1f538834b71590 100644 --- a/zh-cn/application-dev/reference/errorcodes/errorcode-utils.md +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-utils.md @@ -219,3 +219,57 @@ Buffer的属性${propertyName}只读,不能进行设置。 **处理步骤** 不要对Buffer只读属性进行相关设置。 + +## 10200014 非Concurrent函数错误 + +**错误信息** + +The function is not mark as concurrent. + +**错误描述** + +Function未被标记为concurrent。 + +**可能原因** + +任务池执行的任务所需的函数未添加@Concurrent。 + +**处理步骤** + +检查任务池执行的任务所需的函数,并补上@Concurrent装饰器。 + +## 10200015 取消不存在的任务错误 + +**错误信息** + +The task is not exist when cancel it. + +**错误描述** + +取消一个不存在的任务。 + +**可能原因** + +取消任务时,该任务并不存在于任务池中。 + +**处理步骤** + +取消任务前,确保任务已被taskpool.execute调用进入任务池。 + +## 10200016 取消已执行的任务错误 + +**错误信息** + +The task is running when cancel it. + +**错误描述** + +取消已经执行的任务。 + +**可能原因** + +取消任务时,该任务已经处于执行状态。 + +**处理步骤** + +取消任务前,确保任务已被执行完毕。 \ No newline at end of file