在这里插入图片描述

摘要

鸿蒙的 UI 渲染跑在主线程,超分、OCR 推理这类 CPU 密集型任务一旦同步执行,界面立刻卡死。本文以相册超分为例,系统讲解如何用 TaskPool 把重活搬出主线程:从 @Concurrent 顶层函数的写法约束、new taskpool.Task 的可取消任务构造,到用 emitter 回传进度、协作式取消的正确姿势、LongTask 的回收,再到任务组批量处理、并发度控制与 TaskPool/Worker/异步 API 的选型决策。文中给出可直接复用的完整代码骨架、错误写法对照表与调度流程图,帮你避开「取消没反应」「线程不回收」「销毁后回调崩溃」等高频坑。

目录

一、背景与痛点

鸿蒙的 UI 渲染跑在主线程(Actor 模型,一个 UIAbility 一条主线程),这点跟前端很像。但很多做端侧 AI、图像处理的同学容易忽略:超分辨率、OCR 推理、文搜图建库、大图像素处理、加解密这一类 CPU 密集型活儿,一旦写在按钮点击或页面初始化里同步跑,主线程立刻被占满,界面直接掉帧、点击无响应,体验就是"假死"两秒起步。我在做一个相册超分功能时,第一版图省事把推理直接放主线程,结果点一下按钮整个页面卡住,进度条都不带动的,用户还以为崩了。

正确的解法是把这类重活丢到 TaskPool 工作线程。TaskPool 的系统会根据 CPU 负载动态调度线程,你只管把任务函数用 @Concurrent 标记、丢进去执行,干完把结果拿回来。相比 Worker,TaskPool 不用你手写通信、不用管线程生命周期,绝大多数场景官方都建议优先用它。本文就讲清怎么写 @Concurrent 函数、怎么回传进度、怎么取消长任务、怎么兜底异常——都是文档一笔带过、实战必踩的点。

二、核心概念与规格

装饰器 / API作用最低版本关键约束(红字为高频坑)
@Concurrent标记可并发函数API 9必须是顶层函数、不能访问外部变量/this、不能碰 UI
taskpool.execute执行一次性任务,返回 PromiseAPI 9直接 execute(func) 的形式不支持取消
new taskpool.Task构造可取消/可通信任务API 9配合 execute(task) 才能 cancel
taskpool.cancel取消任务API 9协作式取消,函数体要查 isCanceled() 才真停
taskpool.sendData子线程回传进度API 9不能在回调里用,推荐用 emitter 双向通信
taskpool.LongTask长时任务API 12+线程不自动回收,拿结果后要 terminateTask

核心结论:要取消、要进度、要优先级,就先 new taskpool.Task 再 execute;纯一次性计算才用 execute(func) 简写。

三、核心代码(可取消 + 进度回传:错误 vs 正确)

import { taskpool } from '@kit.ArkTS';
import { emitter } from '@kit.BasicServicesKit';

// ✅ 正确:@Concurrent 顶层函数,纯数据进出,用 emitter 回传进度
@Concurrent
function superResolve(total: number): number {
  let acc = 0;
  for (let i = 0; i < total; i++) {
    if (taskpool.isCanceled()) break;       // 协作式取消:及时退出
    acc += Math.sqrt(i);
    if (i % 5000 === 0) {
      emitter.emit({ eventId: 1001 }, { data: Math.floor(i / total * 100) });
    }
  }
  return acc;
}

// ❌ 错误:在 @Concurrent 里改外部 @State(编译不过),且无法取消
// @Concurrent function bad() { this.progress = 50; ... }  // 不能访问 this

@Entry
@Component
struct Page {
  @State progress: number = 0;
  @State result: number = 0;
  private task?: taskpool.Task;

  aboutToAppear() {
    // 订阅子线程进度,回主线程更新 UI
    emitter.on({ eventId: 1001 }, (ev) => { this.progress = ev.data as number; });
  }
  start() {
    this.task = new taskpool.Task(superResolve, 2000000);
    taskpool.execute(this.task)
      .then((r: number) => { this.result = r; })
      .catch((e: Error) => { console.error('失败/取消', e); });
  }
  cancel() {
    if (this.task) { taskpool.cancel(this.task); this.task = undefined; } // 触发 isCanceled
  }
  aboutToDisappear() { emitter.off(1001); } // 记得反注册
}

