Runtime Environment Variables Manual
Inspect one language lane at a time so line-level text and code deltas stay readable.
Diff Lane
English
0 modified sections0 code block delta0 anchor delta
Diff Lane
中文
6 modified sections4 code block delta4 anchor delta
modifiedruntime 初始化可选配置text+1 line
v1.0.5
Section Text
1
注意：2
3
1. 所有整型参数为 Int64 类型，浮点型参数为 Float64 类型;4
2. 所有参数如果未显式规定最大值，默认隐式最大值为该类型最大值;5
3. 所有参数若超出范围则设置无效，自动使用默认值。v1.1.0
Section Text
1
注意：2
3
1. 所有整型参数为 Int64 类型，浮点型参数为 Float64 类型;4
2. 所有参数如果未显式规定最大值，默认隐式最大值为该类型最大值;5
3. 所有参数若超出范围则设置无效，自动使用默认值。6
4. 所有参数在 OpenHarmonyOS 平台下均无效，OpenHarmonyOS 平台下仓颉运行时使用默认值。modified`cjHeapSize`text+1 line, -1 line
v1.0.5
Section Text
1
指定仓颉堆的最大值，支持单位为 kb（KB）、mb（MB）、gb（GB），支持设置范围为[4MB, 系统物理内存]，超出范围的设置无效，仍旧使用默认值。若物理内存低于 1GB，默认值为 64 MB，否则为 256 MB。2
3
例如：Code 1 · shell
1
export cjHeapSize=4GBv1.1.0
Section Text
1
指定仓颉堆的最大值，支持单位为 kb（KB）、mb（MB）、gb（GB），支持设置范围为[4MB, 系统物理内存]，超出范围的设置无效，仍旧使用默认值。若物理内存低于 1GB，默认值为 64MB，否则为 256MB。OpenHarmony 和 Android 平台支持的最小配置值为 64MB，指定小于此值时使用默认值。2
3
例如：Code 1 · shell
1
export cjHeapSize=4GBmodified`cjRegionSize`text+1 line, -1 line
v1.0.5
Section Text
1
指定 region 分配器 thread local buffer 的大小，支持单位为 kb（KB）、mb（MB）、gb（GB)，支持设置范围为[4kb, 2048kb]，超出范围的设置无效，仍旧使用默认值。默认值为 64 KB。2
3
例如：Code 1 · shell
1
export cjRegionSize=1024kbv1.1.0
Section Text
1
指定 region 分配器 thread local buffer 的大小，支持单位为 kb（KB）、mb（MB）、gb（GB），支持设置范围为[4kb, 2048kb]，超出范围的设置无效，仍旧使用默认值。默认值为 64KB。macOS 平台支持的最小配置值为 16KB，指定小于此值时使用默认值。2
3
例如：Code 1 · shell
1
export cjRegionSize=1024kbmodified`cjLargeThresholdSize`text+1 line, -1 line
v1.0.5
Section Text
1
需要大量连续内存空间的对象（例如长数组）称为大对象。堆内频繁分配大对象可能导致堆内连续空间不足，从而触发堆溢出问题。通过增加大对象的最大值，可以提升堆内空间的连续性。2
3
在仓颉语言中，大对象的阈值为 `cjLargeThresholdSize` 和 `cjRegionSize` 的较小者。`cjLargeThresholdSize` 支持的单位有 kb（KB）、mb（MB）、gb（GB)，支持的范围是 [4KB, 2048KB]，超出范围的设置无效，仍旧使用默认值。默认值为 32 KB。4
5
> **说明：**6
>7
> 较大的大对象阈值可能影响程序性能，开发者可根据实际情况设置。8
9
例如：Code 1 · shell
1
export cjLargeThresholdSize=1024kbv1.1.0
Section Text
1
需要大量连续内存空间的对象（例如长数组）称为大对象。堆内频繁分配大对象可能导致堆内连续空间不足，从而触发堆溢出问题。通过增加大对象的最大值，可以提升堆内空间的连续性。2
3
在仓颉语言中，大对象的阈值为 `cjLargeThresholdSize` 和 `cjRegionSize` 的较小者。`cjLargeThresholdSize` 支持的单位有 kb（KB）、mb（MB）、gb（GB），支持的范围是 [4KB, 2048KB]，超出范围的设置无效，仍旧使用默认值。默认值为 32KB。4
5
> **说明：**6
>7
> 较大的大对象阈值可能影响程序性能，开发者可根据实际情况设置。8
9
例如：Code 1 · shell
1
export cjLargeThresholdSize=1024kbmodified仓颉 GWP-Asan 内存安全检测text+1 line, -1 line
v1.0.5
Section Text
1
在仓颉与 C 代码互操作的过程中，可能出现一些仓颉堆内存安全问题。仓颉 GWP-Asan 提供了一种内存安全检测功能。它可以在仓颉程序运行过程中检测代码是否存在仓颉堆内存安全问题。GWP-Asan 通过对仓颉语言标准库提供的 acquireArrayRawData 和 releaseArrayRawData 接口（参见《仓颉编程语言库 API 文档》std.core 包一节）进行采样，并记录对比采样对象前后内存的 Canary 数据，从而检测仓颉与 C 语言互操作过程中是否出现了仓颉堆内存安全问题。2
3
仓颉 GWP-Asan 是一种基于采样的检测工具，可以通过设置不同的值来调整采样频率，以平衡性能影响和检测覆盖率。在默认或更低采样频率下，CPU 性能损失和额外的内存占用极低。4
5
> **说明：**6
>7
> 仓颉 GWP-Asan 内存安全检测仅支持 Linux 和 HarmonyOS 操作系统。v1.1.0
Section Text
1
在仓颉与 C 代码互操作的过程中，可能出现一些仓颉堆内存安全问题。仓颉 GWP-Asan 提供了一种内存安全检测功能。它可以在仓颉程序运行过程中检测代码是否存在仓颉堆内存安全问题。GWP-Asan 通过对仓颉语言标准库提供的 acquireArrayRawData 和 releaseArrayRawData 接口（参见《仓颉编程语言库 API 文档》std.core 包一节）进行采样，并记录对比采样对象前后内存的 Canary 数据，从而检测仓颉与 C 语言互操作过程中是否出现了仓颉堆内存安全问题。2
3
仓颉 GWP-Asan 是一种基于采样的检测工具，可以通过设置不同的值来调整采样频率，以平衡性能影响和检测覆盖率。在默认或更低采样频率下，CPU 性能损失和额外的内存占用极低。4
5
> **说明：**6
>7
> 仓颉 GWP-Asan 内存安全检测仅支持 Linux 和 OpenHarmonyOS 操作系统。modified异常检测类型textcode+9 lines, -7 lines
v1.0.5
Section Text
1
**堆内存写越界**2
3
堆内存写越界指的是，指针实际访问的内存长度超过了数组申请的长度，造成仓颉堆内存写越界。4
5
1. 向前越界6
7
向前越界数组时，runtime 会报告 Head canary 检测失败，使用 `array[-1]` 表示。例如：8
9
```cangjie10
unsafe {11
let array = Array<UInt8>(4, item: 0)12
let cp = acquireArrayRawData(array)13
// array 数组实际可访问的范围是 [0, 4)，而下述写操作访问了第 -2 个字节，导致仓颉堆内存向前溢出 2 个字节。错误报告中使用 array[-1] 表示该向前越界行为。14
cp.pointer.read(-2)15
releaseArrayRawData(array)16
}17
```18
19
对应的错误报告如下：20
21
```text22
2025-05-22 10:57:13.432786 41217 F Gwp-Asan sanity check failed on raw array addr 0x7f7c88736823
2025-05-22 10:57:13.432863 41217 F Head canary (array[-1]) mismatch: expect: 0x2, actual: 0x20000000000000224
2025-05-22 10:57:13.432878 41217 F Gwp-Asan Aborted.25
```26
27
2. 向后越界28
29
向后越界数组时，runtime 会报告 Tail canary 检测失败，并给出相对该数组（`array`）的位置。例如：30
31
```cangjie32
unsafe {33
let array = Array<UInt8>(4, item: 0)34
let cp = acquireArrayRawData(array)35
36
// array 数组实际可访问的范围是 [0, 4)，而下述写操作访问了第 6 个字节，导致仓颉堆内存向前溢出 2 个字节。错误报告中使用 array[size+1] 表示该向后越界行为。37
cp.pointer.read(5)38
releaseArrayRawData(array)39
}40
```41
42
对应的错误报告如下：43
44
```text45
2025-05-22 10:53:09.564580 37872 F Gwp-Asan sanity check failed on raw array addr 0x7f6278a36846
2025-05-22 10:53:09.564761 37872 F Tail canary (array[size+1]) mismatch: expect: 0x6, actual: 0x247
2025-05-22 10:53:09.564788 37872 F Gwp-Asan Aborted.48
```49
50
**仓颉 GC（Garbage Collection）异常**51
52
使用 acquireArrayRawData 获取了数组的指针，但是未配套使用 releaseArrayRawData 释放数组的引用，可能造成仓颉 GC（Garbage Collection）异常。53
54
在 runtime 退出时会检测被采样的数组是否调用了 releaseArrayRawData 释放。未释放时，会报告所有未释放的数组对应的堆地址。例如：55
56
57
对应的错误报告如下：Code 1 · cangjie
1
unsafe {2
let array = Array<UInt8>(4, item: 0)3
let cp = acquireArrayRawData(array)4
cp.pointer.read()5
6
// 未使用 releaseArrayRawData7
return8
}Code 2 · text
1
2025-05-22 10:53:09.564761 1248614 F Unreleased array: 0x7fffd77f92d82
2025-05-22 10:53:09.564788 1248614 F Detect un-released arrayv1.1.0
Section Text
1
**堆内存写越界**2
3
堆内存写越界指的是，指针实际访问的内存长度超过了数组申请的长度，造成仓颉堆内存写越界。4
5
1. 向前越界6
7
向前越界数组时，runtime 会报告 Head canary 检测失败，使用 `array[-1]` 表示。例如：8
9
<!-- compile -->10
11
```cangjie12
unsafe {13
var array = Array<UInt8>(4, repeat: 1)14
var cp = acquireArrayRawData<UInt8>(array)15
cp.pointer.write(-1, 2)16
releaseArrayRawData(cp)17
}18
```19
20
对应的错误报告如下：21
22
```text23
2025-05-22 10:57:13.432786 41217 F Gwp-Asan sanity check failed on raw array addr 0x7f7c88736824
2025-05-22 10:57:13.432863 41217 F Head canary (array[-1]) mismatch: expect: 0x4, actual: 0x20000000000000425
2025-05-22 10:57:13.432878 41217 F Gwp-Asan Aborted.26
```27
28
2. 向后越界29
30
向后越界数组时，runtime 会报告 Tail canary 检测失败，并给出相对该数组（`array`）的位置。例如：31
32
<!-- compile -->33
34
```cangjie35
unsafe {36
let array = Array<UInt8>(4, repeat: 0)37
let cp = acquireArrayRawData(array)38
39
// array 数组实际可访问的范围是 [0, 4)，而下述写操作访问了第 6 个字节，导致仓颉堆内存向前溢出 2 个字节。错误报告中使用 array[size+1] 表示该向后越界行为。40
cp.pointer.write(5, 2)41
releaseArrayRawData(cp)42
}43
```44
45
对应的错误报告如下：46
47
```text48
2025-05-22 10:53:09.564580 37872 F Gwp-Asan sanity check failed on raw array addr 0x7f6278a36849
2025-05-22 10:53:09.564761 37872 F Tail canary (array[size+1]) mismatch: expect: 0x4, actual: 0x250
2025-05-22 10:53:09.564788 37872 F Gwp-Asan Aborted.51
```52
53
**仓颉 GC（Garbage Collection）异常**54
55
使用 acquireArrayRawData 获取了数组的指针，但是未配套使用 releaseArrayRawData 释放数组的引用，可能造成仓颉 GC（Garbage Collection）异常。56
57
在 runtime 退出时会检测被采样的数组是否调用了 releaseArrayRawData 释放。未释放时，会报告所有未释放的数组对应的堆地址。例如：58
59
<!-- compile -->60
61
62
对应的错误报告如下：Code 1 · cangjie
1
unsafe {2
let array = Array<UInt8>(4, repeat: 0)3
let cp = acquireArrayRawData(array)4
cp.pointer.read()5
6
// 未使用 releaseArrayRawData7
return8
}Code 2 · text
1
2025-05-22 10:53:09.564761 1248614 F Unreleased array: 0x7fffd77f92d82
2025-05-22 10:53:09.564788 1248614 F Detect un-released arrayremoved`cjAlloctionRate`
v1.0.5
1
`cjAlloctionRate`2
3
指定仓颉运行时分配对象的速率，该值必须大于 0，单位为 MB/s，表示每秒可分配对象的数量。默认值为 10240，表示每秒可分配 10240 MB 对象。4
5
例如：6
7
export cjAlloctionRate=10240removed`cjAlloctionWaitTime`
v1.0.5
1
`cjAlloctionWaitTime`2
3
指定仓颉运行时分配对象时的等待时间，该值必须大于 0，支持单位为 s、ms、us、ns，推荐单位为纳秒（ns）。若本次分配对象距离上一次分配对象的时间间隔小于此值，则将等待。默认值为 1000 ns。4
5
例如：6
7
export cjAlloctionWaitTime=1000nsadded`cjAllocationRate`
v1.1.0
1
`cjAllocationRate`2
3
指定仓颉运行时分配对象的速率，该值必须大于 0，单位为 MB/s，表示每秒可分配对象的数量。默认值为 10240，表示每秒可分配 10240 MB 对象。4
5
例如：6
7
export cjAllocationRate=10240added`cjAllocationWaitTime`
v1.1.0
1
`cjAllocationWaitTime`2
3
指定仓颉运行时分配对象时的等待时间，该值必须大于 0，支持单位为 s、ms、us、ns，推荐单位为纳秒（ns）。若本次分配对象距离上一次分配对象的时间间隔小于此值，则将等待。默认值为 1000 ns。4
5
例如：6
7
export cjAllocationWaitTime=1000ns