Math Engine Reference: Unlimited

문서 탐색

개요

ABI version 1 unlimited 이름을 보존하는 FULL mode 호환 header다.

Session과 call resolution은 caller-owned 값만 사용하며 mutable global mode가 없다. 새 source는 math_engine_full.h를 include한다. 이 계층은 계산 kernel을 복제하지 않고 기존 execution planner와 mode context를 조합하며 비트 수 무제한을 뜻하지 않는다.

실행 원본: include/math_engine/math_engine_unlimited.h
분류: 수 표현·실행 profile

공개 API

Header 사용 시작

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

#include <math_engine/math_engine_unlimited.h>

Type과 callback

`math_engine_unlimited_session_t`

Immutable capability snapshot과 session 기본 mode.

typedef struct math_engine_unlimited_session {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_unlimited_session_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_UNLIMITED_SESSION_VERSION_1=인 session ABI version이다. */
    uint32_t default_mode; /**< Override가 없는 call에 적용하는 지원된 =math_engine_mode_t= 값이다. */
    uint32_t flags; /**< Version 1 session flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
    math_engine_capability_descriptor_t capabilities; /**< Session 생성 시 복사한 immutable linked-artifact capability snapshot이다. */
    uint64_t session_fingerprint; /**< Default mode와 canonical capability field에서 계산한 deterministic fingerprint다. */
    uint64_t reserved[3]; /**< 향후 ABI 확장용 세 slot이다. Producer는 모두 0을 기록하고 caller가 보존해야 한다. Session validation은 nonzero 값을 INVALID_ARGUMENT로 거부한다. */
} math_engine_unlimited_session_t;

