OpenHarmony語(yǔ)言基礎類(lèi)庫【@ohos.taskpool（啟動(dòng)任務(wù)池）】

任務(wù)池（taskpool）作用是為應用程序提供一個(gè)多線(xiàn)程的運行環(huán)境，降低整體資源的消耗、提高系統的整體性能，且您無(wú)需關(guān)心線(xiàn)程實(shí)例的生命周期。您可以使用任務(wù)池API創(chuàng )建后臺任務(wù)（Task），并對所創(chuàng )建的任務(wù)進(jìn)行如任務(wù)執行、任務(wù)取消的操作。理論上您可以使用任務(wù)池API創(chuàng )建數量不受限制的任務(wù)，但是出于內存因素不建議您這樣做。此外，不建議您在任務(wù)中執行阻塞操作，特別是無(wú)限期阻塞操作，長(cháng)時(shí)間的阻塞操作占據工作線(xiàn)程，可能會(huì )阻塞其他任務(wù)調度，影響您的應用性能。

您所創(chuàng )建的同一優(yōu)先級任務(wù)的執行順序可以由您決定，任務(wù)真實(shí)執行的順序與您調用任務(wù)池API提供的任務(wù)執行接口順序一致。任務(wù)默認優(yōu)先級是MEDIUM。（任務(wù)優(yōu)先級機制暫未支持）

當同一時(shí)間待執行的任務(wù)數量大于任務(wù)池工作線(xiàn)程數量，任務(wù)池會(huì )根據負載均衡機制進(jìn)行擴容，增加工作線(xiàn)程數量，減少整體等待時(shí)長(cháng)。同樣，當執行的任務(wù)數量減少，工作線(xiàn)程數量大于執行任務(wù)數量，部分工作線(xiàn)程處于空閑狀態(tài)，任務(wù)池會(huì )根據負載均衡機制進(jìn)行縮容，減少工作線(xiàn)程數量。（負載均衡機制暫未支持）

任務(wù)池API以數字形式返回錯誤碼。有關(guān)各個(gè)錯誤碼的更多信息，請參閱文檔 鴻蒙開(kāi)發(fā)指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

說(shuō)明：
本模塊首批接口從API version 9 開(kāi)始支持。后續版本的新增接口，采用上角標單獨標記接口的起始版本。

導入模塊

HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿
import taskpool from '@ohos.taskpool';

taskpool.execute

execute(func: Function, ...args: unknown[]): Promise

將待執行的函數放入taskpool內部任務(wù)隊列等待，等待分發(fā)到工作線(xiàn)程執行。當前執行模式不可取消任務(wù)。

系統能力： SystemCapability.Utils.Lang

參數：

返回值：

錯誤碼：

以下錯誤碼的詳細介紹請參見(jiàn)[語(yǔ)言基礎類(lèi)庫錯誤碼]。

示例：

@Concurrent
function printArgs(args) {
    console.log("printArgs: " + args);
    return args;
}

async function taskpoolExecute() {
  let value = await taskpool.execute(printArgs, 100);
  console.log("taskpool result: " + value);
}

taskpoolExecute();

