跳到主要内容

Worker

Worker的主要作用是为应用程序提供一个多线程的运行环境，实现应用程序执行过程与宿主线程分离。通过在后台线程运行脚本处理耗时操作，避免计算密集型或高延迟任务阻塞宿主线程。

Worker运作机制​

图1 Worker运作机制示意图

worker

创建Worker的线程称为宿主线程（不局限于主线程，Worker线程也支持创建Worker子线程）。Worker子线程（或Actor线程、工作线程）是Worker自身运行的线程。每个Worker子线程和宿主线程拥有独立的实例，包含独立执行环境、对象、代码段等。因此，启动每个Worker存在一定的内存开销，需要限制Worker子线程的数量。Worker子线程和宿主线程通过消息传递机制通信，利用序列化、引用传递或转移所有权的机制完成命令和数据的交互。

Worker注意事项​

  • 创建Worker时，提供手动和自动两种创建方式，推荐使用自动创建方式。手动创建Worker线程目录及文件时，需同步进行相关配置，具体要求请参阅创建Worker的注意事项。
  • 使用Worker能力时，构造函数中传入的Worker线程文件的路径在不同版本有不同的规则，详情请参见文件路径注意事项。
  • Worker创建后需要手动管理生命周期。同时运行的Worker子线程数量最多为64个，并且与napi_create_ark_runtime创建的runtime总数不超过80。详情请参见生命周期注意事项。
  • 不同线程中上下文对象是不同的，因此Worker线程只能使用线程安全的库，例如UI相关的非线程安全库不能在Worker子线程中使用。
  • 单次序列化传输的数据量大小限制为16MB。
  • 使用Worker模块时，API version 18及之后的版本建议在宿主线程中注册onAllErrors回调，以捕获Worker线程生命周期内的各种异常。API version 18之前的版本应注册onerror回调。如果未注册onAllErrors或onerror回调，当Worker线程出现异常时会发生jscrash问题。注意，onerror接口仅能捕获onmessage回调中的同步异常，捕获异常后，Worker线程将进入销毁流程，无法继续使用。详情请参见onAllErrors接口与onerror接口之间的行为差异。
  • 不支持在多个HAP之间共享使用相同的Worker线程文件。
  • 引用HAR/HSP中的worker前，需要先配置对HAR/HSP的依赖，详见引用共享包。
  • 不支持在Worker工作线程中使用AppStorage。
  • 从API version 18开始，可以在构造函数的参数WorkerOptions中指定Worker线程的优先级。
  • 在Worker文件中禁止使用export语法导出任何内容，否则会导致jscrash问题。
  • 应用挂起后，该应用的Worker线程会暂停运行。

除上述注意事项外，使用Worker时还需注意并发注意事项。

创建Worker的注意事项​

Worker线程文件需要放在"{moduleName}/src/main/ets/"目录层级之下，否则不会被打包到应用中。有手动和自动两种创建Worker线程目录及文件的方式。

  • 手动创建：开发者手动创建相关目录及文件，通常是在ets目录下创建一个workers文件夹，用于存放worker.ets文件，需要配置build-profile.json5的相关字段信息，确保Worker线程文件被打包到应用中。

    Stage模型：

    "buildOption": {
      "sourceOption": {
        "workers": [
          "./src/main/ets/workers/worker.ets"
        ]
      }
    }

    FA模型：

    "buildOption": {
      "sourceOption": {
        "workers": [
          "./src/main/ets/MainAbility/workers/worker.ets"
        ]
      }
    }

  • 自动创建：DevEco Studio支持一键生成Worker，在对应的{moduleName}目录下任意位置，单击鼠标右键 > New > Worker，即可自动生成Worker的模板文件及配置信息，无需再手动在build-profile.json5中进行相关配置。

文件路径注意事项​

使用Worker模块的具体功能时，需先构造Worker实例对象。构造函数与API版本相关，且需传入Worker线程文件的路径（scriptURL）。

// 导入模块
import { worker } from '@kit.ArkTS';

const worker1: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/worker.ets');

Stage模型下的文件路径规则