3.0 代码逐段拆解:每一行为什么这么写

上面这段代码看着不长,但每一处都是踩过坑才定下来的。逐段说明:

① @Concurrent 修饰的 superResolve 必须是顶层函数。
它不能是某个 class 的方法,也不能是箭头函数,因为并发函数会被序列化后送到工作线程执行,闭包和 this 都无法跨线程传递。参数和返回值也必须是可序列化的纯数据(number、string、ArrayBuffer、普通对象),传 @State 对象或 UI 组件会直接报错。

② 循环里的 taskpool.isCanceled() 是取消的唯一生效点。
taskpool.cancel(task) 只是给任务打一个「已请求取消」的标记,并不会强杀线程。如果函数体里不检查,任务会一直跑到自然结束。所以任何可能长时间运行的循环,都必须在迭代里插入这个检查,这是协作式取消的核心约定。

③ emitter.emit 是子线程回传进度的推荐方式。
taskpool.sendData 只能在任务内部主动调用且不能在回调里用,限制较多;emitter 是事件总线,子线程 emit、主线程 on,天然支持一对多和跨组件,工程里更好用。注意 emit 的数据同样要可序列化。

④ new taskpool.Task(fn, ...args) 而不是 execute(fn)。
只有持有 Task 对象才能调用 cancel。execute(fn) 的简写返回的是 Promise,拿不到任务句柄,等于放弃了取消能力。只要业务上可能出现「用户中途想停」,就必须走 Task 对象这条路。

⑤ aboutToDisappear 里 emitter.off 是防崩溃的关键。
组件销毁后如果 emitter 还挂着回调,子线程再 emit 就会往一个已销毁的组件上写 @State,轻则警告重则崩溃。反注册和取消任务要成对出现。

3.1 完整可运行骨架:进度 + 取消 + 异常兜底

上面是最小示例,实际工程里还要处理「任务重入、进度节流、取消后状态复位」。下面这份骨架可以直接抄进项目:

import { taskpool } from '@kit.ArkTS';
import { emitter } from '@kit.BasicServicesKit';

const EVENT_PROGRESS = 1001;
const EVENT_DONE = 1002;

// ✅ 顶层 @Concurrent 函数:只接收纯数据,返回纯数据
@Concurrent
function ocrInference(imageBytes: ArrayBuffer, threshold: number): string {
  const total = imageBytes.byteLength;
  let lastPercent = -1;
  for (let i = 0; i < total; i += 4096) {
    if (taskpool.isCanceled()) {
      return ''; // 协作式取消:主动退出,别让线程空转
    }
    // ... 真实推理逻辑(此处省略)
    const percent = Math.floor((i / total) * 100);
    // 进度节流:每变化 5% 才回传一次,避免 emitter 刷屏
    if (percent - lastPercent >= 5) {
      lastPercent = percent;
      emitter.emit({ eventId: EVENT_PROGRESS }, { data: percent });
    }
  }
  emitter.emit({ eventId: EVENT_DONE }, { data: threshold });
  return 'ocr-result';
}

@Entry
@Component
struct OcrPage {
  @State progress: number = 0;
  @State running: boolean = false;
  @State result: string = '';
  private task?: taskpool.Task;

  private onProgress = (ev: emitter.EventData) => {
    this.progress = ev.data as number;
  };
  private onDone = (ev: emitter.EventData) => {
    this.result = `完成,阈值=${ev.data}`;
  };

  aboutToAppear() {
    emitter.on({ eventId: EVENT_PROGRESS }, this.onProgress);
    emitter.on({ eventId: EVENT_DONE }, this.onDone);
  }

  async start() {
    if (this.running) return;          // 防重入
    this.running = true;
    this.progress = 0;
    this.task = new taskpool.Task(ocrInference, new ArrayBuffer(1024 * 1024), 0.8);
    try {
      const r = await taskpool.execute(this.task) as string;
      if (r) this.result = r;
    } catch (e) {
      console.error('任务失败或被取消', JSON.stringify(e));
    } finally {
      this.running = false;
      this.task = undefined;           // 复位,允许下次重新发起
    }
  }

