本原创文章帖发布在华为开发者联盟社区，欢迎开发者前往访问评论交流，更多与该内容相关讨论，请点击原帖查看：

剖析libuv Native回调阻塞导致Freeze的分析逻辑-华为开发者话题 | 华为开发者联盟

   在 HarmonyOS 应用开发中，libuv 作为底层异步 IO 的核心引擎，虽然性能卓越，但如果使用不当，极易引发 Freeze（界面卡顿/冻结）。

      很多开发者认为“异步就是安全”，但实际上 主线程阻塞 和 事件循环死锁 是两个高频雷区。今天通过两个Freeze 案例，结合完整的堆栈分析和代码重构方案，帮助搞懂如何安全使用 libuv。

—————————————————————————————————————————————

核心原则：libuv 需正确使用

      主线程禁阻塞：libuv 的同步接口（如 uv_fs_sendfile）会阻塞当前线程。若在主线程调用，直接导致 UI 冻结。

      单例需线程安全：uv_async_t 等句柄与 uv_loop_t强绑定。若同一句柄在不同 Loop 间重复初始化，会导致链表交织，引发无限死循环。

—————————————————————————————————————————————

案例一：主线程调用 uv 阻塞接口

问题描述

      某应用在发送视频文件时，界面完全卡死。日志显示主线程阻塞在 uv_fs_sendfile。

完整堆栈分析

Tid:19473, Name:app_name
#00 pc 00000000000a457c /system/lib/ld-musl-aarch64.so.1
#01 pc 0000000000019f88 /system/lib64/platformsdk/libuv.so(uv__fs_work+2956)
#02 pc 000000000001c048 /system/lib64/platformsdk/libuv.so(uv_fs_sendfile+148)  <-- 阻塞点
#03 pc 000000000011d27c /system/lib64/module/file/libfs.z.so(OHOS::FileManagement::ModuleFileIO::OpenFile...)
#04 pc 000000000011c99c /system/lib64/module/file/libfs.z.so(OHOS::FileManagement::ModuleFileIO::CopyFile::Sync...)
#05 pc 000000000003dec8 /system/lib64/platformsdk/libace_napi.z.so(panda::JSValueRef ArkNativeFunctionCallBack...)
...
#07 at handleSendVideo (entry|feat_chat|1.0.0|src/main/ets/viewmodel/ChatViewModel.ts:874:1) <-- 业务入口
...

      关键路径解读：

         • 业务层：ChatViewModel.ts 中的 handleSendVideo 函数被触发。

         • Native 层调用：通过 NAPI 调用到 libfs.z.so 中的 CopyFile::Sync。

         • 底层阻塞：最终调用 libuv.so 的 uv_fs_sendfile。这是一个同步文件系统操作，它在执行期间会占用 CPU 资源并等待 I/O 完成，若数据量大或磁盘慢，将长时间阻塞主线程。

根本原因

      开发者在 主线程（UI线程） 中直接调用了文件模块的 同步接口（Sync API）。uv_fs_sendfile 是阻塞式操作，直接切断了主线程的事件循环，导致 UI 无法刷新，产生 Freeze。

解决方案：代码重构

      错误写法（当前代码）：

// ChatViewModel.ts
async handleSendVideo() {
    // 直接在主线程调用同步拷贝接口，导致主线程阻塞
    const result = await ohos.fileio.copyFileSync(srcPath, destPath); 
    console.log("Copy done");
}

      正确写法（推荐方案）：
      使用 taskpool 或 worker 将耗时操作移出主线程。

// 1. 定义任务池任务类
import { taskpool } from '@kit.TaskPoolKit';

class CopyFileTask implements taskpool.Task {
    srcPath: string;
    destPath: string;

    constructor(src: string, dest: string) {
        this.srcPath = src;
        this.destPath = dest;
    }

    execute(): void {
        // 在后台线程执行同步 IO，不影响主线程
        try {
            ohos.fileio.copyFileSync(this.srcPath, this.destPath);
        } catch (e) {
            console.error(`Copy failed: ${JSON.stringify(e)}`);
        }
    }
}

// 2. 业务层调用
async handleSendVideo() {
    try {
        // 提交任务到 taskpool，立即返回，不阻塞主线程
        const task = new CopyFileTask(srcPath, destPath);
        await taskpool.execute(task);
        console.log("Copy task submitted and completed in background");
    } catch (e) {
        console.error(`Task pool error: ${JSON.stringify(e)}`);
    }
}

案例二：PDF 场景下必现的“事件循环死锁”

问题描述

      应用在 taskpool 场景中调用第三方 SDK 的 so 接口时，必现卡死。堆栈显示线程卡在 libuv 的事件循环 uv_run 中。

完整堆栈分析

Tid:61139, Name:example.pdftest
#00 pc 0000000000018044 /system/lib64/platformsdk/libuv.so(uv_async_io+360)
#01 pc 0000000000017720 /system/lib64/platformsdk/libuv.so(uv_io_poll+1268)
#02 pc 0000000000018540 /system/lib64/platformsdk/libuv.so(uv_run+376)  <-- 卡死点
#03 pc 00000000000768b4 /system/lib64/platformsdk/libruntime.z.so(OHOS::AbilityRuntime::OHOSLoopHandler::OnTriggered...)
...

深度剖析：为什么死循环？

      通过反编译 libuv.so 源码，卡死位置位于 uv__async_io 函数内部：

