@ohos/aki 源码解读(三):异步与生命周期——Promise、调度中心与保价服务

4 阅读11分钟

@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 都处理了:

  1. 重复 resolve:主线程和子线程同时 resolve 同一个 deferred。Promise::Resolve 用 settled_ 的 compare_exchange_strong 保证只有一个线程能签收,另一个被安全跳过。
  2. 共享状态竞态:多个子线程同时操作 runners map(创建/删除 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 派回即可
PersistentJS 对象被 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 的异步交付。

对使用者的三条实用结论:

  1. 跨线程传数据,不要传 aki::Value。Value 是线程绑定的,传过去就是跨线程访问 JS 堆。要传就传纯 C++ 数据,或者用 Persistent 持有引用。
  2. 异步函数用 JSBIND_PFUNCTION,不要在普通 JSBIND_FUNCTION 里手动开线程 resolve——那容易重复签收和竞态。让框架的 AsyncWorker + Promise 去管。
  3. 长期持有 JS 对象必须包 Persistent。否则 GC 一回收,C++ 侧手里的 napi_value 就悬空了。

下一篇如果要继续深入,可以看 AsyncWorker 的 execute/complete 两阶段模型:napi_async_work 怎么在 worker 线程跑计算、怎么把结果交回 JS 线程,以及它和 Promise 是怎么配合的。


项目地址:@ohos/aki