[](https://gitee.com/openharmony/docs/blob/OpenHarmony-3.2-Release/zh-cn/application-dev/reference/apis/js-apis-taskpool.md#taskpoolexecute-1)taskpool.execute

execute(task: Task, priority?: Priority): Promise

將創(chuàng )建好的任務(wù)放入taskpool內部任務(wù)隊列等待，等待分發(fā)到工作線(xiàn)程執行。當前執行模式可嘗試調用cancel進(jìn)行任務(wù)取消。

系統能力： SystemCapability.Utils.Lang

參數：

返回值：

錯誤碼：

以下錯誤碼的詳細介紹請參見(jiàn)[語(yǔ)言基礎類(lèi)庫錯誤碼]。

示例：

@Concurrent
function printArgs(args) {
    console.log("printArgs: " + args);
    return args;
}

async function taskpoolExecute() {
  let task = new taskpool.Task(printArgs, 100);
  let value = await taskpool.execute(task);
  console.log("taskpool result: " + value);
}

taskpoolExecute();

[](https://gitee.com/openharmony/docs/blob/OpenHarmony-3.2-Release/zh-cn/application-dev/reference/apis/js-apis-taskpool.md#taskpoolcancel)taskpool.cancel

cancel(task: Task): void

取消任務(wù)池中的任務(wù)。

系統能力： SystemCapability.Utils.Lang

參數：

錯誤碼：

以下錯誤碼的詳細介紹請參見(jiàn)[語(yǔ)言基礎類(lèi)庫錯誤碼]。

任務(wù)取消成功示例：

@Concurrent
function printArgs(args) {
    console.log("printArgs: " + args);
    return args;
}

async function taskpoolCancel() {
  let task = new taskpool.Task(printArgs, 100);
  taskpool.execute(task);
  try {
    taskpool.cancel(task);
  } catch (e) {
    console.log("taskpool.cancel occur error:" + e);
  }
}

taskpoolCancel();

已執行的任務(wù)取消失敗示例：

@Concurrent
function printArgs(args) {
    console.log("printArgs: " + args);
    return args;
}

async function taskpoolCancel() {
  let task = new taskpool.Task(printArgs, 100);
  let value = taskpool.execute(task);
  let start = new Date().getTime();
  while (new Date().getTime() - start < 1000) { // 延時(shí)1s，確保任務(wù)已執行
    continue;
  }

  try {
    taskpool.cancel(task); //任務(wù)已執行,取消失敗
  } catch (e) {
    console.log("taskpool.cancel occur error:" + e);
  }
}

taskpoolCancel();

正在執行的任務(wù)取消失敗示例：

@Concurrent
function printArgs(args) {
    console.log("printArgs: " + args);
    return args;
}

async function taskpoolCancel() {
  let task1 = new taskpool.Task(printArgs, 100);
  let task2 = new taskpool.Task(printArgs, 200);
  let task3 = new taskpool.Task(printArgs, 300);
  let task4 = new taskpool.Task(printArgs, 400);
  let task5 = new taskpool.Task(printArgs, 500);
  let task6 = new taskpool.Task(printArgs, 600);

  let res1 = taskpool.execute(task1);
  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);
  try {
    taskpool.cancel(task1); // task1任務(wù)正在執行，取消失敗
  } catch (e) {
    console.log("taskpool.cancel occur error:" + e);
  }
}

taskpoolCancel();

Priority

表示所創(chuàng )建任務(wù)（Task）的優(yōu)先級。（暫未支持）

系統能力： SystemCapability.Utils.Lang

Task

表示任務(wù)。使用以下方法前，需要先構造Task。

constructor

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

Task的構造函數。

系統能力： SystemCapability.Utils.Lang

參數：

錯誤碼：

以下錯誤碼的詳細介紹請參見(jiàn)[語(yǔ)言基礎類(lèi)庫錯誤碼]。

示例：

@Concurrent
function printArgs(args) {
    console.log("printArgs: " + args);
    return args;
}

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

屬性

系統能力： SystemCapability.Utils.Lang

其他說(shuō)明

序列化支持類(lèi)型

序列化支持類(lèi)型包括：All Primitive Type(不包括symbol)、Date、String、RegExp、Array、Map、Set、Object、ArrayBuffer、TypedArray。

注意事項

• 僅支持在Stage模型且module的compileMode為esmodule的project中使用taskpool api。確認module的compileMode方法：查看當前module的build-profile.json5，在buildOption中補充"compileMode": "esmodule"。
• taskpool任務(wù)只支持引用入參傳遞或者import的變量，不支持使用閉包變量，使用裝飾器@Concurrent進(jìn)行攔截。
• taskpool任務(wù)只支持普通函數或者async函數，不支持類(lèi)成員函數或者匿名函數，使用裝飾器@Concurrent進(jìn)行攔截。
• 裝飾器@Concurrent僅支持在ets文件使用。

簡(jiǎn)單使用

示例一

// 支持普通函數、引用入參傳遞
@Concurrent
function printArgs(args) {
    console.log("printArgs: " + args);
    return args;
}

async function taskpoolExecute() {
  // taskpool.execute(task)
  let task = new taskpool.Task(printArgs, "create task, then execute");
  let val1 = await taskpool.execute(task);
  console.log("taskpool.execute(task) result: " + val1);

  // taskpool.execute(function)
  let val2 = await taskpool.execute(func, "execute task by func");
  console.log("taskpool.execute(function) result: " + val2);
}

taskpoolExecute();

示例二

// b.ets
export let c = 2000;

// 引用import變量
// a.ets(與b.ets位于同一目錄中)
import { c } from "./b";

@Concurrent
function printArgs(a) {
    console.log(a);
    console.log(c);
    return a;
}

async function taskpoolExecute() {
  // taskpool.execute(task)
  let task = new taskpool.Task(printArgs, "create task, then execute");
  let val1 = await taskpool.execute(task);
  console.log("taskpool.execute(task) result: " + val1);

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

taskpoolExecute();

示例三

// 支持async函數
@Concurrent
async function delayExcute() {
  let ret = await Promise.all([
    new Promise(resolve = > setTimeout(resolve, 1000, "resolved"))
  ]);
  return ret;
}

async function taskpoolExecute() {
  taskpool.execute(delayExcute).then((result) = > {
    console.log("TaskPoolTest task result: " + result);
  });
}

taskpoolExecute();

示例四

// c.ets
@Concurrent
function strSort(inPutArr) {
  let newArr = inPutArr.sort();
  return newArr;
}
export async function func1() {
    console.log("taskpoolTest start");
    let strArray = ['c test string', 'b test string', 'a test string'];
    let task = new taskpool.Task(strSort, strArray);
    let result = await taskpool.execute(task);
    console.log("func1 result:" + result);
}

export async function func2() {
    console.log("taskpoolTest2 start");
    let strArray = ['c test string', 'b test string', 'a test string'];
    taskpool.execute(strSort, strArray).then((result) = > {
        console.log("func2 result: " + result);
    });
}

// a.ets(與c.ets在同一目錄中)
import { taskpoolTest1, taskpoolTest2 } from "./c";

func1();
func2();

審核編輯 黃宇