// libuv 内部源码片段
uv__queue_move(&loop->async_handles, &queue);
while (!uv__queue_empty(&queue)) {
    q = uv__queue_head(&queue);       // 1. 获取队头节点
    h = uv__queue_data(q, uv_async_t, queue);
    uv__queue_remove(q);         // 2. 从临时队列移除
    
    /* Atomically fetch and clear pending flag */
    pending = (_Atomic int *)&h->pending;
    if (atomic_exchange(pending, 0) == 0)
        continue;             // 如果 pending 为 0，跳过回调

    if (h->async_cb == NULL)
        continue;

    h->async_cb(h);          // 3. 【关键】执行用户回调
}

      死锁复现过程：

      遍历 async_handles 队列，取出节点 h。

      执行 h->async_cb(h)。

      问题点：在该回调函数内部，SDK 代码可能重新调用了 uv_async_send 或类似操作，导致 h 节点再次被添加到 loop->async_handles 队列中。

      由于 queue 是 loop->async_handles 的一个引用（move 操作），重新添加的节点直接进入了当前正在遍历的 queue。

      while (!uv__queue_empty(&queue)) 永远为真，形成 死循环。

      验证日志：
      通过 GDB 调试和日志打印，发现同一个 uv_async_t 句柄在 主线程 Loop 和 TaskWorker 线程 Loop 中都被初始化了。

根本原因

      SDK 中的单例 LibuvSingleton 设计存在缺陷：

      未使用 call_once：uv_async_init 在每次 getInstance() 后的 initialize 中被调用。

      跨 Loop 共享句柄：uv_async_t 是线程局部或 Loop 局部的资源。当它在不同线程（不同 Loop）中被重复初始化时，内部链表结构被破坏，导致不同 Loop 的队列相互交织。

解决方案：代码重构

      错误代码（SDK 内部单例实现）：

class LibuvSingleton {
public:
    static LibuvSingleton &getInstance() {
        static LibuvSingleton instance;
        return instance;
    }

    void initialize(uv_loop_t *loop) {
        loop_ = loop;
        // 危险：每次调用都会重新初始化同一个句柄
        // 如果主线程和子线程都调用了 initialize，同一个 async_handle 会被注册到两个不同的 Loop
        uv_async_init(loop, &async_handle, LibuvSingleton::processTask);
        async_handle.data = this;
    }

private:
    uv_async_t async_handle;
    uv_loop_t *loop_;
    // ... 其他成员
};

      正确代码（修复版）：

      确保单例初始化只执行一次：使用 std::call_once 或标志位。

      确保 Loop 与句柄绑定关系正确：通常建议每个线程/Loop 拥有独立的句柄，或者确保句柄只在特定的 Loop 中初始化且不被重复操作。

#include <mutex>
#include <atomic>

class LibuvSingleton {
public:
    static LibuvSingleton &getInstance() {
        static LibuvSingleton instance;
        return instance;
    }

    // 使用 call_once 确保 initialize 只被调用一次
    void initialize(uv_loop_t *loop) {
        std::call_once(init_flag_, [this, loop]() {
            this->loop_ = loop;
            // 仅在第一次初始化时创建句柄
            // 注意：如果需要在不同 Loop 使用，应创建不同的句柄实例，
            // 而不是复用同一个 static 成员。
            // 此处假设该单例仅服务于单一 Loop 上下文，或需改为线程局部存储
            uv_async_init(loop, &async_handle, LibuvSingleton::processTask);
            async_handle.data = this;
        });
    }

    // ... 其他方法保持不变

private:
    LibuvSingleton() {}
    
    static std::once_flag init_flag_; // 静态成员，用于控制初始化
    uv_async_t async_handle;
    uv_loop_t *loop_;
    // ...
};

// 静态成员初始化
std::once_flag LibuvSingleton::init_flag_;

      更高级的修复（针对多 Loop 场景）：
      如果 SDK 确实需要在多个线程/Loop 中使用异步通知，不能复用同一个 uv_async_t 实例。应改为：使用 thread_local 存储每个线程自己的 uv_async_t 句柄。

      或者，在 initialize 中检查句柄是否已初始化，若已初始化则复用（但需确保 loop 相同，否则报错）。

排查建议

      如果你遇到以下现象，请检查是否存在类似的多 Loop 重复初始化问题：

      应用卡死在 uv_run 或 uv_io_poll。

      创建了多个 napi_threadsafe_function 或 uv_async_t，但回调函数偶尔不执行或执行异常。

      堆栈中出现链表遍历相关的死循环。

—————————————————————————————————————————————

总结与实践

      主线程零阻塞：任何涉及文件 IO、网络请求、复杂计算的同步操作，必须使用 taskpool、worker 或异步 API。

      单例初始化保护：涉及系统底层句柄（如 uv_async_t、pthread_mutex 等）的单例，务必使用 std::call_once 或互斥锁保护，防止多线程竞态条件。

      句柄生命周期管理：uv_async_t 等句柄与 uv_loop_t 强关联。切勿在多个不同的 uv_loop_t 中初始化同一个句柄实例。

      代码审查重点：在 Code Review 时，重点关注 Native C++ 层中全局变量、静态变量在多线程环境下的初始化逻辑。

----------------------------------------------------------------------------------------------------------

🔗 官网开发者学堂视频：https://developer.huawei.com/consumer/cn/training/result?type2List=201783644516849879&orderBy=1&courseType=5?ha_source=zxqy-IT&ha_sourceId=89000468

🔗 社区DFX专题文章： https://developer.huawei.com/consumer/cn/forum/subject/2101218731402391001?ha_source=zxqy-IT&ha_sourceId=89000468

【扫码加入 HarmonyOS DFX 技术交流群】