From 75e1170f452884e0677cba597ccce47773572f5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=91=9B=E4=BA=9A=E8=8A=B3?= Date: Sun, 30 Jul 2023 07:21:30 +0000 Subject: [PATCH] update zh-cn/application-dev/reference/apis/js-apis-taskpool.md. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 葛亚芳 --- .../reference/apis/js-apis-taskpool.md | 694 +++++++++--------- 1 file changed, 348 insertions(+), 346 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-taskpool.md b/zh-cn/application-dev/reference/apis/js-apis-taskpool.md index 4aea866b20..30d6b1677b 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-taskpool.md +++ b/zh-cn/application-dev/reference/apis/js-apis-taskpool.md @@ -16,18 +16,36 @@ ```ts import taskpool from '@ohos.taskpool'; ``` +## taskpool.execute -## Priority +execute(func: Function, ...args: unknown[]): Promise\ -表示所创建任务（Task）的优先级。 +将待执行的函数放入taskpool内部任务队列等待，等待分发到工作线程执行。当前执行模式不可取消任务。 -**系统能力：** SystemCapability.Utils.Lang +**系统能力：** SystemCapability.Utils.Lang -| 名称 | 值 | 说明 | -| -------- | -------- | -------- | -| HIGH | 0 | 任务为高优先级。 | -| MEDIUM | 1 | 任务为中优先级。 | -| LOW | 2 | 任务为低优先级。 | +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ---------------------------------------------------------------------- | +| func | Function | 是 | 执行的逻辑需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | +| args | unknown[] | 否 | 执行逻辑的函数所需要的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------------------ | +| Promise\ | execute是异步方法，返回Promise对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 10200003 | Worker initialization failure. | +| 10200006 | An exception occurred during serialization. | +| 10200014 | The function is not mark as concurrent. | **示例：** @@ -38,59 +56,41 @@ function printArgs(args) { return args; } -let task = new taskpool.Task(printArgs, 100); // 100: test number -let highCount = 0; -let mediumCount = 0; -let lowCount = 0; -let allCount = 100; -for (let i = 0; i < allCount; i++) { - taskpool.execute(task, taskpool.Priority.LOW).then((res: number) => { - lowCount++; - console.log("taskpool lowCount is :" + lowCount); - }).catch((e) => { - console.error("low task error: " + e); - }) - taskpool.execute(task, taskpool.Priority.MEDIUM).then((res: number) => { - mediumCount++; - console.log("taskpool mediumCount is :" + mediumCount); - }).catch((e) => { - console.error("medium task error: " + e); - }) - taskpool.execute(task, taskpool.Priority.HIGH).then((res: number) => { - highCount++; - console.log("taskpool highCount is :" + highCount); - }).catch((e) => { - console.error("high task error: " + e); - }) -} +taskpool.execute(printArgs, 100).then((value) => { // 100: test number + console.log("taskpool result: " + value); +}); ``` -## Task - -表示任务。使用以下方法前，需要先构造Task。 - -### constructor +## taskpool.execute -constructor(func: Function, ...args: unknown[]) +execute(task: Task, priority?: Priority): Promise\ -Task的构造函数。 +将创建好的任务放入taskpool内部任务队列等待，等待分发到工作线程执行。当前执行模式可尝试调用cancel进行任务取消。 **系统能力：** SystemCapability.Utils.Lang **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | -------------------------------------------------------------------- | -| func | Function | 是 | 任务执行需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | -| args | unknown[] | 否 | 任务执行传入函数的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ---------------------------------------- | +| task | [Task](#task) | 是 | 需要在任务池中执行的任务。 | +| priority | [Priority](#priority) | 否 | 等待执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ---------------- | +| Promise\ | 返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 -| 错误码ID | 错误信息 | -| -------- | --------------------------------------- | -| 10200014 | The function is not mark as concurrent. | +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------- | +| 10200003 | Worker initialization failure. | +| 10200006 | An exception occurred during serialization. | +| 10200014 | The function is not mark as concurrent. | **示例：** @@ -101,43 +101,100 @@ function printArgs(args) { return args; } -let task = new taskpool.Task(printArgs, "this is my first Task"); +let task = new taskpool.Task(printArgs, 100); // 100: test number +taskpool.execute(task).then((value) => { + console.log("taskpool result: " + value); +}); ``` -### isCanceled10+ +## taskpool.execute10+ -static isCanceled(): boolean +execute(group: TaskGroup, priority?: Priority): Promise -检查当前正在运行的任务是否已取消。 +将创建好的任务组放入taskpool内部任务队列等待，等待分发到工作线程执行。 **系统能力：** SystemCapability.Utils.Lang +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | --------------------------- | ---- | -------------------------------------------------------------- | +| group | [TaskGroup](#taskgroup) | 是 | 需要在任务池中执行的任务组。 | +| priority | [Priority](#priority) | 否 | 等待执行的任务组的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | + **返回值：** -| 类型 | 说明 | -| ------- | ------------------------------------ | -| boolean | 如果当前正在运行的任务被取消返回true，未被取消返回false。| +| 类型 | 说明 | +| ---------------- | ---------------------------------- | +| Promise\ | execute是异步方法，返回Promise对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------- | +| 10200006 | An exception occurred during serialization. | **示例：** ```ts @Concurrent -function inspectStatus(arg) { - // do something - if (taskpool.Task.isCanceled()) { - console.log("task has been canceled."); - // do something - return arg + 1; - } - // do something - return arg; +function printArgs(args) { + console.log("printArgs: " + args); + return args; } + +let taskGroup1 = 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 = new taskpool.TaskGroup(); +let task1 = new taskpool.Task(printArgs, 100); // 100: test number +let task2 = new taskpool.Task(printArgs, 200); // 200: test number +let task3 = new taskpool.Task(printArgs, 300); // 300: test number +taskGroup2.addTask(task1); +taskGroup2.addTask(task2); +taskGroup2.addTask(task3); +taskpool.execute(taskGroup1).then((res) => { + console.info("taskpool execute res is:" + res); +}).catch((e) => { + console.error("taskpool execute error is:" + e); +}); +taskpool.execute(taskGroup2).then((res) => { + console.info("taskpool execute res is:" + res); +}).catch((e) => { + console.error("taskpool execute error is:" + e); +}); ``` -> **说明：**
-> isCanceled方法需要和taskpool.cancel方法搭配使用，如果不调用cancel方法，isCanceled方法默认返回false。 +## taskpool.cancel -**示例：** +cancel(task: Task): void + +取消任务池中的任务。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------- | ---- | -------------------- | +| task | [Task](#task) | 是 | 需要取消执行的任务。 | + +**错误码：** + +以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 10200015 | The task does not exist when it is canceled. | +| 10200016 | The task is executing when it is canceled. | + +从API version10开始，此接口调用时不再涉及上报错误码10200016。 + +**正在执行的任务取消示例：** ```ts @Concurrent @@ -147,7 +204,7 @@ function inspectStatus(arg) { console.log("task has been canceled before 2s sleep."); return arg + 2; } - // 延时2s + // 2s sleep let t = Date.now(); while (Date.now() - t < 2000) { continue; @@ -157,110 +214,116 @@ function inspectStatus(arg) { console.log("task has been canceled after 2s sleep."); return arg + 3; } - return arg + 1; + return arg + 1; } -let task = new taskpool.Task(inspectStatus, 100); // 100: test number -taskpool.execute(task).then((res)=>{ +let task1 = new taskpool.Task(inspectStatus, 100); // 100: test number +let task2 = new taskpool.Task(inspectStatus, 200); // 200: test number +let task3 = new taskpool.Task(inspectStatus, 300); // 300: test number +let task4 = new taskpool.Task(inspectStatus, 400); // 400: test number +let task5 = new taskpool.Task(inspectStatus, 500); // 500: test number +let task6 = new taskpool.Task(inspectStatus, 600); // 600: test number +taskpool.execute(task1).then((res)=>{ console.log("taskpool test result: " + res); }).catch((err) => { console.log("taskpool test occur error: " + err); }); -// 不调用cancel，isCanceled()默认返回false，task执行的结果为101 +let res2 = taskpool.execute(task2); +let res3 = taskpool.execute(task3); +let res4 = taskpool.execute(task4); +let res5 = taskpool.execute(task5); +let res6 = taskpool.execute(task6); +// 1s后取消task +setTimeout(()=>{ + taskpool.cancel(task1);}, 1000); ``` -### setTransferList10+ - -setTransferList(transfer?: ArrayBuffer[]): void +## taskpool.cancel10+ -设置任务的传输列表。 +cancel(group: TaskGroup): void -> **说明：**
-> 此接口可以设置任务池中ArrayBuffer的transfer列表，transfer列表中的ArrayBuffer对象在传输时不会复制buffer内容到工作线程而是转移buffer控制权至工作线程，传输后当前的ArrayBuffer失效。 +取消任务池中的任务组。 **系统能力：** SystemCapability.Utils.Lang **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------- | ---- | --------------------------------------------- | -| transfer | ArrayBuffer[] | 否 | 可传输对象是ArrayBuffer的实例对象，默认为空数组。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------- | ---- | -------------------- | +| group | [TaskGroup](#taskgroup) | 是 | 需要取消执行的任务组。 | + +**错误码：** + +以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------- | +| 10200018 | The task group does not exist when it is canceled. | **示例：** ```ts -let buffer = new ArrayBuffer(8); -let view = new Uint8Array(buffer); -let buffer1 = new ArrayBuffer(16); -let view1 = new Uint8Array(buffer1); - -console.info("testTransfer view byteLength: " + view.byteLength); -console.info("testTransfer view1 byteLength: " + view1.byteLength); @Concurrent -function testTransfer(arg1, arg2) { - console.info("testTransfer arg1 byteLength: " + arg1.byteLength); - console.info("testTransfer arg2 byteLength: " + arg2.byteLength); - return 100; +function printArgs(args) { + let t = Date.now(); + while (Date.now() - t < 2000) { + continue; + } + console.log("printArgs: " + args); + return args; } -let task = new taskpool.Task(testTransfer, view, view1); -task.setTransferList([view.buffer, view1.buffer]); -taskpool.execute(task).then((res)=>{ - console.info("test result: " + res); -}).catch((e)=>{ - console.error("test catch: " + e); -}) -console.info("testTransfer view byteLength: " + view.byteLength); -console.info("testTransfer view1 byteLength: " + view1.byteLength); -``` -### 属性 +let taskGroup1 = new taskpool.TaskGroup(); +taskGroup1.addTask(printArgs, 10); // 10: test number +let taskGroup2 = new taskpool.TaskGroup(); +taskGroup2.addTask(printArgs, 100); // 100: test number +taskpool.execute(taskGroup1).then((res)=>{ + console.info("taskGroup1 res is:" + res) +}); +taskpool.execute(taskGroup2).then((res)=>{ + console.info("taskGroup2 res is:" + res) +}); +setTimeout(()=>{ + try { + taskpool.cancel(taskGroup2); + } catch (e) { + console.log("taskGroup.cancel occur error:" + e); + } +}, 1000); +``` -**系统能力：** SystemCapability.Utils.Lang -| 名称 | 类型 | 可读 | 可写 | 说明 | -| --------- | --------- | ---- | ---- | ------------------------------------------------------------------------- | -| function | Function | 是 | 是 | 创建任务时需要传入的函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | -| arguments | unknown[] | 是 | 是 | 创建任务传入函数所需的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。 | +## taskpool.getTaskPoolInfo10+ -## TaskGroup10+ -表示任务组。使用以下方法前，需要先构造TaskGroup。 +getTaskPoolInfo(): TaskPoolInfo -### constructor10+ +获取任务池内部信息。 -constructor() +**系统能力：** SystemCapability.Utils.Lang -TaskGroup的构造函数。 +**返回值：** -**系统能力：** SystemCapability.Utils.Lang +| 类型 | 说明 | +| ----------------------------------- | ------------------ | +| [TaskPoolInfo](#taskpoolinfo10) | 任务池的内部信息。 | **示例：** ```ts -let taskGroup = new taskpool.TaskGroup(); +let taskpoolInfo:TaskPoolInfo = taskpool.getTaskPoolInfo(); ``` -### addTask10+ - -addTask(func: Function, ...args: unknown[]): void - -将待执行的函数添加到任务组中。 - -**系统能力：** SystemCapability.Utils.Lang - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | ---------------------------------------------------------------------- | -| func | Function | 是 | 任务执行需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | -| args | unknown[] | 否 | 任务执行函数所需要的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | +## Priority -**错误码：** +表示所创建任务（Task）的优先级。 -以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 +**系统能力：** SystemCapability.Utils.Lang -| 错误码ID | 错误信息 | -| -------- | --------------------------------------- | -| 10200014 | The function is not mark as concurrent. | +| 名称 | 值 | 说明 | +| -------- | -------- | -------- | +| HIGH | 0 | 任务为高优先级。 | +| MEDIUM | 1 | 任务为中优先级。 | +| LOW | 2 | 任务为低优先级。 | **示例：** @@ -271,23 +334,51 @@ function printArgs(args) { return args; } -let taskGroup = new taskpool.TaskGroup(); -taskGroup.addTask(printArgs, 100); // 100: test number +let task = new taskpool.Task(printArgs, 100); // 100: test number +let highCount = 0; +let mediumCount = 0; +let lowCount = 0; +let allCount = 100; +for (let i = 0; i < allCount; i++) { + taskpool.execute(task, taskpool.Priority.LOW).then((res: number) => { + lowCount++; + console.log("taskpool lowCount is :" + lowCount); + }).catch((e) => { + console.error("low task error: " + e); + }) + taskpool.execute(task, taskpool.Priority.MEDIUM).then((res: number) => { + mediumCount++; + console.log("taskpool mediumCount is :" + mediumCount); + }).catch((e) => { + console.error("medium task error: " + e); + }) + taskpool.execute(task, taskpool.Priority.HIGH).then((res: number) => { + highCount++; + console.log("taskpool highCount is :" + highCount); + }).catch((e) => { + console.error("high task error: " + e); + }) +} ``` -### addTask10+ +## Task -addTask(task: Task): void +表示任务。使用以下方法前，需要先构造Task。 -将创建好的任务添加到任务组中。 +### constructor + +constructor(func: Function, ...args: unknown[]) + +Task的构造函数。 **系统能力：** SystemCapability.Utils.Lang **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ---- | ---------------------------------------- | -| task | [Task](#task) | 是 | 需要添加到任务组中的任务。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------------------------------------------------------- | +| func | Function | 是 | 任务执行需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | +| args | unknown[] | 否 | 任务执行传入函数的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | **错误码：** @@ -306,287 +397,217 @@ function printArgs(args) { return args; } -let taskGroup = new taskpool.TaskGroup(); -let task = new taskpool.Task(printArgs, 200); // 200: test number -taskGroup.addTask(task); +let task = new taskpool.Task(printArgs, "this is my first Task"); ``` -## taskpool.execute +### isCanceled10+ -execute(func: Function, ...args: unknown[]): Promise\ +static isCanceled(): boolean -将待执行的函数放入taskpool内部任务队列等待，等待分发到工作线程执行。当前执行模式不可取消任务。 +检查当前正在运行的任务是否已取消。 **系统能力：** SystemCapability.Utils.Lang -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | ---------------------------------------------------------------------- | -| func | Function | 是 | 执行的逻辑需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | -| args | unknown[] | 否 | 执行逻辑的函数所需要的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | - **返回值：** -| 类型 | 说明 | -| ----------------- | ------------------------------------ | -| Promise\ | execute是异步方法，返回Promise对象。 | +| 类型 | 说明 | +| ------- | ------------------------------------ | +| boolean | 如果当前正在运行的任务被取消返回true，未被取消返回false。| -**错误码：** +**示例：** -以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 +```ts +@Concurrent +function inspectStatus(arg) { + // do something + if (taskpool.Task.isCanceled()) { + console.log("task has been canceled."); + // do something + return arg + 1; + } + // do something + return arg; +} +``` -| 错误码ID | 错误信息 | -| -------- | -------------------------------------------- | -| 10200003 | Worker initialization failure. | -| 10200006 | An exception occurred during serialization. | -| 10200014 | The function is not mark as concurrent. | +> **说明：**
+> isCanceled方法需要和taskpool.cancel方法搭配使用，如果不调用cancel方法，isCanceled方法默认返回false。 **示例：** ```ts @Concurrent -function printArgs(args) { - console.log("printArgs: " + args); - return args; +function inspectStatus(arg) { + // 第一时间检查取消并回复 + if (taskpool.Task.isCanceled()) { + console.log("task has been canceled before 2s sleep."); + return arg + 2; + } + // 延时2s + let t = Date.now(); + while (Date.now() - t < 2000) { + continue; + } + // 第二次检查取消并作出响应 + if (taskpool.Task.isCanceled()) { + console.log("task has been canceled after 2s sleep."); + return arg + 3; + } + return arg + 1; } -taskpool.execute(printArgs, 100).then((value) => { // 100: test number - console.log("taskpool result: " + value); +let task = new taskpool.Task(inspectStatus, 100); // 100: test number +taskpool.execute(task).then((res)=>{ + console.log("taskpool test result: " + res); +}).catch((err) => { + console.log("taskpool test occur error: " + err); }); +// 不调用cancel，isCanceled()默认返回false，task执行的结果为101 ``` -## taskpool.execute +### setTransferList10+ -execute(task: Task, priority?: Priority): Promise\ +setTransferList(transfer?: ArrayBuffer[]): void -将创建好的任务放入taskpool内部任务队列等待，等待分发到工作线程执行。当前执行模式可尝试调用cancel进行任务取消。 +设置任务的传输列表。 + +> **说明：**
+> 此接口可以设置任务池中ArrayBuffer的transfer列表，transfer列表中的ArrayBuffer对象在传输时不会复制buffer内容到工作线程而是转移buffer控制权至工作线程，传输后当前的ArrayBuffer失效。 **系统能力：** SystemCapability.Utils.Lang **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ---- | ---------------------------------------- | -| task | [Task](#task) | 是 | 需要在任务池中执行的任务。 | -| priority | [Priority](#priority) | 否 | 等待执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | - -**返回值：** - -| 类型 | 说明 | -| ---------------- | ---------------- | -| Promise\ | 返回Promise对象。 | - -**错误码：** - -以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 - -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------- | -| 10200003 | Worker initialization failure. | -| 10200006 | An exception occurred during serialization. | -| 10200014 | The function is not mark as concurrent. | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------- | ---- | --------------------------------------------- | +| transfer | ArrayBuffer[] | 否 | 可传输对象是ArrayBuffer的实例对象，默认为空数组。 | **示例：** ```ts +let buffer = new ArrayBuffer(8); +let view = new Uint8Array(buffer); +let buffer1 = new ArrayBuffer(16); +let view1 = new Uint8Array(buffer1); + +console.info("testTransfer view byteLength: " + view.byteLength); +console.info("testTransfer view1 byteLength: " + view1.byteLength); @Concurrent -function printArgs(args) { - console.log("printArgs: " + args); - return args; +function testTransfer(arg1, arg2) { + console.info("testTransfer arg1 byteLength: " + arg1.byteLength); + console.info("testTransfer arg2 byteLength: " + arg2.byteLength); + return 100; } - -let task = new taskpool.Task(printArgs, 100); // 100: test number -taskpool.execute(task).then((value) => { - console.log("taskpool result: " + value); -}); +let task = new taskpool.Task(testTransfer, view, view1); +task.setTransferList([view.buffer, view1.buffer]); +taskpool.execute(task).then((res)=>{ + console.info("test result: " + res); +}).catch((e)=>{ + console.error("test catch: " + e); +}) +console.info("testTransfer view byteLength: " + view.byteLength); +console.info("testTransfer view1 byteLength: " + view1.byteLength); ``` -## taskpool.execute10+ - -execute(group: TaskGroup, priority?: Priority): Promise - -将创建好的任务组放入taskpool内部任务队列等待，等待分发到工作线程执行。 +### 属性 **系统能力：** SystemCapability.Utils.Lang -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| --------- | --------------------------- | ---- | -------------------------------------------------------------- | -| group | [TaskGroup](#taskgroup) | 是 | 需要在任务池中执行的任务组。 | -| priority | [Priority](#priority) | 否 | 等待执行的任务组的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | +| 名称 | 类型 | 可读 | 可写 | 说明 | +| --------- | --------- | ---- | ---- | ------------------------------------------------------------------------- | +| function | Function | 是 | 是 | 创建任务时需要传入的函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | +| arguments | unknown[] | 是 | 是 | 创建任务传入函数所需的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。 | -**返回值：** +## TaskGroup10+ +表示任务组。使用以下方法前，需要先构造TaskGroup。 -| 类型 | 说明 | -| ---------------- | ---------------------------------- | -| Promise\ | execute是异步方法，返回Promise对象。 | +### constructor10+ -**错误码：** +constructor() -以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 +TaskGroup的构造函数。 -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------- | -| 10200006 | An exception occurred during serialization. | +**系统能力：** SystemCapability.Utils.Lang **示例：** ```ts -@Concurrent -function printArgs(args) { - console.log("printArgs: " + args); - return args; -} - -let taskGroup1 = 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 = new taskpool.TaskGroup(); -let task1 = new taskpool.Task(printArgs, 100); // 100: test number -let task2 = new taskpool.Task(printArgs, 200); // 200: test number -let task3 = new taskpool.Task(printArgs, 300); // 300: test number -taskGroup2.addTask(task1); -taskGroup2.addTask(task2); -taskGroup2.addTask(task3); -taskpool.execute(taskGroup1).then((res) => { - console.info("taskpool execute res is:" + res); -}).catch((e) => { - console.error("taskpool execute error is:" + e); -}); -taskpool.execute(taskGroup2).then((res) => { - console.info("taskpool execute res is:" + res); -}).catch((e) => { - console.error("taskpool execute error is:" + e); -}); +let taskGroup = new taskpool.TaskGroup(); ``` -## taskpool.cancel +### addTask10+ -cancel(task: Task): void +addTask(func: Function, ...args: unknown[]): void -取消任务池中的任务。 +将待执行的函数添加到任务组中。 **系统能力：** SystemCapability.Utils.Lang **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------------- | ---- | -------------------- | -| task | [Task](#task) | 是 | 需要取消执行的任务。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ---------------------------------------------------------------------- | +| func | Function | 是 | 任务执行需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | +| args | unknown[] | 否 | 任务执行函数所需要的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | **错误码：** 以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 -| 错误码ID | 错误信息 | -| -------- | -------------------------------------------- | -| 10200015 | The task does not exist when it is canceled. | -| 10200016 | The task is executing when it is canceled. | - -从API version10开始，此接口调用时不再涉及上报错误码10200016。 +| 错误码ID | 错误信息 | +| -------- | --------------------------------------- | +| 10200014 | The function is not mark as concurrent. | -**正在执行的任务取消示例：** +**示例：** ```ts @Concurrent -function inspectStatus(arg) { - // 第一时间检查取消并回复 - if (taskpool.Task.isCanceled()) { - console.log("task has been canceled before 2s sleep."); - return arg + 2; - } - // 2s sleep - let t = Date.now(); - while (Date.now() - t < 2000) { - continue; - } - // 第二次检查取消并作出响应 - if (taskpool.Task.isCanceled()) { - console.log("task has been canceled after 2s sleep."); - return arg + 3; - } - return arg + 1; +function printArgs(args) { + console.log("printArgs: " + args); + return args; } -let task1 = new taskpool.Task(inspectStatus, 100); // 100: test number -let task2 = new taskpool.Task(inspectStatus, 200); // 200: test number -let task3 = new taskpool.Task(inspectStatus, 300); // 300: test number -let task4 = new taskpool.Task(inspectStatus, 400); // 400: test number -let task5 = new taskpool.Task(inspectStatus, 500); // 500: test number -let task6 = new taskpool.Task(inspectStatus, 600); // 600: test number -taskpool.execute(task1).then((res)=>{ - console.log("taskpool test result: " + res); -}).catch((err) => { - console.log("taskpool test occur error: " + err); -}); -let res2 = taskpool.execute(task2); -let res3 = taskpool.execute(task3); -let res4 = taskpool.execute(task4); -let res5 = taskpool.execute(task5); -let res6 = taskpool.execute(task6); -// 1s后取消task -setTimeout(()=>{ - taskpool.cancel(task1);}, 1000); +let taskGroup = new taskpool.TaskGroup(); +taskGroup.addTask(printArgs, 100); // 100: test number ``` -## taskpool.cancel10+ +### addTask10+ -cancel(group: TaskGroup): void +addTask(task: Task): void -取消任务池中的任务组。 +将创建好的任务添加到任务组中。 **系统能力：** SystemCapability.Utils.Lang **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ----------------------- | ---- | -------------------- | -| group | [TaskGroup](#taskgroup) | 是 | 需要取消执行的任务组。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ---------------------------------------- | +| task | [Task](#task) | 是 | 需要添加到任务组中的任务。 | **错误码：** 以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------------------- | -| 10200018 | The task group does not exist when it is canceled. | +| 错误码ID | 错误信息 | +| -------- | --------------------------------------- | +| 10200014 | The function is not mark as concurrent. | **示例：** ```ts @Concurrent function printArgs(args) { - let t = Date.now(); - while (Date.now() - t < 2000) { - continue; - } console.log("printArgs: " + args); return args; } -let taskGroup1 = new taskpool.TaskGroup(); -taskGroup1.addTask(printArgs, 10); // 10: test number -let taskGroup2 = new taskpool.TaskGroup(); -taskGroup2.addTask(printArgs, 100); // 100: test number -taskpool.execute(taskGroup1).then((res)=>{ - console.info("taskGroup1 res is:" + res) -}); -taskpool.execute(taskGroup2).then((res)=>{ - console.info("taskGroup2 res is:" + res) -}); -setTimeout(()=>{ - try { - taskpool.cancel(taskGroup2); - } catch (e) { - console.log("taskGroup.cancel occur error:" + e); - } -}, 1000); +let taskGroup = new taskpool.TaskGroup(); +let task = new taskpool.Task(printArgs, 200); // 200: test number +taskGroup.addTask(task); ``` + ## State10+ 表示任务（Task）状态的枚举。 @@ -647,25 +668,6 @@ setTimeout(()=>{ | threadInfos | [ThreadInfo[]](#threadinfo10) | 是 | 否 | 工作线程的内部信息。 | | taskInfos | [TaskInfo[]](#taskinfo10) | 是 | 否 | 任务的内部信息。 | -## taskpool.getTaskPoolInfo10+ - -getTaskPoolInfo(): TaskPoolInfo - -获取任务池内部信息。 - -**系统能力：** SystemCapability.Utils.Lang - -**返回值：** - -| 类型 | 说明 | -| ----------------------------------- | ------------------ | -| [TaskPoolInfo](#taskpoolinfo10) | 任务池的内部信息。 | - -**示例：** - -```ts -let taskpoolInfo:TaskPoolInfo = taskpool.getTaskPoolInfo(); -``` ## 其他说明 -- GitLab