React Native 鸿蒙 FASTKit 调度诊断实战:用 react-native-fast-scheduler 核对 PerfHint 到底有没有生效
本文围绕 FASTKit 调度诊断台(fastkit-diagnostic-studio)的 React Native 鸿蒙开发过程展开,针对 PerfHint 场景提示目标线程错位、BEGIN 与 END 配对收尾及滚动预测采样核对问题,结合 react-native-fast-scheduler 完成能力接入与诊断页面实现。
配套实战项目已开源在 abaoge/fastkit-diagnostic-studio,使用的第三方库已开源在 oh-react-native/react-native-fast-scheduler,有问题可以到 三方库 Issue 提问,也可以来 鸿蒙系统 React Native 开源社区 交流。
前言
🌈 我在 React Native 鸿蒙工程里做了一个 FASTKit 调度诊断台,用固定种子生成的四万条订单记录跑 JS 筛选与排序,顺便核对场景提示(PerfHint)的线程号和系统回执。排查包裹器的调用链时我发现一个乌龙:接口每次都返回 0,但它默认提示的是原生线程池里的四条工作线程,而筛选和排序其实一直在 RN 的 JS 线程上同步执行。
于是我改用 JSI 同步方法在 JS 线程上直接读取内核线程号,把通用调度与预测接口拆进第三方库 react-native-fast-scheduler,让诊断台 fastkit-diagnostic-studio 专心负责测试负载、交互界面和采样记录。接着在华为畅享 100 Pro Max 真机和 Pura X View 手机模拟器上验证时,我又发现两组样本的静置等待时长、滚动预测的目标采样时刻都会左右结论。把这些条件固定进采样协议后,页面终于能清楚区分“接口调通了”“线程提示对了”和“耗时到底有没有变化”。
一、使用场景与真实痛点
1.1 在诊断台里核对 JS 重计算与滚动预测
日常接入鸿蒙 FASTKit 系统性能优化能力时,最容易踩的坑就是只看接口有没有报错。schedulingOptimization.perfHint 接收一组线程号(tids)和场景类型,向系统申请调度支持,但它既不会替应用把任务搬到目标线程,也不保证每次请求都让计算变快。
为了在开发阶段把这条链路看明白,我在诊断台里放了两个贴近真实业务的检查入口:
- JS 线程重计算 A/B 对照:点击按钮后,程序按固定随机种子生成四万条订单数据,在 RN 的 JS 线程上依次执行关键词筛选、权重计算与前 200 条排序序列化。数据种子、关键词和计算量完全固定,并用校验和核对两组有没有少算。
- 长列表滚动索引预测:页面下方放了一个真实的 ScrollView 列表,滚动时采集最近几帧的毫秒时间戳和首项索引,传给
mathPrediction.predictIndex,再拿返回的预测索引跟下一次真实滚动采样做比对。
即便 perfHint 返回了代表成功的 0,诊断台仍会继续核对三件事:
- 提示的线程对不对? 传入的
tids必须是当前进程里存活的线程,而且确实正在跑这段耗时任务。如果任务在 JS 线程执行,传进去的却是 UI 线程或空闲的原生线程池线程号,系统就算提频也帮不上忙。 - 两组的起跑条件一样吗? 连续跑多轮重计算时,JIT 预热、垃圾回收和两轮之间的静置休息时间都会影响单次耗时。如果开启提示的一组为了避开系统频控多休息了 3 秒,而对照组只歇了 0.3 秒,测出来的差值就不能算到 PerfHint 头上。
- 预测比的是哪个时刻? 滚动预测是异步跨端调用,结果返回时列表可能又滑过了好几次事件。核对误差时必须锁定发起请求后的第一个
onScroll采样点,不能拿更晚的事件顶替。

