Math Engine Reference: Status

문서 탐색

Math Engine 전체 목차

개요

Math Engine의 공통 성공과 오류 상태를 선언한다.

모든 component가 공유하는 안정된 음수 오류 code와 진단용 영문 이름 조회 함수를 제공한다. 반환된 이름은 process lifetime 동안 유효한 borrowed 문자열이다.

계약: 공통 반환·output 보존 계약
MATH_ENGINE_STATUS_OK 만 operation 성공을 뜻한다. Miss와 empty는 오류가 아니므로 status는 OK이고 math_engine_result_info_t.flags 의 primary result flag로 구분한다.
Usable하지만 오차가 남는 값은 OK와 MATH_ENGINE_RESULT_FLAG_UNCERTAIN 을 함께 사용한다. 요청한 보증 자체를 만족할 수 없으면 MATH_ENGINE_STATUS_UNCERTAIN 이다.
별도 문서가 partial output 또는 required-size 출력을 허용하지 않는 한, OK가 아닌 반환에서 caller-owned output object와 buffer content는 호출 전 값 그대로다.
함수는 모든 input, alias와 capacity를 검사한 뒤에만 output을 commit한다.

Result flag와 공통 result POD는 math_engine_types.h 에 선언한다. 순환 include를 피하기 위해 이 header는 해당 type을 직접 include하지 않는다.

실행 원본: include/math_engine/math_engine_status.h
분류: 진입점·ABI·공통 계약

공개 API

Header 사용 시작

이 module의 public declaration을 사용하려면 installed SDK의 다음 header를 include한다.

#include <math_engine/math_engine_status.h>

Type과 callback

`math_engine_status_t`

Math Engine 공통 상태 code다.

typedef enum math_engine_status {
    MATH_ENGINE_STATUS_OK = 0, /**< 요청이 계약대로 완료됐다. Miss와 empty도 이 status와 result flag로 표현한다. */
    MATH_ENGINE_STATUS_INVALID_ARGUMENT = -1, /**< Nullability, range, alias 또는 조합 계약을 위반한 argument다. */
    MATH_ENGINE_STATUS_INVALID_SIZE = -2, /**< Versioned POD의 =struct_size=나 입력 길이가 계약과 맞지 않는다. */
    MATH_ENGINE_STATUS_UNSUPPORTED = -3, /**< 현재 build·backend·capability가 유효한 요청을 지원하지 않는다. */
    MATH_ENGINE_STATUS_NON_FINITE = -4, /**< Finite여야 하는 입력 또는 중간 결과에서 NaN/무한대를 발견했다. */
    MATH_ENGINE_STATUS_DEGENERATE = -5, /**< 영벡터, singular matrix 등 수학적으로 퇴화한 입력이라 결과를 유일하게 정할 수 없다. */
    MATH_ENGINE_STATUS_NOT_CONVERGED = -6, /**< 허용된 수치 절차 안에서 요구 tolerance로 수렴하지 못했다. */
    MATH_ENGINE_STATUS_BUDGET_EXHAUSTED = -7, /**< Context의 iteration 또는 evaluation budget을 모두 사용했다. */
    MATH_ENGINE_STATUS_CANCELLED = -8, /**< Caller의 취소 callback 또는 token이 중단을 요청했다. */
    MATH_ENGINE_STATUS_INSUFFICIENT_WORKSPACE = -9, /**< Caller가 제공한 workspace byte 수나 정렬이 요구량을 만족하지 않는다. */
    MATH_ENGINE_STATUS_INTERNAL_ERROR = -10, /**< 유효 입력에 대해 library 내부 invariant가 깨졌다. 재현 가능한 결함으로 보고해야 한다. */
    /** 입력 또는 요청 결과가 API가 지원하는 수치·index 범위 밖이다. */
    MATH_ENGINE_STATUS_OUT_OF_RANGE = -11,
    /** 산술 결과가 선택한 scalar representation 범위를 넘었다. */
    MATH_ENGINE_STATUS_OVERFLOW = -12,
    /** 유효한 값을 요청한 보증 수준으로 판정하거나 인증할 수 없다. */
    MATH_ENGINE_STATUS_UNCERTAIN = -13,
    /** Caller-owned output buffer capacity가 required size보다 작다. */
    MATH_ENGINE_STATUS_INSUFFICIENT_BUFFER = -14,
    /** Integer divisor가 0이라 quotient/remainder를 정의할 수 없다. */
    MATH_ENGINE_STATUS_DIVIDE_BY_ZERO = -15,
    /** Shift count가 scalar bit width의 유효 범위 밖이다. */
    MATH_ENGINE_STATUS_INVALID_SHIFT = -16,
    /** Finite input is outside the mathematical domain of the requested function. */
    MATH_ENGINE_STATUS_DOMAIN_ERROR = -17,
    /** Input is an exact singularity or pole of the requested function. */
    MATH_ENGINE_STATUS_POLE = -18,
    /** A nonzero mathematical result rounded to zero in the selected representation. */
    MATH_ENGINE_STATUS_UNDERFLOW = -19,
    /** 정확한 입력은 유효하지만 요청한 제한 표현 family로는 결과를 보존할 수 없다. */
    MATH_ENGINE_STATUS_NOT_REPRESENTABLE = -20
} math_engine_status_t;