构造函数中的scriptURL要求如下：

  • scriptURL的组成包含{moduleName}/ets和相对路径relativePath。
  • relativePath是Worker线程文件相对于"{moduleName}/src/main/ets/"目录的相对路径。

1） 加载Ability中的Worker线程文件：

加载Ability中的worker线程文件。路径规则：{moduleName}/ets/{relativePath}。

import { worker } from '@kit.ArkTS';

// worker线程文件所在路径："entry/src/main/ets/workers/worker.ets"
const workerStage1: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/worker.ets');

// worker线程文件所在路径："testworkers/src/main/ets/ThreadFile/workers/worker.ets"
const workerStage2: worker.ThreadWorker = new worker.ThreadWorker('testworkers/ets/ThreadFile/workers/worker.ets');

2） 加载HSP中Worker线程文件

加载HSP中的worker线程文件。路径规则：{moduleName}/ets/{relativePath}。

import { worker } from '@kit.ArkTS';

// worker线程文件所在路径： "hsp/src/main/ets/workers/worker.ets"
const workerStage3: worker.ThreadWorker = new worker.ThreadWorker('hsp/ets/workers/worker.ets');

3） 加载HAR中Worker线程文件

加载HAR中worker线程文件存在以下两种情况：

  • @标识路径加载形式：所有种类的模块加载本地HAR中的Worker线程文件，加载路径规则：@{moduleName}/ets/{relativePath}。

  • 相对路径加载形式：本地HAR加载该包内的Worker线程文件，路径规则为：创建Worker对象所在文件与Worker线程文件的相对路径。

说明：

当开启useNormalizedOHMUrl（在工程目录中与entry同级别的应用级build-profile.json5文件中，将strictMode属性下的useNormalizedOHMUrl字段配置为true）或HAR包被打包成三方包使用时，HAR包中使用Worker仅支持通过相对路径的加载形式创建。

import { worker } from '@kit.ArkTS';

// @标识路径加载形式：
// worker线程文件所在路径: "har/src/main/ets/workers/worker.ets"
const workerStage4: worker.ThreadWorker = new worker.ThreadWorker('@har/ets/workers/worker.ets');

// 相对路径加载形式：
// worker线程文件所在路径: "har/src/main/ets/workers/worker.ets"
// 创建Worker对象的文件所在路径："har/src/main/ets/components/mainpage/MainPage.ets"
const workerStage5: worker.ThreadWorker = new worker.ThreadWorker('../../workers/worker.ets');

FA模型下的文件路径规则

构造函数中的scriptURL为：Worker线程文件与"{moduleName}/src/main/ets/MainAbility"的相对路径。

import { worker } from '@kit.ArkTS';

// 主要说明以下三种场景：

// 场景1： Worker线程文件所在路径："{moduleName}/src/main/ets/MainAbility/workers/worker.ets"
const workerFA1: worker.ThreadWorker = new worker.ThreadWorker('workers/worker.ets', {name:'first worker in FA model'});

// 场景2： Worker线程文件所在路径："{moduleName}/src/main/ets/workers/worker.ets"
const workerFA2: worker.ThreadWorker = new worker.ThreadWorker('../workers/worker.ets');

// 场景3： Worker线程文件所在路径："{moduleName}/src/main/ets/MainAbility/ThreadFile/workers/worker.ets"
const workerFA3: worker.ThreadWorker = new worker.ThreadWorker('ThreadFile/workers/worker.ets');

生命周期注意事项​

  • Worker的创建和销毁会消耗较多的系统资源，建议开发者合理管理并重复使用已创建的Worker。Worker空闲时仍会占用资源，当不需要Worker时，可以调用terminate()接口或close()方法主动销毁Worker。若Worker处于已销毁或正在销毁等非运行状态时，调用其功能接口，会抛出相应的错误。

  • Worker的数量由内存管理策略决定，设定的内存阈值为1.5GB和设备物理内存的60%中的较小值。在内存允许的情况下，系统最多可以同时运行64个Worker。尝试创建的Worker数量超出上限时，系统将抛出错误：“Worker initialization failure, the number of workers exceeds the maximum.”。实际运行的Worker数量会根据当前内存使用情况实时调整。当所有Worker和主线程的累积内存占用超过设定的阈值时，系统将触发内存溢出（OOM）错误，导致应用程序崩溃。