图1 诊断流程
1.2 所用第三方库与实战项目的职责边界
为了让业务工程接入时不必夹带诊断代码,我把通用能力和诊断界面拆成了两个独立工程。诊断台通过标准 npm 依赖引入第三方库 📦 oh-react-native/react-native-fast-scheduler(当前验证版本 v0.2.1,MIT 许可,基于 React Native 0.84.1 与 RNOH 0.84.6)。这个库只封装业务可直接复用的五个接口:能力探测 probeCapabilities、同步获取 JS 线程号 getJsThreadTid、开启与结束场景提示 beginPerfScene / endPerfScene、带档位冷却和配对收尾的包裹器 withPerfScene,以及滚动预测 predictScrollIndex。
带完整诊断面板的实战项目放在 abaoge/fastkit-diagnostic-studio(当前验证版本 v1.0.1)。常驻原生线程池、48 × 48 矩阵乘法负载和三路互斥基准只服务于诊断对比,放在实战项目内部的本地鸿蒙模块 fastkit-bench 中,不塞进通用第三方库。系统、第三方库与实战项目的职责边界如下:
| 层次 | 对应载体 | 负责的具体内容 |
|---|---|---|
| 鸿蒙系统层 | FASTKit、NDK 调度与 QoS 接口 | 提供 schedulingOptimization.perfHint 场景提示、mathPrediction.predictIndex 轨迹预测,以及原生线程调度与 QoS 接口 |
| 通用第三方库 | react-native-fast-scheduler | 同步读取 RN JS 线程号、校验参数与线程列表、按时长档位执行冷却守卫、保证 BEGIN 与 END 配对收尾并转发预测结果 |
| 独立实战项目 | fastkit-diagnostic-studio(含内部模块 fastkit-bench) | 组织四万条订单筛选排序 A/B、常驻原生池、三路矩阵基准与真实 ScrollView 采样核对,展示回执与逐轮日志 |
表1 职责划分
二、验证环境与诊断结果
2.1 验证设备与运行环境
我在华为畅享 100 Pro Max 真机和 Pura X View 手机模拟器两套 HarmonyOS API 26 环境上做了验证。先在真机(型号 YEW-AL80)上基于库 v0.2.0 和诊断台 v1.0.0 跑通了 schedulingOptimization.perfHint、mathPrediction.predictIndex、C++ 同步 getJsThreadTid()、5 轮原生三路矩阵基准、2 轮 12 对 JS 线程重计算 A/B 以及 3 轮 110 次真实列表滚动预测。复盘真机日志时我发现,当时有提示组受冷却间隔限制每次等待 3300 ms,而无提示组只等待 300 ms,两组休息时间并不对称(具体数据放在 4.4 节对比)。
随后我把 JS A/B 升级为相同预热与 3300 ms 对称静置、锁定请求后首个 onScroll 事件、补齐三档冷却和 endError 收尾诊断(升级为库 v0.2.1、诊断台 v1.0.1),并在 Pura X View 手机模拟器上重跑了完整验证。本章展示的运行截图、动图与数据表均采自这台模拟器:
| 项目 | 手机模拟器(v0.2.1 / v1.0.1 对称协议复验) | 鸿蒙真机(v0.2.0 / v1.0.0 硬件链路与首轮采样) |
|---|---|---|
| 设备型号 | Pura X View 手机模拟器(ARM64,4 核) | 华为畅享 100 Pro Max(YEW-AL80,真机) |
| 屏幕参数 | 1320 × 2232 像素,density 480 | 1128 × 2444 像素(原生投屏采集帧) |
| 系统与镜像 | phone_all_arm 7.0.0.107 / OpenHarmony 7.0.0.105(API 26) | HarmonyOS 7.0.0 / OpenHarmony 7.0(API 26) |
| 工具链与框架 | DevEco Studio 26.0.0.865;SDK 26.0.0.105;RN 0.84.1 / RNOH 0.84.6 | DevEco Studio 26.0.0.865;SDK 26.0.0.105;RN 0.84.1 / RNOH 0.84.6 |
| 验证范围 | 对称预热/静置 JS A/B、三路基准、相邻 onScroll 预测核对(见本章) | 真机 FASTKit/NDK 调通、5 轮三路基准、12 对 JS A/B、110 次预测(见 4.4 节) |
表2 验证环境
2.2 首页探针:先区分线程与能力
打开诊断台首页,顶部探针卡片会分别列出 ArkTS 侧的 FASTKit 能力状态、当前 RN JS 线程号,以及项目内部模块创建的四条常驻原生线程。可以看到调度库和 QoS 动态库均可正常加载,四条常驻工作线程也通过了进程任务目录存活检查。这里的“就绪”只代表接口可调用、线程已存活,还不涉及任何优先级提升。

