@ohos.taskpool (Using the Task Pool)

The task pool provides a multi-thread running environment for applications. It helps reduce resource consumption and improve system performance. It also frees you from caring about the lifecycle of thread instances. You can use the TaskPool APIs to create background tasks and perform operations on them, for example, executing or canceling a task. Theoretically, you can create an unlimited number of tasks, but this is not recommended for memory considerations. In addition, you are not advised performing blocking operations in a task, especially indefinite blocking. Long-time blocking operations occupy worker threads and may block other task scheduling, adversely affecting your application performance.

You can determine the execution sequence of tasks with the same priority. They are executed in the same sequence as you call the task execution APIs. The default task priority is MEDIUM. (The task priority mechanism is not supported yet.)

If the number of tasks to be executed is greater than the number of worker threads in the task pool, the task pool scales out based on load balancing to minimize the waiting duration. Similarly, when the number of tasks to be executed falls below the number of worker threads, the task pool scales in to reduce the number of worker threads. (The load balancing mechanism is not supported yet.)

The TaskPool APIs return error codes in numeric format. For details about the error codes, see Utils Error Codes.

NOTE
The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import taskpool from '@ohos.taskpool';

Priority

Enumerates the priorities available for created tasks. (This enum is not supported yet.)

System capability: SystemCapability.Utils.Lang

Task

Implements a task. Before using any of the following APIs, you must create a Task instance.

constructor

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

A constructor used to create a Task instance.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

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

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

Attributes

System capability: SystemCapability.Utils.Lang

taskpool.execute

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

Executes a task in the task pool. You must pass in a function and arguments to execute the task, and the task executed in this mode cannot be canceled.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Utils Error Codes.

Example

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

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

taskpoolTest();

taskpool.execute

execute(task: Task, priority?: Priority): Promise<unknown>

Executes a task in the task pool. You must pass in a created task, and the task executed in this mode can be canceled.

System capability: SystemCapability.Utils.Lang

Parameters

Return value

Error codes

For details about the error codes, see Utils Error Codes.

Example

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

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

taskpoolTest();

taskpool.cancel

cancel(task: Task): void

Cancels a task in the task pool.

System capability: SystemCapability.Utils.Lang

Parameters

Error codes

For details about the error codes, see Utils Error Codes.

Example

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

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

taskpoolTest();

Additional Information

Sequenceable Data Types

The following sequenceable data types are supported: All Primitive Type (excluding symbol), Date, String, RegExp, Array, Map, Set, Object, ArrayBuffer, and TypedArray.

Precautions

• The task pool APIs can be used only in the module with compileMode set to esmodule in the stage model. To check the compileMode setting of a module, open the build-profile.json5 file of the module and check for "compileMode": "esmodule" under buildOption.
• A task in the task pool can reference only variables passed in by input parameters or imported variables, rather than closure variables. The decorator @Concurrent is used to intercept unsupported variables.
• A task in the task pool supports only common functions or async functions, rather than class member functions or anonymous functions. The decorator @Concurrent is used to intercept unsupported functions.
• The decorator @Concurrent can be used only in the .ets file. To create a task in the task pool in the .ts file, use the statement use concurrent.

Using the Task Pool in Simple Mode

Example 1

// Common functions are supported, and variables passed in by input parameters are also supported.
@Concurrent
function func(args) {
    console.log("func: " + args);
    return args;
}

async function taskpoolTest() {
  // taskpool.execute(task)
  let task = new taskpool.Task(func, "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);
}

taskpoolTest();

Example 2

// b.ets
export var c = 2000;

// Reference an imported variable.
// a.ets (in the same directory as b.ets)
import { c } from "./b";

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

async function taskpoolTest() {
  // taskpool.execute(task)
  let task = new taskpool.Task(test, "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(test, "execute task by func");
  console.log("taskpool.execute(function) result: " + val2);
}

taskpoolTest();

Example 3

// The async functions are supported.
@Concurrent
async function task() {
  let ret = await Promise.all([
    new Promise(resolve => setTimeout(resolve, 1000, "resolved"))
  ]);
  return ret;
}

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

taskpoolTest();

Example 4

// Use use concurrent to create a task in the task pool in the .ts file.
// c.ts
function test1(n) {
    "use concurrent"
    return n;
}
export async function taskpoolTest1() {
    console.log("taskpoolTest1 start");
    var task = new taskpool.Task(test1, 100);
    var result = await taskpool.execute(task);
    console.log("taskpoolTest1 result:" + result);
}

async function test2() {
    "use concurrent"
    var ret = await Promise.all([
        new Promise(resolve => setTimeout(resolve, 1000, "resolved"))
    ]);
    return ret;
}
export async function taskpoolTest2() {
    console.log("taskpoolTest2 start");
    taskpool.execute(test2).then((result) => {
        console.log("TaskPoolTest2 result: " + result);
    });
}

/ / a.ets (in the same directory as c.ts)
import { taskpoolTest1, taskpoolTest2 } from "./c";

taskpoolTest1();
taskpoolTest2();