1# @ohos.taskpool（启动任务池） 2 3任务池（taskpool）作用是为应用程序提供一个多线程的运行环境，降低整体资源的消耗、提高系统的整体性能，且您无需关心线程实例的生命周期。您可以使用任务池API创建后台任务（Task），并对所创建的任务进行如任务执行、任务取消的操作。理论上您可以使用任务池API创建数量不受限制的任务，但是出于内存因素不建议您这样做。此外，不建议您在任务中执行阻塞操作，特别是无限期阻塞操作，长时间的阻塞操作占据工作线程，可能会阻塞其他任务调度，影响您的应用性能。 4 5您所创建的同一优先级任务的执行顺序可以由您决定，任务真实执行的顺序与您调用任务池API提供的任务执行接口顺序一致。任务默认优先级是MEDIUM。（任务优先级机制暂未支持） 6 7当同一时间待执行的任务数量大于任务池工作线程数量，任务池会根据负载均衡机制进行扩容，增加工作线程数量，减少整体等待时长。同样，当执行的任务数量减少，工作线程数量大于执行任务数量，部分工作线程处于空闲状态，任务池会根据负载均衡机制进行缩容，减少工作线程数量。（负载均衡机制暂未支持） 8 9任务池API以数字形式返回错误码。有关各个错误码的更多信息，请参阅文档[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 10 11> **说明：**<br/> 12> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 13 14## 导入模块 15 16```ts 17import taskpool from '@ohos.taskpool'; 18``` 19 20## taskpool.execute 21 22execute(func: Function, ...args: unknown[]): Promise\<unknown> 23 24将待执行的函数放入taskpool内部任务队列等待，等待分发到工作线程执行。当前执行模式不可取消任务。 25 26**系统能力：** SystemCapability.Utils.Lang 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| ------ | --------- | ---- | ---------------------------------------------------------------------- | 32| func | Function | 是 | 执行的逻辑需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 33| args | unknown[] | 否 | 执行逻辑的函数所需要的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 34 35**返回值：** 36 37| 类型 | 说明 | 38| ----------------- | ------------------------------------ | 39| Promise\<unknown> | execute是异步方法，返回Promise对象。 | 40 41**错误码：** 42 43以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 44 45| 错误码ID | 错误信息 | 46| -------- | ----------------------------------------- | 47| 10200003 | Worker initialization failure. | 48| 10200006 | Serializing an uncaught exception failed. | 49| 10200014 | The function is not mark as concurrent. | 50 51**示例：** 52 53```ts 54@Concurrent 55function printArgs(args) { 56 console.log("printArgs: " + args); 57 return args; 58} 59 60async function taskpoolExecute() { 61 let value = await taskpool.execute(printArgs, 100); 62 console.log("taskpool result: " + value); 63} 64 65taskpoolExecute(); 66``` 67 68## taskpool.execute 69 70execute(task: Task, priority?: Priority): Promise\<unknown> 71 72将创建好的任务放入taskpool内部任务队列等待，等待分发到工作线程执行。当前执行模式可尝试调用cancel进行任务取消。 73 74**系统能力：** SystemCapability.Utils.Lang 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| -------- | --------------------- | ---- | ------------------------------------ | 80| task | [Task](#task) | 是 | 需要在任务池中执行的任务。 | 81| priority | [Priority](#priority) | 否 | 等待执行的任务的优先级（暂未支持）。 | 82 83**返回值：** 84 85| 类型 | 说明 | 86| ---------------- | ------------------------------ | 87| Promise\<unknown> | execute是异步方法，返回Promise对象。 | 88 89**错误码：** 90 91以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 92 93| 错误码ID | 错误信息 | 94| -------- | ----------------------------------------- | 95| 10200003 | Worker initialization failure. | 96| 10200006 | Serializing an uncaught exception failed. | 97| 10200014 | The function is not mark as concurrent. | 98 99**示例：** 100 101```ts 102@Concurrent 103function printArgs(args) { 104 console.log("printArgs: " + args); 105 return args; 106} 107 108async function taskpoolExecute() { 109 let task = new taskpool.Task(printArgs, 100); 110 let value = await taskpool.execute(task); 111 console.log("taskpool result: " + value); 112} 113 114taskpoolExecute(); 115``` 116 117## taskpool.cancel 118 119cancel(task: Task): void 120 121取消任务池中的任务。 122 123**系统能力：** SystemCapability.Utils.Lang 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| ------ | ------------- | ---- | -------------------- | 129| task | [Task](#task) | 是 | 需要取消执行的任务。 | 130 131**错误码：** 132 133以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 134 135| 错误码ID | 错误信息 | 136| -------- | ------------------------- | 137| 10200015 | If the task is not exist. | 138| 10200016 | If the task is running. | 139 140**任务取消成功示例：** 141 142```ts 143@Concurrent 144function printArgs(args) { 145 console.log("printArgs: " + args); 146 return args; 147} 148 149async function taskpoolCancel() { 150 let task = new taskpool.Task(printArgs, 100); 151 taskpool.execute(task); 152 try { 153 taskpool.cancel(task); 154 } catch (e) { 155 console.log("taskpool.cancel occur error:" + e); 156 } 157} 158 159taskpoolCancel(); 160``` 161 162**已执行的任务取消失败示例：** 163 164```ts 165@Concurrent 166function printArgs(args) { 167 console.log("printArgs: " + args); 168 return args; 169} 170 171async function taskpoolCancel() { 172 let task = new taskpool.Task(printArgs, 100); 173 let value = taskpool.execute(task); 174 let start = new Date().getTime(); 175 while (new Date().getTime() - start < 1000) { // 延时1s，确保任务已执行 176 continue; 177 } 178 179 try { 180 taskpool.cancel(task); //任务已执行,取消失败 181 } catch (e) { 182 console.log("taskpool.cancel occur error:" + e); 183 } 184} 185 186taskpoolCancel(); 187``` 188 189**正在执行的任务取消失败示例：** 190 191```ts 192@Concurrent 193function printArgs(args) { 194 console.log("printArgs: " + args); 195 return args; 196} 197 198async function taskpoolCancel() { 199 let task1 = new taskpool.Task(printArgs, 100); 200 let task2 = new taskpool.Task(printArgs, 200); 201 let task3 = new taskpool.Task(printArgs, 300); 202 let task4 = new taskpool.Task(printArgs, 400); 203 let task5 = new taskpool.Task(printArgs, 500); 204 let task6 = new taskpool.Task(printArgs, 600); 205 206 let res1 = taskpool.execute(task1); 207 let res2 = taskpool.execute(task2); 208 let res3 = taskpool.execute(task3); 209 let res4 = taskpool.execute(task4); 210 let res5 = taskpool.execute(task5); 211 let res6 = taskpool.execute(task6); 212 try { 213 taskpool.cancel(task1); // task1任务正在执行，取消失败 214 } catch (e) { 215 console.log("taskpool.cancel occur error:" + e); 216 } 217} 218 219taskpoolCancel(); 220``` 221 222## Priority 223 224表示所创建任务（Task）的优先级。（暂未支持） 225 226**系统能力：** SystemCapability.Utils.Lang 227 228| 名称 | 值 | 说明 | 229| -------- | -------- | -------- | 230| HIGH | 0 | 任务为高优先级。 | 231| MEDIUM | 1 | 任务为中优先级。 | 232| LOW | 2 | 任务为低优先级。 | 233 234## Task 235 236表示任务。使用以下方法前，需要先构造Task。 237 238### constructor 239 240constructor(func: Function, ...args: unknown[]) 241 242Task的构造函数。 243 244**系统能力：** SystemCapability.Utils.Lang 245 246**参数：** 247 248| 参数名 | 类型 | 必填 | 说明 | 249| ------ | --------- | ---- | -------------------------------------------------------------------- | 250| func | Function | 是 | 任务执行需要传入函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 251| args | unknown[] | 否 | 任务执行传入函数的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。默认值为undefined。 | 252 253**错误码：** 254 255以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 256 257| 错误码ID | 错误信息 | 258| -------- | --------------------------------------- | 259| 10200014 | The function is not mark as concurrent. | 260 261**示例：** 262 263```ts 264@Concurrent 265function printArgs(args) { 266 console.log("printArgs: " + args); 267 return args; 268} 269 270let task = new taskpool.Task(printArgs, "this is my first Task"); 271``` 272 273### 属性 274 275**系统能力：** SystemCapability.Utils.Lang 276 277| 名称 | 类型 | 可读 | 可写 | 说明 | 278| --------- | --------- | ---- | ---- | ------------------------------------------------------------------------- | 279| function | Function | 是 | 是 | 创建任务时需要传入的函数，支持的函数返回值类型请查[序列化支持类型](#序列化支持类型)。 | 280| arguments | unknown[] | 是 | 是 | 创建任务传入函数所需的参数，支持的参数类型请查[序列化支持类型](#序列化支持类型)。 | 281 282## 其他说明 283 284### 序列化支持类型 285序列化支持类型包括：All Primitive Type(不包括symbol)、Date、String、RegExp、Array、Map、Set、Object、ArrayBuffer、TypedArray。 286 287### 注意事项 288- 仅支持在Stage模型且module的compileMode为esmodule的project中使用taskpool api。确认module的compileMode方法：查看当前module的build-profile.json5，在buildOption中补充"compileMode": "esmodule"。 289- taskpool任务只支持引用入参传递或者import的变量，不支持使用闭包变量，使用装饰器@Concurrent进行拦截。 290- taskpool任务只支持普通函数或者async函数，不支持类成员函数或者匿名函数，使用装饰器@Concurrent进行拦截。 291- 装饰器@Concurrent仅支持在ets文件使用。 292 293### 简单使用 294 295**示例一** 296 297```ts 298// 支持普通函数、引用入参传递 299@Concurrent 300function printArgs(args) { 301 console.log("printArgs: " + args); 302 return args; 303} 304 305async function taskpoolExecute() { 306 // taskpool.execute(task) 307 let task = new taskpool.Task(printArgs, "create task, then execute"); 308 let val1 = await taskpool.execute(task); 309 console.log("taskpool.execute(task) result: " + val1); 310 311 // taskpool.execute(function) 312 let val2 = await taskpool.execute(func, "execute task by func"); 313 console.log("taskpool.execute(function) result: " + val2); 314} 315 316taskpoolExecute(); 317``` 318 319**示例二** 320 321```ts 322// b.ets 323export var c = 2000; 324``` 325```ts 326// 引用import变量 327// a.ets(与b.ets位于同一目录中) 328import { c } from "./b"; 329 330@Concurrent 331function printArgs(a) { 332 console.log(a); 333 console.log(c); 334 return a; 335} 336 337async function taskpoolExecute() { 338 // taskpool.execute(task) 339 let task = new taskpool.Task(printArgs, "create task, then execute"); 340 let val1 = await taskpool.execute(task); 341 console.log("taskpool.execute(task) result: " + val1); 342 343 // taskpool.execute(function) 344 let val2 = await taskpool.execute(printArgs, "execute task by func"); 345 console.log("taskpool.execute(function) result: " + val2); 346} 347 348taskpoolExecute(); 349``` 350 351**示例三** 352 353```ts 354// 支持async函数 355@Concurrent 356async function delayExcute() { 357 let ret = await Promise.all([ 358 new Promise(resolve => setTimeout(resolve, 1000, "resolved")) 359 ]); 360 return ret; 361} 362 363async function taskpoolExecute() { 364 taskpool.execute(delayExcute).then((result) => { 365 console.log("TaskPoolTest task result: " + result); 366 }); 367} 368 369taskpoolExecute(); 370``` 371 372**示例四** 373 374```ts 375// c.ets 376@Concurrent 377function strSort(inPutArr) { 378 let newArr = inPutArr.sort(); 379 return newArr; 380} 381export async function func1() { 382 console.log("taskpoolTest start"); 383 let strArray = ['c test string', 'b test string', 'a test string']; 384 var task = new taskpool.Task(strSort, strArray); 385 var result = await taskpool.execute(task); 386 console.log("func1 result:" + result); 387} 388 389export async function func2() { 390 console.log("taskpoolTest2 start"); 391 let strArray = ['c test string', 'b test string', 'a test string']; 392 taskpool.execute(strSort, strArray).then((result) => { 393 console.log("func2 result: " + result); 394 }); 395} 396``` 397 398```ts 399// a.ets(与c.ets在同一目录中) 400import { taskpoolTest1, taskpoolTest2 } from "./c"; 401 402func1(); 403func2(); 404```