图2 首页探针
本次运行中,RN JS 线程号是 3968,与 ArkTS UI 线程(3791)以及四条常驻池线程(3985~3988)互不相同。由于内核在每次应用进程启动时都会重新分配线程号,核对日志时只需要认准同一次进程内的线程号对应关系。react-native-fast-scheduler 默认把 3968 作为提示目标;只有当业务显式传入原生工作线程号时,才会去提示那四条常驻线程。
2.3 相同准备条件下的 JS 线程对照
点击“JS 线程重计算 A/B”后,有提示组与无提示组的每个样本在计时前都会先跑一次相同规模的预热计算,再静置等待 3300 ms,随后才用 performance.now() 包住核心筛选排序函数计时。六对样本按“偶数组先开提示、奇数组先跑无提示”交替执行,避免单向顺序偏差。

图3 JS线程对照
| 指标 | 未开启提示 | 成功提示组 |
|---|---|---|
| 单次中位数 | 13.44 ms | 14.47 ms 🟢↑ |
| 单次均值 | 13.66 ms | 14.04 ms 🟢↑ |
| 单次最大值 | 15.50 ms | 15.16 ms 🔴↓ |
| 有效样本 | 6 | 6 |
表3 JS任务耗时
六次提示的 BEGIN 和 END 全部返回 0,没有触发频控跳过或收尾报错;六对计算每次都命中 3833 条记录,校验和完全一致。在这 6 对样本中,P3 与 P4 两对是提示组更快(例如 P3 从 15.16 ms 降到 11.13 ms),单次最大值也从 15.50 ms 微降到 15.16 ms 🔴↓,但整体中位数与均值在宿主机共享 CPU 波动下反而略高(13.44 ms 对比 14.47 ms 🟢↑)。这组数据清楚证明提示确实落到了 JS 线程 3968 上且配对收尾正常,同时受样本量和模拟器宿主机调度波动限制,不能单凭回执为 0 就宣称提示能稳定缩短每次 JS 计算耗时。
2.4 原生三路基准:先看回执再看耗时
为了对比原生工作线程上的调用表现,项目内部模块 fastkit-bench 为“默认不加提示”“仅开启 PerfHint”“仅申请 QoS”三种策略分别创建独立的四线程组,各跑 24 轮 48 × 48 矩阵乘法。三组计算出的校验和完全一致(539296.12),其中 PerfHint 组的 BEGIN 与 END 均返回 0,而 QoS 组的 OH_QoS_SetThreadQoS 返回 -1(四条线程生效数为 0)。

图4 三路回执
| 策略 | 总耗时(ms) | 单轮中位数(ms) | 最慢一轮(ms) |
|---|---|---|---|
| 默认 | 8.84 | 0.291 | 1.50 |
| 仅 PerfHint | 10.11 | 0.308 | 2.54 |
| 仅 QoS(设置返回 -1) | 11.57 | 0.260 | 2.41 |
表4 原生负载
把回执和耗时放在一起看,就能体现诊断面板的价值:如果不检查每条线程的返回码,看到“仅 QoS”组跑出 11.57 ms,很容易误以为是 QoS 策略拖慢了线程;实际上这台模拟器上 QoS 根本没有设置成功,耗时变化只是宿主机负载波动造成的。同理,表中三组按固定顺序执行,中位数与总耗时仅代表当次抽样观测值。
2.5 滚动预测:核对下一次真实采样
点击自动滚动后,页面驱动真实的 ScrollView 连续滑动,并记录每次 onScroll 事件的时间戳和可见首项索引(即使相邻两次事件的首项索引相同也照常记录)。每次发出预测请求后,代码会立即锁定“下一个到达的 onScroll 事件”作为核对目标。滚动停止时如果还有未凑成配对的尾部请求,会单独计入“未完成核对”,不混进准确率分母。

