仓颉运行时与标准库 cangjie_runtime 深入指南:架构解析、全并发 GC 与构建实践
仓颉运行时与标准库 cangjie_runtime 深入指南:架构解析、全并发 GC 与构建实践
在仓颉编程语言中,程序执行依赖于运行时和标准库两大基础件:仓颉运行时(Cangjie Runtime)作为轻量高效的基础引擎,负责程序运行时的内存、线程等核心资源管理;仓颉语言标准库(std)则提供数据结构、算法、数学计算、正则、文件、网络等开箱即用的内置能力。本文基于 cangjie_runtime 仓库的 README 为主体骨架,结合仓库源码实现,系统讲解运行时的全并发垃圾回收、CJThread 线程管理、异常与回栈、包加载、对象模型等核心机制,并给出运行时与标准库的完整构建参数和产物说明,帮助开发者在理解原理的同时完成从源码构建到产物集成的全流程。
项目定位与三方库依赖
本仓库提供仓颉运行时和仓颉编程语言标准库的源码,二者关系为:运行时提供运行底座,标准库构建在运行时之上,最终与 cjc 编译器一起组成完整工具链。
仓库对三方库的依赖方式有明确约定(见 README),不同三方库的集成方式直接影响构建方式:
| 三方库 | 使用主体 | 使用方式 |
|---|---|---|
libboundscheck |
仓颉运行时 + 标准库 | 源码依赖,编译集成到二进制发布包 |
OpenSSL |
仓颉运行时 | 动态链接系统动态库,不依赖源码 |
PCRE2 |
标准库 regex |
源码依赖,编译集成到二进制发布包 |
flatbuffers |
标准库 ast |
源码依赖,编译集成到二进制发布包 |
从源码结构看,PCRE2 的 CMake 集成位于 stdlib/third_party/cmake/Pcre2.cmake;运行时的 bounds check 源码则在顶层 CMake 中通过 add_subdirectory(third_party/third_party_bounds_checking_function) 引入(见 runtime/CMakeLists.txt)。
仓颉运行时(Runtime)
总体架构
仓颉运行时是仓颉 Native 后端(CJNative)的核心组件之一,以高性能和轻量化为设计目标,为仓颉语言在全场景下的高性能表现提供有力支持。它作为仓颉程序运行的基础引擎,提供自动内存管理(GC)、CJThread、Loader 等基础驱动功能。
架构图包含以下关键子系统,下面逐一展开,并结合源码给出实现层面的佐证。
自动内存管理:低时延全并发 GC
自动内存管理采用了低时延的全并发内存整理算法,核心目标是追求更低的业务时延与更低的内存开销,帮助开发者更好地聚焦业务本身。其三大特性:
- 全并发垃圾回收:消除全局暂停(Stop-The-World, STW),优化执行时延;
- 内存整理:通过对象搬移整理堆内存,提高内存利用率,支持应用长时在线;
- 指针标记:在引用对象处对指针加上标记,以区分指针是垃圾内存还是被复用的新内存,保证全并发垃圾回收的正确性。
源码层面,这套机制落在 Heap 模块的收集器体系中:
- GC 阶段流水线。Collector.h 定义了
GCPhase枚举,完整回收周期经过GC_PHASE_INIT → GC_PHASE_ENUM → GC_PHASE_TRACE → GC_PHASE_CLEAR_SATB_BUFFER → GC_PHASE_POST_TRACE → GC_PHASE_PREFORWARD → GC_PHASE_FORWARD七个并发阶段,与"枚举根、追踪、清理 SATB、预搬移、正式搬移"的并发流程一一对应;同时定义了CollectorType(区域复制收集器COPY_COLLECTOR与平滑收集器SMOOTH_COLLECTOR)。 - 指针标记的实现。WCollector.h 中,
WCollector(类型即SMOOTH_COLLECTOR)维护一个currentTagID,每轮 GC 通过FlipTagID()执行currentTagID ^= 1翻转标签;IsOldPointer/IsCurrentPointer通过比对引用字段的 tag 与上一轮/当前 tag ID,精确判断一个引用是"垃圾旧指针"还是"新内存指针"。底层的引用字段由 RefField.h 以 tagged-pointer 方式实现,支持CompareExchange原子操作,保证并发下的正确性。 - 写屏障与内存整理。Mutator 侧的 SatbBuffer.h 负责"buffer modified field of mutator write",即缓冲业务线程对对象引用的写入(SATB = Snapshot At The Beginning),使 GC 枚举时不遗漏并发新增引用;搬移后的地址重定位则通过
ForwardTable::RouteObject查询旧地址到新地址的映射(WCollector.h)。 - 堆容量语义。Heap.h 明确定义了堆内六层容量语义:
net size ≤ allocated size ≤ used size ≤ committed size ≤ current capacity ≤ max capacity,配合RegisterExportRoot/VisitStaticRoots等根管理机制,以及按 GC 阶段安装不同Barrier(InstallBarrier)来实现全并发访问控制。
此外,运行时对外暴露了 GC 阈值调优接口:CangjieRuntime.h 的 SetGCThreshold 允许以 KB 为单位设置 gcParam.gcThreshold,设置无效值(0)时会记录错误日志,这是 DFX 调优能力的具体落点。
线程管理:CJThread
CJThread 提供了更轻量、更具弹性能力的线程管理方案,能更好地应对各种体量的并发场景:
- 仓颉线程调度:包含执行线程(thread)、监视器(monitor)、处理器(processor)、调度器(schmon)等基本模块,各模块承担不同任务,使仓颉进程可以在充分利用多核硬件资源的基础上进一步扩展并发能力;
- 仓颉栈扩缩容:仓颉栈采用连续栈,当使用达到上限之后,自动扩容至 2 倍大小。
源码佐证:调度实现位于 runtime/src/CJThread/src/runtime/schedule,其中 inner/ 目录下可见 thread.h、processor.h、schmon.h、schdpoll.h 等模块头文件;cjthread.h 的 CJThread 结构同时挂有全局调度队列(schdDulink)、所属线程(thread)、线程上下文(context)、调度器(schedule)与栈(stack),直观呈现了"协程式调度 + 绑定 OS 线程"的模型。栈扩容方面,CangjieRuntime.h 提供了 StackGrowConfig(STACK_GROW_OFF / STACK_GROW_ON)开关,各架构的 StackGrowStub.S(如 runtime/src/arch/x86_64_linux/StackGrowStub.S)负责执行实际的连续栈搬移,StackGrowStackInfo.h 则在栈扩容后借助 StackMap 记录并修正栈内指针。
异常管理:Exception 与 Error
异常管理提供两类异常处理方式,从严重程度可分为 Exception 和 Error:
Exception:描述程序运行时的逻辑错误或IO错误导致的异常,例如数组越界、试图打开一个不存在的文件等。这类异常需要在程序中捕获处理;Error:描述仓颉运行时系统内部错误和资源耗尽错误。应用程序不应该抛出这种类型的错误;一旦出现内部错误,只能通知用户并尽快安全终止程序。
源码中 Exception.h 的 ExceptionWrapper::ExceptionType 枚举了运行时内部抛出的异常类型(OUT_OF_MEMORY、STACK_OVERFLOW、ARITHMETIC、INCOMPATIBILE_PACKAGE 等),其名称表 L156-L162 与标准库 core 包中的异常类严格对应:out_of_memory_error.cj、stack_overflow_error.cj、arithmetic_exception.cj、incompatible_package_exception.cj——这正是"运行时内部错误对应 std.core 中 Error 家族"的实现证据。抛出过程由 Exception.h 的 ExceptionHandling 驱动:先通过栈回溯构建 EH 帧信息(BuildEHFrameInfo),再用 landing pad 值改写受管栈上的返回地址,最终经汇编 stub(如 RestoreContextForEH.S)跳转回仓颉代码的 catch 路径。
回栈(Stack Trace)
回栈使用基于 frame pointer 的栈回溯方式:使用 rbp 寄存器保存栈帧地址,rsp 寄存器保存栈顶指针,在过程调用时将上一个栈帧地址入栈保存。
实现落在 UnwindStack 模块,从源码结构看按场景拆分为多种 StackInfo 派生类:PrintStackInfo(打印堆栈)、EhStackInfo(异常回溯)、GcStackInfo(GC 枚举栈根)、StackGrowStackInfo(栈扩容后的指针记录与修正,见 StackGrowStackInfo.h 的 RecordStackPtrs 系列方法),配合 Signal 模块在信号上下文中捕获寄存器现场,Demangler 模块(CangjieDemangle / cjfilt)负责将 C++ 风格的 mangling 符号还原为可读的仓颉符号名。
包管理(Loader)
包管理支持以仓颉包为粒度加载和管理仓颉代码,并支持反射特性。ILoader.h 定义的加载器抽象接口清晰体现了"包粒度"设计:GetPackageInfo / GetPackageInfoByPath / RemovePackageInfo 管理包元数据,FileHasLoaded / FileHasMultiPackage 管理文件与包的映射,CheckPackageCompatibility 负责包版本兼容性校验,FindTypeInfoFromLoadedFiles / FindTypeTemplateFromLoadedFiles 支撑反射所需的类型查询,LoadCJLibrary / UnloadLibrary / FindSymbol 支撑动态加载与跨语言符号查找。包文件解析由 Loader/BinaryFile(CjFile 格式)完成,包元数据模型(PackageInfo、TypeInfo、MethodInfo)则位于 ObjectModel 模块。
仓颉对象模型
对象模型包含仓颉对象元数据、成员信息、方法信息和方法表,为仓颉对象的创建、管理、调用和释放提供支持。对应源码位于 runtime/src/ObjectModel:MObject(对象头/基类)、MClass(类元数据)、MFuncdesc(方法描述)、Field / RefField(成员与引用字段)、TypeInfo / PackageInfo(类型与包元信息)。从源码结构看,运行时中所有引用均通过前述 tagged-pointer 的 RefField 表达,这是 GC 指针标记、SATB 屏障与对象搬移能够统一处理所有引用的前提。
跨语言调用(FFI)
FFI 通过外部函数接口实现仓颉语言与 C 语言、ArkTS 语言之间的函数调用和数据交互。标准库侧的支撑包括 core 包的 C 互操作类型(c_type.cj、c_pointer_resource.cj、c_string_resource.cj、native.cj)与 std.interop 包;加载器接口的 FindSymbol(ILoader.h)则提供了运行期符号解析能力。
DFX 调试与调优
DFX 提供日志打印、CPU 采集、堆快照导出等调试调优功能,支持运行时状态检测和故障排查:
- 日志:
Base/Log、Log级别宏(RTLOG_INFO/RTLOG_ERROR/RTLOG_FATAL等)贯穿运行时各模块,如SetGCThreshold中即通过LOG输出配置结果; - CPU 采集:runtime/src/CpuProfiler(
CpuProfiler+SamplesRecord采样记录); - 堆快照:runtime/src/Inspector 提供
CjHeapData/CjAllocData数据采集与 HeapSnapshotJsonSerializer 快照序列化输出,以及ProfilerAgentImpl对接外部分析工具; - 内存检查器:runtime/src/Sanitizer 支持 AddressSanitizer、HWAddressSanitizer、GWP-ASan 与 ThreadSanitizer 多种实现,构建时通过 CMake 的 sanitizer 开关按需链接。
运行时目录结构
完整继承 README 的目录说明,runtime/src 下各模块职责如下:
/cangjie_runtime
├── runtime
│ ├── build # 构建脚本
│ └── src
│ ├── Base # 日志等基础能力模块
│ ├── CJThread # 仓颉线程管理模块
│ ├── Common # 通用模块
│ ├── Concurrency # 并发管理模块
│ ├── CpuProfiler # CPU 采集工具
│ ├── Demangler # 符号去混淆工具
│ ├── Exception # 异常处理模块
│ ├── Heap # 内存管理模块
│ ├── Inspector # DFX 工具
│ ├── Loader # 加载器
│ ├── Mutator # GC 与业务线程状态同步模块
│ ├── ObjectModel # 对象模型
│ ├── Signal # 信号管理模块
│ ├── StackMap # 回栈元数据分析模块
│ ├── Sync # 同步原语实现模块
│ ├── UnwindStack # 回栈模块
│ ├── Utils # 工具类
│ ├── arch # 硬件平台适配代码
│ └── os # 软件平台适配代码
└── stdlib
其中 arch/ 按 CPU 架构(x86_64 / aarch64 / arm)与操作系统(linux / macos / ios / windows)组合提供汇编桩(Cjstart.S、StackGrowStub.S、HandleSafepointStub.S、C2NStub.S 等);os/ 按 Linux / Macos / Windows 提供 Loader、路径、Section 等平台适配实现。
仓颉运行时编译构建
约束
当前暂不支持 Windows 环境内对仓颉运行时进行构建,需要在 Linux 环境内通过交叉编译方式生成可在 Windows 平台运行的仓颉运行时产物(CMake 中通过 -target x86_64-w64-mingw32 交叉目标实现,见 runtime/CMakeLists.txt)。未来支持计划见下文平台支持计划。
构建步骤
独立构建请执行 build.py 脚本(构建前需按目标产物搭建编译环境,即 cangjie_build 仓库中的"仓颉 SDK 集成构建指导书"),脚本支持构建(build)、安装(install)和清理(clean)三个功能:
$ git clone https://gitcode.com/Cangjie/cangjie_runtime.git
构建命令:build 用于独立构建仓颉运行时,可配置项如下(详见 构建仓颉运行时):
| 参数 | 说明 |
|---|---|
--target <value> |
指定构建目标,默认 native。可选:native(Linux/macOS 到本机平台)、windows-x86_64、ohos-aarch64、ohos-x86_64(后三者均为 Linux 出发的交叉编译) |
-t, --build-type <value> |
构建模式:release、debug、relwithdebinfo,区分大小写,默认 release |
-v, --version <value> |
指定仓颉运行时版本号,默认 0.0.1 |
--prefix <value> |
构建产物安装路径,默认 runtime/output/common;build 与 install 同时指定时以 install 为准 |
-hwasan |
使能 Hardware-Assisted Address Sanitizer (HWASAN) |
--target-toolchain <value> |
交叉编译工具链,交叉编译构建时为必选参数 |
--cjlib-sanitizer-support |
构建支持运行 sanitizer 版本仓颉二进制的 runtime,可选值 asan、tsan、hwasan |
示例:
$ python3 build.py build --target native --build-type release -v 0.0.1
安装命令:
$ python3 build.py install
--prefix <value> 可选,不指定时沿用 build 中指定的路径。
清理命令(删除所有构建产物及中间产物):
$ python3 build.py clean
构建产物
/runtime
└─ output
├─ common # 编译产物默认安装路径
| └─ <target_platform>_<build_type>_<target_arch> # 产物描述
| ├─ bin # 可执行文件
| ├─ include # 头文件
| ├─ lib # 静态库等
| └─ runtime # 动态库等
└─ temp # 临时产物路径
从 CMake 安装规则看(runtime/CMakeLists.txt),产物还包括:动态库 libcangjie-runtime(安装到 runtime/lib/<arch>)、静态库 libcangjie-runtime.a(cangjie-runtime-static 目标)、进程启动汇编对象 cjstart.o、OHOS 场景的 cjpgo.o、以及符号去混淆工具 cjfilt;Release/MinSizeRel 构建还会对产物执行 strip。启用 RUNTIME_TRACE_FLAG 时额外产出线程追踪动态库 libcangjie-trace。
使用说明
运行时独立构建产物需要配合 cjc 编译器及标准库等使用,整体可在 Linux、macOS、Windows、OpenHarmony、iOS 与 Android 系统上直接运行;具体集成方式参见 cangjie_build 仓库中的"仓颉 SDK 集成构建指导书"。
仓颉编程语言标准库(std)
简介
仓颉编程语言标准库(std)是官方提供的一套核心库,预先定义了一组函数、类、结构体等,旨在提供常用的功能和工具,以便开发者能够更快速、更高效地编写程序。其三项特点和追求:
- 使用方便:标准库随编译器、工具链一起发布,不需要用户另外下载,开箱即用;
- 功能通用:提供开发者最常使用的一些库能力,旨在解决大部分基础问题;
- 质量标杆:追求在性能、代码风格等方面为其他仓颉库树立范例和标杆。
标准库的完整 API 与示例文档见仓库内的 标准库文档汇总(按包组织,含各包 API、异常类与示例教程)。
系统架构
包目录与功能说明
标准库源码位于 stdlib/libs/std,完整包列表见 stdlib/libs/std 下的源码组织。各包功能如下(继承自 README 目录说明):
/cangjie_runtime
├── runtime
└── stdlib
└── libs
└── std
├── argopt # 命令行参数字符串解析
├── ast # 语法解析器
├── binary # 提供基础数据类型和二进制字节数组的不同端序转换接口,以及端序反转接口
├── collection # 常见数据结构的实现、相关抽象接口的定义以及在集合类型中常用的函数功能
├── console # 提供和标准输入、标准输出、标准错误进行交互的方法
├── convert # 提供从字符串转到特定类型的 Convert 系列函数以及提供格式化能力
├── core # 标准库的核心包
├── crypto # 对称加解密和常用摘要算法能力
├── database # 仓颉访问数据库能力
├── deriving # 提供一组宏来自动生成接口实现
├── env # 提供当前进程的相关信息与功能
├── fs # 文件库
├── io # 提供程序与外部设备进行数据交换的能力
├── math # 数学库
├── net # 网络通信
├── objectpool # 对象缓存
├── overflow # 溢出处理
├── posix # 适配 POSIX 系统调用,提供跨平台的系统操作接口
├── process # 进程库
├── random # 提供生成伪随机数的能力
├── ref # 提供弱引用相关的能力
├── reflect # 反射功能
├── regex # 正则库
├── runtime # 运行时交互
├── sort # 排序
├── sync # 并发编程
├── time # 时间库
├── unicode # 字符处理
└── unittest # 用于编写仓颉项目单元测试代码
标准库总入口为 stdlib/libs/std/std.cj。按 标准库概述,除上述包外,std 还包含 collection.concurrent(并发安全集合)、concurrent(结构化并发)、crypto.cipher / crypto.digest(对称加解密 / 摘要算法)、database.sql、math.numeric、objectpool、unittest.mock / unittest.testmacro 等子包,每个包均可单独输出 AST、静态库、动态库等产物,并支持 import fullPackageName.{item1, item2} 等导入语法。
平台支持
标准库 API 支持的操作系统及版本要求(见 标准库概述):
| 操作系统 | CPU 架构 | 环境及其版本要求 |
|---|---|---|
| Linux | x86_64 | glibc 2.22;Linux Kernel 4.12 或更高版本;libstdc++ 6.0.24 或更高版本 |
| Linux | aarch64 | glibc 2.27;Linux Kernel 4.15 或更高版本;libstdc++ 6.0.24 或更高版本 |
| Windows | x86_64 | Windows 10 或更高版本 |
| macOS | aarch64 / x86_64 | macOS 12.0 或更高版本 |
| OpenHarmony | aarch64 / arm32 / x86_64 | OpenHarmony 5.1 或更高版本 |
| HarmonyOS | aarch64 | HarmonyOS 5.1 或更高版本 |
| iOS | aarch64 / x86_64(模拟器) | iOS 11 或更高版本(ast 库需要 iOS 12 或更高版本) |
| Android | aarch64 / x86_64 / arm32 | 分别要求 Android API 23 / 26 / 23 或更高版本 |
约束与构建
当前暂不支持 Windows 环境内对标准库进行构建,需要在 Linux 环境内通过交叉编译方式生成 Windows 平台产物。构建前需先构建本仓库的运行时与 cangjie_compiler,完整流程见 构建仓颉标准库:
- 配置
cjc环境(source源码构建产出的envsetup.sh),并用cjc -v验证版本信息; - 进入标准库目录执行
build.py(支持 build、clean、install 三个功能):
cd std
python3 build.py clean
python3 build.py build -t release --target-lib=<path to runtime build output directory> --target-lib=<path to openssl lib>
python3 build.py install
-t / --build-type:产物类型,release或debug;--target-lib:指定 openssl 库目录与运行时产物目录(运行时产物默认在 runtime/output 下),可同时多次指定。
install将产物安装到output目录,可选--prefix指定安装路径。
构建产物结构:
output
├── lib # std 静态库
├── modules # std cjo 文件
└── runtime # std 动态库
build.py build 还支持更多交叉编译选项(见 build_std.md):--target 支持 native、ohos-aarch64/x86_64/arm、windows-x86_64、ios-aarch64、ios-simulator-aarch64/x86_64、android-aarch64(API 23/26/31)、android-x86_64(API 26/31)、android23-arm 等目标;--target-toolchain、--target-sysroot 为交叉编译必选;另有 --build-args(cjc 构建选项)、--jobs(-j)(并发任务数)、--hwasan、--cjlib-sanitizer-support(asan/tsan/hwasan)等参数。标准库源码中的 CMake 工具链文件(如 stdlib/cmake/linux_toolchain.cmake、stdlib/cmake/ohos_aarch64_clang_toolchain.cmake 等)即为这些交叉目标的底层配置。
使用说明
标准库构建产物需要配合 cjc 编译器及运行时等使用,整体可在 Linux、macOS、Windows、OpenHarmony、iOS 与 Android 系统上直接运行,具体集成方式参见 cangjie_build 仓库中的"仓颉 SDK 集成构建指导书"。
平台支持计划
- 构建平台演进:计划于 2025 年底支持 Windows 构建出仓颉运行时和标准库产物;
- 仓颉应用运行平台演进:计划 2025 年 10 月 20 日支持仓颉应用在 OHOS-ARM32 平台运行;反射、动态加载特性以及部分编译器优化等高级特性计划在 2025 Q4 支持。
相关仓库、协议与贡献
仓颉语言生态由多个仓库协同组成,与本仓库直接相关的包括:编译器仓库 cangjie_compiler、工具仓库 cangjie_tools、扩展标准库 cangjie_stdx、文档仓库 cangjie_docs、SDK 集成构建仓库 cangjie_build 以及测试仓库 cangjie_test。
本项目基于 Apache-2.0 with Runtime Library Exception 开源协议(见 LICENSE),欢迎开发者贡献代码、文档等;具体贡献流程和方式可参见 OpenHarmony 社区的参与贡献指南。
小结
- 仓颉运行时围绕"全并发 GC + CJThread + 包级 Loader + 对象模型 + FFI + DFX"构建:GC 以枚举/追踪/搬移七阶段流水线配合指针标记与 SATB 屏障消除 STW,CJThread 以协程式调度与连续栈自动翻倍扩容应对各体量并发场景;
- 运行时与标准库均通过
build.py完成源码构建,运行时产物为动态库/静态库/cjstart.o等,标准库产物为lib/modules/runtime三部分,均可交叉编译至 OHOS、Windows、iOS、Android 等平台; - 源码入口可优先从 runtime/src/CangjieRuntime.h(运行时总控)、runtime/src/Heap/WCollector/WCollector.h(全并发收集器)、runtime/src/Loader/ILoader.h(包加载)与 stdlib/libs/std/std.cj(标准库总入口)切入。


