【OpenHarmony】OpenHarmony ETS Utils实现

OpenHarmony ETS Utils 模块

1. 模块概述

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

1.1 功能与目标

1.1.1 主要功能

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

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 依赖组件

1.3 设计思路与模式

1.3.1 设计思路

1. 分层架构设计

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

2. 模块化设计

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

3. 异步优先设计

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

1.3.2 设计模式

2. 模块结构

2.1 源文件与头文件

2.1.1 js_concurrent_module (并发模块)

TaskPool 子模块

Worker 子模块

Utils 子模块

2.1.2 js_api_module (API模块)

2.1.3 js_sys_module (系统模块)

2.1.4 js_util_module (工具模块)

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

2.2.1 核心类设计

Task 类 (任务类)

classTask{public:// 构造函数Task()=default;Task(napi_env env,TaskType taskType,constchar*name);~Task()=default;// 静态工厂方法staticTask*GenerateTask(napi_env env,napi_value task,napi_value func,napi_value name,napi_value*args,size_t argc);staticTask*GenerateFunctionTask(napi_env env,napi_value func,napi_value*args,size_t argc,TaskType type);staticTaskInfo*GenerateTaskInfo(napi_env env,napi_value func,napi_value args,napi_value transferList,napi_value cloneList,Priority priority,booldefaultTransfer=true,booldefaultCloneSendable=false);// N-API 回调方法staticnapi_valueTaskConstructor(napi_env env,napi_callback_info cbinfo);staticnapi_valueSetTransferList(napi_env env,napi_callback_info cbinfo);staticnapi_valueIsCanceled(napi_env env,napi_callback_info cbinfo);staticnapi_valueSendData(napi_env env,napi_callback_info cbinfo);staticnapi_valueAddDependency(napi_env env,napi_callback_info cbinfo);staticnapi_valueRemoveDependency(napi_env env,napi_callback_info cbinfo);// 状态管理方法boolUpdateTaskStateToWaiting();boolUpdateTaskStateToRunning();boolUpdateTaskStateToCanceled();boolUpdateTaskStateToFinished();// 任务属性boolIsRepeatableTask()const;boolIsGroupTask()const;boolIsLongTask()const;boolIsPeriodicTask()const;public:// 成员变量napi_env env_=nullptr;std::atomic<TaskType>taskType_{TaskType::TASK};std::string name_{};uint32_ttaskId_{};std::atomic<ExecuteState>taskState_{ExecuteState::NOT_FOUND};uint64_tgroupId_{};uint64_tseqRunnerId_{};TaskInfo*currentTaskInfo_{};std::list<TaskInfo*>pendingTaskInfos_{};void*result_=nullptr;std::atomic<bool>success_{true};void*worker_{nullptr};// ... 更多成员};

TaskManager 类 (任务管理器 - 单例)

classTaskManager{public:// 单例获取staticTaskManager&GetInstance();// 任务管理voidStoreTask(Task*task);boolRemoveTask(uint32_ttaskId);Task*GetTask(uint32_ttaskId);voidEnqueueTaskId(uint32_ttaskId,Priority priority=Priority::DEFAULT);std::pair<uint32_t,Priority>DequeueTaskId();voidCancelTask(napi_env env,uint32_ttaskId);// Worker管理voidNotifyWorkerIdle(Worker*worker);voidNotifyWorkerCreated(Worker*worker);voidNotifyWorkerRunning(Worker*worker);voidRemoveWorker(Worker*worker);// 负载均衡voidInitTaskManager(napi_env env);voidUpdateExecutedInfo(uint64_tduration);voidTryTriggerExpand();// 状态查询uint32_tGetTaskNum();uint32_tGetIdleWorkers();uint32_tGetThreadNum();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 类 (工作线程)

classWorker{public:// 状态枚举enumRunnerState{STARTING,RUNNING,TERMINATEING,TERMINATED};enumHostState{ACTIVE,INACTIVE};enumListenerMode{ONCE,PERMANENT};enumScriptMode{CLASSIC,MODULE};// 构造与析构Worker(napi_env env,napi_ref thisVar);~Worker();// 静态方法 - N-API回调staticnapi_valuePostMessage(napi_env env,napi_callback_info cbinfo);staticnapi_valueTerminate(napi_env env,napi_callback_info cbinfo);staticnapi_valueOn(napi_env env,napi_callback_info cbinfo);staticnapi_valueOff(napi_env env,napi_callback_info cbinfo);staticnapi_valueConstructor(napi_env env,napi_callback_info cbinfo,boollimitSign=false,WorkerVersion version=WorkerVersion::NONE);// 消息处理staticvoidHostOnMessage(constuv_async_t*req);staticvoidWorkerOnMessage(constuv_async_t*req);staticvoidExecuteInThread(constvoid*data);// 状态管理boolUpdateWorkerState(RunnerState state);boolIsRunning()const;boolIsTerminated()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 类

classURL{public:// 构造函数explicitURL(conststd::string&input);URL(conststd::string&input,conststd::string&base);URL(conststd::string&input,constURL&base);~URL(){}// Getter方法napi_valueGetHostname(napi_env env)const;napi_valueGetSearch(napi_env env)const;napi_valueGetUsername(napi_env env)const;napi_valueGetPassword(napi_env env)const;napi_valueGetFragment(napi_env env)const;napi_valueGetScheme(napi_env env)const;napi_valueGetPath(napi_env env)const;napi_valueGetPort(napi_env env)const;napi_valueGetHost(napi_env env)const;// Setter方法voidSetHostname(conststd::string&input);voidSetUsername(conststd::string&input);voidSetPassword(conststd::string&input);voidSetScheme(conststd::string&input);voidSetFragment(conststd::string&input);voidSetSearch(conststd::string&input);voidSetHost(conststd::string&input);voidSetPort(conststd::string&input);voidSetHref(conststd::string&input);voidSetPath(conststd::string&input);private:UrlData urlData_;std::bitset<11>flags_;};

Buffer 类

classBuffer{public:Buffer()=default;virtual~Buffer();// 初始化方法voidInit(uint32_tsize);voidInit(Buffer*buffer);voidInit(Buffer*pool,unsignedintpoolOffset,unsignedintlength);voidInit(uint8_t*buffer,unsignedintbyteOffset,unsignedintlength);// 属性访问unsignedintGetLength();voidSetLength(unsignedintlen);unsignedintGetByteOffset();int32_tGet(uint32_tindex);voidSet(uint32_tindex,uint8_tvalue);// 读写方法voidWriteInt32BE(int32_tvalue,uint32_toffset);voidWriteInt32LE(int32_tvalue,uint32_toffset);int32_tReadInt32BE(uint32_toffset);int32_tReadInt32LE(uint32_toffset);// 字符串操作unsignedintWriteString(std::string value,unsignedintsize);unsignedintWriteString(std::string value,unsignedintoffset,unsignedintlength,std::string encoding);// Buffer操作voidSubBuffer(Buffer*tBuf,uint32_tstart,uint32_tend);uint32_tCopy(Buffer*tBuf,uint32_ttStart,uint32_tsStart,uint32_tsEnd);intCompare(Buffer*tBuf,uint32_ttargetStart,uint32_tsourceStart,uint32_tlength);private:uint8_t*raw_{nullptr};unsignedintbyteOffset_{};unsignedintlength_{};boolneedRelease_{true};};

2.2.2 关键结构体

// 任务执行状态enumExecuteState{NOT_FOUND,// 未找到WAITING,// 等待中RUNNING,// 执行中CANCELED,// 已取消FINISHED,// 已完成DELAYED,// 延迟中ENDING// 结束中};// 任务类型enumTaskType{TASK,// 普通任务FUNCTION_TASK,// 函数任务SEQRUNNER_TASK,// 序列运行器任务COMMON_TASK,// 通用任务GROUP_COMMON_TASK,// 组通用任务GROUP_FUNCTION_TASK,// 组函数任务ASYNCRUNNER_TASK// 异步运行器任务};// 任务优先级enumPriority{HIGH=0,// 高优先级MEDIUM=1,// 中优先级LOW=2,// 低优先级IDLE=3,// 空闲优先级DEFAULT=MEDIUM,NUMBER=4};// 任务信息结构体structTaskInfo{napi_deferred deferred=nullptr;Priority priority=Priority::DEFAULT;void*serializationFunction=nullptr;void*serializationArguments=nullptr;};// 任务组信息structGroupInfo{uint32_tfinishedTaskNum{};napi_ref resArr{nullptr};Priority priority{Priority::DEFAULT};napi_deferred deferred{nullptr};int32_tfailedIndex{-1};};// 定时器回调信息structTimerCallbackInfo{napi_env env_{nullptr};uint32_ttId_{};int32_ttimeout_{};napi_ref callback_{};boolrepeat_{};uv_timer_t*timeReq_{nullptr};size_t argc_{};napi_ref*argv_{nullptr};};

2.2.3 继承关系图

2.3 类图

2.3.1 TaskPool 模块类图

2.3.2 Worker 模块类图

2.3.3 API 模块类图

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 异步处理机制流程图

3.1.4 多线程处理方式

3.1.5 事件驱动机制

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

// 事件类型-"message"// 消息事件-"error"// 错误事件-"messageerror"// 消息错误事件-"exit"// 退出事件// 监听方式worker.on("message",callback);// 持久监听worker.once("message",callback);// 单次监听worker.off("message");// 取消监听

3.2 外部依赖框图

4. 状态机转换图

4.1 Task 状态机模型

4.1.1 状态定义

4.1.2 状态机树图

4.1.3 状态切换规则

4.2 Worker 状态机模型

4.2.1 RunnerState 状态机

4.2.2 HostState 状态机

4.3 AsyncLock 状态机模型

4.3.1 LockMode 状态

4.4 状态机转换图 (综合)

5. 接口设计

5.1 公共接口

5.1.1 TaskPool 接口

5.1.2 Task 接口

5.1.3 Worker 接口

5.1.4 URL 接口

5.1.5 Buffer 接口

5.1.6 Process 接口

5.1.7 Timer 接口

5.1.8 AsyncLock 接口

5.2 数据交换接口

5.2.1 序列化协议

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

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

5.2.2 消息格式

// Worker消息格式interfaceMessageEvent{data:any;// 消息数据type:string;// 消息类型}// 错误消息格式interfaceErrorEvent{message:string;// 错误信息filename:string;// 文件名lineno:number;// 行号colno:number;// 列号error:Error;// 错误对象}

5.3 接口调用时序图

5.3.1 TaskPool.execute 时序图

5.3.2 Worker 消息传递时序图

5.3.3 AsyncLock 加锁时序图

5.3.4 Timer 定时器时序图

附录

A. 错误码定义

B. 平台兼容性

C. 性能指标