图5 采样核对
| 项目 | 本次记录 |
|---|---|
| 实际滚动事件 | 103 个,序号连续 |
| 完成核对 / 未完成 | 58 / 1 |
| 冷启动 / 热态预测耗时 | 106.58 us / 8.04 us |
| 平均 / 最大绝对误差 | 0.76 / 5 项 |
| rAF 动画回调平均帧间隔 | 14.21 ms |
表5 下一采样误差
本次完成的 58 组配对中,目标事件的序号都严格等于输入样本末尾序号加 1。误差直接用接口返回的原始预测值计算,而供界面高亮展示的列表索引则会按列表首尾范围裁剪后另存,避免越界裁剪掩盖了真实预测偏差。此外,面板里的帧间隔读数统计的是 0.5~250 ms 范围内的 JS requestAnimationFrame 回调间隔,反映的是滚动期间 JS 动画回调的节奏。
2.6 连续调用频控、配置与日志
在“场景边界”卡片里,点击“原生池包裹”会把常驻池的四条线程号显式传给 withPerfScene;点击“连续 BEGIN 调用”则会在第一次 beginPerfScene 返回后不加等待立刻发起第二次调用,用来观察系统对高频请求的拦截或包裹器的冷却降级。下面这段模拟器实录动图展示了完整的点击操作与回执查看过程:

图6 模拟器操作
在工程配置上,通用库与项目内部基准模块分别在宿主中独立注册;三档时长冷却参数与 A/B 对称静置参数也各自独立配置,前者保护系统接口不被高频打爆,后者保证实验两组起跑线一致。

图7 关键配置
查看底部的 HiLog 与应用日志时,我会先核对进程号与线程号 13925,再看 BEGIN、业务计算和 END 的时间戳顺序,确认业务耗时确实包裹在提示窗口之内。

图8 日志节选
三、原理与核心代码分析
3.1 三条调用链路的分工
诊断台上的三类核心操作分别走三条独立链路:三路矩阵基准完全在实战项目内部模块 fastkit-bench 的 C++ 层闭环完成;滚动索引预测从 JS 参数校验到 ArkTS 调用 mathPrediction.predictIndex,全部封装在 react-native-fast-scheduler 库内;场景包裹 withPerfScene 则由库负责读取线程号、检查冷却间隔并配对触发 BEGIN 与 END,中间包裹的既可以是同步 JS 计算,也可以是应用显式传入线程号的原生池任务。

