Worker Thread Initialization

Import the worker module and instantiate a thread. For API version 9 and later, utilize ThreadWorker. Earlier versions rely on the deprecated Worker class.

import worker from '@ohos.worker';

// API 9+ instantiation
const backgroundTask: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/TaskProcessor.ets');
// API 8 instantiation (deprecated)
const legacyTask: worker.Worker = new worker.Worker('entry/ets/workers/LegacyProcessor.ets');

Stage Model Path Configuration

The scriptURL parameter in the constructor must follow specific routing rules based on the module type. The general format requires {moduleName}/ets followed by the relative path of the worker script.

Loading from an Ability

When referencing a worker file within an Ability, the path format is {moduleName}/ets/{relativePath}.

import worker from '@ohos.worker';

// Worker location: "entry/src/main/ets/workers/TaskProcessor.ets"
const mainWorker: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/TaskProcessor.ets');

// Worker location: "feature/src/main/ets/threads/TaskProcessor.ets"
const featureWorker: worker.ThreadWorker = new worker.ThreadWorker('feature/ets/threads/TaskProcessor.ets');

Loading from an HSP (Shared Package)

To load a worker from a Harmony Shared Package (HSP), apply the same {moduleName}/ets/{relativePath} convention.

import worker from '@ohos.worker';

// Worker location: "shared_module/src/main/ets/workers/TaskProcessor.ets"
const sharedPkgWorker: worker.ThreadWorker = new worker.ThreadWorker('shared_module/ets/workers/TaskProcessor.ets');

Loading from an HAR (Static Package)

Loading workers from a Harmony Archive (HAR) supports two distinct path formats:

• @ Notation: Used by any module type to reference a local HAR worker. Format: @{moduleName}/ets/{relativePath}.
• Relative Path: Used by a local HAR to reference its own internal worker. Format: Relative path from the caller file to the worker file.

If the HAR is distributed as a third-party package, only the relative path format is supported for worker creation.

import worker from '@ohos.worker';

// @ notation format
// Worker location: "static_module/src/main/ets/workers/TaskProcessor.ets"
const staticPkgWorker: worker.ThreadWorker = new worker.ThreadWorker('@static_module/ets/workers/TaskProcessor.ets');

// Relative path format
// Worker location: "static_module/src/main/ets/workers/TaskProcessor.ets"
// Caller location: "static_module/src/main/ets/pages/Index.ets"
const relativeStaticWorker: worker.ThreadWorker = new worker.ThreadWorker('../workers/TaskProcessor.ets');

FA Model Path Configuration

In the Feature Ability (FA) model, the scriptURL is resolved as a relative path from the worker file to the {moduleName}/src/main/ets/MainAbility directory.

import worker from '@ohos.worker';

// Worker location: "{moduleName}/src/main/ets/MainAbility/workers/TaskProcessor.ets"
const directPathWorker: worker.ThreadWorker = new worker.ThreadWorker("workers/TaskProcessor.ets");

// Worker location: "{moduleName}/src/main/ets/workers/TaskProcessor.ets"
const parentDirWorker: worker.ThreadWorker = new worker.ThreadWorker("../workers/TaskProcessor.ets");

// Worker location: "{moduleName}/src/main/ets/MainAbility/threads/TaskProcessor.ets"
const nestedDirWorker: worker.ThreadWorker = new worker.ThreadWorker("threads/TaskProcessor.ets");

Lifecycle Management Constraints

• Creating and destroying worker threads consumes significant resources. Reuse existing instances rather than spawning new ones for transient tasks.
• Idle workers remain active in memory. Explicitly terminate them via terminate() or parentPort.close() when no longer required to prevent resource leaks.
• Invoking interfaces on a worker that is destroyed or undergoing destruction will result in an exception.
• The system enforces a strict concurrency limit of 8 simultaneous worker threads per process. Exceeding this threshold triggers the error: Worker initialization failure, the number of workers exceeds the maximum.