@ohos/aki 源码解读(三):异步与生命周期——Promise、调度中心与保价服务
先看两个你多半踩过的坑
做 ArkTS 与 C++ 混合开发,异步场景几乎必然遇到这两类问题:
坑一:你在 C++ 侧 new Promise(),在子线程里 promise.Resolve(result),结果 ArkTS 侧的 await 迟迟没返回,或者偶发崩溃。
坑二:你把一个 aki::Value 从主线程传到子线程去用,程序没跑几次就崩了。看日志,是多线程检测报错。
这两个坑的共同点是:都发生在"跨线程"这个边界上。JS 对象和 napi_env 是线程绑定的,而 C++ 的计算任务又经常要跑在子线程。怎么让两边安全交接,是 AKI 必须回答的问题。
前两篇分别讲了"宏、模板、索引"和"类型系统"。这一篇讲支撑异步的第三套机制:Promise 怎么防重复签收、TaskRunner 怎么做跨线程调度、Persistent 怎么用引用计数防 GC、ArgStorage 怎么做所有权转移。
本文内容:先用"跨国快递"的类比建立图景,再分四节看这四个角色怎么工作,最后回到"跨线程传值为什么会崩"这个具体问题。读完你会确切知道:settled_ 为什么用原子标志、TaskRunner 为什么必须在 JS 线程创建、Persistent 的引用计数怎么算、以及跨线程传值到底该传什么不该传什么。
📦 仓库地址 | 本文基于 v1.3.3 头文件在
include/aki/,实现文件在src/,下文路径分别相对这两个目录。
一、先建立图景:跨国快递
把 AKI 的异步机制想象成跨国快递:
- C++ 侧的计算结果是要寄出的包裹。
- ArkTS 侧的
await是收件人。 - 跨国运输要经过海关、转运仓、保价服务几个环节。
四个角色对应:
| 角色 | AKI 组件 | 职责 |
|---|---|---|
| 快递单 | Promise | 承诺必达,只能签收一次,重复签收无效 |
| 调度中心 | TaskRunner | 决定包裹走哪条线路(哪个线程),把任务派回 JS 线程 |
| 保价服务 | Persistent | 用引用计数给包裹保价,计数归 0 才允许销毁 |
| 转运仓 | ArgStorage | 临时存放待构造的对象,Init 入库、TaskClass 出库转移所有权 |
"子线程 resolve 偶发崩溃"和"跨线程传值崩溃",在这个图景里就是:快递单被签收了两次(线程安全问题),或者包裹在跨国运输中被海关扣了(env 线程绑定问题)。
下面分四节,分别看这四个角色怎么工作。
二、Promise:只能签收一次的快递单
Promise 是 AKI 对 ArkTS Promise 的 C++ 封装。它最重要的设计是防止重复 resolve/reject。
📄 value/promise.h
class AKI_EXPORT Promise {
public:
Promise();
explicit Promise(napi_value promise);
~Promise();
Promise(const Promise& other); // 拷贝构造
Promise& operator=(const Promise& other); // 拷贝赋值
template<typename T> void Resolve(T&& t) const;
template<typename T> void Reject(T&& t) const;
private:
napi_env env_ = nullptr;
napi_value promise_ = nullptr;
napi_deferred deferred_ = nullptr;
mutable napi_ref promiseRef_ = nullptr;
std::shared_ptr<std::atomic<bool>> settled_; // ← 原子签收标志
};
注意最后那个字段:std::shared_ptr<std::atomic<bool>> settled_。
settled_ 是 shared_ptr<atomic<bool>>,意味着多个 Promise 对象可以共享同一个签收状态。为什么要共享?因为 Then/Catch 会返回新的 Promise 对象(链式调用),它们底层是同一个 deferred,签收状态必须共享——否则链上每一环都以为自己能 resolve 一次。
Resolve 和 Reject 的实现:
📄 value/napi/napi_value_trait.h
template<typename T>
void Promise::Resolve(T&& t) const
{
bool expected = false;
if (!settled_ || !settled_->compare_exchange_strong(expected, true)) {
AKI_LOG(ERROR) << "Promise::Resolve: promise already settled, skip duplicate resolve";
return;
}
napi_env env = aki::Binding::GetScopedEnv();
if (env == nullptr) env = env_;
if (env == nullptr || deferred_ == nullptr) {
AKI_LOG(ERROR) << "Promise::Resolve: env or deferred is nullptr";
return;
}
napi_value result = NapiValue<typename ValueDefiner<T>::RawType>::ToNapiValue(env, std::forward<T>(t));
napi_resolve_deferred(env, deferred_, result);
CleanupRef();
}
compare_exchange_strong(expected, true) 是关键:只有当前状态是 false 时,才把它改成 true 并继续;如果已经是 true(已签收),直接返回并打一条 promise already settled, skip duplicate resolve 日志。
用人话说:快递单只允许签收一次,第二次签收直接忽略并提示。
为什么这对"子线程 resolve 偶发崩溃"重要?因为子线程和主线程可能同时尝试 resolve 同一个 deferred。如果没有原子标志,两个线程都进入 resolve 流程,napi_resolve_deferred 被调两次,deferred 状态就乱了。compare_exchange_strong 保证只有一个线程能真正签收,另一个被安全地跳过。
Reject 走完全相同的模式。CleanupRef() 在签收成功后调用,释放 promiseRef_ 的 napi_ref,防止引用泄漏。
三、TaskRunner:跨线程调度中心
TaskRunner 负责把任务从子线程派回 JS 线程。它是"调度中心"。
📄 task_runner/task_runner.h
class AKI_EXPORT TaskRunner {
public:
using Closure = std::function<void ()>;
static const TaskRunner* Create(std::string taskName);
static bool RemoveTaskRunner(const std::string& taskName);
static void PostTask(const std::string& taskName, Closure task);
private:
explicit TaskRunner(napi_env env);
static std::unordered_map<std::string, std::unique_ptr<TaskRunner>> runners;
static std::mutex runnersMutex_;
napi_threadsafe_function tsfn_ = nullptr;
};
tsfn_ 是 napi_threadsafe_function——NAPI 提供的跨线程函数调用句柄,作用就是"允许你在子线程里安全地调用 JS 函数"。
创建时的关键约束:
📄 src/task_runner/task_runner.cpp
const TaskRunner* TaskRunner::Create(std::string taskName)
{
napi_env env = Binding::GetScopedEnv();
AKI_DCHECK(env != nullptr) << "should be created at js thread.";
if (env == nullptr) {
AKI_LOG(ERROR) << "TaskRunner::Create: env is nullptr";
return nullptr;
}
...
}
Create 必须在 JS 线程调用,因为它需要 napi_env 来创建 napi_threadsafe_function。源码里用 AKI_DCHECK 直接断言"should be created at js thread"。
PostTask 的实现:
📄 src/task_runner/task_runner.cpp
void TaskRunner::PostTask(Closure task) const
{
if (tsfn_ == nullptr) {
AKI_LOG(ERROR) << "TaskRunner::PostTask: tsfn_ is nullptr";
return;
}
napi_status status = napi_acquire_threadsafe_function(tsfn_);
if (status != napi_ok) {
AKI_LOG(ERROR) << "napi_acquire_threadsafe_function failed, status: " << status;
return;
}
Closure* taskPtr = new Closure(std::move(task));
// 随后通过 napi_call_threadsafe_function 派回 JS 线程
...
}
napi_acquire_threadsafe_function + napi_call_threadsafe_function 是跨线程调用的标准两步:先获取调用权,再把任务投递到 JS 线程的消息队列,由 JS 线程在合适时机执行。
runners 是静态 map,配 runnersMutex_ 互斥锁:
📄 src/task_runner/task_runner.cpp
std::unordered_map<std::string, std::unique_ptr<TaskRunner>> TaskRunner::runners;
std::mutex TaskRunner::runnersMutex_;
bool TaskRunner::RemoveTaskRunner(const std::string& taskName)
{
std::lock_guard<std::mutex> lock(runnersMutex_);
auto it = runners.find(taskName);
...
}
为什么要有互斥锁? 因为多个子线程可能同时 Create/RemoveTaskRunner/PostTask,操作同一个 runners map。没有锁保护,map 的读写就会竞态——这是"子线程 resolve 偶发崩溃"的另一类根因:不是 Promise 的问题,是调度中心的共享状态被多线程同时改了。
四、Persistent:用引用计数给包裹保价
Persistent 持有 napi_ref,用引用计数防止 JS 对象被 GC 回收。这是"保价服务"。
📄 persistent/persistent.h
class AKI_EXPORT Persistent {
public:
Persistent() = default;
explicit Persistent(napi_value value);
Persistent(const Persistent& that);
Persistent& operator=(const Persistent& that);
~Persistent();
inline bool IsValid() const { return ref_ != nullptr; }
napi_value GetValue() const;
private:
void ReleaseRef();
void CopyRefFrom(const Persistent& that);
napi_ref ref_ = nullptr;
napi_env env_ = nullptr;
bool refCounted_ = false;
};
refCounted_ 这个布尔标记很关键——它记录"这个引用是否由本对象负责计数",防止同一个 napi_ref 被多个 Persistent 对象重复释放。
构造与拷贝:
📄 src/persistent/persistent.cpp
Persistent::Persistent(napi_value value)
{
napi_env env = JSBind::GetScopedEnv();
if (env == nullptr) return;
env_ = env;
napi_create_reference(env, value, 1, &ref_); // 初始计数 1
refCounted_ = true;
}
Persistent::Persistent(const Persistent& that)
{
napi_env scopedEnv = JSBind::GetScopedEnv();
if (scopedEnv != nullptr) {
env_ = scopedEnv; // 优先当前线程的 scoped env
} else {
env_ = that.env_; // 否则用原对象的 env
}
CopyRefFrom(that);
}
注意 env 的选择顺序:优先 GetScopedEnv()(当前线程的 env),没有才用原对象的 env_。这是为了跨线程安全——napi_ref 的操作必须在与它创建时相同的 env 里执行,换线程就要用新线程的 scoped env。
析构时的释放:
📄 src/persistent/persistent.cpp
void Persistent::ReleaseRef()
{
if (ref_ == nullptr) return;
if (!refCounted_) {
AKI_LOG(WARNING) << "Persistent: ref not ref-counted by this object, skip unref/delete";
ref_ = nullptr;
return;
}
napi_env env = JSBind::GetScopedEnv();
if (env == nullptr) env = env_;
if (env == nullptr) {
AKI_LOG(ERROR) << "Persistent: no env available, cannot unref/delete reference";
ref_ = nullptr;
refCounted_ = false;
return;
}
uint32_t count = 0;
napi_reference_unref(env, ref_, &count); // 计数 -1
if (count == 0) {
napi_delete_reference(env, ref_); // 归 0 才真正 delete
}
ref_ = nullptr;
refCounted_ = false;
}
计数归 0 才 napi_delete_reference,否则只减不删。拷贝时 napi_reference_ref 计数 +1。这就是标准的 RAII 引用计数。
refCounted_ 防的是"重复释放":如果一个 napi_ref 被两个 Persistent 共享(比如拷贝构造),其中一个析构时不能把对方的引用也删了。refCounted_ = false 的对象在析构时只置空自己的 ref_,不去动别人的计数。
"保价"的含义:只要计数不归 0,JS 对象就不会被 GC 回收,C++ 侧就能一直安全地持有和使用它。
五、ArgStorage:转运仓的所有权转移
ArgStorage 用于跨 NAPI 边界转发构造函数参数。它是"转运仓"。
📄 arg_storage/arg_storage.h
class ArgStorage {
public:
explicit ArgStorage(uint32_t overloadId) : overloadId_(overloadId) {}
virtual ~ArgStorage() = default;
uint32_t GetOverloadGroupId() const { return overloadId_; }
virtual void* GetTemplate() = 0;
private:
const uint32_t overloadId_;
};
template <typename C>
class TemplatedArgStorage : public ArgStorage {
public:
explicit TemplatedArgStorage(uint32_t overloadId)
: ArgStorage(overloadId), data_(nullptr) {}
~TemplatedArgStorage()
{
if (data_) delete data_; // 如果 data_ 还在,析构时释放
}
template <typename... Args>
void Init(Args&&... args)
{
data_ = new C(std::forward<Args>(args)...); // 入库:构造 C 实例
}
C* TaskClass()
{
C* temp = data_;
data_ = nullptr; // 出库:置空,所有权交出
return temp;
}
private:
C* data_;
};
Init 和 TaskClass 是一对"入库 / 出库"操作:
Init(args...):new C(args...)构造实例存入data_TaskClass():返回data_并把data_置nullptr,所有权从 ArgStorage 转移给调用方
为什么 TaskClass 要置空 data_? 为了防止双重释放。如果 TaskClass() 不置空,调用方拿到指针后可能会 delete,而 ~TemplatedArgStorage() 里 if (data_) delete data_; 又会 delete 一次——同一块内存被释放两次,崩溃。
置空之后,析构时 data_ 是 nullptr,if (data_) 为假,不会重复 delete。这是"出库即移交所有权"的标准实现。
overloadId_ 标记这个存储属于哪个重载组,配合上一篇讲的 NapiOverloader 按 arity 分发使用。
六、回到最初的问题:跨线程传值为什么会崩
开头提了两个坑,现在可以分别给出机制层面的答案。
坑一:子线程 resolve 偶发崩溃
可能的根因有两个,AKI 都处理了:
- 重复 resolve:主线程和子线程同时 resolve 同一个 deferred。
Promise::Resolve用settled_的compare_exchange_strong保证只有一个线程能签收,另一个被安全跳过。 - 共享状态竞态:多个子线程同时操作
runnersmap(创建/删除 TaskRunner)。runnersMutex_互斥锁保护 map 读写。
坑二:跨线程传 aki::Value 崩溃
aki::Value 包装的是 napi_value,而 napi_value 是线程绑定的——它属于创建它的那个 JS 线程。把 Value 从主线程传到子线程访问,等于跨线程访问 JS 堆,NAPI 的多线程检测就会报错。
正确的做法不是传 Value,而是传纯 C++ 数据:
💡 跨线程传值写法对照(非库源码原文)
// ❌ 把 aki::Value 带到子线程
std::thread([jsValue]() { auto d = jsValue.As<int>(); }).detach();
// ✅ 在 JS 线程取出纯数据,只把数据带到子线程
int data = jsValue.As<int>();
std::thread([data]() { compute(data); }).detach();
如果确实需要跨线程持有 JS 对象,AKI 提供了 Persistent——它内部用 napi_ref 引用计数,并且优先使用当前线程的 scoped env 来做 ref/unref 操作,规避了"在错误的 env 里操作引用"的问题。
所以"跨线程传值"的正确姿势是:传数据用值拷贝,传对象用 Persistent,调度任务用 TaskRunner,签收结果用 Promise 的原子标志。四个角色各管一段,合起来才是完整的跨线程方案。
七、这四个角色怎么支撑"一行绑定"
回头看,AKI 把异步开发的四个易错点分别做成了可复用的组件:
| 角色 | 解决的易错点 | 使用者要做的 |
|---|---|---|
Promise | 重复 resolve 导致状态混乱 | 不用管,settled_ 原子标志自动防重 |
TaskRunner | 子线程直接调 JS 函数导致崩溃 | Create 在 JS 线程,PostTask 派回即可 |
Persistent | JS 对象被 GC 回收后 C++ 还在用 | 需要长持有时包一层,计数归 0 自动释放 |
ArgStorage | 构造参数跨边界传递时双重释放 | Init 入库,TaskClass 出库即移交所有权 |
裸写 NAPI 时,每一段你都要自己处理:deferred 的状态管理、threadsafe function 的创建与释放、napi_ref 的引用计数、跨边界对象的所有权。AKI 把这些都封装好了,业务侧只需要写:
💡 异步绑定宏使用示例(非库源码原文)
JSBIND_PFUNCTION(fetchUser) // 异步函数绑定,返回 Promise
"PFunction"和普通 Function 的区别,就是它内部走 AsyncWorker + Promise 这套机制。这也是 JSBIND_FUNCTION 与 JSBIND_PFUNCTION 两个宏并存的原因——同步走 FunctionDefiner,异步走 PFunctionDefiner,底层复用同一套 Binder/索引机制,但多了 Promise 的异步交付。
对使用者的三条实用结论:
- 跨线程传数据,不要传
aki::Value。Value 是线程绑定的,传过去就是跨线程访问 JS 堆。要传就传纯 C++ 数据,或者用Persistent持有引用。 - 异步函数用
JSBIND_PFUNCTION,不要在普通JSBIND_FUNCTION里手动开线程 resolve——那容易重复签收和竞态。让框架的 AsyncWorker + Promise 去管。 - 长期持有 JS 对象必须包
Persistent。否则 GC 一回收,C++ 侧手里的napi_value就悬空了。
下一篇如果要继续深入,可以看 AsyncWorker 的 execute/complete 两阶段模型:napi_async_work 怎么在 worker 线程跑计算、怎么把结果交回 JS 线程,以及它和 Promise 是怎么配合的。
项目地址:@ohos/aki