Runtime Environment Variable User Guide

This section describes the environment variables provided by runtime.

In the Linux shell and macOS shell, you can use the following mode to set the environment variables provided at Cangjie runtime:

$ export VARIABLE=value

In the Windows cmd, you can use the following mode to set the environment variables provided at Cangjie runtime:

> set VARAIBLE=value

The examples in this section use the setting method for Linux shell. You can choose an appropriate method for setting environment variables based on your operating platform.

Optional Configuration for Runtime Initialization

Note:

All integer parameters are of the Int64 type, and floating-point parameters are of the Float64 type.
If the maximum value is not explicitly specified by any parameter, the implicit maximum value is the maximum value of such type by default.
If any parameter exceeds the specified range, the default value is used automatically.

`cjHeapSize`

Specifies the maximum size of the Cangjie heap. The unit can be KB, MB, or GB. The value range is [4 MB, System physical memory]. If the specified value is out of the range, the default value is used. If the physical memory is less than 1 GB, the default size is 64 MB. Otherwise, the default size is 256 MB.

Example:

export cjHeapSize=32GB

`cjRegionSize`

Specifies the size of the thread local buffer of the region allocator. The unit can be KB, MB, or GB. The value range is [4 KB, 2048 KB]. If the value is out of the range, the default value is used. The default size is 64 KB.

Example:

export cjRegionSize=1024kb

`cjExemptionThreshold`

Specifies the threshold of live regions. The value range is (0,1]. If the number of live objects in a region is greater than this value multiplied by the region size, the region will not be collected (dead objects continue to occupy the memory). A larger value indicates a higher probability that regions are collected and less fragmentation in the heap. However, frequent region collection affects performance. If the value is out of the range, the default value is used. The default size is 1024 KB. The default value is 0.8, that is, 80%.

Example:

export cjExemptionThreshold=0.8

`cjHeapUtilization`

Specifies the Cangjie heap utilization. This parameter is used as a reference for updating the heap threshold after GC. The value range is (0, 1]. When the total size of objects in the heap reaches the threshold, GC is performed. A smaller value indicates a higher updated heap threshold and a lower probability of triggering GC. If the value is out of the range, the default value is used. The default value is 0.8, that is, 80%.

Example:

export cjHeapUtilization=0.8

`cjHeapGrowth`

Specifies the growth rate of the Cangjie heap. This parameter is used as a reference for updating the heap threshold after GC. The value must be greater than 0. The growth rate is calculated as 1 + cjHeapGrowth. A larger value indicates a higher updated heap threshold and a lower probability of triggering GC. The default value is 0.15, indicating that the growth rate is 1.15.

Example:

export cjHeapGrowth=0.15

`cjAlloctionRate`

Specifies the rate at which the Cangjie runtime allocates objects. The value must be greater than 0, measured in MB/s, indicating the number of objects that can be allocated per second. The default value is 10240, indicating that 10240 MB objects can be allocated per second.

Example:

export cjAlloctionRate=10240

`cjAlloctionWaitTime`

Specifies the wait time for the Cangjie runtime when objects are being allocated. The value must be greater than 0. The unit can be s, ms, μs, or ns (recommended). If the time interval since the last object allocation is less than this value, the system waits. The default interval is 1000 ns.

Example:

export cjAlloctionWaitTime=1000ns

`cjGCThreshold`

Specifies the reference threshold of the Cangjie heap. The unit can be KB, MB, or GB. The value must be an integer greater than 0. When the size of the Cangjie heap exceeds this value, GC is triggered. The default value is the heap size.

Example:

export cjGCThreshold=20480KB

`cjGarbageThreshold`

When GC occurs, if the ratio of dead objects in a region exceeds this environment variable, the region is placed in the candidate set and may be collected later (if affected by other policies, the region may not be collected). The default value is 0.5, unitless. The value range is [0.0, 1.0].

Example:

export cjGarbageThreshold=0.5

`cjGCInterval`

Specifies the interval time between two GCs. The value must be greater than 0. The unit can be s, ms (recommended), μs, or ns. If the interval since the last GC is less than this value, the current GC will be ignored. This parameter controls the GC frequency. The default interval is 150 ms.

Example:

export cjGCInterval=150ms

`cjBackupGCInterval`