  cancel() {
    if (this.task) {
      taskpool.cancel(this.task);      // 只是「请求取消」,函数体需自查 isCanceled
      this.task = undefined;
      this.running = false;
    }
  }

  aboutToDisappear() {
    emitter.off(EVENT_PROGRESS, this.onProgress);
    emitter.off(EVENT_DONE, this.onDone);
    this.cancel();                     // 页面销毁顺手取消,避免野任务
  }

  build() {
    Column({ space: 12 }) {
      Progress({ value: this.progress, total: 100, type: ProgressType.Linear })
      Text(this.result || '待处理')
      Row({ space: 12 }) {
        Button('开始').enabled(!this.running).onClick(() => this.start())
        Button('取消').enabled(this.running).onClick(() => this.cancel())
      }
    }.padding(16)
  }
}

3.2 错误写法对照表

场景❌ 错误写法✅ 正确写法后果
取消任务const p = taskpool.execute(fn); taskpool.cancel(p)const t = new taskpool.Task(fn); taskpool.cancel(t)Promise 不是任务对象,cancel 无效
函数内退出只 cancel,不检查循环里 if (taskpool.isCanceled()) break线程继续跑满 CPU
回传进度在 @Concurrent 里改 @Stateemitter.emit 回主线程改编译报错「无法访问外部作用域」
长任务回收用完不管await 后 taskpool.terminateTask(task)线程堆积不缩容
页面销毁不反注册aboutToDisappear 里 emitter.off已销毁组件收到回调崩溃

3.3 LongTask 的正确回收姿势

@Concurrent
function longListen(): void {
  // 常驻监听类长活,例如持续消费推理队列
  while (!taskpool.isCanceled()) {
    // ... 处理逻辑
  }
}

async function runLongTask() {
  const task = new taskpool.LongTask(longListen);
  try {
    await taskpool.execute(task);
  } finally {
    taskpool.terminateTask(task);   // 关键:不 terminate 线程不回收
  }
}

四、流程图解:任务从主线程到工作线程再回来

先看整体调度链路,理解「谁在哪个线程上跑」:

是

否

主线程:点击开始按钮

new taskpool.Task(fn, args)

taskpool.execute(task)

TaskPool 调度器按 CPU 负载分配工作线程

工作线程执行 @Concurrent 函数

isCanceled()?

主动 return 退出

继续计算 + emitter.emit 进度

返回结果 Promise resolve

主线程 then/await 拿到结果

更新 @State 刷新 UI

catch 捕获取消异常

复位 running / task 状态

再看「取消」这条支线的时序,很多坑都出在这里:

"工作线程" "TaskPool 调度器" "主线程 UI" "工作线程" "TaskPool 调度器" "主线程 UI" "execute(task)" "分配线程执行 @Concurrent" "emitter.emit 进度 30%" "cancel(task)" "标记取消(不强制杀线程)" "下一轮循环 isCanceled() === true" "return 提前退出" "catch 兜底 + 状态复位"

关键点:cancel 只是打标记,真正停下来靠函数体自己查 isCanceled(),这也是为什么「取消没反应」几乎都是忘了在循环里检查。

五、深入应用分析:从单任务到批量流水线

单任务跑通只是起点,真实业务里更常见的是「一次处理几十上百张图」。这一节把 TaskPool 从「会用」推进到「用对」。

5.1 批量任务:用任务组统一等待与取消

一张一张 execute 再 Promise.all 也能跑,但拿不到统一的任务句柄,取消时只能逐个 cancel。更规范的做法是用 taskpool.TaskGroup 把一批任务打包:

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

@Concurrent
function processOne(index: number): number {
  if (taskpool.isCanceled()) return -1;
  // ... 单张图处理
  return index * 2;
}

async function batchProcess(count: number): Promise<number[]> {
  const group = new taskpool.TaskGroup();
  for (let i = 0; i < count; i++) {
    group.addTask(new taskpool.Task(processOne, i));
  }
  // 一次性提交整组,由调度器并发执行
  const results = await taskpool.execute(group) as number[];
  return results;
}

任务组的好处:提交一次、调度器自动并发、结果按加入顺序返回。要整体取消时,对组内每个 Task 调 cancel 即可,比散落各处的 Promise 好管理得多。

