Math Engine Reference: Replay

문서 탐색

개요

Immutable context의 runtime binding, cancellation과 replay provenance ABI다.

실행 원본: include/math_engine/math_engine_replay.h
분류: 물리·운동·제어

공개 API

Header 사용 시작

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

#include <math_engine/math_engine_replay.h>

Type과 callback

`math_engine_cancellation_token_t`

Caller-owned atomic cancellation token storage다. state 는 opaque이며 직접 읽거나 쓰지 않고 아래 API와 callback으로만 접근한다.

typedef struct math_engine_cancellation_token {
    uint32_t struct_size; /**< Initializer가 =sizeof(math_engine_cancellation_token_t)=로 기록하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_CANCELLATION_TOKEN_VERSION_1=인 token ABI version이다. */
    volatile uint32_t state; /**< API가 atomic하게 접근하는 opaque 0(non-cancelled) 또는 1(cancelled) state다. 직접 접근하지 않는다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Initializer는 0을 기록하고 caller는 변경하지 않는다. */
} math_engine_cancellation_token_t;

math_engine_cancellation_token_t.struct_size
Initializer가 sizeof(math_engine_cancellation_token_t) 로 기록하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_cancellation_token_t.struct_version
MATH_ENGINE_CANCELLATION_TOKEN_VERSION_1 인 token ABI version이다.
```
uint32_t struct_version;
```
math_engine_cancellation_token_t.state
API가 atomic하게 접근하는 opaque 0(non-cancelled) 또는 1(cancelled) state다. 직접 접근하지 않는다.
```
volatile uint32_t state;
```
math_engine_cancellation_token_t.reserved
향후 ABI 확장용이다. Initializer는 0을 기록하고 caller는 변경하지 않는다.
```
uint32_t reserved;
```

`math_engine_runtime_binding_t`

Immutable resolved context에 caller-owned cancellation/workspace를 빌려 연결한다. Library는 pointer를 호출 이후 보관하지 않는다.

typedef struct math_engine_runtime_binding {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_runtime_binding_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_RUNTIME_BINDING_VERSION_1=인 binding ABI version이다. */
    const math_engine_resolved_context_t* context; /**< Caller-owned immutable resolved context를 non-null로 빌린다. 호출 종료까지 유효하며 보관하지 않는다. */
    const math_engine_cancellation_token_t* cancellation; /**< 선택적인 caller-owned atomic token을 빌린다. NULL이면 cancellation을 관측하지 않으며 보관하지 않는다. */
    math_engine_workspace_t workspace; /**< 실행 중에만 사용하는 caller-owned scratch view다. Nested =data=는 capacity 0일 때 NULL 가능하다. */
    uint32_t flags; /**< Version 1 runtime-binding flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Caller는 0으로 설정해야 하며 nonzero binding은 INVALID_ARGUMENT로 거부된다. */
} math_engine_runtime_binding_t;

