OpenHarmony語言基礎(chǔ)類庫【@ohos.taskpool（啟動任務(wù)池）】

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

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

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

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

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

導(dǎo)入模塊

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

taskpool.execute

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

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

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

返回值：

錯誤碼：

以下錯誤碼的詳細(xì)介紹請參見[語言基礎(chǔ)類庫錯誤碼]。

示例：

@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內(nèi)部任務(wù)隊列等待，等待分發(fā)到工作線程執(zhí)行。當(dāng)前執(zhí)行模式可嘗試調(diào)用cancel進(jìn)行任務(wù)取消。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

返回值：

錯誤碼：

以下錯誤碼的詳細(xì)介紹請參見[語言基礎(chǔ)類庫錯誤碼]。

示例：

@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ù)。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細(xì)介紹請參見[語言基礎(chǔ)類庫錯誤碼]。

任務(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();

已執(zhí)行的任務(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) { // 延時1s，確保任務(wù)已執(zhí)行
    continue;
  }

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

taskpoolCancel();

正在執(zhí)行的任務(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ù)正在執(zhí)行，取消失敗
  } catch (e) {
    console.log("taskpool.cancel occur error:" + e);
  }
}

taskpoolCancel();

Priority

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

系統(tǒng)能力： SystemCapability.Utils.Lang

Task

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

constructor

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

Task的構(gòu)造函數(shù)。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細(xì)介紹請參見[語言基礎(chǔ)類庫錯誤碼]。

示例：

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

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

屬性

系統(tǒng)能力： SystemCapability.Utils.Lang

其他說明

序列化支持類型

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

注意事項

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

簡單使用

示例一

// 支持普通函數(shù)、引用入?yún)鬟f
@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函數(shù)
@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();

審核編輯 黃宇