onAllErrors接口与onerror接口之间的行为差异​

  1. 异常捕获范围

    onAllErrors接口可以捕获Worker线程的onmessage回调、timer回调以及文件执行等流程中产生的全局异常。

    onerror接口仅能捕获Worker线程的onmessage回调中同步方法产生的异常，无法捕获多线程回调和模块化相关异常。

  2. 异常捕获后的线程状态

    onAllErrors接口捕获异常后，Worker线程仍然存活并可以继续使用。这使开发者可以在捕获异常后执行其他操作，无需担心线程终止。

    onerror接口捕获异常后，Worker线程会进入销毁流程，无法继续使用。这意味着在onerror触发后，Worker线程将被终止，后续操作将无法进行。

  3. 适用场景

    onAllErrors接口适用于捕获Worker线程中所有类型异常的场景，特别是确保异常发生后Worker线程仍能继续运行的复杂场景。

    onerror接口适用于只需要捕获onmessage回调中同步异常的简单场景。由于捕获异常后线程会被销毁，适用于不需要继续使用Worker线程的情况。

    推荐使用onAllErrors接口，因为它提供了更全面的异常捕获能力，并且不会导致线程终止。

Worker基本用法示例​

  1. DevEco Studio支持一键生成Worker，在对应的{moduleName}目录下任意位置，单击鼠标右键 > New > Worker，即可自动生成Worker的模板文件及配置信息。本文以创建“worker”为例。

    支持手动创建Worker文件，具体方式和注意事项请参阅创建Worker的注意事项。

  2. 导入Worker模块。

    // Index.ets
    import { ErrorEvent, MessageEvents, worker } from '@kit.ArkTS'

  3. 在宿主线程中，通过调用ThreadWorker的constructor()方法创建Worker对象，并注册回调函数。

    // Index.ets
    @Entry
    @Component
    struct Index {
      @State message: string = 'Hello World';

      build() {
        RelativeContainer() {
          Text(this.message)
            .id('HelloWorld')
            .fontSize(50)
            .fontWeight(FontWeight.Bold)
            .alignRules({
              center: { anchor: '__container__', align: VerticalAlign.Center },
              middle: { anchor: '__container__', align: HorizontalAlign.Center }
            })
            .onClick(() => {
              // 创建Worker对象
              let workerInstance = new worker.ThreadWorker('entry/ets/workers/worker.ets');

              // 注册onmessage回调，捕获宿主线程接收到来自其创建的Worker通过workerPort.postMessage接口发送的消息。该回调在宿主线程执行
              workerInstance.onmessage = (e: MessageEvents) => {
                let data: string = e.data;
                console.info('workerInstance onmessage is: ', data);
              }

              // 注册onAllErrors回调，捕获Worker线程的onmessage回调、timer回调以及文件执行等流程产生的全局异常。该回调在宿主线程执行
              workerInstance.onAllErrors = (err: ErrorEvent) => {
                console.error('workerInstance onAllErrors message is: ' + err.message);
              }

              // 注册onmessageerror回调，当Worker对象接收到无法序列化的消息时被调用，在宿主线程执行
              workerInstance.onmessageerror = () => {
                console.error('workerInstance onmessageerror');
              }

              // 注册onexit回调，当Worker销毁时被调用，在宿主线程执行
              workerInstance.onexit = (e: number) => {
                // Worker正常退出时，code为0；异常退出时，code为1
                console.info('workerInstance onexit code is: ', e);
              }

              // 发送消息给Worker线程
              workerInstance.postMessage('1');
            })
        }
        .height('100%')
        .width('100%')
      }
    }

  4. 在Worker文件中注册回调函数。

    // worker.ets
    import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

    const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

    // 注册onmessage回调，当Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用，在Worker线程执行
    workerPort.onmessage = (e: MessageEvents) => {
      let data: string = e.data;
      console.info('workerPort onmessage is: ', data);

      // 向宿主线程发送消息
      workerPort.postMessage('2');
    }

    // 注册onmessageerror回调，当Worker对象接收到一条无法被序列化的消息时被调用，在Worker线程执行
    workerPort.onmessageerror = () => {
      console.error('workerPort onmessageerror');
    }

    // 注册onerror回调，捕获Worker在执行过程中发生的异常，在Worker线程执行
    workerPort.onerror = (err: ErrorEvent) => {
      console.error('workerPort onerror err is: ', err.message);
    }