math_engine_runtime_binding_t.struct_size
Caller가 sizeof(math_engine_runtime_binding_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_runtime_binding_t.struct_version
MATH_ENGINE_RUNTIME_BINDING_VERSION_1 인 binding ABI version이다.
```
uint32_t struct_version;
```
math_engine_runtime_binding_t.context
Caller-owned immutable resolved context를 non-null로 빌린다. 호출 종료까지 유효하며 보관하지 않는다.
```
const math_engine_resolved_context_t* context;
```
math_engine_runtime_binding_t.cancellation
선택적인 caller-owned atomic token을 빌린다. NULL이면 cancellation을 관측하지 않으며 보관하지 않는다.
```
const math_engine_cancellation_token_t* cancellation;
```
math_engine_runtime_binding_t.workspace
실행 중에만 사용하는 caller-owned scratch view다. Nested data 는 capacity 0일 때 NULL 가능하다.
```
math_engine_workspace_t workspace;
```
math_engine_runtime_binding_t.flags
Version 1 runtime-binding flag bitset이다. 정의되지 않은 bit는 0이어야 한다.
```
uint32_t flags;
```
math_engine_runtime_binding_t.reserved
향후 ABI 확장용이다. Caller는 0으로 설정해야 하며 nonzero binding은 INVALID_ARGUMENT로 거부된다.
```
uint32_t reserved;
```

`math_engine_execution_provenance_t`

Backend/version/floating environment와 replay fingerprint를 기록한다.

typedef struct math_engine_execution_provenance {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_execution_provenance_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_EXECUTION_PROVENANCE_VERSION_1=인 provenance ABI version이다. */
    uint32_t mode; /**< 실행에 적용한 =math_engine_mode_t= 값이다. */
    uint32_t scalar_backend; /**< 실제 수치 연산에 사용한 =math_engine_scalar_backend_t= 값이다. */
    uint32_t binary_rounding; /**< Resolved context가 요구한 binary rounding policy 식별자다. */
    uint32_t decimal_rounding; /**< Resolved context가 요구한 =math_engine_decimal_rounding_t= 값이다. */
    uint32_t floating_rounding; /**< 실행 thread에서 관측한 C floating-point rounding mode 값이다. */
    int32_t execution_status; /**< 계산 또는 replay 검증의 =math_engine_status_t= 값이다. Provenance API 자체 status와 구별한다. */
    uint32_t semantic_version_major; /**< Loaded library semantic-version major 성분이다. */
    uint32_t semantic_version_minor; /**< Loaded library semantic-version minor 성분이다. */
    uint32_t semantic_version_patch; /**< Loaded library semantic-version patch 성분이다. */
    uint32_t abi_version; /**< Loaded library가 구현한 =MATH_ENGINE_ABI_VERSION= 값이다. */
    uint64_t context_fingerprint; /**< Mode, tolerance, budget와 rounding을 결합한 resolved-context fingerprint다. */
    uint64_t capability_fingerprint; /**< 실행 당시 immutable capability manifest fingerprint다. */
    uint64_t input_fingerprint; /**< Caller가 canonical input bytes에서 계산해 제공한 fingerprint다. */
    uint64_t output_fingerprint; /**< Caller가 canonical output bytes에서 계산해 제공한 fingerprint다. */
    uint64_t execution_fingerprint; /**< Version·context·capability·input·output·status를 결합한 replay key다. */
    uint32_t deterministic; /**< 실행 context가 deterministic 계약을 요구하고 충족했으면 1이다. */
    uint32_t cancellation_observed; /**< Binding token이 provenance 생성 시 cancelled 상태였으면 1이다. */
    uint32_t locale_independent; /**< 실행이 process locale과 무관한 경로임을 인증하면 1이다. */
    uint32_t flags; /**< Version 1 provenance flag bitset이다. 정의되지 않은 bit는 0이다. */
} math_engine_execution_provenance_t;

math_engine_execution_provenance_t.struct_size
Caller가 sizeof(math_engine_execution_provenance_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_execution_provenance_t.struct_version
MATH_ENGINE_EXECUTION_PROVENANCE_VERSION_1 인 provenance ABI version이다.
```
uint32_t struct_version;
```
math_engine_execution_provenance_t.mode
실행에 적용한 math_engine_mode_t 값이다.
```
uint32_t mode;
```
math_engine_execution_provenance_t.scalar_backend
실제 수치 연산에 사용한 math_engine_scalar_backend_t 값이다.
```
uint32_t scalar_backend;
```
math_engine_execution_provenance_t.binary_rounding
Resolved context가 요구한 binary rounding policy 식별자다.
```
uint32_t binary_rounding;
```
math_engine_execution_provenance_t.decimal_rounding
Resolved context가 요구한 math_engine_decimal_rounding_t 값이다.
```
uint32_t decimal_rounding;
```
math_engine_execution_provenance_t.floating_rounding
실행 thread에서 관측한 C floating-point rounding mode 값이다.
```
uint32_t floating_rounding;
```
math_engine_execution_provenance_t.execution_status
계산 또는 replay 검증의 math_engine_status_t 값이다. Provenance API 자체 status와 구별한다.
```
int32_t execution_status;
```
math_engine_execution_provenance_t.semantic_version_major
Loaded library semantic-version major 성분이다.
```
uint32_t semantic_version_major;
```
math_engine_execution_provenance_t.semantic_version_minor
Loaded library semantic-version minor 성분이다.
```
uint32_t semantic_version_minor;
```
math_engine_execution_provenance_t.semantic_version_patch
Loaded library semantic-version patch 성분이다.
```
uint32_t semantic_version_patch;
```
math_engine_execution_provenance_t.abi_version
Loaded library가 구현한 MATH_ENGINE_ABI_VERSION 값이다.
```
uint32_t abi_version;
```
math_engine_execution_provenance_t.context_fingerprint
Mode, tolerance, budget와 rounding을 결합한 resolved-context fingerprint다.
```
uint64_t context_fingerprint;
```
math_engine_execution_provenance_t.capability_fingerprint
실행 당시 immutable capability manifest fingerprint다.
```
uint64_t capability_fingerprint;
```
math_engine_execution_provenance_t.input_fingerprint
Caller가 canonical input bytes에서 계산해 제공한 fingerprint다.
```
uint64_t input_fingerprint;
```
math_engine_execution_provenance_t.output_fingerprint
Caller가 canonical output bytes에서 계산해 제공한 fingerprint다.
```
uint64_t output_fingerprint;
```
math_engine_execution_provenance_t.execution_fingerprint
Version·context·capability·input·output·status를 결합한 replay key다.
```
uint64_t execution_fingerprint;
```
math_engine_execution_provenance_t.deterministic
실행 context가 deterministic 계약을 요구하고 충족했으면 1이다.
```
uint32_t deterministic;
```
math_engine_execution_provenance_t.cancellation_observed
Binding token이 provenance 생성 시 cancelled 상태였으면 1이다.
```
uint32_t cancellation_observed;
```
math_engine_execution_provenance_t.locale_independent
실행이 process locale과 무관한 경로임을 인증하면 1이다.
```
uint32_t locale_independent;
```
math_engine_execution_provenance_t.flags
Version 1 provenance flag bitset이다. 정의되지 않은 bit는 0이다.
```
uint32_t flags;
```

Macro와 constant

`MATH_ENGINE_CANCELLATION_TOKEN_VERSION_1`

math_engine_cancellation_token_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_CANCELLATION_TOKEN_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXECUTION_PROVENANCE_VERSION_1`

math_engine_execution_provenance_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_EXECUTION_PROVENANCE_VERSION_1 UINT32_C(1)

`MATH_ENGINE_RUNTIME_BINDING_VERSION_1`

math_engine_runtime_binding_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_RUNTIME_BINDING_VERSION_1 UINT32_C(1)

Function

`math_engine_cancellation_token_init`

Token을 non-cancelled 상태로 초기화한다.

매개변수 out_token: 초기화할 caller-owned token storage.
반환: 성공 시 OK. NULL이면 INVALID_ARGUMENT이다.

같은 storage에 대한 다른 접근을 시작하기 전에 호출해야 한다.

Math Engine ownership: out_token=caller
Math Engine nullable: out_token=false
Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_cancellation_token_init(
    math_engine_cancellation_token_t* out_token);

`math_engine_cancellation_token_request`

여러 thread에서 idempotent하게 cancellation을 요청한다.

매개변수 token: 초기화된 caller-owned token. 상태만 release atomic store로 1이 된다.
반환: 성공 시 OK. Header/version 오류에서는 상태를 변경하지 않는다.
Math Engine ownership: token=caller
Math Engine nullable: token=false
Math Engine thread_safety: atomic

MATH_ENGINE_API math_engine_status_t math_engine_cancellation_token_request(
    math_engine_cancellation_token_t* token);

`math_engine_cancellation_token_is_requested`

Atomic cancellation 상태를 acquire load로 조회한다.

매개변수 token: 초기화된 borrowed token.
매개변수 out_requested: 성공 시 취소 전 0, 요청 후 1을 받는 caller output.
반환: 성공 시 OK. Header/state/output 오류에서는 out_requested 를 보존한다.
Math Engine ownership: token=borrowed out_requested=caller
Math Engine nullable: token=false out_requested=false
Math Engine thread_safety: atomic

MATH_ENGINE_API math_engine_status_t math_engine_cancellation_token_is_requested(
    const math_engine_cancellation_token_t* token,
    uint32_t* out_requested);

`math_engine_cancellation_token_callback`

math_engine_cancel_fn 과 호환되는 fail-closed callback adapter다.

매개변수 user_data: math_engine_cancellation_token_t 를 가리키는 borrowed pointer.
반환: 유효한 non-cancelled token이면 0, cancellation 요청 또는 NULL/손상 token이면 1.

Pointer를 보관하지 않고 호출 thread에서 atomic 조회만 수행한다.

Math Engine ownership: user_data=borrowed
Math Engine nullable: user_data=true
Math Engine thread_safety: atomic

MATH_ENGINE_API int math_engine_cancellation_token_callback(void* user_data);

`math_engine_runtime_binding_validate`

Context, token, workspace와 memory budget 조합을 검증한다.

매개변수 binding: 검증할 immutable binding. Nested context는 필수이고 token은 nullable이다.
반환: 유효하면 OK. Workspace capacity가 finite memory budget을 넘으면 OUT_OF_RANGE며

입력이나 workspace content를 변경하지 않는다. Library는 nested pointer를 보관하지 않는다.

Math Engine ownership: binding=borrowed
Math Engine nullable: binding=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_runtime_binding_validate(
    const math_engine_runtime_binding_t* binding);

`math_engine_execution_provenance_get`

실행 전후 fingerprint와 현재 floating environment를 provenance로 commit한다.

API 호출은 유효한 provenance 생성 여부를 반환하고, floating rounding 불일치나 cancellation은 out_provenance->execution_status 로 기록한다.

매개변수 binding: 검증할 immutable resolved context/token/workspace binding.
매개변수 scalar_backend: 실제 계산에 사용한 backend. FULL이 아니면 context backend와 같아야 한다.
매개변수 input_fingerprint: caller가 정의한 deterministic input fingerprint.
매개변수 output_fingerprint: caller가 정의한 deterministic output fingerprint.
매개변수 out_provenance: size/version을 설정한 caller output.
반환: Provenance가 생성되면 OK. 취소 또는 floating-rounding 불일치는 API 실패가 아니라

execution_status 에 기록된다. Validation 오류에서는 output을 보존한다. Binding과 output은 overlap하지 않아야 하고 pointer는 보관하지 않는다.

Math Engine ownership: binding=borrowed out_provenance=caller
Math Engine nullable: binding=false out_provenance=false
Math Engine thread_safety: fenv-thread-local

MATH_ENGINE_API math_engine_status_t math_engine_execution_provenance_get(
    const math_engine_runtime_binding_t* binding,
    math_engine_scalar_backend_t scalar_backend,
    uint64_t input_fingerprint,
    uint64_t output_fingerprint,
    math_engine_execution_provenance_t* out_provenance);

Math Engine Reference: Replay

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_cancellation_token_t

math_engine_runtime_binding_t

math_engine_execution_provenance_t

Macro와 constant

MATH_ENGINE_CANCELLATION_TOKEN_VERSION_1

MATH_ENGINE_EXECUTION_PROVENANCE_VERSION_1

MATH_ENGINE_RUNTIME_BINDING_VERSION_1

Function

math_engine_cancellation_token_init

math_engine_cancellation_token_request

math_engine_cancellation_token_is_requested

math_engine_cancellation_token_callback

math_engine_runtime_binding_validate

math_engine_execution_provenance_get