Skip to content

Environment Variables

The runtime reads environment variables exactly once, when configuration is first needed (the first Ha* or ha_drv_* API call, or the first host memory allocation). Changing a value after that point has no effect, so set it before launch (in the shell) or before the first Ha* API call.

Environment variables not listed in this document are not intended to be set, and incorrectly specified names do not produce a warning.

⚠️ Caution: Handling Invalid Environment Variable Values

  • Partial application — Reading environment variables stops when an invalid value is encountered. Settings already applied are kept, and the rest remain at their defaults. The process continues.
  • Read order — The order in which environment variables are read is not specified. If a value is invalid, it is not possible to predict which settings will take effect.
  • Checking errors — If an error occurs while reading settings from environment variables, the runtime writes an Error-level log. Check this log first if a setting does not take effect.
  • Logger settings — The runtime applies logger settings after reading all environment variables. If reading stops because of an invalid value, HA_LOG_LEVEL, HA_LOG_PATH, and HA_LOG_OUTPUT_MODE are not applied to the logger.

1. How to Set

Environment variables can be set in the launch environment (CLI) or with setenv() in program initialization code. Either way, they must be in place before the first Ha* call.

Set them in the terminal without changing code. This is the safest option because the values are guaranteed to be set before the process starts.

1
HA_LOG_LEVEL=1 HA_HUGE_POOL_THRESHOLD_SIZE_MB=128 ./my_app

To set them in code, do so before the first Ha* call so that the runtime reads them correctly.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
#include <cstdlib>

int main() {
  // Must be set before the first Ha* API call
  setenv("HA_LOG_LEVEL", "1", 1);
  setenv("HA_HUGE_POOL_THRESHOLD_SIZE_MB", "64", 1);

  // First runtime API call (the runtime is created and reads the environment variables here)
  HaSetDevice(0);
  // ...
}

As with C++, set them before the first hart API call. import hart itself does not create the runtime yet, so setting them right after the import also works.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import os

# Must be set before the first hart API call
os.environ["HA_LOG_LEVEL"] = "1"
os.environ["HA_HUGE_POOL_THRESHOLD_SIZE_MB"] = "64"

import hart

# First runtime API call (the runtime is created and reads the environment variables here)
hart.set_device(0)
# ...

2. Environment Variable Reference

Memory

Variable Value Default Effect
HA_HUGE_POOL_THRESHOLD_SIZE_MB Integer (MB) 0 (off) If greater than 0, enables the Huge tier in the Large pool and uses this size as the threshold. (Does not apply to the Small pool)
HA_MAX_PAGE_WASTE_RATIO Float (0.0 to 1.0) 0.0 Tail waste ratio allowed when selecting a page
HA_SMALL_POOL_MIN_SPLIT_REMAINDER_KB Integer (KiB, 0 or greater) 512 Minimum remainder when splitting a block in the Small pool. If the remainder would be smaller, the block is allocated whole without splitting. Values below 32 are raised to 32, and negative values are rejected as invalid
HA_DEVICE_MEM_STATS_PRINT 0 or 1 Value of HA_MEM_STATS_PRINT If 1, querying device memory statistics (HaDeviceMemGetStats(), ha_drv_device_mem_get_stats(), Python device_mem_get_stats()) also prints the same statistics to standard error

Memory Copy

Variable Value Default Effect
HA_MEMCPYND_PARALLEL_MIN_PER_THREAD Integer (bytes) 2 MiB Minimum amount one worker must handle in the host↔host portion of HaMemCpyNd(). If the total is smaller, the copy runs sequentially
HA_MEMCPYND_PARALLEL_MAX_THREADS Integer 0 (auto) Upper bound on the number of workers for the same path. 0 determines it automatically from the number of physical cores, up to 8
HA_MEMCPYND_ASYNC_STAGING_MAX_UNSYNCED_BYTES Integer (bytes), negative turns it off 8 GiB When the total of unsynchronized asynchronous N-D copy staging buffers exceeds this value, a new staging copy first synchronizes its own stream and then proceeds. Nothing is rejected, so a wrong setting only changes throughput
HA_MEMCPYND_STAGING_MAX_BYTES Integer (bytes), negative turns it off Off Upper bound on the total staging buffers of asynchronous N-D copies. Copies that exceed it are rejected with HaHostMemLimitExceeded. If set together with HA_HOST_MEM_MAX_BYTES, the lower one applies, and a value at or above HA_HOST_MEM_MAX_BYTES logs a warning that it has no effect. A value below an enabled HA_MEMCPYND_ASYNC_STAGING_MAX_UNSYNCED_BYTES is a configuration error

The defaults assume a typical server. In containers whose CPU is limited by cgroups or on asymmetric topologies, it is better to set HA_MEMCPYND_PARALLEL_MAX_THREADS explicitly.

Host Memory

Applies to the per-process host memory manager. This manager is shared by the runtime API HaHostMemAlloc() and driver API host memory, and the host staging buffers of N-D copies are also allocated from it, so these limits apply to them too.

Variable Value Default Effect
HA_HOST_MEM_MAX_BYTES Integer (bytes), negative turns it off Off Upper bound on host memory the process obtains from the OS. Includes both pool segments (including cached free blocks) and allocations that bypass the pool. An allocation that exceeds it is rejected with HaHostMemLimitExceeded if it still does not fit after free segments are released
HA_HOST_MEM_STATS_PRINT 0 or 1 Value of HA_MEM_STATS_PRINT If 1, querying host memory statistics (HaHostMemGetStats(), ha_drv_host_mem_get_stats(), Python host_mem_get_stats()) also prints the same statistics to standard error
HA_MEM_STATS_PRINT 0 or 1 0 (off) If 1, turns on both host and device memory statistics output. If HA_HOST_MEM_STATS_PRINT or HA_DEVICE_MEM_STATS_PRINT is set separately, that variable takes precedence for its kind

Logging

Variable Value Default Effect
HA_LOG_LEVEL Integer (0 to 6) 2 (Info); 3 (Warn) in release builds Sets the log level (0: Trace, 1: Debug, 2: Info, 3: Warn, 4: Error, 5: Critical, 6: Off)
HA_LOG_OUTPUT_MODE Integer (0 or 1) 0 (console) Log output mode (0: console, 1: file)
HA_LOG_PATH Path ha_runtime.log Log file path (effective only when HA_LOG_OUTPUT_MODE=1)

Minimum log level in release builds

Release builds do not support the Trace, Debug, or Info log levels (0 to 2). If HA_LOG_LEVEL is set to one of these values, it is raised to Warn (3).

HA_LOG_PATH is used as the log file path only when HA_LOG_OUTPUT_MODE=1. If the specified log file does not exist, a warning is logged. When file output is enabled, the required parent directories and log file are created.

See Error Handling for how to change logging settings in a program. If the program changes a logging setting after it was set through an environment variable, the new setting takes effect.

3. Settings Not Available Through Environment Variables

The settings below cannot be set through environment variables. Use the API.

  • Current device: HaSetDevice() / hart.set_device(). Set separately for each thread.
  • Sampling parameters: HaSetSamplingParams() / hart.set_sampling_params()
  • TLB initialization: HaInitTlb() / hart.init_tlb()

See also