文档编程语言【免费下载链接】cangjie_docs仓颉编程语言开发者文档。项目地址https://gitcode.com/Cangjie/cangjie_docs点击查看免费下载仓颉Cangjie编程语言的 runtime运行时为仓颉可执行程序提供内存分配、垃圾回收GC、线程管理等底层能力。runtime 暴露了一系列环境变量允许开发者在不改动代码的前提下针对不同业务场景精细调优堆大小、GC 策略、region 分配、线程栈/并发数、运维日志输出等行为并可通过 GWP-Asan 机制检测仓颉与 C 语言互操作中的堆内存安全问题。本文以官方文档 runtime_env.md 为骨架结合仓库内编译选项、运行时部署、工具链手册等资料完整梳理这些环境变量的语义、默认值、有效范围与实战用法读完即可直接上手调优仓颉程序运行时。环境变量的设置方式仓颉运行时提供的环境变量均为进程级配置需在启动仓颉程序之前设置到当前 shell 环境中。不同操作系统设置方式不同Linux shell 与 macOS shell使用export命令。$ export VARIABLEvalueWindows cmd使用set命令。 set VARIABLEvalue下文所有示例均基于 Linux shell 的export写法若运行平台不符请替换为对应平台的环境变量设置方式。环境变量仅在程序启动前设置才生效程序运行期间修改不会影响当前进程如需长期生效可将配置写入.bashrc或系统环境变量。运行时初始化可选配置runtime 初始化参数用于控制堆、region 分配器与 GC 的默认行为。使用前需了解以下四条通用约束所有整型参数为Int64类型浮点型参数为Float64类型所有参数如果未显式规定最大值默认隐式最大值为该类型最大值所有参数若超出设置范围则设置无效自动使用默认值所有参数在 OpenHarmony 平台下均无效OpenHarmony 平台下仓颉运行时一律使用默认值。cjHeapSize指定仓颉堆的最大值仓颉堆heap是 runtime 管理对象内存的区域。cjHeapSize指定堆的最大值支持单位为kbKB、mbMB、gbGB有效范围为[4MB, 系统物理内存]超出范围的设置无效仍使用默认值。默认值规则若物理内存低于 1GB默认值为64MB否则为256MB。OpenHarmony 与 Android 平台支持的最小配置值为 64MB配置值低于该值时会自动回退到默认值。export cjHeapSize4GB实战参考当程序因堆空间不足抛出VirtualMachineError OutOfMemoryError时可通过增大该参数缓解。cjcov_manual.md 中针对覆盖率工具执行时的 OOM 场景给出了同样的建议默认情况下仓颉分配 1MB 栈与 256MB 堆内存通常 2GB 堆即可满足多数场景不足时可继续按需调大export cjHeapSize2GB此外在宏替换macro substitution场景中runtime 初始化配置默认使用宏提供的默认值其中cjHeapSize与cjStackSize是用户可修改的两个参数见 compiling_error_reporting_and_debugging.md。cjRegionSize指定 region 分配器线程本地缓冲区大小region 分配器将堆划分为若干 region 进行管理每个线程拥有独立的本地缓冲区thread local buffer。cjRegionSize指定该缓冲区大小支持单位为kb、mb、gb有效范围为[4kb, 2048kb]默认值为64KB。macOS 平台支持的最小配置值为 16KB低于该值的配置将使用默认值。export cjRegionSize1024kbcjLargeThresholdSize指定大对象阈值需要大量连续内存空间的对象例如长数组称为大对象。堆内频繁分配大对象可能导致堆内连续空间不足从而触发堆溢出问题。通过增大该阈值可以让更多对象按大对象路径分配从而提升堆内空间的连续性。在仓颉语言中大对象的阈值为cjLargeThresholdSize与cjRegionSize的较小者。cjLargeThresholdSize支持单位kb、mb、gb有效范围为[4KB, 2048KB]默认值为32KB。说明较大的大对象阈值可能影响程序性能开发者应根据实际需求设置。export cjLargeThresholdSize1024kbcjExemptionThreshold指定存活 region 的水线值取值(0, 1]Float64该值与 region 大小相乘若 region 中存活对象大小大于相乘后的值则该 region 不会被回收其中死亡对象继续占用内存。该值指定得越大region 被回收的概率越大堆中碎片空间越少但频繁回收 region 也会影响性能。默认值为0.880%。export cjExemptionThreshold0.8cjHeapUtilization指定仓颉堆的利用率取值(0, 1]是 GC 后更新堆水线heap waterline的参考依据之一。堆水线是指当堆中对象总大小达到水线值时即触发 GC。该参数指定得越小更新后的堆水线越高触发 GC 的概率相对越低。默认值为0.880%。export cjHeapUtilization0.8cjHeapGrowth指定仓颉堆的增长率取值必须大于 0同样是 GC 后更新堆水线的参考依据之一。增长率的计算方式为1 cjHeapGrowth参数值越大更新后的堆水线越高触发 GC 的概率越低。默认值为0.15表示增长率为1.15。export cjHeapGrowth0.15cjAllocationRate指定对象分配速率指定仓颉运行时分配对象的速率取值必须大于 0单位为MB/s表示每秒可分配对象的数量。默认值为10240即每秒可分配 10240MB 对象。export cjAllocationRate10240cjAllocationWaitTime指定对象分配等待时间取值必须大于 0支持单位为s、ms、us、ns推荐使用纳秒ns。若本次分配对象距离上一次分配对象的时间间隔小于该值则分配将等待。默认值为1000 ns。export cjAllocationWaitTime1000nscjGCThreshold指定仓颉堆的参考水线值支持单位为kb、mb、gb取值必须为大于 0 的整数。当仓颉堆大小超过该值时触发 GC。默认值为堆大小即由cjHeapSize决定的值。export cjGCThreshold20480KBcjGarbageThreshold指定 region 回收候选判定阈值当 GC 发生时如果 region 中死亡对象所占比率大于该环境变量此 region 会被放入回收候选集中后续可被回收若受到其他策略影响也可能不被回收。默认值为0.5无量纲有效区间为[0.0, 1.0]。export cjGarbageThreshold0.5cjGCInterval指定两次 GC 的间隔时间取值必须大于 0支持单位为s、ms、us、ns推荐使用毫秒ms。若本次 GC 距离上次 GC 的间隔小于该值则本次 GC 将被忽略。该参数用于控制 GC 的频率默认值为150 ms。export cjGCInterval150mscjBackupGCInterval指定备份 GC 的间隔取值必须大于 0支持单位为s、ms、us、ns推荐使用秒s。当仓颉运行时在该参数设定时间内未触发 GC则触发一次备份 GCbackup GC防止堆长期无 GC 导致内存膨胀。默认值为240 秒4 分钟。export cjBackupGCInterval240scjProcessorNum指定仓颉线程的最大并发数有效范围为(0, CPU 核数 × 2]超出范围的设置无效使用默认值。runtime 会调用系统 API 获取 CPU 核数若获取成功默认值为 CPU 核数否则默认值为8。export cjProcessorNum2cjStackSize指定仓颉线程的栈大小支持单位为kb、mb、gb有效范围Linux 平台为[64KB, 1GB]Windows 平台为[128KB, 1GB]超出范围设置无效使用默认值。默认值为128KB。export cjStackSize100kb为什么需要调整栈大小在仓颉与 C 语言互操作FFI场景中虽然仓颉CJNative 后端提供了栈扩展能力但 C 函数的栈使用对仓颉是不可见的因此 FFI 调用 C 函数仍然存在栈溢出风险可能导致运行时崩溃或未定义行为。开发者应结合实际需求调整cjStackSize配置见 cangjie-c.md。运维日志可选配置runtime 支持将内部运行信息输出为运维日志便于排查问题。以下环境变量用于控制日志的文件大小、输出路径与级别。MRT_LOG_FILE_SIZE指定运维日志文件大小默认值为10MB支持单位为kb、mb、gb设置值需大于 0。日志大小超过该值时会重新回到日志开头进行打印循环覆盖式写文件。最终生成的日志大小会略大于MRT_LOG_FILE_SIZE。export MRT_LOG_FILE_SIZE100kbMRT_LOG_PATH指定运维日志输出路径指定 runtime 运维日志的输出路径。若该环境变量未设置或路径设置失败运维日志默认打印到stdout标准输出或 stderr标准错误。export MRT_LOG_PATH/home/cangjie/runtime/runtime_log.txtMRT_LOG_LEVEL指定运维日志最小输出级别大于等于该级别的日志会被打印默认值为eERROR。支持值[v|d|i|w|e|f|s]含义分别为取值级别含义vVERBOSE最详细含所有运行信息dDEBUG调试信息iINFO常规信息wWARNING警告eERROR错误默认fFATAL致命错误sFATAL_WITHOUT_ABORT致命但不终止进程export MRT_LOG_LEVELvMRT_REPORT指定 GC 日志输出路径指定 runtime GC 日志的输出路径。若该环境变量未设置或路径设置失败该日志默认不打印。可用于观察 GC 触发时机与堆状态辅助调优前述 GC 相关参数。export MRT_REPORT/home/cangjie/runtime/gc_log.txtMRT_LOG_CJTHREAD指定 cjthread 日志输出路径指定 cjthread仓颉线程日志的输出路径。若该环境变量未设置或路径设置失败该日志默认不打印。export MRT_LOG_CJTHREAD/home/cangjie/runtime/cjthread_log.txtcjHeapDumpOnOOM是否输出堆快照指定是否在发生堆溢出OutOfMemoryError后输出堆快照文件默认不开启。支持值为[on|off]设定为on时开启设定off或其他值不开启。export cjHeapDumpOnOOMoncjHeapDumpLog指定堆快照输出路径指定堆快照文件的输出路径。注意指定的路径必须已存在且应用执行者对其具有读写权限。如果不指定堆快照文件将输出到当前执行目录。export cjHeapDumpLog/home/cangjie运行环境可选配置以下参数用于控制运行时对栈溢出等异常场景的处理行为。MRT_STACK_CHECK开启 native stack overflow 检查开启 native stack overflow 检查默认不开启。支持设置为1、true、TRUE开启该功能。export MRT_STACK_CHECKtrueCJ_SOF_SIZE控制 StackOverflowError 异常栈折叠长度当 StackOverflowError 发生时runtime 会自动折叠异常调用栈方便阅读折叠后栈帧层数默认值为32。可通过该环境变量控制折叠栈长度支持设置为 int 范围内的整数其语义为CJ_SOF_SIZE 0打印所有调用栈CJ_SOF_SIZE 0从栈底开始打印环境变量配置层数CJ_SOF_SIZE 0从栈顶开始打印环境变量配置层数CJ_SOF_SIZE未配置默认打印栈顶开始 32 层调用栈。export CJ_SOF_SIZE30仓颉 GWP-Asan 内存安全检测在仓颉与 C 代码互操作的过程中可能出现仓颉堆内存安全问题。仓颉 GWP-Asan提供了一种内存安全检测功能可以在仓颉程序运行过程中检测代码是否存在仓颉堆内存安全问题。其原理是对仓颉语言标准库提供的acquireArrayRawData与releaseArrayRawData接口参见《仓颉编程语言库 API 文档》std.core包一节进行采样记录并对比采样对象前后内存的Canary 数据从而检测仓颉与 C 语言互操作过程中是否出现了仓颉堆内存安全问题。仓颉 GWP-Asan 是一种基于采样的检测工具可以通过设置不同的采样频率来平衡性能影响和检测覆盖率。在默认或更低采样频率下CPU 性能损失和额外的内存占用极低。说明仓颉 GWP-Asan 内存安全检测仅支持Linux 与 OpenHarmony操作系统。cjEnableGwpAsan开启 GWP-Asan 检测仓颉 GWP-Asan 内存安全检测功能默认关闭。通过将环境变量cjEnableGwpAsan设置为1、true或TRUE可以开启该功能。export cjEnableGwpAsantruecjGwpAsanSampleRate设置采样频率在 GWP-Asan 开启状态下可通过该环境变量设置采样频率。支持设置为 32 位整型数值范围内的正整数即(0, 2^31 - 1]。默认值为5000即每 5000 次acquireArrayRawData接口调用进行一次采样。export cjGwpAsanSampleRate1000说明采样会影响性能采样率越高对性能影响越大能检出更多的问题采样率越低性能影响越小检出的问题更少。请根据实际需求设置采样率。cjGwpAsanHelp输出 GWP-Asan 帮助信息通过该环境变量设置是否在控制台输出 GWP-Asan 帮助信息默认不开启。设置为1、true或TRUE时会在控制台输出帮助信息。export cjGwpAsanHelptrue约束限制仓颉 GWP-Asan 是一种基于采样的内存检查工具内存越界问题可能无法完全检出仓颉 GWP-Asan 对仓颉堆内存的越界检测范围有限无法检测内存读越界访问仅能检测部分写越界访问向前写越界 8 字节以内向后写越界到尾部的填充区域根据数组对象长度的不同填充区域可能为 0-7 字节。异常检测类型与错误报告堆内存写越界堆内存写越界指的是指针实际访问的内存长度超过了数组申请的长度造成仓颉堆内存写越界。1. 向前越界向前越界数组时runtime 会报告Head canary检测失败使用array[-1]表示。示例代码通过acquireArrayRawData获取数组原始数据指针后向数组头部之前的越界位置写入unsafe { var array ArrayUInt8(4, repeat: 1) var cp acquireArrayRawDataUInt8(array) cp.pointer.write(-1, 2) releaseArrayRawData(cp) }对应的错误报告如下2025-05-22 10:57:13.432786 41217 F Gwp-Asan sanity check failed on raw array addr 0x7f7c887368 2025-05-22 10:57:13.432863 41217 F Head canary (array[-1]) mismatch: expect: 0x4, actual: 0x200000000000004 2025-05-22 10:57:13.432878 41217 F Gwp-Asan Aborted.2. 向后越界向后越界数组时runtime 会报告Tail canary检测失败并给出相对该数组array的位置。示例中数组实际可访问范围是[0, 4)而写操作访问了第 6 个字节导致堆内存向后溢出 2 个字节错误报告使用array[size1]表示该行为unsafe { let array ArrayUInt8(4, repeat: 0) let cp acquireArrayRawData(array) // array 数组实际可访问的范围是 [0, 4)而下述写操作访问了第 6 个字节导致仓颉堆内存向后溢出 2 个字节。错误报告中使用 array[size1] 表示该向后越界行为。 cp.pointer.write(5, 2) releaseArrayRawData(cp) }对应的错误报告如下2025-05-22 10:53:09.564580 37872 F Gwp-Asan sanity check failed on raw array addr 0x7f6278a368 2025-05-22 10:53:09.564761 37872 F Tail canary (array[size1]) mismatch: expect: 0x4, actual: 0x2 2025-05-22 10:53:09.564788 37872 F Gwp-Asan Aborted.仓颉 GC 异常使用acquireArrayRawData获取了数组的指针但未配套使用releaseArrayRawData释放数组的引用可能造成仓颉 GCGarbage Collection异常。在 runtime 退出时会检测被采样的数组是否调用了releaseArrayRawData释放未释放时会报告所有未释放数组对应的堆地址unsafe { let array ArrayUInt8(4, repeat: 0) let cp acquireArrayRawData(array) cp.pointer.read() // 未使用 releaseArrayRawData return }对应的错误报告如下2025-05-22 10:53:09.564761 1248614 F Unreleased array: 0x7fffd77f92d8 2025-05-22 10:53:09.564788 1248614 F Detect un-released array因此在使用acquireArrayRawData时必须保证成对调用releaseArrayRawData避免泄漏数组引用导致 GC 异常。补充运行时配置的工程化实践通过cjpm配置测试环境变量在cjpm的cjpm.toml配置中[profile.test.env]段支持为测试进程注入运行时环境变量例如cjHeapSize { value 32GB, splice-type replace }可将运行时参数固化到工程配置中与命令行export互补见 cjpm_manual.md。与运行时部署配合环境变量调优的前提是运行时动态库已正确部署。Linux 下需通过LD_LIBRARY_PATH指向${CANGJIE_HOME}/runtime/lib/linux_${hw_arch}_cjnativemacOS 使用DYLD_LIBRARY_PATH见 runtime_deploy.md。若编译时使用--static全静态链接仅 Linux 生效runtime 模块已嵌入可执行文件则无需额外部署运行时见 compile_options.md。版本兼容注意运行时加载仓颉包时会执行二进制兼容性检查0.59.4 版本起若运行时与包版本不兼容会终止执行或抛出IncompatiblePackageException调优前请确认运行时与库版本匹配见 cangjie_package_compatibility.md。参数速查表环境变量作用单位有效范围默认值cjHeapSize仓颉堆最大值kb/mb/gb[4MB, 物理内存]内存 1GB 时 64MB否则 256MBcjRegionSizeregion 分配器线程本地缓冲区kb/mb/gb[4kb, 2048kb]64KBcjLargeThresholdSize大对象阈值取与 region size 的较小者kb/mb/gb[4KB, 2048KB]32KBcjExemptionThreshold存活 region 水线无量纲(0, 1]0.8cjHeapUtilization堆利用率无量纲(0, 1]0.8cjHeapGrowth堆增长率实际增长 1 值无量纲 00.15cjAllocationRate对象分配速率MB/s 010240cjAllocationWaitTime对象分配等待时间s/ms/us/ns 01000nscjGCThreshold触发 GC 的堆参考水线kb/mb/gb正整数堆大小cjGarbageThresholdregion 回收候选判定阈值无量纲[0.0, 1.0]0.5cjGCInterval两次 GC 最小间隔s/ms/us/ns 0150mscjBackupGCInterval备份 GC 间隔s/ms/us/ns 0240scjProcessorNum线程最大并发数无(0, CPU核数×2]CPU 核数获取失败时 8cjStackSize线程栈大小kb/mb/gbLinux [64KB, 1GB] / Windows [128KB, 1GB]128KBMRT_LOG_FILE_SIZE运维日志文件大小kb/mb/gb 010MBMRT_LOG_PATH运维日志输出路径路径—stdout/stderrMRT_LOG_LEVEL运维日志最小级别v/d/i/w/e/f/s—eMRT_REPORTGC 日志输出路径路径—不打印MRT_LOG_CJTHREADcjthread 日志输出路径路径—不打印cjHeapDumpOnOOMOOM 后输出堆快照on/off—offcjHeapDumpLog堆快照输出路径路径路径需存在且可读写当前执行目录MRT_STACK_CHECK开启 native 栈溢出检查1/true/TRUE—关闭CJ_SOF_SIZEStackOverflowError 折叠栈长度intint 范围32栈顶cjEnableGwpAsan开启 GWP-Asan 检测仅 Linux/OpenHarmony1/true/TRUE—关闭cjGwpAsanSampleRateGWP-Asan 采样频率次(0, 2³¹-1]5000cjGwpAsanHelp输出 GWP-Asan 帮助信息1/true/TRUE—关闭调优时遵循先观测、再调整的原则优先通过MRT_LOG_PATH、MRT_REPORT等日志观察堆与 GC 实际行为再针对性地调整堆大小、GC 间隔与 region 相关参数涉及 C 互操作的场景按需开启 GWP-Asan 并调整采样率在性能开销与检测覆盖之间取得平衡。赞分享文档编程语言【免费下载链接】cangjie_docs仓颉编程语言开发者文档。项目地址https://gitcode.com/Cangjie/cangjie_docs点击查看免费下载相关推荐仓颉编程语言完整开发环境配置终极指南仓颉编程语言完整开发环境配置终极指南 仓颉编程语言是一款全场景智能化应用编程语言为开发者提供了高效、安全的开发体验。本文将详细介绍如何快速搭建仓颉编程语言的完文档知识库仓颉编程基础及应用Windows 下仓颉 SDK含编译器下载、安装与环境变量配置实战仓颉编程基础及应用Windows 下仓颉 SDK含编译器下载、安装与环境变量配置实战 本文以随书仓库《仓颉编程基础及应用》 扩展阅读资料 https://示例工程教程TCMalloc GWP-ASan 实战指南用低开销采样检测生产环境的堆越界与 Use-After-FreeTCMalloc GWP ASan 实战指南用低开销采样检测生产环境的堆越界与 Use After Free 导读 GWP ASan 是 Google TCM内存管理系统编程上一篇30亿参数撬动企业AI变革IBM Granite-4.0-H-Micro重新定义轻量化智能部署下一篇Pulse v6.4.0-rc.7 告警引擎演进全解析滚动窗口评估、容量预测与事件日志权威化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考