【OpenHarmony】OpenHarmony ETS Utils实现

fakerth2025-12-13 8:56

OpenHarmony ETS Utils 模块

1. 模块概述

源码：https://gitee.com/openharmony/commonlibrary_ets_utils

1.1 功能与目标

1.1.1 主要功能

OpenHarmony ETS Utils 是一个综合性的工具库，为OpenHarmony系统提供核心的JavaScript/TypeScript运行时工具支持。该模块包含以下四个主要子模块：

子模块 功能描述
js_api_module 提供URL解析、URI处理、XML解析/序列化、Buffer数据处理等API功能
js_util_module 提供通用工具类，包括容器数据结构、JSON处理、流处理等
js_sys_module 提供系统级功能，包括进程管理、控制台输出、定时器等
js_concurrent_module 提供并发编程支持，包括TaskPool任务池、Worker线程、异步锁等

1.1.2 设计目标

  1. 高性能: 采用C++实现核心功能，通过N-API与JavaScript层交互
  2. 跨平台: 支持OHOS、Windows、Mac、iOS、Android等多平台
  3. 线程安全: 提供完善的并发控制机制
  4. 易用性: 提供简洁的JavaScript API接口

1.1.3 使用场景

  • URL/URI解析与处理
  • XML文档的解析与生成
  • 二进制数据的Buffer操作
  • 多线程任务调度与执行
  • 进程信息获取与管理
  • 定时器功能实现
  • 异步锁与并发控制

1.2 系统位置

1.2.1 在系统中的位置

ETS Utils模块位于OpenHarmony的commonlibrary 子系统中，是系统的核心基础模块，为上层应用和框架提供基础工具支持。

1.2.2 与其他模块的关系 - 系统框图

复制代码 
┌─────────────────────────────────────────────────────────────────┐
│                      应用层 (Application Layer)                   │
├─────────────────────────────────────────────────────────────────┤
│                      框架层 (Framework Layer)                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  ACE Engine │  │   ArkUI     │  │   其他框架   │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
├─────────┼────────────────┼────────────────┼─────────────────────┤
│         │                │                │                      │
│         ▼                ▼                ▼                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    ETS Utils 模块                         │   │
│  │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────┐ │   │
│  │  │js_api_mod  │ │js_util_mod │ │js_sys_mod  │ │js_conc │ │   │
│  │  │  ·URL      │ │  ·容器     │ │  ·Process  │ │·TaskPool│ │   │
│  │  │  ·URI      │ │  ·JSON     │ │  ·Console  │ │·Worker │ │   │
│  │  │  ·XML      │ │  ·Stream   │ │  ·Timer    │ │·Locks  │ │   │
│  │  │  ·Buffer   │ │            │ │            │ │        │ │   │
│  │  └────────────┘ └────────────┘ └────────────┘ └────────┘ │   │
│  └──────────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────┤
│                      系统服务层 (System Services)                 │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │  NAPI   │ │  libuv  │ │  FFRT   │ │ HiLog   │ │ HiSysEv │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
└─────────────────────────────────────────────────────────────────┘

1.2.3 依赖组件

依赖组件 用途
napi N-API接口，实现JS与C++交互
libuv 异步I/O和事件循环
ffrt 函数流运行时，任务调度
hilog 日志系统
hisysevent 系统事件上报
icu 国际化支持
openssl 加密支持
libxml2 XML解析库

1.3 设计思路与模式

1.3.1 设计思路

  1. 分层架构设计

    • JavaScript层: 提供用户友好的API接口
    • N-API绑定层: 实现JS与C++的桥接
    • C++核心层: 实现核心业务逻辑
    • 平台适配层: 处理跨平台差异

  2. 模块化设计

    • 各子模块功能独立，低耦合
    • 统一的错误处理机制
    • 共享公共工具类

  3. 异步优先设计

    • 大量使用异步操作避免阻塞
    • 基于libuv实现事件驱动
    • 支持Promise和回调两种异步模式

1.3.2 设计模式

设计模式 应用场景 示例
单例模式 全局唯一管理器 TaskManager::GetInstance()
工厂模式 对象创建 Task::GenerateTask()
观察者模式 事件监听 Worker的事件监听机制
策略模式 任务调度策略 任务优先级调度
状态模式 状态管理 Task的ExecuteState状态机
命令模式 任务封装 TaskInfo封装任务信息

2. 模块结构

2.1 源文件与头文件

2.1.1 js_concurrent_module (并发模块)