math_engine_unlimited_session_t.struct_size
Caller가 sizeof(math_engine_unlimited_session_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_unlimited_session_t.struct_version
MATH_ENGINE_UNLIMITED_SESSION_VERSION_1 인 session ABI version이다.
```
uint32_t struct_version;
```
math_engine_unlimited_session_t.default_mode
Override가 없는 call에 적용하는 지원된 math_engine_mode_t 값이다.
```
uint32_t default_mode;
```
math_engine_unlimited_session_t.flags
Version 1 session flag bitset이다. 정의되지 않은 bit는 0이어야 한다.
```
uint32_t flags;
```
math_engine_unlimited_session_t.capabilities
Session 생성 시 복사한 immutable linked-artifact capability snapshot이다.
```
math_engine_capability_descriptor_t capabilities;
```
math_engine_unlimited_session_t.session_fingerprint
Default mode와 canonical capability field에서 계산한 deterministic fingerprint다.
```
uint64_t session_fingerprint;
```
math_engine_unlimited_session_t.reserved
향후 ABI 확장용 세 slot이다. Producer는 모두 0을 기록하고 caller가 보존해야 한다. Session validation은 nonzero 값을 INVALID_ARGUMENT로 거부한다.
```
uint64_t reserved[3];
```

`math_engine_unlimited_call_request_t`

mode_override=INVALID이면 session 기본 mode를 사용한다.

typedef struct math_engine_unlimited_call_request {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_unlimited_call_request_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_UNLIMITED_CALL_REQUEST_VERSION_1=인 request ABI version이다. */
    uint32_t mode_override; /**< INVALID이면 session default, 아니면 이 call에만 적용할 =math_engine_mode_t= 값이다. */
    uint32_t workload_class; /**< Backend 선택을 구체화하는 =math_engine_workload_class_t= 값이다. */
    uint32_t requested_precision_bits; /**< 요청 significand precision(bit)이다. 0이면 effective mode 기본값을 사용한다. */
    uint32_t flags; /**< =MATH_ENGINE_UNLIMITED_CALL_FLAG_*= bit의 조합이다. */
    double observed_error_bound; /**< 이전 stage가 관측한 finite nonnegative 무차원 error bound다. */
    double observed_residual; /**< 이전 stage가 관측한 finite nonnegative 무차원 residual이다. */
    double target_error_bound; /**< 승격을 판단할 finite nonnegative 무차원 target이다. 0이면 관측 기반 승격을 끈다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero request는 INVALID_ARGUMENT로 거부된다. */
} math_engine_unlimited_call_request_t;

math_engine_unlimited_call_request_t.struct_size
Caller가 sizeof(math_engine_unlimited_call_request_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_unlimited_call_request_t.struct_version
MATH_ENGINE_UNLIMITED_CALL_REQUEST_VERSION_1 인 request ABI version이다.
```
uint32_t struct_version;
```
math_engine_unlimited_call_request_t.mode_override
INVALID이면 session default, 아니면 이 call에만 적용할 math_engine_mode_t 값이다.
```
uint32_t mode_override;
```
math_engine_unlimited_call_request_t.workload_class
Backend 선택을 구체화하는 math_engine_workload_class_t 값이다.
```
uint32_t workload_class;
```
math_engine_unlimited_call_request_t.requested_precision_bits
요청 significand precision(bit)이다. 0이면 effective mode 기본값을 사용한다.
```
uint32_t requested_precision_bits;
```
math_engine_unlimited_call_request_t.flags
MATH_ENGINE_UNLIMITED_CALL_FLAG_* bit의 조합이다.
```
uint32_t flags;
```
math_engine_unlimited_call_request_t.observed_error_bound
이전 stage가 관측한 finite nonnegative 무차원 error bound다.
```
double observed_error_bound;
```
math_engine_unlimited_call_request_t.observed_residual
이전 stage가 관측한 finite nonnegative 무차원 residual이다.
```
double observed_residual;
```
math_engine_unlimited_call_request_t.target_error_bound
승격을 판단할 finite nonnegative 무차원 target이다. 0이면 관측 기반 승격을 끈다.
```
double target_error_bound;
```
math_engine_unlimited_call_request_t.reserved
향후 ABI 확장용 두 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero request는 INVALID_ARGUMENT로 거부된다.
```
uint64_t reserved[2];
```

`math_engine_unlimited_call_trace_t`

Call별 effective mode, canonical execution plan과 deterministic provenance.

typedef struct math_engine_unlimited_call_trace {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_unlimited_call_trace_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_UNLIMITED_CALL_TRACE_VERSION_1=인 trace ABI version이다. */
    uint32_t session_default_mode; /**< Session이 보유한 기본 =math_engine_mode_t= 값이다. */
    uint32_t requested_mode; /**< Override 해석 뒤 call이 요청한 =math_engine_mode_t= 값이다. */
    uint32_t effective_mode; /**< Workload·관측치·capability 적용 뒤 실제 실행할 concrete mode다. */
    uint32_t flags; /**< =MATH_ENGINE_UNLIMITED_TRACE_FLAG_*= provenance bit의 조합이다. */
    math_engine_execution_trace_t execution; /**< Effective mode로 생성한 canonical backend/kernel execution plan이다. */
    double observed_error_bound; /**< Resolution에 사용한 finite nonnegative 무차원 observed error다. */
    double observed_residual; /**< Resolution에 사용한 finite nonnegative 무차원 observed residual이다. */
    uint64_t session_fingerprint; /**< 입력 session fingerprint의 검증된 복사본이다. */
    uint64_t call_fingerprint; /**< Session, request, effective mode와 execution plan을 결합한 deterministic fingerprint다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_unlimited_call_trace_t;

math_engine_unlimited_call_trace_t.struct_size
Caller가 sizeof(math_engine_unlimited_call_trace_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_unlimited_call_trace_t.struct_version
MATH_ENGINE_UNLIMITED_CALL_TRACE_VERSION_1 인 trace ABI version이다.
```
uint32_t struct_version;
```
math_engine_unlimited_call_trace_t.session_default_mode
Session이 보유한 기본 math_engine_mode_t 값이다.
```
uint32_t session_default_mode;
```
math_engine_unlimited_call_trace_t.requested_mode
Override 해석 뒤 call이 요청한 math_engine_mode_t 값이다.
```
uint32_t requested_mode;
```
math_engine_unlimited_call_trace_t.effective_mode
Workload·관측치·capability 적용 뒤 실제 실행할 concrete mode다.
```
uint32_t effective_mode;
```
math_engine_unlimited_call_trace_t.flags
MATH_ENGINE_UNLIMITED_TRACE_FLAG_* provenance bit의 조합이다.
```
uint32_t flags;
```
math_engine_unlimited_call_trace_t.execution
Effective mode로 생성한 canonical backend/kernel execution plan이다.
```
math_engine_execution_trace_t execution;
```
math_engine_unlimited_call_trace_t.observed_error_bound
Resolution에 사용한 finite nonnegative 무차원 observed error다.
```
double observed_error_bound;
```
math_engine_unlimited_call_trace_t.observed_residual
Resolution에 사용한 finite nonnegative 무차원 observed residual이다.
```
double observed_residual;
```
math_engine_unlimited_call_trace_t.session_fingerprint
입력 session fingerprint의 검증된 복사본이다.
```
uint64_t session_fingerprint;
```
math_engine_unlimited_call_trace_t.call_fingerprint
Session, request, effective mode와 execution plan을 결합한 deterministic fingerprint다.
```
uint64_t call_fingerprint;
```
math_engine_unlimited_call_trace_t.reserved
향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다.
```
uint64_t reserved[2];
```

Macro와 constant

`MATH_ENGINE_UNLIMITED_CALL_FLAG_ESCALATE_UNCERTAIN`

Initial backend 결과가 uncertain이면 더 강한 FULL backend로 승격하도록 허용하는 request bit다.

#define MATH_ENGINE_UNLIMITED_CALL_FLAG_ESCALATE_UNCERTAIN \
    (UINT32_C(1) << 0u)

`MATH_ENGINE_UNLIMITED_CALL_REQUEST_VERSION_1`

math_engine_unlimited_call_request_t historical storage의 최초 안정 ABI version이다.

#define MATH_ENGINE_UNLIMITED_CALL_REQUEST_VERSION_1 UINT32_C(1)

`MATH_ENGINE_UNLIMITED_CALL_TRACE_VERSION_1`

math_engine_unlimited_call_trace_t historical storage의 최초 안정 ABI version이다.

#define MATH_ENGINE_UNLIMITED_CALL_TRACE_VERSION_1 UINT32_C(1)

`MATH_ENGINE_UNLIMITED_SESSION_VERSION_1`

math_engine_unlimited_session_t historical storage의 최초 안정 ABI version이다.

#define MATH_ENGINE_UNLIMITED_SESSION_VERSION_1 UINT32_C(1)

`MATH_ENGINE_UNLIMITED_TRACE_FLAG_CALL_OVERRIDE`

Call request의 valid mode override를 사용했음을 나타내는 trace bit다.

#define MATH_ENGINE_UNLIMITED_TRACE_FLAG_CALL_OVERRIDE \
    (UINT32_C(1) << 1u)

`MATH_ENGINE_UNLIMITED_TRACE_FLAG_DEFAULT_MODE`

Call이 session default mode를 override 없이 사용했음을 나타내는 trace bit다.

#define MATH_ENGINE_UNLIMITED_TRACE_FLAG_DEFAULT_MODE \
    (UINT32_C(1) << 0u)

`MATH_ENGINE_UNLIMITED_TRACE_FLAG_FINANCE_LOCK`

Money workload가 effective mode를 FINANCE_FIXED로 고정했음을 나타내는 trace bit다.

#define MATH_ENGINE_UNLIMITED_TRACE_FLAG_FINANCE_LOCK \
    (UINT32_C(1) << 3u)

`MATH_ENGINE_UNLIMITED_TRACE_FLAG_OBSERVED_ESCALATION`

관측 error/residual이 target을 넘어 effective mode를 승격했음을 나타내는 trace bit다.

#define MATH_ENGINE_UNLIMITED_TRACE_FLAG_OBSERVED_ESCALATION \
    (UINT32_C(1) << 2u)

Function

`math_engine_unlimited_session_init`

Immutable capability snapshot과 지원되는 기본 mode로 session을 초기화한다.

매개변수 default_mode: 호출별 override가 없을 때 사용할 mode.
매개변수 capabilities: 검증할 immutable capability descriptor.
매개변수 out_session: size/version을 설정한 caller output.
반환: 성공 시 OK. 잘못된/미지원 mode, capability 또는 output ABI에서는 output을

보존한다. 결과 fingerprint는 canonical capability field와 mode에 deterministic하다. Input과 output은 overlap하지 않아야 하고 pointer는 보관하지 않는다.

Math Engine ownership: capabilities=borrowed out_session=caller
Math Engine nullable: capabilities=false out_session=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unlimited_session_init(
    math_engine_mode_t default_mode,
    const math_engine_capability_descriptor_t* capabilities,
    math_engine_unlimited_session_t* out_session);

`math_engine_unlimited_session_validate`

Session 구조, nested capability와 fingerprint를 다시 검증한다.

매개변수 session: 검증할 immutable caller-owned session snapshot.
반환: 유효하고 default mode가 지원되면 OK. 입력은 변경하지 않는다.
Math Engine ownership: session=borrowed
Math Engine nullable: session=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unlimited_session_validate(
    const math_engine_unlimited_session_t* session);

`math_engine_unlimited_call_resolve`

호출별 mode를 해석해 독립 context와 deterministic execution trace를 만든다.

매개변수 session: 검증할 immutable capability/default-mode snapshot.
매개변수 request: override/workload/precision과 관측 오차를 담은 immutable request.
매개변수 out_context: 성공 시 effective mode 기본 policy로 초기화되는 caller output.
매개변수 out_trace: size/version을 설정한 caller output.
반환: 성공 시 OK. 유효하지 않은 finite nonnegative 관측값, 금지된 finance 조합,

capability/precision/ABI 오류에서는 두 output을 모두 보존한다.

Call별 mode를 해석해 실제 canonical kernel에 전달할 독립 context와 trace를 만든다. FULL money는 항상 FINANCE_FIXED이며, observed error/residual이 target을 넘는 realtime call은 GAME_FAST 시작점에서 PC_PRECISION으로 승격한다. Error bound와 residual은 dimensionless이며 target 0은 관측 기반 승격 없음이다. 모든 input/output storage는 non-overlapping이고 library가 pointer를 보관하지 않는다.

Math Engine ownership: session=borrowed request=borrowed out_context=caller out_trace=caller
Math Engine nullable: session=false request=false out_context=false out_trace=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unlimited_call_resolve(
    const math_engine_unlimited_session_t* session,
    const math_engine_unlimited_call_request_t* request,
    math_engine_context_t* out_context,
    math_engine_unlimited_call_trace_t* out_trace);

Math Engine Reference: Unlimited

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_unlimited_session_t

math_engine_unlimited_call_request_t

math_engine_unlimited_call_trace_t

Macro와 constant

MATH_ENGINE_UNLIMITED_CALL_FLAG_ESCALATE_UNCERTAIN

MATH_ENGINE_UNLIMITED_CALL_REQUEST_VERSION_1

MATH_ENGINE_UNLIMITED_CALL_TRACE_VERSION_1

MATH_ENGINE_UNLIMITED_SESSION_VERSION_1

MATH_ENGINE_UNLIMITED_TRACE_FLAG_CALL_OVERRIDE

MATH_ENGINE_UNLIMITED_TRACE_FLAG_DEFAULT_MODE

MATH_ENGINE_UNLIMITED_TRACE_FLAG_FINANCE_LOCK

MATH_ENGINE_UNLIMITED_TRACE_FLAG_OBSERVED_ESCALATION