Math Engine Reference: Context

취소 요청이 있으면 0이 아닌 값을 반환하는 동기 callback이다.

• 매개변수 user_data: math_engine_context_t.cancel_user_data 에서 전달되는 borrowed pointer.
• 반환: 계속하려면 0, 현재 연산을 MATH_ENGINE_STATUS_CANCELLED 로 중단하려면 0이 아닌 값.

Kernel은 실행한 caller thread에서 호출하며 pointer를 보관하지 않는다. user_data 의 유효 기간과 동시 접근 동기화는 caller가 보장한다. C++ callback은 exception을 ABI 밖으로 전파해서는 안 된다.

• Math Engine ownership: user_data=borrowed
• Math Engine nullable: user_data=true
• Math Engine thread_safety: conditional
• Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

typedef int (*math_engine_cancel_fn)(void* user_data);

절대·상대 허용 오차다. 두 값은 finite이고 0 이상이어야 한다.

typedef struct math_engine_tolerance {
    double absolute; /**< 소비 API의 값 단위로 표현하는 finite nonnegative 절대 허용 오차다. */
    double relative; /**< 기준값 크기에 곱하는 finite nonnegative 무차원 상대 허용 오차다. */
} math_engine_tolerance_t;

Caller-owned immutable 계산 정책이다.

typedef struct math_engine_context {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_context_t)=로 설정해야 하는 byte 크기다. */
    uint32_t abi_version; /**< =MATH_ENGINE_ABI_VERSION=과 일치해야 하는 context ABI version이다. */
    math_engine_tolerance_t tolerance; /**< 모든 component가 수렴·동등·퇴화 판정에 사용하는 절대·상대 tolerance다. */
    uint64_t max_iterations; /**< 반복 알고리즘이 넘지 못하는 iteration budget이다. 0의 허용 여부는 개별 API가 정한다. */
    uint64_t max_evaluations; /**< 함수·식·kernel 평가 횟수 budget이다. 0의 허용 여부는 개별 API가 정한다. */
    uint32_t deterministic; /**< 0이면 일반 실행, 1이면 지원되는 deterministic 실행을 요구한다. 다른 값은 유효하지 않다. */
    /** ABI-preserved expansion slot. Selected =math_engine_mode_t=; access through API. */
    uint32_t reserved;
    math_engine_cancel_fn cancel; /**< 선택적인 borrowed 취소 callback이다. NULL이면 취소 polling을 하지 않으며 library는 보관하지 않는다. */
    void* cancel_user_data; /**< =cancel= 호출 때 그대로 전달하는 nullable borrowed payload다. 수명과 동기화는 caller 책임이다. */
} math_engine_context_t;

Caller storage를 현재 build의 기본 계산 정책으로 초기화한다.

• 매개변수 out_context: 초기화할 caller-owned storage. NULL이면 오류다.
• 반환: Desktop에서는 PC_PRECISION, embedded에서는 GAME_FAST 기본값으로 초기화하면

OK. 지원 capability 오류에서는 output을 보존한다.

• Math Engine ownership: out_context=caller
• Math Engine nullable: out_context=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_context_init(
    math_engine_context_t* out_context);

Caller storage를 선택 desktop mode의 기본 policy로 초기화한다.

현재 compiled backend가 mode의 필수 capability를 만족하지 않으면 UNSUPPORTED이고 output을 보존한다. Desktop build에서 math_engine_context_init 은 PC_PRECISION의 호환 shorthand이고 embedded build에서는 GAME_FAST를 선택한다.

• 매개변수 mode: 기본 tolerance와 budget을 선택할 mode.
• 매개변수 out_context: 성공 시 한 번에 초기화되는 caller-owned storage.
• 반환: 성공 시 OK. 잘못된 mode 또는 미지원 capability에서는 output을 보존한다.

Tolerance 단위는 호출할 domain API가 정의하며 기본값은 deterministic하다.

• Math Engine ownership: out_context=caller
• Math Engine nullable: out_context=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_context_init_for_mode(
    math_engine_mode_t mode,
    math_engine_context_t* out_context);

검증된 context의 selected mode를 output 보존 규칙으로 조회한다.

• 매개변수 context: selected mode를 읽을 immutable context.
• 매개변수 out_mode: 성공 시 mode를 받는 caller output.
• 반환: 성공 시 OK. Context 또는 output 오류에서는 out_mode 를 보존한다.
• Math Engine ownership: context=borrowed out_mode=caller
• Math Engine nullable: context=false out_mode=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_context_get_mode(
    const math_engine_context_t* context,
    math_engine_mode_t* out_mode);

Context의 size, ABI version, tolerance, mode와 budget을 검증한다.

• 매개변수 context: 검증할 borrowed context. NULL이면 오류다.
• 반환: 유효하면 MATH_ENGINE_STATUS_OK, 아니면 음수 상태 code.
• Math Engine ownership: context=borrowed
• Math Engine nullable: context=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_context_validate(
    const math_engine_context_t* context);