跨har包加载Worker​

  1. 创建HAR详情参考开发静态共享包。

  2. 在HAR中创建Worker线程文件相关内容。

    // worker.ets
    workerPort.onmessage = (e: MessageEvents) => {
      console.info('worker thread receive message: ', e.data);
      workerPort.postMessage('worker thread post message to main thread');
    }

  3. 在entry模块的oh-package.json5文件中配置HAR包的依赖。

    // 在entry模块配置har包的依赖
    {
      "name": "entry",
      "version": "1.0.0",
      "description": "Please describe the basic information.",
      "main": "",
      "author": "",
      "license": "",
      "dependencies": {
        "har": "file:../har"
      }
    }

  4. 在entry模块中加载HAR包中的Worker线程文件。

    // Index.ets
    import { worker } from '@kit.ArkTS';

    @Entry
    @Component
    struct Index {
      @State message: string = 'Hello World';

      build() {
        RelativeContainer() {
          Text(this.message)
            .id('HelloWorld')
            .fontSize(50)
            .fontWeight(FontWeight.Bold)
            .alignRules({
              center: { anchor: '__container__', align: VerticalAlign.Center },
              middle: { anchor: '__container__', align: HorizontalAlign.Center }
            })
            .onClick(() => {
              // 通过@标识路径加载形式，加载har中Worker线程文件
              let workerInstance = new worker.ThreadWorker('@har/ets/workers/worker.ets');
              workerInstance.onmessage = () => {
                console.info('main thread onmessage');
              };
              workerInstance.postMessage('hello world');
            })
        }
        .height('100%')
        .width('100%')
      }
    }

多级Worker生命周期管理​

支持创建多级Worker，即父Worker可以创建子Worker，形成层级线程关系。由于Worker线程的生命周期由开发者管理，因此需要正确管理多级Worker的生命周期。当销毁父Worker时未能终止其子Worker的运行，可能会导致不可预期的结果。所以需要确保子Worker的生命周期在父Worker生命周期范围内，销毁父Worker前，先销毁所有子Worker，以防止不可预期的结果。

推荐使用示例​

// 在宿主线程中创建Worker线程（父Worker），在worker线程中再次创建Worker线程（子Worker）
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

// 宿主线程中创建父worker对象
const parentWorker = new worker.ThreadWorker('entry/ets/workers/ParentWorker.ets');

parentWorker.onmessage = (e: MessageEvents) => {
  console.info('宿主线程收到父worker线程信息 ' + e.data);
}

parentWorker.onexit = () => {
  console.info('父worker退出');
}

parentWorker.onAllErrors = (err: ErrorEvent) => {
  console.error('宿主线程接收到父worker报错 ' + err.message);
}

parentWorker.postMessage('宿主线程发送消息给父worker-推荐示例');
// ParentWorker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

// 创建父Worker线程中与宿主线程通信的对象
const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e : MessageEvents) => {
  if (e.data == '宿主线程发送消息给父worker-推荐示例') {
    let childWorker = new worker.ThreadWorker('entry/ets/workers/ChildWorker.ets');

    childWorker.onmessage = (e: MessageEvents) => {
      console.info('父Worker收到子Worker的信息 ' + e.data);
      if (e.data == '子Worker向父Worker发送信息') {
        workerPort.postMessage('父Worker向宿主线程发送信息');
      }
    }

    childWorker.onexit = () => {
      console.info('子Worker退出');
      // 子Worker退出后再销毁父Worker
      workerPort.close();
    }

    childWorker.onAllErrors = (err: ErrorEvent) => {
      console.error('子Worker发生报错 ' + err.message);
    }

    childWorker.postMessage('父Worker向子Worker发送信息-推荐示例');
  }
}
// ChildWorker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

