6. 에러 처리¶
모든 C++ 진입점은 HaError를 반환하고, 예외를 던지지 않습니다. 단, HaLaunchArgs 생성자는 메모리가
부족하면 std::bad_alloc을 던집니다. 반환값을 버리면 실패가
조용히 지나가고, 그 결과는 몇 단계 뒤에서 엉뚱한 증상으로 나타납니다. 이 장은 무엇을
확인해야 하고 실패 뒤에 무엇을 할 수 있는지를 다룹니다.
핵심은 모든 실패가 같은 성격이 아니라는 것입니다. 인자를 고쳐 다시 부르면 되는 것, 자원을 정리하고 재시도해야 하는 것, 그 디바이스를 더는 신뢰할 수 없는 것이 섞여 있습니다. 반환값 하나만 보고 일괄로 재시도하면 마지막 부류에서 문제가 커집니다.
Contents¶
| Section | Objective |
|---|---|
| 6.1 반환 규약 | 함수별로 무엇을 반환하고 무엇을 반환하지 않는지에 대한 규약 |
| 6.2 실패 분류 | 에러 대응 방법이 갈리는 기준과 분류 기준 |
| 6.3 0이 아니라고 모두 실패는 아닙니다 | 에러가 아닌 정상 흐름의 일부인 반환값 판별 |
| 6.4 실패 이후의 상태 | 재시도 가능 여부(Transient vs Permanent)를 결정하는 기준 |
| 6.5 프로세스의 첫 호출들 | 프로세스 초기 시작 단계에서만 발생하는 특수 실패 유형 |
| 6.6 Python 인터페이스 | C/C++ 반환값 체계가 Python 레이어에서 예외(Exception)로 변환되는 방식 |
| 6.7 로깅 | 반환값만으로는 알 수 없는 내부 상태를 파악하기 위한 로깅 활용법 |
전체 코드 목록은 에러 코드에, 증상별 대응은 문제 해결에 있습니다.
6.1 반환 규약¶
1 2 3 4 | |
C++ API 전반에 적용되는 반환 규약(Return Contract)입니다.
- 반환값은 항상
HaError입니다. 결과는 포인터 파라미터로 전달됩니다. - 실패 시 출력 파라미터의 값에 의존하지 마십시오. 실패 원인에 따라 그대로 남거나 0이 기록될 수
있습니다. 직접 초기화하고, 실패한
HaMemAlloc()이후ptr을 사용하지 마십시오. - API 경계를 넘어 예외가 전파되지 않습니다.
6.2 실패 분류¶
HaError는 값의 상위 비트에 실패 카테고리를 인코딩하는 방식으로 설계되어 있어,
전체 코드를 일일이 나열하지 않고도 실패의 대분류만으로 분기 처리를 할 수
있습니다.
| 카테고리 | 인코딩 | 포함 |
|---|---|---|
| 성공 | 0 |
|
| 공통 | 1 – 65535 |
잘못된 인자, 미지원, 타임아웃, 내부 오류 |
| 디바이스 | (1 << 16) \| code |
가용성, 초기화, open/close/reset |
| 메모리 | (2 << 16) \| code |
주소, 정렬, 할당, 복사 |
| 커널 | (3 << 16) \| code |
인자, 로드, 실행 |
| 스트림 | (4 << 16) \| code |
핸들, 생성/파괴, 동기화 |
| 이벤트 | (5 << 16) \| code |
핸들, 기록, 완료 |
1 2 | |
이 인코딩 규칙은 버전 간에 안정적으로 유지됩니다. 카테고리 단위의 분기를 계약(Contract)으로 삼고, 개별 코드 값은 진단(Diagnostic) 목적의 부가 정보로만 취급하는 것이 안전합니다.
6.3 0이 아니라고 모두 실패는 아닙니다¶
다음 세 개의 코드는 질의(Query) 결과를 알리는 정상적인 제어 흐름의 일부이며, 실패를 의미하는 에러가 아닙니다.
| 코드 | 반환하는 곳 | 의미 |
|---|---|---|
HaStreamNotReady |
HaStreamQuery() |
작업이 아직 진행 중 |
HaEventNotReady |
HaEventQuery() |
이벤트가 아직 완료되지 않음 |
HaEventNotRecorded |
HaEventQuery(), HaEventSynchronize() |
이 이벤트에 HaEventRecord()가 호출된 적 없음 |
HaSuccess가 아닌 모든 반환값을 치명적 오류로 취급하는 폴링(Polling) 루프는
첫 반복에서 곧바로 중단되는 결함을 갖게 됩니다. 위 세 코드는 반드시 별도로
명시적으로 확인해야 합니다.
6.4 실패 이후의 상태¶
| 실패 | 이후 상태 |
|---|---|
HaMemAlloc()이 에러 반환 |
아무것도 할당되지 않았고 누수도 없음. 출력 포인터는 사용하지 말 것(0이 기록될 수 있음) |
HaMemCpy()가 에러 반환 |
대상이 부분적으로 쓰였을 수 있음. 변경되지 않았다고 가정하지 마십시오 |
HaLaunchKernel()이 HaKernelExecutionFailed 반환 |
디바이스 상태가 보장되지 않음. 커널 출력을 사용 가능하다고 가정하지 마십시오 |
HaStreamCreate()가 에러 반환 |
스트림이 생성되지 않았고 핸들은 그대로 |
HaGetLastError()는 없습니다. 실패한 호출이 곧 알려 줍니다.
실패한 실행을 재시도하는 것에 대해
HaKernelExecutionFailed는 디바이스가 사용 가능한 상태인지 알려 주지 않습니다.
같은 실행을 재시도하는 것은 안전한 복구 전략이 아닙니다. 서빙 프로세스라면 요청을
실패시키고 에러를 노출하십시오. 테스트 루프라면 계속하기 전에 디바이스를
리셋하십시오. 단, 리셋은 그 디바이스의 모든 할당과 스트림을 무효화합니다.
6.5 프로세스의 첫 호출들¶
프로세스의 첫 실행에서 발생하는 실패는 대체로 다음 두 코드 중 하나이며, 각각이 가리키는 원인은 서로 명확히 다릅니다.
| 코드 | 원인 | 조치 |
|---|---|---|
HaDeviceNotAvailable |
디바이스가 없거나 열 수 없음 | KMD가 로드되어 있는지, 프로세스가 디바이스 노드에 접근할 수 있는지 확인 |
HaDeviceInvalidArgument |
이 스레드에 현재 디바이스가 없음 | 해당 스레드에서 HaSetDevice()를 먼저 호출 |
메인 스레드에서는 정상 동작하는데 워커 스레드에서만 HaDeviceInvalidArgument가
발생한다면, 거의 예외 없이 두 번째 경우에 해당합니다. 현재 디바이스는
스레드마다 따로 지정하기 때문입니다.
멀티 디바이스 프로그래밍을 참고하십시오.
6.6 Python 인터페이스¶
Python 바인딩은 C++과 달리 에러 코드를 반환값으로 돌려주는 대신, 실패 시 예외(Exception)를 발생시키는 방식으로 설계되어 있습니다.
1 2 3 4 | |
예외 메시지에는 실패한 호출과 HaError 코드 이름이 포함됩니다.
hart.mem_free(None)은 에러가 아니라 아무 동작도 하지 않으므로, 정리 경로에서 별도로
방어할 필요가 없습니다.
6.7 로깅¶
런타임은 HyperAccel 전 제품군이 공유하는 로거(halogger)를 통해 로그를
남깁니다. 실패를 진단할 때는 로그 레벨과 출력 위치를 지정하고, 문제를 보고할 때는 그 출력을
반드시 함께 첨부해야 합니다.
1 2 3 4 | |
1 2 3 4 | |
레벨은 Trace(0), Debug(1), Info(2, 기본값), Warn(3), Error(4),
Critical(5), Off(6)입니다. Python의 set_level()은 레벨을 소문자 문자열로 받습니다.
배포 빌드에서는 Warn보다 낮은 레벨(Trace, Debug, Info)을 지정해도 Warn으로 적용됩니다.
환경 변수로도 지정할 수 있습니다
런타임은 첫 Ha* 호출 시점에 HA_LOG_LEVEL(0–6, 위 숫자와 같음),
HA_LOG_OUTPUT_MODE(0 콘솔 / 1 파일), HA_LOG_PATH를 읽습니다. 환경 변수는 런타임이
초기 설정을 읽기 전에 지정해야 합니다. 다만, 환경 변수로 로그 레벨이 설정된 이후
halogger.set_level()이나 HA_SET_LOG_LEVEL()을 호출하면 새로 지정한 로그 레벨이 적용됩니다.
환경 변수를 참고하십시오.