图9 调用流程
3.2 getJsThreadTid:在 JS 线程上同步读线程号
要让 PerfHint 作用于 RN 的 JS 重计算,第一步是拿到 JS 线程在鸿蒙内核里的真实线程号。RNOH 的 ArkTS TurboModule 运行在主界面 UI 线程上,如果在 ArkTS 里调用 process.tid,拿到的是 UI 线程号;而如果走异步 C++ 方法,任务又会被抛到后台异步队列。只有将 TurboModule 方法声明为同步返回,JSI 才会在当前 RN JS 线程上直接原地调用 C++ 函数。因此,我在 RNFastSchedulerTurboModule.cpp 里只用了一个极简的同步宿主函数:
// JSI 同步调用直接在当前 RN JS 线程栈上执行,此时 gettid() 返回的就是 JS 线程内核 TID
jsi::Value hostGetJsThreadTid(jsi::Runtime& /*rt*/,
react::TurboModule& /*turboModule*/,
const jsi::Value* /*args*/,
size_t /*count*/) {
return jsi::Value(static_cast<double>(gettid()));
}
RNFastSchedulerCxxModule::RNFastSchedulerCxxModule(const ArkTSTurboModule::Context ctx, const std::string name)
: RNFastScheduler(ctx, name) {
// 仅在 C++ 层同步拦截 getJsThreadTid,其余异步方法继续透传给 ArkTS TurboModule
methodMap_["getJsThreadTid"] = MethodMetadata{0, hostGetJsThreadTid};
}
配合 Codegen 规范文件将 getJsThreadTid 声明为返回数字的同步签名,生成的桥接元数据就会走同步直调路径,从而每次都能准确拿到 JS 线程号。
3.3 默认目标解析、档位冷却与配对收尾
拿到 JS 线程号后,JS 侧契约文件 schedulerContract.js 需要在发起提示前做好两件事:一是当调用方没有传 tids 时,自动填入 getJsThreadTid(),并对显式传入的线程数组做正整数校验、保序去重和 16 条上限检查;二是根据 SHORT、MEDIUM、LONG 三个时长档位强制计算最低冷却间隔(在系统要求的 3 秒、30 秒、180 秒基础上各加 200 ms 安全余量):
// SDK 要求三个档位调用间隔分别严格大于 3 / 30 / 180 秒;预留 200 ms 余量避免踩到临界值报错
const PERF_HINT_INTERVAL_MARGIN_MS = 200;
const PERF_HINT_INTERVAL_MS = Object.freeze({
[FastDurationType.SHORT]: 3000 + PERF_HINT_INTERVAL_MARGIN_MS,
[FastDurationType.MEDIUM]: 30000 + PERF_HINT_INTERVAL_MARGIN_MS,
[FastDurationType.LONG]: 180000 + PERF_HINT_INTERVAL_MARGIN_MS,
});
function resolveTargetTids(tids, getJsThreadTid) {
const normalized = normalizeTids(tids);
if (normalized.length > 0) {
return normalized; // 调用方显式指定了原生工作线程 TID 时优先使用
}
if (typeof getJsThreadTid === 'function') {
const jsTid = getJsThreadTid();
// 未传 tids 时默认回退到当前 RN JS 线程
if (typeof jsTid === 'number' && Number.isInteger(jsTid) && jsTid > 0) {
return [jsTid];
}
}
return [];
}
function normalizeMinInterval(minIntervalMs, durationType) {
const requiredIntervalMs = PERF_HINT_INTERVAL_MS[durationType];
if (minIntervalMs === undefined) {
return requiredIntervalMs;
}
// 即便调用方手动传入更小的间隔,也会被抬升到当前档位的安全下限
if (typeof minIntervalMs === 'number' && Number.isFinite(minIntervalMs) && minIntervalMs >= 0) {
return Math.max(minIntervalMs, requiredIntervalMs);
}
throw new RangeError(`minIntervalMs must be a non-negative finite number, got ${String(minIntervalMs)}`);
}
在此基础上,withPerfScene 负责把“冷却判断 → BEGIN 提示 → 执行业务回调 → finally 配对 END”串成闭环。写这段逻辑时有三个关键保护点:
- 切换档位不能绕过上一轮冷却:判断冷却时取
Math.max(minIntervalMs, lastIntervalMs)。如果上一次刚跑完 MEDIUM(需冷却 30.2 秒),哪怕下一秒切成 SHORT(3.2 秒),也必须等够上一轮的 30.2 秒;冷却期内不会报错中断业务,而是直接执行任务并返回throttled: true。 - 只有 BEGIN 成功才触发 END:如果 BEGIN 因为系统高负载或后台状态返回失败,
finally块不会盲目调用endPerfScene,避免关闭并非本次开启的场景。 - 收尾失败不吞业务结果:一旦
endPerfScene返回非 0 状态码或抛出跨端异常,包裹器会把错误整理成结构化的endError并触发可选的onEndError回调,同时原样返回业务计算结果(或继续抛出业务自身的异常)。
而在 ArkTS 侧(RNFastSchedulerTurboModule.ts),由于系统要求结束提示时传入的 durationType 与开启时保持一致,模块用 activeSceneDurations 字典按场景类型记住了开启时的档位:
export class RNFastSchedulerTurboModule extends UITurboModule implements RNFastScheduler.Spec {
static readonly NAME: string = 'RNFastScheduler';
// 记录每个活跃场景开启时的时长档位,确保 END 与 BEGIN 传入相同的 durationType
private activeSceneDurations: Map<number, number> = new Map<number, number>();
async beginPerfScene(sceneType: number, durationType: number, tidsJson: string): Promise<string> {
return this.invokeArkTsPerfHint(
sceneType,
resolveSceneStateBegin(),
durationType,
tidsJson,
);
}
async endPerfScene(sceneType: number, tidsJson: string): Promise<string> {
// 取出该场景开启时登记的档位;若无记录则以 SHORT 兜底
const matchedDuration = this.activeSceneDurations.get(sceneType) ?? resolveDurationShort();
return this.invokeArkTsPerfHint(
sceneType,
resolveSceneStateEnd(),
matchedDuration,
tidsJson,
);
}
}
需要注意的是,invokeArkTsPerfHint 内部只有在 schedulingOptimization.perfHint 真正执行成功后,才会更新或删除 activeSceneDurations 里的记录,防止一次因频控失败的 BEGIN 请求覆盖掉之前正在运行的有效档位。
3.4 锁内记起点的原生基准计时门
在实战项目的内部模块 fastkit-bench(FastKitBenchEngine.cpp)中,为了测量四条工作线程并行计算矩阵乘法的单轮耗时,协调线程与工作线程通过条件变量同步。如果协调线程先调用 notify_all() 唤醒工作线程、再去读时钟记起点,获得调度提升的线程很可能在起点记录前就已经跑完了一部分分片,导致提升组的耗时被人为少算。因此,runSingleRound 严格在持有互斥锁且唤醒工作线程之前记录起点时间戳:
double runSingleRound(int round) {
std::unique_lock<std::mutex> lock(mutex_);
// 等待 4 条工作线程全部进入就绪屏障
ctrlCv_.wait(lock, [this]() { return readyCount_ == workerCount_; });
readyCount_ = 0;
doneCount_ = 0;
// 必须在 notify_all 唤醒工作线程之前记录起点,防止被提频的线程抢跑漏计耗时
roundStart_ = std::chrono::steady_clock::now();
releasedRound_ = round;
workerCv_.notify_all();
// 最后一条完成分片的工作线程会在锁内写入 roundEnd_ 并唤醒协调线程
ctrlCv_.wait(lock, [this]() { return doneCount_ == workerCount_; });
return std::chrono::duration<double, std::micro>(roundEnd_ - roundStart_).count();
}
3.5 A/B 对称静置与滚动采样核对协议
JS 重计算负载写在实战项目的 jsWorkload.ts 中。为了只测量纯计算耗时,单次读数只包住 runFilterSortTask 的同步执行过程,跨端 BEGIN 与 END 通信、预热和静置等待都不计入该毫秒数。每对样本开始前都调用同一个准备函数:先跑一遍同规模预热,再静置 3300 ms;只要某次提示未成功开启或收尾报错,该次样本就会单独归入异常分类,不混入成功提示组的耗时均值与中位数计算。
滚动预测的核对逻辑则重点解决异步返回延迟问题。应用在每次 onScroll 回调里为事件编上连续序号。当采样点满 4 个并发起异步 predictScrollIndex 时,代码立即将目标事件序号锁定为当前末尾序号加 1。哪怕 ArkTS 异步返回较慢、返回时列表又滑过了两三次事件,核对器依然拿早已记录下来的那个目标序号真实首项索引计算偏差,保证“预测下一采样点”的定义前后一致。
四、踩坑与边界条件
4.1 线程号对上,任务才与提示有关
⚠️ perfHint 的 tids 参数只决定系统向哪些线程倾斜调度资源,不会自动迁移业务代码。接入时需要先确认耗时工作到底跑在哪条线程上:
| 任务位置 | 线程号来源 | 推荐调用方式 |
|---|---|---|
| RN 同步 JS 计算(筛选、排序、大 JSON 解析) | getJsThreadTid() | 直接使用 withPerfScene 默认目标(不传 tids) |
| 应用自建的 C++ / 原生异步工作线程 | 原生模块返回真实存活的内核线程号 | 将原生线程号数组显式传入 options.tids |
| ArkTS 主线程 UI 构建工作 | 能力探针返回的 arktsTid | 仅在确认瓶颈位于 ArkTS 主线程时显式传入 |
表6 线程选择
如果在 withPerfScene 的回调里 await 了另一个第三方原生模块(例如异步图片解码或文件解压),此时 RN JS 线程只是在挂起等待 Promise 完成,真正的重负载跑在那个模块的内部线程上。这种情况下只提示 JS 线程是无效的,必须由对应原生模块暴露其工作线程号。
4.2 时长档位与冷却间隔必须一起选
FASTKit 对 SHORT、MEDIUM、LONG 三个档位规定了严格的单次最大持续时间和最小调用间隔。react-native-fast-scheduler 在包裹器里内置了带 200 ms 余量的保守下限:
| 档位 | 单次最长持续时间 | 系统要求的最小间隔 | 包裹器内置最低间隔 |
|---|---|---|---|
| SHORT | 1 秒 | 大于 3 秒 | 3200 ms |
| MEDIUM | 10 秒 | 大于 30 秒 | 30200 ms |
| LONG | 60 秒 | 大于 180 秒 | 180200 ms |
表7 时长与间隔
冷却计时从上一次成功场景的 END 收尾结束后才开始起算,并且由长档位切回短档位时不能提前跳过上一轮冷却。需要注意的是,这套防重入和冷却守卫维护在 withPerfScene 实例内部;如果业务代码绕过包裹器直接裸调 beginPerfScene,就不会经过这层间隔保护,因此建议在业务工程里统一通过 withPerfScene 发起提示。另外,本篇在设备与模拟器上实测的是 SHORT 档位,MEDIUM 和 LONG 的长间隔边界通过注入虚拟时钟的单元测试覆盖。
4.3 收尾失败也要保留诊断上下文
哪怕 BEGIN 返回成功,随后的 END 也可能因为场景超时自动失效或跨端异常而失败。处理 withPerfScene 的返回结果时,我按下面三步排查日志:
- 先看业务返回值或业务异常:确认筛选排序等核心任务本身有没有算完,不把调度收尾异常当成业务失败。
- 再看
throttled与beginResult:区分这次调用是处于冷却期被主动跳过,还是已经向系统发出了 BEGIN 请求。 - 最后核对
endResult与endError:不能只用endResult === null判断收尾状态,因为未开启提示和 END 抛出异常都会导致endResult为空;查看结构化的endError(含kind、code、message)才能准确区分。
4.4 准备条件不一致会制造假收益
我在华为畅享 100 Pro Max 真机上跑第一版试验(v0.2.0 / v1.0.0)时,曾得到一组看起来非常漂亮的数据:两轮共 12 对 JS 重计算样本里,开启提示组的中位数是 54.9 ms,未开启组是 87.6 ms,12 对里有 11 对都是提示组更快。但回头检查日志时间戳才发现,当时只给有提示组加了 3300 ms 的冷却等待,而无提示组每次只等 300 ms 就接着跑。有提示组在每次计算前都获得了充分的 CPU 降温和垃圾回收空档,这组差值混入了休息时间差异,不能归功于 PerfHint。
改成两组都先预热再对称静置 3300 ms 后,我在模拟器上也遇到过反向波动:有一批同条件抽样里,提示组中位数达到了 71.45 ms,而无提示组只有 19.27 ms,跟第 2.3 节那批样本的方向刚好相反。我把这两批记录都保留在工程证据里,因为它们刚好说明了一件事:统一预热和对称静置能排除等待时长不公的干扰,但在模拟器虚拟化环境或宿主机后台繁忙时,系统调度的不确定性依然可能盖过单次提示的作用。做性能诊断时,如实记录全部有效样本和边界条件,比挑出一组有利数字更重要。
4.5 QoS 与滚动预测的使用边界
在原生线程调度上,不要对同一条线程同时混用鸿蒙 QoS 接口(OH_QoS_SetThreadQoS)和带 tids 的 perfHint,因为一侧的结束或重置操作可能覆盖另一侧的调度属性。这也是为什么实战项目的矩阵基准要为三种策略分别创建独立线程组。
在滚动预测上,喂给 predictScrollIndex 的采样点必须按时间戳单调非递减排列,且至少包含 2 个点。当用户在列表上突然反向滑动(折返)时,应用需要先清空旧方向的采样窗口,只用新方向的连续点发起预测,否则把上下两个方向的位移混在一起会算出偏离实际的索引。如果后续要把预测索引拿去做图片或接口预加载,还需要根据列表项高度、网络延迟和命中率单独调优预取窗口大小。
五、结论与可直接复用的建议
5.1 依赖安装与鸿蒙宿主配置
react-native-fast-scheduler 解决了 React Native 鸿蒙应用接入 FASTKit 时的三个痛点:用同步 JSI 方法准确读取 JS 线程号、按时长档位自动守卫冷却间隔并保证 BEGIN 与 END 配对收尾,以及对滚动预测样本做前置校验。在 RN 工程根目录下安装已验证的 v0.2.1 版本:
npm install 'git+https://atomgit.com/abaoge/react-native-fast-scheduler.git#v0.2.1'
接着在鸿蒙宿主工程的 entry/oh-package.json5 中引入本地 HAR 模块(若 harmony 目录位于 RN 工程根目录下,路径前缀为 ../../node_modules):
{
"dependencies": {
"@rnoh/react-native-openharmony": "0.84.6",
// 关联 react-native-fast-scheduler 的鸿蒙原生模块目录
"@rnoh/react-native-fast-scheduler": "file:../../node_modules/react-native-fast-scheduler/harmony/fast_scheduler"
}
}
随后按 RNOH 标准流程完成三处注册即可:在 RNPackagesFactory.ets 中添加 new RNFastSchedulerPackage(ctx),在 CMakeLists.txt 中添加子目录并链接 rnoh_fast_scheduler,最后在 PackageProvider.cpp 中注册 RNFastSchedulerPackage。
5.2 业务页面调用示例与接入建议
在业务代码里,推荐用 withPerfScene 包裹耗时在 1 秒以内的同步 JS 重计算(如大列表筛选、排序或本地数据聚合):
import FastScheduler, { FastDurationType, FastSceneType } from 'react-native-fast-scheduler';
// 列表筛选条件变化时调用:不传 tids 默认提示当前 RN JS 线程,SHORT 档位单次上限 1 秒
export async function refreshFilteredRows<T>(computeRows: () => T): Promise<T> {
const cap = await FastScheduler.probeCapabilities();
if (!cap.arkts.schedulingOptimizationAvailable) {
// 当前设备或系统版本不支持 FASTKit 调度优化时,直接降级执行原函数
return computeRows();
}
const { value, endError } = await FastScheduler.withPerfScene(
{
sceneType: FastSceneType.PAGE_DRAWING,
durationType: FastDurationType.SHORT,
},
() => computeRows(),
);
if (endError) {
// 业务结果已正常产出,仅记录收尾阶段的系统回执异常供排查
console.warn('[FastScheduler] endPerfScene diagnostic:', endError.code, endError.message);
}
return value;
}
日常项目接入时,建议重点留意下面四条边界:
- 💡 同步 JS 计算直接用默认目标,异步原生任务显式传线程号:不传
tids时包裹器默认提示当前 JS 线程;如果耗时逻辑在应用自建的 C++ 线程池里跑,需要把那些存活工作线程的线程号传给options.tids。 - 按任务实际持续时间选档位:几百毫秒的短计算用 SHORT(冷却 3.2 秒);若切换到 MEDIUM(最长 10 秒)或 LONG(最长 60 秒),要同步留出 30.2 秒或 180.2 秒的冷却窗口。
- 区分业务结果与调度回执:冷却期跳过(
throttled: true)或 BEGIN 被系统拒绝时,业务函数仍会正常执行;做性能统计时要把这些未生效样本单独拆开。 - 预测索引先裁剪再消费:
predictScrollIndex返回的原始索引可能超出列表首尾边界,用于预加载或视图定位前先按列表长度范围裁剪,并在滑动方向反转时清空历史采样窗口。
本文 v0.2.1 与 v1.0.1 的对称协议复验在 HarmonyOS API 26 手机模拟器上完成,真机链路验证基于 v0.2.0 与 v1.0.0 在华为畅享 100 Pro Max(API 26)上完成;Android 与 iOS 端仅保留空操作降级回退,未做运行回归。完整的诊断台源码、原生矩阵基准模块与复现说明见 abaoge/fastkit-diagnostic-studio。
小结
做完这个诊断台,我最大的体会是调通性能接口和验证它真正生效中间隔着好几道关卡:拿到返回码 0 只是第一步,还得确认提示的线程号是不是正在干活的那条线程、两组对比的预热与静置条件是否对称、异步预测比对的是不是同一次目标采样。把通用线程号读取、冷却守卫和配对收尾沉淀到 react-native-fast-scheduler 后,业务工程几行代码就能安全接入,而诊断台保留下来的三路对照与采样协议,也帮我养成了先对齐线程和测量口径、再评估优化收益的习惯。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)