TaskPool 并发实战:把超分/OCR 推理搬出主线程不卡 UI【鸿蒙心迹】

摘要
鸿蒙的 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 | 执行一次性任务,返回 Promise | API 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 里改 @State | emitter.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 线程不回收
}
}
四、流程图解:任务从主线程到工作线程再回来
先看整体调度链路,理解「谁在哪个线程上跑」:
再看「取消」这条支线的时序,很多坑都出在这里:
关键点: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,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、销毁别忘反注册。
更多推荐

所有评论(0)