math_engine_status_t.MATH_ENGINE_STATUS_OK
요청이 계약대로 완료됐다. Miss와 empty도 이 status와 result flag로 표현한다.
```
MATH_ENGINE_STATUS_OK = 0,
```
math_engine_status_t.MATH_ENGINE_STATUS_INVALID_ARGUMENT
Nullability, range, alias 또는 조합 계약을 위반한 argument다.
```
MATH_ENGINE_STATUS_INVALID_ARGUMENT = -1,
```
math_engine_status_t.MATH_ENGINE_STATUS_INVALID_SIZE
Versioned POD의 struct_size 나 입력 길이가 계약과 맞지 않는다.
```
MATH_ENGINE_STATUS_INVALID_SIZE = -2,
```
math_engine_status_t.MATH_ENGINE_STATUS_UNSUPPORTED
현재 build·backend·capability가 유효한 요청을 지원하지 않는다.
```
MATH_ENGINE_STATUS_UNSUPPORTED = -3,
```
math_engine_status_t.MATH_ENGINE_STATUS_NON_FINITE
Finite여야 하는 입력 또는 중간 결과에서 NaN/무한대를 발견했다.
```
MATH_ENGINE_STATUS_NON_FINITE = -4,
```
math_engine_status_t.MATH_ENGINE_STATUS_DEGENERATE
영벡터, singular matrix 등 수학적으로 퇴화한 입력이라 결과를 유일하게 정할 수 없다.
```
MATH_ENGINE_STATUS_DEGENERATE = -5,
```
math_engine_status_t.MATH_ENGINE_STATUS_NOT_CONVERGED
허용된 수치 절차 안에서 요구 tolerance로 수렴하지 못했다.
```
MATH_ENGINE_STATUS_NOT_CONVERGED = -6,
```
math_engine_status_t.MATH_ENGINE_STATUS_BUDGET_EXHAUSTED
Context의 iteration 또는 evaluation budget을 모두 사용했다.
```
MATH_ENGINE_STATUS_BUDGET_EXHAUSTED = -7,
```
math_engine_status_t.MATH_ENGINE_STATUS_CANCELLED
Caller의 취소 callback 또는 token이 중단을 요청했다.
```
MATH_ENGINE_STATUS_CANCELLED = -8,
```
math_engine_status_t.MATH_ENGINE_STATUS_INSUFFICIENT_WORKSPACE
Caller가 제공한 workspace byte 수나 정렬이 요구량을 만족하지 않는다.
```
MATH_ENGINE_STATUS_INSUFFICIENT_WORKSPACE = -9,
```
math_engine_status_t.MATH_ENGINE_STATUS_INTERNAL_ERROR
유효 입력에 대해 library 내부 invariant가 깨졌다. 재현 가능한 결함으로 보고해야 한다.
```
MATH_ENGINE_STATUS_INTERNAL_ERROR = -10,
```