Specifies the backup GC interval. The value must be greater than 0. The unit can be s (recommended), ms, μs, or ns. If GC is not triggered within this time, a backup GC is triggered. The default interval is 240 seconds, that is, 4 minutes.

Example:

export cjBackupGCInterval=240s

`cjGCThreads`

Specifies a factor that affects the number of GC threads. The value must be greater than 0. The number of GC threads is calculated as follows: (Number of concurrent threads supported by the system/cjGCThreads) – 1. The default value is 8.

Example:

export cjGCThreads=8

`cjProcessorNum`

Specifies the maximum number of concurrent Cangjie threads. The value range is (0, Number of CPU cores x 2]. If the value is out of the range, the default value is used. The system API is called to obtain the number of CPU cores. If the operation is successful, the default value is the number of CPU cores. Otherwise, the default value is 8.

Example:

export cjProcessorNum=2

`cjStackSize`

Specifies the stack size of the Cangjie thread. The unit can be KB, MB, or GB. The value range is [64 KB, 1 GB] on the Linux platform and [128 KB, 1 GB] on the Windows platform. If the value is out of the range, the default value is used. The default size is 64 KB on Linux and 128 KB on Windows.

Example:

export cjStackSize=100kb

Optional Configuration for O&M Logs

`MRT_LOG_FILE_SIZE`

Specifies the size of runtime O&M logs. The default size is 10 MB. The unit can be KB, MB, or GB. The value must be greater than 0.

When the log size exceeds this value, logs are printed from the beginning.

The size of the generated logs is slightly greater than the value of MRT_LOG_FILE_SIZE.

Example:

export MRT_LOG_FILE_SIZE=100kb

`MRT_LOG_PATH`

Specifies the output path of runtime O&M logs. If the environment variable is not set or the path fails to be set, O&M logs are printed to stdout (standard output) or stderr (standard error) by default.

Example:

export MRT_LOG_PATH=/home/cangjie/runtime/runtime_log.txt

`MRT_LOG_LEVEL`

Specifies the minimum output level of runtime O&M logs. Logs at or above this level will be printed. The default value is e. The value range is [v|d|i|w|e|f|s]: v (VERBOSE), d (DEBUGY), i (INFO), w (WARNING), e (ERROR), f (FATAL), s (FATAL_WITHOUT_ABORT).

Example:

export MRT_LOG_LEVEL=v

`MRT_REPORT`

Specifies the output path of runtime GC logs. If the environment variable is not set or the path fails to be set, the logs are not printed by default.

Example:

export MRT_REPORT=/home/cangjie/runtime/gc_log.txt

`MRT_LOG_CJTHREAD`

Specifies the output path of cjthread logs. If the environment variable is not set or the path fails to be set, the logs are not printed by default.

Example:

export MRT_LOG_CJTHREAD=/home/cangjie/runtime/cjthread_log.txt

`cjHeapDumpOnOOM`

Specifies whether to output a heap snapshot file after a heap overflow occurs. By default, this function is disabled. The value range is [on|off]. If the value is on, the function is enabled. If the value is off or other values, the function is disabled.

Example:

export cjHeapDumpOnOOM=on

`cjHeapDumpLog`

Specifies the path of an output heap snapshot file. The specified path must exist and the application executor must have the read and write permissions on the path. If it is not specified, the heap snapshot file is exported to the current execution directory.

Example:

export cjHeapDumpLog=/home/cangjie

Optional Configuration for Runtime Environment

`MRT_STACK_CHECK`

Enables the native stack overflow check. This function is disabled by default and supports the values 1, true, or TRUE to enable it.

Example:

export MRT_STACK_CHECK=true

`CJ_SOF_SIZE`

When StackOverflowError occurs, the exception stack is automatically folded to facilitate reading. The default number of stack frames after folding is 32. You can set this environment variable to control the length of the folded stack. The value can be an integer within the int range. CJ_SOF_SIZE = 0: prints the entire call stack. CJ_SOF_SIZE < 0: starts printing from the bottom of the stack for the number of frames set by the environment variable. CJ_SOF_SIZE > 0: starts printing from the top of the stack for the number of frames set by the environment variable. If CJ_SOF_SIZE is not configured, the default is to print 32 layers of the call stack starting from the top.

Example:

export CJ_SOF_SIZE=30