// 创建子Worker线程中与父Worker线程通信的对象
const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e: MessageEvents) => {
  if (e.data == '父Worker向子Worker发送信息-推荐示例') {
    // 子Worker线程业务逻辑...
    console.info('业务执行结束，然后子Worker销毁');
    workerPort.close();
  }
}

不推荐使用示例​

不建议在父Worker销毁后，子Worker继续向父Worker发送消息。

import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

const parentWorker = new worker.ThreadWorker('entry/ets/workers/ParentWorker.ets');

parentWorker.onmessage = (e: MessageEvents) => {
  console.info('宿主线程收到父Worker信息' + e.data);
}

parentWorker.onexit = () => {
  console.info('父Worker退出');
}

parentWorker.onAllErrors = (err: ErrorEvent) => {
  console.error('宿主线程接收到父Worker报错 ' + err.message);
}

parentWorker.postMessage('宿主线程发送消息给父Worker');
// ParentWorker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e : MessageEvents) => {
  console.info('父Worker收到宿主线程的信息 ' + e.data);

  let childWorker = new worker.ThreadWorker('entry/ets/workers/ChildWorker.ets')

  childWorker.onmessage = (e: MessageEvents) => {
    console.info('父Worker收到子Worker的信息 ' + e.data);
  }

  childWorker.onexit = () => {
    console.info('子Worker退出');
    workerPort.postMessage('父Worker向宿主线程发送信息');
  }

  childWorker.onAllErrors = (err: ErrorEvent) => {
    console.error('子Worker发生报错 ' + err.message);
  }

  childWorker.postMessage('父Worker向子Worker发送信息');

  // 创建子Worker后，销毁父Worker
  workerPort.close();
}
// ChildWorker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e: MessageEvents) => {
  console.info('子Worker收到信息 ' + e.data);

  // 父Worker销毁后，子Worker向父Worker发送信息，行为不可预期
  workerPort.postMessage('子Worker向父Worker发送信息');
  setTimeout(() => {
    workerPort.postMessage('子Worker向父Worker发送信息');
  }, 1000);
}

不建议在父Worker发起销毁操作的执行阶段创建子Worker。在创建子Worker线程之前，需确保父Worker线程始终处于存活状态，建议在确定父Worker未发起销毁操作的情况下创建子Worker。

import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

const parentWorker = new worker.ThreadWorker('entry/ets/workers/ParentWorker.ets');

parentWorker.onmessage = (e: MessageEvents) => {
  console.info('宿主线程收到父Worker信息' + e.data);
}

parentWorker.onexit = () => {
  console.info('父Worker退出');
}

parentWorker.onAllErrors = (err: ErrorEvent) => {
  console.error('宿主线程接收到父Worker报错 ' + err.message);
}

parentWorker.postMessage('宿主线程发送消息给父Worker');
// ParentWorker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e : MessageEvents) => {
  console.info('父Worker收到宿主线程的信息 ' + e.data);

  // 父Worker销毁后创建子Worker，行为不可预期
  workerPort.close();
  let childWorker = new worker.ThreadWorker('entry/ets/workers/ChildWorker.ets');

  // 子Worker线程未确认创建成功前销毁父Worker，行为不可预期
  // let childWorker = new worker.ThreadWorker('entry/ets/workers/ChildWorker.ets');
  // workerPort.close();

  childWorker.onmessage = (e: MessageEvents) => {
    console.info('父Worker收到子Worker的信息 ' + e.data);
  }

  childWorker.onexit = () => {
    console.info('子Worker退出');
    workerPort.postMessage('父Worker向宿主线程发送信息');
  }

  childWorker.onAllErrors = (err: ErrorEvent) => {
    console.error('子Worker发生报错 ' + err.message);
  }

  childWorker.postMessage('父Worker向子Worker发送信息');
}
// ChildWorker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e: MessageEvents) => {
  console.info('子Worker收到信息 ' + e.data);
}