math_engine_status_t.MATH_ENGINE_STATUS_OUT_OF_RANGE

입력 또는 요청 결과가 API가 지원하는 수치·index 범위 밖이다.

/** 입력 또는 요청 결과가 API가 지원하는 수치·index 범위 밖이다. */
    MATH_ENGINE_STATUS_OUT_OF_RANGE = -11,

math_engine_status_t.MATH_ENGINE_STATUS_OVERFLOW

산술 결과가 선택한 scalar representation 범위를 넘었다.

/** 산술 결과가 선택한 scalar representation 범위를 넘었다. */
    MATH_ENGINE_STATUS_OVERFLOW = -12,

math_engine_status_t.MATH_ENGINE_STATUS_UNCERTAIN

유효한 값을 요청한 보증 수준으로 판정하거나 인증할 수 없다.

/** 유효한 값을 요청한 보증 수준으로 판정하거나 인증할 수 없다. */
    MATH_ENGINE_STATUS_UNCERTAIN = -13,

math_engine_status_t.MATH_ENGINE_STATUS_INSUFFICIENT_BUFFER

Caller-owned output buffer capacity가 required size보다 작다.

/** Caller-owned output buffer capacity가 required size보다 작다. */
    MATH_ENGINE_STATUS_INSUFFICIENT_BUFFER = -14,

math_engine_status_t.MATH_ENGINE_STATUS_DIVIDE_BY_ZERO

Integer divisor가 0이라 quotient/remainder를 정의할 수 없다.

/** Integer divisor가 0이라 quotient/remainder를 정의할 수 없다. */
    MATH_ENGINE_STATUS_DIVIDE_BY_ZERO = -15,

math_engine_status_t.MATH_ENGINE_STATUS_INVALID_SHIFT

Shift count가 scalar bit width의 유효 범위 밖이다.

/** Shift count가 scalar bit width의 유효 범위 밖이다. */
    MATH_ENGINE_STATUS_INVALID_SHIFT = -16,

math_engine_status_t.MATH_ENGINE_STATUS_DOMAIN_ERROR

Finite input is outside the mathematical domain of the requested function.

/** Finite input is outside the mathematical domain of the requested function. */
    MATH_ENGINE_STATUS_DOMAIN_ERROR = -17,

math_engine_status_t.MATH_ENGINE_STATUS_POLE

Input is an exact singularity or pole of the requested function.

/** Input is an exact singularity or pole of the requested function. */
    MATH_ENGINE_STATUS_POLE = -18,

math_engine_status_t.MATH_ENGINE_STATUS_UNDERFLOW

A nonzero mathematical result rounded to zero in the selected representation.

/** A nonzero mathematical result rounded to zero in the selected representation. */
    MATH_ENGINE_STATUS_UNDERFLOW = -19,

math_engine_status_t.MATH_ENGINE_STATUS_NOT_REPRESENTABLE

정확한 입력은 유효하지만 요청한 제한 표현 family로는 결과를 보존할 수 없다.

/** 정확한 입력은 유효하지만 요청한 제한 표현 family로는 결과를 보존할 수 없다. */
    MATH_ENGINE_STATUS_NOT_REPRESENTABLE = -20,

Function

`math_engine_status_name`

상태 code의 안정된 영문 이름을 조회한다.

매개변수 status: 조회할 상태 code.
반환: process lifetime 동안 유효한 NUL 종료 borrowed 문자열.
Math Engine ownership: return=borrowed
Math Engine nullable: return=false
Math Engine thread_safety: safe

MATH_ENGINE_API const char* math_engine_status_name(math_engine_status_t status);