TaskPool 子模块
文件 功能描述
task.h/cpp 任务类定义，封装可执行任务
taskpool.h/cpp 任务池主入口，提供Execute/Cancel等API
task_manager.h/cpp 任务管理器，单例模式，管理所有任务和工作线程
task_queue.h/cpp 任务队列，按优先级管理待执行任务
task_group.h/cpp 任务组，支持批量任务执行
sequence_runner.h/cpp 序列运行器，保证任务顺序执行
async_runner.h/cpp 异步运行器，支持异步任务执行
worker.h/cpp 工作线程，执行具体任务
thread.h/cpp 线程基类，封装uv_thread
Worker 子模块
文件 功能描述
worker.h/cpp Worker线程实现，支持消息传递
worker_runner.h/cpp Worker运行器
message_queue.h/cpp 消息队列，线程间通信
Utils 子模块
文件 功能描述
utils.h/cpp 工具类入口
locks/async_lock.h/cpp 异步锁实现
locks/async_lock_manager.h/cpp 异步锁管理器
locks/lock_request.h/cpp 锁请求封装
condition/*.h/cpp 条件变量实现

2.1.2 js_api_module (API模块)

子目录 主要文件 功能描述
url/ js_url.h/cpp URL解析与操作
uri/ js_uri.h/cpp URI解析与操作
xml/ js_xml.h/cpp XML序列化与解析
buffer/ js_buffer.h/cpp Buffer数据操作
convertxml/ js_convertxml.h/cpp XML转换工具

2.1.3 js_sys_module (系统模块)

子目录 主要文件 功能描述
process/ js_process.h/cpp 进程信息获取与管理
console/ console.h/cpp 控制台输出
timer/ sys_timer.h/cpp 定时器实现
dfx/ native_module_dfx.cpp DFX诊断功能

2.1.4 js_util_module (工具模块)

子目录 主要文件 功能描述
container/ 各容器实现文件 ArrayList, HashMap, TreeMap等容器
json/ native_module_json.cpp JSON处理
stream/ native_module_stream.cpp 流处理
util/ js_util.h/cpp 通用工具函数

2.2 类、结构体、函数与方法

2.2.1 核心类设计

Task 类 (任务类)
cpp 复制代码 
class Task {
public:
    // 构造函数
    Task() = default;
    Task(napi_env env, TaskType taskType, const char* name);
    ~Task() = default;

    // 静态工厂方法
    static Task* GenerateTask(napi_env env, napi_value task, napi_value func,
                              napi_value name, napi_value* args, size_t argc);
    static Task* GenerateFunctionTask(napi_env env, napi_value func, 
                                      napi_value* args, size_t argc, TaskType type);
    static TaskInfo* GenerateTaskInfo(napi_env env, napi_value func, napi_value args,
                                      napi_value transferList, napi_value cloneList, 
                                      Priority priority, bool defaultTransfer = true,
                                      bool defaultCloneSendable = false);

    // N-API 回调方法
    static napi_value TaskConstructor(napi_env env, napi_callback_info cbinfo);
    static napi_value SetTransferList(napi_env env, napi_callback_info cbinfo);
    static napi_value IsCanceled(napi_env env, napi_callback_info cbinfo);
    static napi_value SendData(napi_env env, napi_callback_info cbinfo);
    static napi_value AddDependency(napi_env env, napi_callback_info cbinfo);
    static napi_value RemoveDependency(napi_env env, napi_callback_info cbinfo);
    
    // 状态管理方法
    bool UpdateTaskStateToWaiting();
    bool UpdateTaskStateToRunning();
    bool UpdateTaskStateToCanceled();
    bool UpdateTaskStateToFinished();
    
    // 任务属性
    bool IsRepeatableTask() const;
    bool IsGroupTask() const;
    bool IsLongTask() const;
    bool IsPeriodicTask() const;
    
public:
    // 成员变量
    napi_env env_ = nullptr;
    std::atomic<TaskType> taskType_ {TaskType::TASK};
    std::string name_ {};
    uint32_t taskId_ {};
    std::atomic<ExecuteState> taskState_ {ExecuteState::NOT_FOUND};
    uint64_t groupId_ {};
    uint64_t seqRunnerId_ {};
    TaskInfo* currentTaskInfo_ {};
    std::list<TaskInfo*> pendingTaskInfos_ {};
    void* result_ = nullptr;
    std::atomic<bool> success_ {true};
    void* worker_ {nullptr};
    // ... 更多成员
};
TaskManager 类 (任务管理器 - 单例)
cpp 复制代码 
class TaskManager {
public:
    // 单例获取
    static TaskManager& GetInstance();

    // 任务管理
    void StoreTask(Task* task);
    bool RemoveTask(uint32_t taskId);
    Task* GetTask(uint32_t taskId);
    void EnqueueTaskId(uint32_t taskId, Priority priority = Priority::DEFAULT);
    std::pair<uint32_t, Priority> DequeueTaskId();
    void CancelTask(napi_env env, uint32_t taskId);
    
    // Worker管理
    void NotifyWorkerIdle(Worker* worker);
    void NotifyWorkerCreated(Worker* worker);
    void NotifyWorkerRunning(Worker* worker);
    void RemoveWorker(Worker* worker);
    
    // 负载均衡
    void InitTaskManager(napi_env env);
    void UpdateExecutedInfo(uint64_t duration);
    void TryTriggerExpand();
    
    // 状态查询
    uint32_t GetTaskNum();
    uint32_t GetIdleWorkers();
    uint32_t GetThreadNum();
    
private:
    TaskManager();
    ~TaskManager();
    
    // 私有成员
    std::unordered_map<uint32_t, Task*> tasks_ {};
    std::unordered_set<Worker*> workers_ {};
    std::unordered_set<Worker*> idleWorkers_ {};
    std::array<std::unique_ptr<ExecuteQueue>, Priority::NUMBER> taskQueues_ {};
    // ... 更多成员
};
Worker 类 (工作线程)
cpp 复制代码 
class Worker {
public:
    // 状态枚举
    enum RunnerState { STARTING, RUNNING, TERMINATEING, TERMINATED };
    enum HostState { ACTIVE, INACTIVE };
    enum ListenerMode { ONCE, PERMANENT };
    enum ScriptMode { CLASSIC, MODULE };

    // 构造与析构
    Worker(napi_env env, napi_ref thisVar);
    ~Worker();

    // 静态方法 - N-API回调
    static napi_value PostMessage(napi_env env, napi_callback_info cbinfo);
    static napi_value Terminate(napi_env env, napi_callback_info cbinfo);
    static napi_value On(napi_env env, napi_callback_info cbinfo);
    static napi_value Off(napi_env env, napi_callback_info cbinfo);
    static napi_value Constructor(napi_env env, napi_callback_info cbinfo, 
                                  bool limitSign = false, WorkerVersion version = WorkerVersion::NONE);
    
    // 消息处理
    static void HostOnMessage(const uv_async_t* req);
    static void WorkerOnMessage(const uv_async_t* req);
    static void ExecuteInThread(const void* data);
    
    // 状态管理
    bool UpdateWorkerState(RunnerState state);
    bool IsRunning() const;
    bool IsTerminated() const;
    
private:
    // 私有成员
    std::string script_ {};
    std::string name_ {};
    MessageQueue workerMessageQueue_ {};
    MessageQueue hostMessageQueue_ {};
    std::atomic<RunnerState> runnerState_ {STARTING};
    napi_env hostEnv_ {nullptr};
    napi_env workerEnv_ {nullptr};
    // ... 更多成员
};
URL 类
cpp 复制代码 
class URL {
public:
    // 构造函数
    explicit URL(const std::string& input);
    URL(const std::string& input, const std::string& base);
    URL(const std::string& input, const URL& base);
    ~URL() {}

    // Getter方法
    napi_value GetHostname(napi_env env) const;
    napi_value GetSearch(napi_env env) const;
    napi_value GetUsername(napi_env env) const;
    napi_value GetPassword(napi_env env) const;
    napi_value GetFragment(napi_env env) const;
    napi_value GetScheme(napi_env env) const;
    napi_value GetPath(napi_env env) const;
    napi_value GetPort(napi_env env) const;
    napi_value GetHost(napi_env env) const;
    
    // Setter方法
    void SetHostname(const std::string& input);
    void SetUsername(const std::string& input);
    void SetPassword(const std::string& input);
    void SetScheme(const std::string& input);
    void SetFragment(const std::string& input);
    void SetSearch(const std::string& input);
    void SetHost(const std::string& input);
    void SetPort(const std::string& input);
    void SetHref(const std::string& input);
    void SetPath(const std::string& input);

private:
    UrlData urlData_;
    std::bitset<11> flags_;
};
Buffer 类
cpp 复制代码 
class Buffer {
public:
    Buffer() = default;
    virtual ~Buffer();
    
    // 初始化方法
    void Init(uint32_t size);
    void Init(Buffer *buffer);
    void Init(Buffer *pool, unsigned int poolOffset, unsigned int length);
    void Init(uint8_t *buffer, unsigned int byteOffset, unsigned int length);

    // 属性访问
    unsigned int GetLength();
    void SetLength(unsigned int len);
    unsigned int GetByteOffset();
    int32_t Get(uint32_t index);
    void Set(uint32_t index, uint8_t value);

    // 读写方法
    void WriteInt32BE(int32_t value, uint32_t offset);
    void WriteInt32LE(int32_t value, uint32_t offset);
    int32_t ReadInt32BE(uint32_t offset);
    int32_t ReadInt32LE(uint32_t offset);
    
    // 字符串操作
    unsigned int WriteString(std::string value, unsigned int size);
    unsigned int WriteString(std::string value, unsigned int offset, 
                            unsigned int length, std::string encoding);
    
    // Buffer操作
    void SubBuffer(Buffer *tBuf, uint32_t start, uint32_t end);
    uint32_t Copy(Buffer *tBuf, uint32_t tStart, uint32_t sStart, uint32_t sEnd);
    int Compare(Buffer *tBuf, uint32_t targetStart, uint32_t sourceStart, uint32_t length);

private:
    uint8_t *raw_ {nullptr};
    unsigned int byteOffset_ {};
    unsigned int length_ {};
    bool needRelease_ {true};
};

2.2.2 关键结构体

cpp 复制代码 
// 任务执行状态
enum ExecuteState { 
    NOT_FOUND,  // 未找到
    WAITING,    // 等待中
    RUNNING,    // 执行中
    CANCELED,   // 已取消
    FINISHED,   // 已完成
    DELAYED,    // 延迟中
    ENDING      // 结束中
};

// 任务类型
enum TaskType {
    TASK,              // 普通任务
    FUNCTION_TASK,     // 函数任务
    SEQRUNNER_TASK,    // 序列运行器任务
    COMMON_TASK,       // 通用任务
    GROUP_COMMON_TASK, // 组通用任务
    GROUP_FUNCTION_TASK, // 组函数任务
    ASYNCRUNNER_TASK   // 异步运行器任务
};

// 任务优先级
enum Priority {
    HIGH = 0,    // 高优先级
    MEDIUM = 1,  // 中优先级
    LOW = 2,     // 低优先级
    IDLE = 3,    // 空闲优先级
    DEFAULT = MEDIUM,
    NUMBER = 4
};

// 任务信息结构体
struct TaskInfo {
    napi_deferred deferred = nullptr;
    Priority priority = Priority::DEFAULT;
    void* serializationFunction = nullptr;
    void* serializationArguments = nullptr;
};

// 任务组信息
struct GroupInfo {
    uint32_t finishedTaskNum {};
    napi_ref resArr {nullptr};
    Priority priority {Priority::DEFAULT};
    napi_deferred deferred {nullptr};
    int32_t failedIndex {-1};
};

// 定时器回调信息
struct TimerCallbackInfo {
    napi_env env_ {nullptr};
    uint32_t tId_ {};
    int32_t timeout_ {};
    napi_ref callback_ {};
    bool repeat_ {};
    uv_timer_t* timeReq_ {nullptr};
    size_t argc_ {};
    napi_ref* argv_ {nullptr};
};

2.2.3 继承关系图

继承 包含 包含 包含 包含 <<abstract>> Thread +uv_thread_t tid_ +Start() : bool +Run() : void +GetThreadId() : uv_thread_t TaskPoolWorker +napi_env env_ +Run() : void +NotifyIdle() : void XmlPullParser +strXml_ string +position_ size_t +Parse() : void +GetDepth() : int +GetName() : string ParseInfo +GetDepth() : napi_value +GetColumnNumber() : napi_value +GetLineNumber() : napi_value +GetName() : napi_value Worker +hostEnv_ napi_env +workerEnv_ napi_env +runnerState_ RunnerState +PostMessage() : napi_value +Terminate() : napi_value WorkerListener +env_ napi_env +callback_ napi_ref +mode_ ListenerMode WorkerParams +name_ string +type_ ScriptMode +workerPriority_ WorkerPriority WorkerWrapper +workerPtr_ Worker +GetWorker()

2.3 类图

2.3.1 TaskPool 模块类图

使用 创建 管理 管理 包含 包含 关联 关联 执行 <<static>> TaskPool +Execute(env, cbinfo) : napi_value +ExecuteDelayed(env, cbinfo) : napi_value +Cancel(env, cbinfo) : napi_value +GetTaskPoolInfo(env, cbinfo) : napi_value -HandleTaskResult(task) : void -ExecuteTask(env, task, priority) : void <<singleton>> TaskManager -tasks_ unordered_map -workers_ unordered_set -idleWorkers_ unordered_set -taskQueues_ array +GetInstance() +StoreTask(task) : void +GetTask(taskId) +EnqueueTaskId(taskId, priority) : void +DequeueTaskId() : pair +NotifyWorkerIdle(worker) : void +NotifyWorkerCreated(worker) : void Task +env_ napi_env +taskType_ TaskType +name_ string +taskId_ uint32_t +taskState_ ExecuteState +groupId_ uint64_t +currentTaskInfo_ TaskInfo +GenerateTask() +GenerateFunctionTask() +IsCanceled() : napi_value +SendData() : napi_value +UpdateTaskStateToWaiting() : bool +UpdateTaskStateToRunning() : bool TaskInfo +deferred napi_deferred +priority Priority +serializationFunction void +serializationArguments void Worker -tid_ uv_thread_t -env_ napi_env +Run() : void +NotifyIdle() : void TaskGroup +env_ napi_env +groupId_ uint64_t +taskIds_ list +taskNum_ uint32_t +groupState_ ExecuteState +AddTask() : napi_value +CancelGroupTask(env, taskId) : void SequenceRunner +seqRunnerId_ uint64_t +priority_ Priority +seqRunnerTasks_ deque +Execute() : napi_value +AddTask(task) : void +TriggerTask(env) : void ExecuteQueue -tasks_ list +EnqueueTaskId(taskId) : void +DequeueTaskId() : uint32_t +IsEmpty() : bool +GetTaskNum() : uint32_t

2.3.2 Worker 模块类图

使用 使用 包含 使用 Worker -hostEnv_ napi_env -workerEnv_ napi_env -runnerState_ RunnerState -hostState_ HostState -workerMessageQueue_ MessageQueue -hostMessageQueue_ MessageQueue -script_ string -name_ string +PostMessage() : napi_value +Terminate() : napi_value +On() : napi_value +Off() : napi_value +Constructor() : napi_value +HostOnMessage() : void +WorkerOnMessage() : void +ExecuteInThread() : void +UpdateWorkerState(state) : bool +IsRunning() : bool +IsTerminated() : bool MessageQueue -queue_ list -mutex_ mutex +Push(data) : void +Pop() : MessageData +Clear(env) : void +IsEmpty() : bool WorkerRunner -worker_ Worker +Run() : void WorkerListener +env_ napi_env +callback_ napi_ref +mode_ ListenerMode +NextIsAvailable() : bool +SetMode(mode) : void WorkerParams +name_ string +type_ ScriptMode +workerPriority_ WorkerPriority

2.3.3 API 模块类图

关联 URL -urlData_ UrlData -flags_ bitset +GetHostname(env) : napi_value +SetHostname(input) : void +GetSearch(env) : napi_value +SetSearch(input) : void +GetUsername(env) : napi_value +SetUsername(input) : void +GetPath(env) : napi_value +SetPath(input) : void +GetPort(env) : napi_value +SetPort(input) : void URLSearchParams -searchParams vector +IsHas(env, name) : napi_value +Get(env, buffer) : napi_value +GetAll(env, buffer) : napi_value +Append(env, buffer, temp) : void +Delete(env, buffer) : void +Set(env, name, value) : void +Sort() : void Buffer -raw_ uint8_t -length_ uint -byteOffset_ uint -needRelease_ bool +Init(size) : void +Get(index) : int32_t +Set(index, value) : void +WriteInt32BE(value, offset) : void +ReadInt32BE(offset) : int32_t +Copy(tBuf, tStart, sStart, sEnd) : uint32_t +Compare(tBuf, targetStart, sourceStart, length) : int XmlSerializer -pStart_ char -iLength_ size_t -encoding_ string +SetAttributes(name, value) : void +AddEmptyElement(name) : void +StartElement(name) : void +EndElement() : void +SetComment(comment) : void +SetCData(data) : void XmlPullParser -strXml_ string -position_ size_t -depth size_t +GetDepth() : int +GetName() : string +GetText() : string +Parse(env, thisVar, deprecated) : void +ParseTagType(inDeclaration) : TagEnum

2.4 模块内部依赖框图

复制代码 
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           模块内部依赖关系图                                       │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  js_concurrent_module                                                           │
│  ┌─────────────────────────────────────────────────────────────────────────┐   │
│  │                                                                         │   │
│  │  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐             │   │
│  │  │  taskpool/  │─────►│   common/   │◄─────│   worker/   │             │   │
│  │  │             │      │   helper/   │      │             │             │   │
│  │  └──────┬──────┘      └─────────────┘      └──────┬──────┘             │   │
│  │         │                    ▲                    │                     │   │
│  │         │                    │                    │                     │   │
│  │         ▼                    │                    ▼                     │   │
│  │  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐             │   │
│  │  │   utils/    │─────►│   tools/    │◄─────│  platform/  │             │   │
│  │  │   locks/    │      │    log.h    │      │             │             │   │
│  │  └─────────────┘      └─────────────┘      └─────────────┘             │   │
│  │                                                                         │   │
│  └─────────────────────────────────────────────────────────────────────────┘   │
│                                                                                 │
│  js_api_module                                                                  │
│  ┌─────────────────────────────────────────────────────────────────────────┐   │
│  │                                                                         │   │
│  │  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐             │   │
│  │  │    url/     │      │    uri/     │      │    xml/     │             │   │
│  │  └──────┬──────┘      └──────┬──────┘      └──────┬──────┘             │   │
│  │         │                    │                    │                     │   │
│  │         └────────────────────┼────────────────────┘                     │   │
│  │                              ▼                                          │   │
│  │                       ┌─────────────┐                                   │   │
│  │  ┌─────────────┐      │   buffer/   │      ┌─────────────┐             │   │
│  │  │ convertxml/ │─────►│  converter  │◄─────│ fastbuffer/ │             │   │
│  │  └─────────────┘      └─────────────┘      └─────────────┘             │   │
│  │                                                                         │   │
│  └─────────────────────────────────────────────────────────────────────────┘   │
│                                                                                 │
│  js_sys_module                                                                  │
│  ┌─────────────────────────────────────────────────────────────────────────┐   │
│  │                                                                         │   │
│  │  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐             │   │
│  │  │  process/   │      │  console/   │      │   timer/    │             │   │
│  │  └──────┬──────┘      └──────┬──────┘      └──────┬──────┘             │   │
│  │         │                    │                    │                     │   │
│  │         └────────────────────┼────────────────────┘                     │   │
│  │                              ▼                                          │   │
│  │                       ┌─────────────┐                                   │   │
│  │                       │    dfx/     │                                   │   │
│  │                       └─────────────┘                                   │   │
│  │                                                                         │   │
│  └─────────────────────────────────────────────────────────────────────────┘   │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

3. 模块间交互

3.1 交互描述

3.1.1 与NAPI的交互

所有模块都通过N-API与JavaScript层进行交互：

  • 使用napi_value进行值传递
  • 使用napi_callback_info获取回调参数
  • 使用napi_env管理JavaScript执行环境
  • 使用napi_ref管理JavaScript对象引用

3.1.2 与libuv的交互

并发模块大量使用libuv进行异步操作：

  • uv_async_t: 异步信号通知
  • uv_timer_t: 定时器
  • uv_thread_t: 线程管理
  • uv_loop_t: 事件循环

3.1.3 异步处理机制流程图

主线程回调 C++层 - Worker线程 N-API层 JavaScript层 napi_resolve_deferred TaskPool::HandleTaskResult 执行任务函数 Worker::Run uv_async_send 通知主线程 创建 napi_deferred TaskPool::Execute TaskManager::EnqueueTaskId await result taskpool.execute

3.1.4 多线程处理方式

机制 用途 实现方式
TaskPool 任务并行执行 线程池 + 任务队列
Worker 独立线程执行 独立线程 + 消息传递
AsyncLock 异步锁 Promise + 等待队列
SequenceRunner 顺序执行 任务队列 + 依赖管理

3.1.5 事件驱动机制

Worker模块采用事件驱动机制：

cpp 复制代码 
// 事件类型
- "message"      // 消息事件
- "error"        // 错误事件
- "messageerror" // 消息错误事件
- "exit"         // 退出事件

// 监听方式
worker.on("message", callback);      // 持久监听
worker.once("message", callback);    // 单次监听
worker.off("message");               // 取消监听

3.2 外部依赖框图

系统依赖 功能依赖 诊断依赖 核心依赖 c_utils
C++工具 IPC
进程间通信 SAMGR
服务管理 EventHandler
事件处理 ICU
国际化 OpenSSL
加密 libxml2
XML解析 HiLog
日志 HiSysEvent
事件上报 HiTrace
跟踪 NAPI
JS绑定 libuv
异步I/O FFRT
任务调度 ETS Utils 模块

4. 状态机转换图

4.1 Task 状态机模型

4.1.1 状态定义

状态 值 描述
NOT_FOUND 0 任务未找到/初始状态
WAITING 1 等待执行
RUNNING 2 正在执行
CANCELED 3 已取消
FINISHED 4 已完成
DELAYED 5 延迟执行中
ENDING 6 结束中

4.1.2 状态机树图

execute executeDelayed cancel dequeue cancel timeout cancel success cancel ending cleanup NOT_FOUND
初始状态 WAITING
等待中 DELAYED
延迟中 RUNNING
执行中 CANCELED
已取消 FINISHED
已完成 ENDING
结束中

4.1.3 状态切换规则

当前状态 目标状态 触发条件 触发方法
NOT_FOUND WAITING 任务入队 UpdateTaskStateToWaiting()
NOT_FOUND DELAYED 延迟任务入队 UpdateTaskStateToDelayed()
NOT_FOUND CANCELED 任务取消 UpdateTaskStateToCanceled()
WAITING RUNNING 工作线程获取任务 UpdateTaskStateToRunning()
WAITING CANCELED 用户取消任务 UpdateTaskStateToCanceled()
DELAYED WAITING 延迟时间到达 UpdateTaskStateToWaiting()
DELAYED CANCELED 用户取消任务 UpdateTaskStateToCanceled()
RUNNING FINISHED 任务执行完成 UpdateTaskStateToFinished()
RUNNING CANCELED 任务执行中取消 UpdateTaskStateToCanceled()
RUNNING ENDING 任务开始结束 UpdateTaskStateToEnding()
ENDING FINISHED 结束处理完成 UpdateTaskStateToFinished()

4.2 Worker 状态机模型

4.2.1 RunnerState 状态机

创建Worker 线程启动完成 调用terminate() 重新激活 清理完成 STARTING RUNNING TERMINATEING TERMINATED

4.2.2 HostState 状态机

Worker创建 宿主环境退出 ACTIVE INACTIVE

4.3 AsyncLock 状态机模型

4.3.1 LockMode 状态

初始化 获取共享锁 获取排他锁 所有持有者释放 持有者释放 LOCK_MODE_UNLOCK LOCK_MODE_SHARED LOCK_MODE_EXCLUSIVE

4.4 状态机转换图 (综合)

execute() executeDelayed() cancel() dequeue() cancel() timeout() cancel() success() cancel() ending() cleanup() NOT_FOUND WAITING DELAYED CANCELED RUNNING FINISHED ENDING 初始状态 等待执行 延迟中 执行中 结束中 已完成 已取消

5. 接口设计

5.1 公共接口

5.1.1 TaskPool 接口

接口名称 功能描述 参数 返回值
execute(task, priority?) 执行任务 task: Task对象, priority: 优先级 Promise
execute(func, ...args) 执行函数任务 func: 函数, args: 参数 Promise
executeDelayed(delay, task, priority?) 延迟执行任务 delay: 延迟毫秒, task: Task对象 Promise
executePeriodically(period, task, priority?) 周期执行任务 period: 周期毫秒, task: Task对象 void
cancel(task) 取消任务 task: Task对象 void
terminateTask(task) 终止长任务 task: Task对象 void
getTaskPoolInfo() 获取任务池信息 无 TaskPoolInfo
isConcurrent(func) 判断是否为并发函数 func: 函数 boolean

5.1.2 Task 接口

接口名称 功能描述 参数 返回值
constructor(func, ...args) 创建任务 func: 函数, args: 参数 Task
setTransferList(list) 设置转移列表 list: ArrayBuffer数组 void
setCloneList(list) 设置克隆列表 list: 可克隆对象数组 void
isCanceled() 检查是否已取消 无 boolean
isDone() 检查是否已完成 无 boolean
sendData(...args) 发送数据 args: 数据 void
onReceiveData(callback) 接收数据回调 callback: 回调函数 void
addDependency(task) 添加依赖 task: 依赖任务 void
removeDependency(task) 移除依赖 task: 依赖任务 void
onEnqueued(callback) 入队回调 callback: 回调函数 void
onStartExecution(callback) 开始执行回调 callback: 回调函数 void
onExecutionSucceeded(callback) 执行成功回调 callback: 回调函数 void
onExecutionFailed(callback) 执行失败回调 callback: 回调函数 void

5.1.3 Worker 接口

接口名称 功能描述 参数 返回值
constructor(script, options?) 创建Worker script: 脚本路径, options: 配置 Worker
postMessage(data, transfer?) 发送消息 data: 数据, transfer: 转移列表 void
postMessageWithSharedSendable(data) 发送共享消息 data: 可共享数据 void
terminate() 终止Worker 无 void
on(type, callback) 添加事件监听 type: 事件类型, callback: 回调 void
once(type, callback) 添加单次监听 type: 事件类型, callback: 回调 void
off(type, callback?) 移除事件监听 type: 事件类型, callback: 回调 void
addEventListener(type, callback) 添加事件监听 type: 事件类型, callback: 回调 void
removeEventListener(type, callback?) 移除事件监听 type: 事件类型, callback: 回调 void
dispatchEvent(event) 分发事件 event: 事件对象 boolean
registerGlobalCallObject(name, obj) 注册全局调用对象 name: 名称, obj: 对象 void
unregisterGlobalCallObject(name) 注销全局调用对象 name: 名称 void

5.1.4 URL 接口

接口名称 功能描述 参数 返回值
constructor(url, base?) 创建URL url: URL字符串, base: 基础URL URL
href 完整URL getter/setter string
origin 来源 getter string
protocol 协议 getter/setter string
username 用户名 getter/setter string
password 密码 getter/setter string
host 主机(含端口) getter/setter string
hostname 主机名 getter/setter string
port 端口 getter/setter string
pathname 路径 getter/setter string
search 查询字符串 getter/setter string
searchParams 查询参数 getter URLSearchParams
hash 哈希 getter/setter string
toString() 转字符串 无 string
toJSON() 转JSON 无 string

5.1.5 Buffer 接口

接口名称 功能描述 参数 返回值
alloc(size, fill?, encoding?) 分配Buffer size: 大小, fill: 填充值 Buffer
allocUnsafe(size) 不安全分配 size: 大小 Buffer
from(data, encoding?) 从数据创建 data: 数据, encoding: 编码 Buffer
concat(list, totalLength?) 连接Buffer list: Buffer数组, totalLength: 总长度 Buffer
compare(buf1, buf2) 比较Buffer buf1, buf2: Buffer number
isBuffer(obj) 判断是否Buffer obj: 对象 boolean
byteLength(string, encoding?) 字节长度 string: 字符串, encoding: 编码 number
copy(target, targetStart?, sourceStart?, sourceEnd?) 复制 target: 目标Buffer number
slice(start?, end?) 切片 start: 起始, end: 结束 Buffer
write(string, offset?, length?, encoding?) 写入字符串 string: 字符串 number
toString(encoding?, start?, end?) 转字符串 encoding: 编码 string
readInt32BE(offset) 读取32位整数(大端) offset: 偏移 number
writeInt32BE(value, offset) 写入32位整数(大端) value: 值, offset: 偏移 number

5.1.6 Process 接口

接口名称 功能描述 参数 返回值
uid 用户ID getter number
gid 组ID getter number
euid 有效用户ID getter number
egid 有效组ID getter number
pid 进程ID getter number
ppid 父进程ID getter number
tid 线程ID getter number
cwd() 当前工作目录 无 string
chdir(dir) 改变工作目录 dir: 目录 void
uptime() 运行时间 无 number
kill(pid, signal) 发送信号 pid: 进程ID, signal: 信号 boolean
exit(code) 退出进程 code: 退出码 void
abort() 中止进程 无 void
isIsolatedProcess() 是否隔离进程 无 boolean
is64Bit() 是否64位 无 boolean
getUidForName(name) 通过名称获取UID name: 用户名 number
getThreadPriority(tid) 获取线程优先级 tid: 线程ID number
getSystemConfig(name) 获取系统配置 name: 配置名 number
getEnvironmentVar(name) 获取环境变量 name: 变量名 string

5.1.7 Timer 接口

接口名称 功能描述 参数 返回值
setTimeout(callback, delay?, ...args) 设置超时 callback: 回调, delay: 延迟 number
setInterval(callback, delay?, ...args) 设置间隔 callback: 回调, delay: 间隔 number
clearTimeout(id) 清除超时 id: 定时器ID void
clearInterval(id) 清除间隔 id: 定时器ID void

5.1.8 AsyncLock 接口

接口名称 功能描述 参数 返回值
constructor(name?) 创建异步锁 name: 锁名称 AsyncLock
lockAsync(callback, mode?, options?) 异步加锁 callback: 回调, mode: 锁模式 Promise
query() 查询锁状态 无 LockState

5.2 数据交换接口

5.2.1 序列化协议

TaskPool和Worker使用序列化机制进行数据传递：

cpp 复制代码 
// 序列化支持的类型
- 基本类型: number, string, boolean, null, undefined
- 对象类型: Object, Array, Map, Set
- 特殊类型: ArrayBuffer, TypedArray, DataView
- 可转移对象: ArrayBuffer (通过transferList)
- 可共享对象: SharedArrayBuffer, Sendable对象

5.2.2 消息格式

typescript 复制代码 
// Worker消息格式
interface MessageEvent {
    data: any;          // 消息数据
    type: string;       // 消息类型
}

// 错误消息格式
interface ErrorEvent {
    message: string;    // 错误信息
    filename: string;   // 文件名
    lineno: number;     // 行号
    colno: number;      // 列号
    error: Error;       // 错误对象
}

5.3 接口调用时序图

5.3.1 TaskPool.execute 时序图

Application TaskPool TaskManager Worker Task execute(task) GenerateTask() task StoreTask(task) EnqueueTaskId(taskId, priority) NotifyExecuteTask() DequeueTaskId() taskId GetTask(taskId) task Execute() result HandleTaskResult(task) Promise.resolve(result) Application TaskPool TaskManager Worker Task

5.3.2 Worker 消息传递时序图

Application Worker(Host) MessageQueue Worker(Thread) WorkerScript new Worker(script) StartThread() LoadScript() postMessage(data) Serialize() & Push() uv_async_send() Pop() Deserialize() & onmessage() postMessage(response) Serialize() & Push() uv_async_send() onmessage event Application Worker(Host) MessageQueue Worker(Thread) WorkerScript

5.3.3 AsyncLock 加锁时序图

Application AsyncLock LockRequest AsyncLockManager Callback lockAsync(callback) new LockRequest() CanAcquireLock() AddToHeldList() ExecuteCallback() result CleanUpLockRequest() ProcessPendingLockRequest() Promise.resolve(result) AddToPendingList() 等待锁释放 alt [可以获取锁] [不能获取锁] Application AsyncLock LockRequest AsyncLockManager Callback

5.3.4 Timer 定时器时序图

Application Timer TimerTable uv_timer Callback setTimeout(callback, delay) CreateTimerCallbackInfo() uv_timer_init() uv_timer_start() timerId 等待 timeout TimerCallback() callback() DeleteTimer() Application Timer TimerTable uv_timer Callback

附录

A. 错误码定义

错误码 描述
10200001 值超出范围
10200002 参数无效
10200003 Worker初始化失败
10200004 Worker实例不支持此API
10200005 Worker未运行
10200006 序列化异常
10200007 Worker文件路径无效
10200014 任务已执行
10200015 取消不存在的任务
10200016 任务不支持取消
10200034 任务组已执行

B. 平台兼容性

平台 支持状态 备注
OpenHarmony ✅ 完全支持 主要目标平台
Windows ✅ 支持 开发调试用
macOS ✅ 支持 开发调试用
iOS ⚠️ 部分支持 部分功能受限
Android ⚠️ 部分支持 部分功能受限

C. 性能指标

指标 参考值 说明
ROM占用 ~1400KB 编译后代码大小
RAM占用 ~4096KB 运行时内存占用
线程池大小 CPU核心数-1 动态调整
任务队列容量 无限制 受内存限制
相关推荐
●VON2 小时前
小V健身助手开发手记（二）：从数据输入到任务管理——构建动态运动记录系统
学习·openharmony·总结·开源鸿蒙·von
豫狮恒18 小时前
OpenHarmony Flutter 分布式多模态交互：融合音视频、手势与环境感知的跨端体验革新
flutter·wpf·openharmony
豫狮恒20 小时前
OpenHarmony Flutter 分布式数据共享实战：从基础存储到跨设备协同
flutter·wpf·openharmony
豫狮恒1 天前
OpenHarmony Flutter 分布式安全防护：跨设备身份认证与数据加密传输方案
flutter·wpf·openharmony
豫狮恒1 天前
OpenHarmony Flutter 分布式设备发现与组网：跨设备无感连接与动态组网方案
分布式·flutter·wpf·openharmony
豫狮恒1 天前
OpenHarmony Flutter 分布式安全防护：跨设备身份认证与数据加密方案
分布式·安全·flutter·wpf·openharmony
●VON1 天前
小V健身助手开发手记（一）：启动即合规——实现隐私协议弹窗与用户授权状态管理
学习·华为·项目·openharmony·开源鸿蒙
豫狮恒1 天前
OpenHarmony Flutter 分布式数据管理：跨设备数据同步与一致性保障方案
分布式·flutter·wpf·openharmony
豫狮恒1 天前
OpenHarmony Flutter 分布式音视频：跨设备实时流传输与协同播放方案
分布式·flutter·wpf·openharmony
热门推荐
01GitHub 镜像站点02【AutoGLM部署】本地私有化部署AI手机Agent03UV安装并设置国内源04【超详细教程】手把手教你从微软官网免费下载Windows 10官方原版ISO镜像（2025最新版）05Open-AutoGLM Windows 安装部署教程06Cursor 又偷偷更新，这个功能太实用：Visual Editor for Cursor Browser07安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）08Linux下V2Ray安装配置指南09BongoCat - 跨平台键盘猫动画工具10Windows 11 官方系统安装与重装完整教程（2025年最新版）