5.2 并发度控制:别把线程池打满

TaskPool 会根据 CPU 负载动态调度,但不代表你可以无脑提交一万个任务。任务过多会导致排队延迟、内存上涨,甚至挤占其他模块的线程资源。经验做法:

  • 批量任务按「CPU 核数 × 1~2」分批提交,处理完一批再提交下一批;
  • 单任务内部按数据分片,而不是按文件拆成海量小任务;
  • 对实时性要求高的任务(如用户点击触发的单张超分)与后台批处理任务分开提交,避免互相排队。
async function chunkedProcess(files: string[], batchSize: number): Promise<void> {
  for (let i = 0; i < files.length; i += batchSize) {
    const slice = files.slice(i, i + batchSize);
    const group = new taskpool.TaskGroup();
    slice.forEach((f, idx) => group.addTask(new taskpool.Task(processOne, i + idx)));
    await taskpool.execute(group);
  }
}

5.3 性能对比:主线程 vs TaskPool

以相册超分为例,同一张 4K 图在两种方式下的实测体感差异非常明显:

指标主线程同步执行TaskPool 工作线程
单帧耗时约 800ms约 800ms(计算量不变)
期间 UI 帧率掉到个位数,明显卡顿稳定 60fps
用户可交互否,点击无响应是,可滚动、可取消
进度反馈无(主线程被占)实时百分比
取消能力无支持协作式取消

结论很直接:TaskPool 不减少计算量,它解决的是「计算不阻塞交互」。凡是耗时超过一帧(约 16ms)的 CPU 任务,都应该考虑搬出去。

5.4 选型决策:TaskPool、Worker 还是异步 API

是

否

否

是

否

是

是

否

有一个耗时任务

是纯 IO 吗?
网络/文件

用系统异步 API
如 http / fs 的 Promise 版

是 CPU 密集型吗?

普通异步即可

需要常驻后台
或复杂双向通信?

TaskPool
首选方案

Worker
常驻线程 + 消息通道

任务很长?

LongTask + terminateTask

普通 Task + isCanceled

一句话总结选型:IO 走异步 API,CPU 密集走 TaskPool,常驻长服务才上 Worker。绝大多数端侧 AI 推理场景,TaskPool 都是性价比最高的选择。

六、实战要点

要点 1:@Concurrent 函数里别碰外部变量和 UI,否则直接编译失败。
我当初想在并发函数里直接改 @State 进度,结果报"无法访问外部作用域"。正确做法是用 emitter 或 taskpool.sendData 把数据传回主线程,由主线程更新 UI。记住:子线程只算数,UI 只能主线程动。

要点 2:想取消任务,必须先 new taskpool.Task 再 cancel,并在函数里查 isCanceled()。
我当初写成 const id = taskpool.execute(fn) 然后 cancel(id),根本取消不了——execute 返回的是 Promise 不是任务对象,而且即使 cancel 了,函数不主动检查也不会停。规范:用 Task 对象 cancel + 函数体内周期性 isCanceled() 退出。

要点 3:长时任务(LongTask)拿完结果必须 terminateTask 释放线程。
用 taskpool.LongTask 做监听类长活时,线程不会自动缩容,不显式 terminateTask 会一直占着资源。我在做持续推理服务时忘了回收,跑几次线程就堆满。拿到结果(await/then 里)立刻 terminate。

要点 4:异常要兜底,页面销毁要反注册 emitter。
子线程抛错会走 execute().catch,务必捕获;同时 aboutToDisappear 里 emitter.off 反注册,否则已销毁组件收到回调会崩。

七、小结与边界

这套并发方案适用于一切 CPU 密集型、会卡主线程的端侧任务:超分/OCR 推理、文搜图建库、大图处理、加解密、大 JSON 解析。它的边界是:纯 IO 类(网络、文件)优先用系统异步 API,别为了并发而并发;需要常驻后台、复杂双向通信的长服务再考虑 Worker。能用 TaskPool 就别上 Worker。落地口诀记牢:重活丢 TaskPool、函数加 @Concurrent、进度走 emitter、取消靠 Task 加 isCanceled、长任务记得 terminate、销毁别忘反注册。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