환경 변수¶
런타임은 설정이 처음 필요한 시점(첫 번째 Ha*·ha_drv_* API 호출, 또는 첫 호스트 메모리
할당)에 환경 변수를 단 한 번 읽습니다. 따라서 프로세스 실행 이후에 값을 변경해도 반영되지 않으므로, 반드시 실행
전(셸) 또는 첫 Ha* API 호출 전에 설정해야 합니다.
본 문서에 나열된 환경 변수 외에는 설정 대상이 아니며, 잘못 지정해도 경고하지 않습니다.
⚠️ 주의: 잘못된 환경 변수 값 처리¶
- 환경 변수 부분 적용 — 잘못된 값을 만나면 환경 변수 읽기를 중단합니다. 이미 적용된 설정은 유지되고, 나머지는 기본값으로 남습니다. 프로세스 실행은 계속됩니다.
- 읽기 순서 — 환경 변수를 읽는 순서는 정해져 있지 않습니다. 잘못된 값이 있을 때 어떤 설정이 반영될지 알 수 없습니다.
- 오류 확인 — 환경 변수에서 설정을 읽는 중 오류가 발생하면
Error레벨 로그를 남깁니다. 설정이 반영되지 않는다면 먼저 이 로그를 확인하십시오. - 로거 설정 — 런타임은 환경 변수를 전부 읽은 뒤 로거 설정 적용을 시작합니다. 잘못된 값으로
환경 변수 읽기가 중단되면
HA_LOG_LEVEL,HA_LOG_PATH,HA_LOG_OUTPUT_MODE는 로거에 적용되지 않습니다.
1. 설정 방법¶
환경 변수는 실행 환경(CLI)에서 지정하거나, 프로그램 초기화 코드에서 setenv()로 설정할 수
있습니다. 둘 다 반드시 첫 Ha* 호출보다 먼저 적용되어 있어야 합니다.
별도의 코드 수정 없이 터미널에서 지정합니다. 실행 전 주입이 보장되므로 가장 안전합니다.
1 | |
코드 내에서 설정하려면 반드시 첫 Ha* 호출 이전에 수행해야 런타임이 정상적으로
읽어들입니다.
1 2 3 4 5 6 7 8 9 10 11 | |
C++과 마찬가지로, 반드시 hart의 첫 API 호출 이전에 설정해야 합니다. import hart
자체는 아직 런타임을 생성하지 않으므로, import 직후에 설정해도 됩니다.
1 2 3 4 5 6 7 8 9 10 11 | |
2. 환경 변수 상세 항목¶
메모리¶
| 변수 | 값 | 기본값 | 효과 |
|---|---|---|---|
HA_HUGE_POOL_THRESHOLD_SIZE_MB |
정수(MB) | 0 (꺼짐) |
0보다 크면 Large 풀에 Huge 단계를 활성화하고 이 크기를 임계값으로 사용합니다. (Small 풀에는 미적용) |
HA_MAX_PAGE_WASTE_RATIO |
실수(0.0 ~ 1.0) |
0.0 |
페이지 선택 시 허용할 꼬리 낭비 비율 |
HA_SMALL_POOL_MIN_SPLIT_REMAINDER_KB |
정수(KiB, 0 이상) |
512 |
Small 풀에서 블록을 나눌 때 남는 크기의 최소값. 남는 크기가 이보다 작으면 블록을 나누지 않고 통째로 할당합니다. 32보다 작은 값은 32로 올려 적용되며, 음수는 잘못된 값으로 거부됩니다 |
HA_DEVICE_MEM_STATS_PRINT |
0 또는 1 |
HA_MEM_STATS_PRINT의 값 |
1이면 디바이스 메모리 통계를 조회할 때(HaDeviceMemGetStats(), ha_drv_device_mem_get_stats(), Python device_mem_get_stats()) 같은 시점의 통계를 표준 에러에도 출력합니다 |
메모리 복사¶
| 변수 | 값 | 기본값 | 효과 |
|---|---|---|---|
HA_MEMCPYND_PARALLEL_MIN_PER_THREAD |
정수(바이트) | 2 MiB |
HaMemCpyNd()의 호스트↔호스트 구간에서 워커 하나가 최소한 처리해야 할 양. 총량이 이보다 작으면 순차 처리합니다 |
HA_MEMCPYND_PARALLEL_MAX_THREADS |
정수 | 0 (자동) |
동일 경로의 워커 수 상한. 0이면 물리 코어 수 기준으로 자동 결정하며 최대 8개까지만 허용합니다 |
HA_MEMCPYND_ASYNC_STAGING_MAX_UNSYNCED_BYTES |
정수(바이트), 음수는 꺼짐 | 8 GiB |
동기화되지 않은 비동기 N-D 복사 스테이징 버퍼의 합계가 이 값을 넘으면, 새 스테이징 복사가 자기 스트림을 먼저 동기화한 뒤 진행합니다. 거부하지 않으므로 잘못 설정해도 처리량만 달라집니다 |
HA_MEMCPYND_STAGING_MAX_BYTES |
정수(바이트), 음수는 꺼짐 | 꺼짐 | 비동기 N-D 복사의 스테이징 버퍼 합계 상한. 넘는 복사는 HaHostMemLimitExceeded로 거부됩니다. HA_HOST_MEM_MAX_BYTES와 함께 설정하면 더 낮은 쪽이 적용되며, HA_HOST_MEM_MAX_BYTES 이상이면 효과가 없다는 경고를 남깁니다. 켜져 있는 HA_MEMCPYND_ASYNC_STAGING_MAX_UNSYNCED_BYTES보다 작으면 설정 오류로 처리됩니다 |
기본값은 일반적인 서버를 가정합니다. cgroup으로 CPU가 제한된 컨테이너나 비대칭 토폴로지에서는
HA_MEMCPYND_PARALLEL_MAX_THREADS를 직접 지정하는 편이 낫습니다.
호스트 메모리¶
프로세스 단위 호스트 메모리 관리자에 적용됩니다. 이 관리자는 런타임 API의 HaHostMemAlloc()과
드라이버 API 호스트 메모리가 함께
쓰며, N-D 복사의 호스트 스테이징 버퍼도 이 관리자에서 할당되므로 함께 영향을 받습니다.
| 변수 | 값 | 기본값 | 효과 |
|---|---|---|---|
HA_HOST_MEM_MAX_BYTES |
정수(바이트), 음수는 꺼짐 | 꺼짐 | 프로세스가 OS에서 확보하는 호스트 메모리의 상한. 풀 세그먼트(캐시된 빈 블록 포함)와 풀을 거치지 않는 할당이 모두 포함되며, 넘는 할당은 빈 세그먼트를 반환한 뒤에도 부족하면 HaHostMemLimitExceeded로 거부됩니다 |
HA_HOST_MEM_STATS_PRINT |
0 또는 1 |
HA_MEM_STATS_PRINT의 값 |
1이면 호스트 메모리 통계를 조회할 때(HaHostMemGetStats(), ha_drv_host_mem_get_stats(), Python host_mem_get_stats()) 같은 시점의 통계를 표준 에러에도 출력합니다 |
HA_MEM_STATS_PRINT |
0 또는 1 |
0 (꺼짐) |
1이면 호스트와 디바이스 메모리 통계 출력을 함께 켭니다. HA_HOST_MEM_STATS_PRINT나 HA_DEVICE_MEM_STATS_PRINT를 따로 설정하면 그 종류는 개별 설정을 따릅니다 |
로깅¶
| 변수 | 값 | 기본값 | 효과 |
|---|---|---|---|
HA_LOG_LEVEL |
정수(0~6) |
2(Info); 릴리스 빌드는 3(Warn) |
로그 레벨 지정 (0: Trace, 1: Debug, 2: Info, 3: Warn, 4: Error, 5: Critical, 6: Off) |
HA_LOG_OUTPUT_MODE |
정수(0 또는 1) |
0(콘솔) |
로그 출력 방식 (0: 콘솔, 1: 파일) |
HA_LOG_PATH |
경로 | ha_runtime.log |
로그 파일 저장 경로 (HA_LOG_OUTPUT_MODE=1일 때만 유효) |
릴리스 빌드의 최소 로그 레벨 안내
릴리스 빌드에서는 Trace·Debug·Info(0~2) 로그 레벨이 지원되지 않습니다.
HA_LOG_LEVEL이 해당 값들로 지정될 시, Warn(3)으로 올려 적용됩니다.
HA_LOG_PATH는 HA_LOG_OUTPUT_MODE=1일 때만 로그 파일의 경로로 사용됩니다. 지정한 로그 파일이
존재하지 않으면 경고가 출력되며, 파일 출력 시 필요한 상위 디렉터리와 로그 파일이 생성됩니다.
프로그램에서 로그 설정을 변경하는 방법은 에러 처리를 참고하십시오. 환경 변수로 설정한 이후 프로그램에서 로그 설정을 변경하면 새 설정이 적용됩니다.
3. 환경 변수로 지정할 수 없는 설정¶
아래는 환경 변수로 지정할 수 없습니다. API를 쓰십시오.
- 현재 디바이스:
HaSetDevice()/hart.set_device(). 스레드마다 따로 지정되므로 모든 스레드에서 설정합니다. - 샘플링 파라미터:
HaSetSamplingParams()/hart.set_sampling_params() - TLB 초기화:
HaInitTlb()/hart.init_tlb()