Math Engine Reference: Abi

문서 탐색

개요

Backend-neutral value, span, string buffer와 workspace C ABI를 선언한다.

모든 object와 storage는 caller-owned다. 함수는 memory를 allocate하거나 pointer를 보관하지 않는다. Pointer를 포함한 POD layout은 data model과 각 field의 sizeof/alignof/offsetof snapshot으로 관리하며 process 간 raw struct serialization을 허용하지 않는다. Tagged scalar만 아래의 명시 endian wire function으로 serialize한다.

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

공개 API

Header 사용 시작

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

#include <math_engine/math_engine_abi.h>

Type과 callback

`math_engine_scalar_tag_t`

Fixed-width scalar tag 값이다. Public struct field에는 fixed-width integer로 저장한다.

typedef enum math_engine_scalar_tag {
    MATH_ENGINE_SCALAR_TAG_INVALID = 0, /**< Active scalar storage가 없거나 tag가 초기화되지 않은 sentinel이다. */
    MATH_ENGINE_SCALAR_TAG_I32 = 1, /**< =math_engine_scalar_storage_t.i32=가 active인 signed 32-bit integer다. */
    MATH_ENGINE_SCALAR_TAG_U32 = 2, /**< =math_engine_scalar_storage_t.u32=가 active인 unsigned 32-bit integer다. */
    MATH_ENGINE_SCALAR_TAG_I64 = 3, /**< =math_engine_scalar_storage_t.i64=가 active인 signed 64-bit integer다. */
    MATH_ENGINE_SCALAR_TAG_U64 = 4, /**< =math_engine_scalar_storage_t.u64=가 active인 unsigned 64-bit integer다. */
    MATH_ENGINE_SCALAR_TAG_F32 = 5, /**< =math_engine_scalar_storage_t.f32=가 active인 IEEE-754 binary32 값이다. */
    MATH_ENGINE_SCALAR_TAG_F64 = 6 /**< =math_engine_scalar_storage_t.f64=가 active인 IEEE-754 binary64 값이다. */
} math_engine_scalar_tag_t;

math_engine_scalar_tag_t.MATH_ENGINE_SCALAR_TAG_INVALID
Active scalar storage가 없거나 tag가 초기화되지 않은 sentinel이다.
```
MATH_ENGINE_SCALAR_TAG_INVALID = 0,
```
math_engine_scalar_tag_t.MATH_ENGINE_SCALAR_TAG_I32
math_engine_scalar_storage_t.i32 가 active인 signed 32-bit integer다.
```
MATH_ENGINE_SCALAR_TAG_I32 = 1,
```
math_engine_scalar_tag_t.MATH_ENGINE_SCALAR_TAG_U32
math_engine_scalar_storage_t.u32 가 active인 unsigned 32-bit integer다.
```
MATH_ENGINE_SCALAR_TAG_U32 = 2,
```
math_engine_scalar_tag_t.MATH_ENGINE_SCALAR_TAG_I64
math_engine_scalar_storage_t.i64 가 active인 signed 64-bit integer다.
```
MATH_ENGINE_SCALAR_TAG_I64 = 3,
```
math_engine_scalar_tag_t.MATH_ENGINE_SCALAR_TAG_U64
math_engine_scalar_storage_t.u64 가 active인 unsigned 64-bit integer다.
```
MATH_ENGINE_SCALAR_TAG_U64 = 4,
```
math_engine_scalar_tag_t.MATH_ENGINE_SCALAR_TAG_F32
math_engine_scalar_storage_t.f32 가 active인 IEEE-754 binary32 값이다.
```
MATH_ENGINE_SCALAR_TAG_F32 = 5,
```
math_engine_scalar_tag_t.MATH_ENGINE_SCALAR_TAG_F64
math_engine_scalar_storage_t.f64 가 active인 IEEE-754 binary64 값이다.
```
MATH_ENGINE_SCALAR_TAG_F64 = 6,
```

`math_engine_byte_order_t`

Canonical wire byte order다. Host endian을 추정하거나 native memcpy하지 않는다.

typedef enum math_engine_byte_order {
    MATH_ENGINE_BYTE_ORDER_LITTLE_ENDIAN = 1, /**< Multi-byte integer와 floating payload의 least-significant byte를 먼저 기록한다. */
    MATH_ENGINE_BYTE_ORDER_BIG_ENDIAN = 2 /**< Multi-byte integer와 floating payload의 most-significant byte를 먼저 기록한다. */
} math_engine_byte_order_t;

math_engine_byte_order_t.MATH_ENGINE_BYTE_ORDER_LITTLE_ENDIAN
Multi-byte integer와 floating payload의 least-significant byte를 먼저 기록한다.
```
MATH_ENGINE_BYTE_ORDER_LITTLE_ENDIAN = 1,
```
math_engine_byte_order_t.MATH_ENGINE_BYTE_ORDER_BIG_ENDIAN
Multi-byte integer와 floating payload의 most-significant byte를 먼저 기록한다.
```
MATH_ENGINE_BYTE_ORDER_BIG_ENDIAN = 2,
```

`math_engine_scalar_storage_t`

Tagged scalar의 64-bit fixed storage다. Active member는 scalar_tag 가 결정한다.

typedef union math_engine_scalar_storage {
    int32_t i32; /**< =MATH_ENGINE_SCALAR_TAG_I32=일 때 읽고 쓰는 signed 32-bit payload다. */
    uint32_t u32; /**< =MATH_ENGINE_SCALAR_TAG_U32=일 때 읽고 쓰는 unsigned 32-bit payload다. */
    int64_t i64; /**< =MATH_ENGINE_SCALAR_TAG_I64=일 때 읽고 쓰는 signed 64-bit payload다. */
    uint64_t u64; /**< =MATH_ENGINE_SCALAR_TAG_U64=일 때 읽고 쓰는 unsigned 64-bit payload다. */
    float f32; /**< =MATH_ENGINE_SCALAR_TAG_F32=일 때 읽고 쓰는 IEEE-754 binary32 payload다. */
    double f64; /**< =MATH_ENGINE_SCALAR_TAG_F64=일 때 읽고 쓰는 IEEE-754 binary64 payload다. */
    uint64_t bits; /**< Union storage 전체를 초기화·검사할 때 사용하는 raw 64-bit view다. Wire endian을 뜻하지 않는다. */
} math_engine_scalar_storage_t;

math_engine_scalar_storage_t.i32
MATH_ENGINE_SCALAR_TAG_I32 일 때 읽고 쓰는 signed 32-bit payload다.
```
int32_t i32;
```
math_engine_scalar_storage_t.u32
MATH_ENGINE_SCALAR_TAG_U32 일 때 읽고 쓰는 unsigned 32-bit payload다.
```
uint32_t u32;
```
math_engine_scalar_storage_t.i64
MATH_ENGINE_SCALAR_TAG_I64 일 때 읽고 쓰는 signed 64-bit payload다.
```
int64_t i64;
```
math_engine_scalar_storage_t.u64
MATH_ENGINE_SCALAR_TAG_U64 일 때 읽고 쓰는 unsigned 64-bit payload다.
```
uint64_t u64;
```
math_engine_scalar_storage_t.f32
MATH_ENGINE_SCALAR_TAG_F32 일 때 읽고 쓰는 IEEE-754 binary32 payload다.
```
float f32;
```
math_engine_scalar_storage_t.f64
MATH_ENGINE_SCALAR_TAG_F64 일 때 읽고 쓰는 IEEE-754 binary64 payload다.
```
double f64;
```
math_engine_scalar_storage_t.bits
Union storage 전체를 초기화·검사할 때 사용하는 raw 64-bit view다. Wire endian을 뜻하지 않는다.
```
uint64_t bits;
```

`math_engine_value_t`

Size/version header를 가진 16-byte caller-owned scalar value다.

typedef struct math_engine_value {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_value_t)=로 설정하는 byte 크기다. */
    uint16_t struct_version; /**< =MATH_ENGINE_STRUCT_VERSION_1=인 value layout version이다. */
    uint16_t scalar_tag; /**< Active =data= member를 선택하는 =math_engine_scalar_tag_t= 값이다. */
    math_engine_scalar_storage_t data; /**< =scalar_tag=로 선택된 fixed-width scalar payload다. 비활성 bytes는 canonical하게 0이다. */
} math_engine_value_t;

math_engine_value_t.struct_size
Caller가 sizeof(math_engine_value_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_value_t.struct_version
MATH_ENGINE_STRUCT_VERSION_1 인 value layout version이다.
```
uint16_t struct_version;
```
math_engine_value_t.scalar_tag
Active data member를 선택하는 math_engine_scalar_tag_t 값이다.
```
uint16_t scalar_tag;
```
math_engine_value_t.data
scalar_tag 로 선택된 fixed-width scalar payload다. 비활성 bytes는 canonical하게 0이다.
```
math_engine_scalar_storage_t data;
```

`math_engine_const_byte_span_t`

Read-only caller-owned byte view다. data=NULL 은 size 가 0일 때만 유효하다.

typedef struct math_engine_const_byte_span {
    const void* data; /**< Caller가 소유하는 read-only =size= byte의 시작 주소다. =size==0=일 때만 NULL 가능하며 보관되지 않는다. */
    uint64_t size; /**< =data=에서 읽을 수 있는 byte 수다. */
} math_engine_const_byte_span_t;

math_engine_const_byte_span_t.data
Caller가 소유하는 read-only size byte의 시작 주소다. =size==0=일 때만 NULL 가능하며 보관되지 않는다.
```
const void* data;
```
math_engine_const_byte_span_t.size
data 에서 읽을 수 있는 byte 수다.
```
uint64_t size;
```

`math_engine_mutable_byte_span_t`

Writable caller-owned byte view다. data=NULL 은 size 가 0일 때만 유효하다.

typedef struct math_engine_mutable_byte_span {
    void* data; /**< Caller가 소유하는 writable =size= byte의 시작 주소다. =size==0=일 때만 NULL 가능하며 보관되지 않는다. */
    uint64_t size; /**< =data=에 쓸 수 있는 byte capacity다. */
} math_engine_mutable_byte_span_t;

math_engine_mutable_byte_span_t.data
Caller가 소유하는 writable size byte의 시작 주소다. =size==0=일 때만 NULL 가능하며 보관되지 않는다.
```
void* data;
```
math_engine_mutable_byte_span_t.size
data 에 쓸 수 있는 byte capacity다.
```
uint64_t size;
```

`math_engine_string_buffer_t`

Caller-owned NUL-terminated UTF-8 output buffer다.

capacity 와 required_size 는 trailing NUL을 포함하고 size 는 포함하지 않는다. MATH_ENGINE_STATUS_INSUFFICIENT_BUFFER 에서는 data와 size를 보존하고 required_size 만 갱신할 수 있다. Source와 destination overlap은 허용하지 않는다.

typedef struct math_engine_string_buffer {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_string_buffer_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_STRUCT_VERSION_1=인 string-buffer layout version이다. */
    char* data; /**< Caller-owned writable UTF-8 storage다. =capacity==0=일 때만 NULL 가능하며 호출 뒤 보관되지 않는다. */
    uint64_t capacity; /**< =data=의 전체 byte capacity이며 trailing NUL 자리도 포함한다. */
    uint64_t size; /**< 현재 또는 성공 시 기록된 UTF-8 payload byte 수다. Trailing NUL은 제외한다. */
    uint64_t required_size; /**< 요청 text와 trailing NUL을 모두 담는 데 필요한 byte 수다. Size query와 부족 오류에서도 갱신될 수 있다. */
} math_engine_string_buffer_t;

math_engine_string_buffer_t.struct_size
Caller가 sizeof(math_engine_string_buffer_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_string_buffer_t.struct_version
MATH_ENGINE_STRUCT_VERSION_1 인 string-buffer layout version이다.
```
uint32_t struct_version;
```
math_engine_string_buffer_t.data
Caller-owned writable UTF-8 storage다. =capacity==0=일 때만 NULL 가능하며 호출 뒤 보관되지 않는다.
```
char* data;
```
math_engine_string_buffer_t.capacity
data 의 전체 byte capacity이며 trailing NUL 자리도 포함한다.
```
uint64_t capacity;
```
math_engine_string_buffer_t.size
현재 또는 성공 시 기록된 UTF-8 payload byte 수다. Trailing NUL은 제외한다.
```
uint64_t size;
```
math_engine_string_buffer_t.required_size
요청 text와 trailing NUL을 모두 담는 데 필요한 byte 수다. Size query와 부족 오류에서도 갱신될 수 있다.
```
uint64_t required_size;
```

`math_engine_workspace_t`

Allocation 없는 operation에 전달하는 caller-owned workspace다.

alignment 은 0 또는 2의 거듭제곱이고 non-null data 주소가 이를 만족해야 한다. Operation은 부족할 때 data content를 보존하고 required_size 만 갱신할 수 있다. flags 는 현재 0만 허용한다. Library는 pointer를 호출 이후 보관하지 않는다.

typedef struct math_engine_workspace {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_workspace_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_STRUCT_VERSION_1=인 workspace layout version이다. */
    void* data; /**< Caller-owned writable scratch storage다. =capacity==0=일 때만 NULL 가능하며 호출 뒤 보관되지 않는다. */
    uint64_t capacity; /**< =data=가 제공하는 scratch byte 수다. */
    uint64_t required_size; /**< Operation이 요구한 scratch byte 수다. 부족 오류에서도 갱신될 수 있다. */
    uint32_t alignment; /**< =data=가 만족하는 byte alignment다. 0 또는 2의 거듭제곱이어야 한다. */
    uint32_t flags; /**< Workspace policy bitset이다. ABI version 1에서는 반드시 0이다. */
} math_engine_workspace_t;

math_engine_workspace_t.struct_size
Caller가 sizeof(math_engine_workspace_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_workspace_t.struct_version
MATH_ENGINE_STRUCT_VERSION_1 인 workspace layout version이다.
```
uint32_t struct_version;
```
math_engine_workspace_t.data
Caller-owned writable scratch storage다. =capacity==0=일 때만 NULL 가능하며 호출 뒤 보관되지 않는다.
```
void* data;
```
math_engine_workspace_t.capacity
data 가 제공하는 scratch byte 수다.
```
uint64_t capacity;
```
math_engine_workspace_t.required_size
Operation이 요구한 scratch byte 수다. 부족 오류에서도 갱신될 수 있다.
```
uint64_t required_size;
```
math_engine_workspace_t.alignment
data 가 만족하는 byte alignment다. 0 또는 2의 거듭제곱이어야 한다.
```
uint32_t alignment;
```
math_engine_workspace_t.flags
Workspace policy bitset이다. ABI version 1에서는 반드시 0이다.
```
uint32_t flags;
```

`math_engine_runtime_info_t`

Build/runtime identity를 pointer 없이 반환하는 versioned POD다.

Source revision은 7~64자리 hexadecimal과 NUL, fingerprint는 64자리 lowercase SHA-256 hex와 NUL이다. 이 identity는 installed ABI manifest와 정확히 일치해야 한다.

typedef struct math_engine_runtime_info {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_runtime_info_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_RUNTIME_INFO_VERSION_1=인 runtime-info layout version이다. */
    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= 값이다. */
    uint32_t source_dirty; /**< Build source tree에 commit되지 않은 변경이 있었으면 1, 아니면 0이다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    char source_revision[MATH_ENGINE_SOURCE_REVISION_CAPACITY]; /**< Build source Git revision의 7~64자리 hexadecimal NUL-terminated text다. */
    char public_header_fingerprint[MATH_ENGINE_SHA256_HEX_CAPACITY]; /**< 설치 public header set의 SHA-256 lowercase hexadecimal NUL-terminated text다. */
} math_engine_runtime_info_t;

math_engine_runtime_info_t.struct_size
Caller가 sizeof(math_engine_runtime_info_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_runtime_info_t.struct_version
MATH_ENGINE_RUNTIME_INFO_VERSION_1 인 runtime-info layout version이다.
```
uint32_t struct_version;
```
math_engine_runtime_info_t.semantic_version_major
Loaded library의 semantic-version major 성분이다.
```
uint32_t semantic_version_major;
```
math_engine_runtime_info_t.semantic_version_minor
Loaded library의 semantic-version minor 성분이다.
```
uint32_t semantic_version_minor;
```
math_engine_runtime_info_t.semantic_version_patch
Loaded library의 semantic-version patch 성분이다.
```
uint32_t semantic_version_patch;
```
math_engine_runtime_info_t.abi_version
Loaded library가 구현하는 MATH_ENGINE_ABI_VERSION 값이다.
```
uint32_t abi_version;
```
math_engine_runtime_info_t.source_dirty
Build source tree에 commit되지 않은 변경이 있었으면 1, 아니면 0이다.
```
uint32_t source_dirty;
```
math_engine_runtime_info_t.reserved
향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다.
```
uint32_t reserved;
```
math_engine_runtime_info_t.source_revision
Build source Git revision의 7~64자리 hexadecimal NUL-terminated text다.
```
char source_revision[MATH_ENGINE_SOURCE_REVISION_CAPACITY];
```
math_engine_runtime_info_t.public_header_fingerprint
설치 public header set의 SHA-256 lowercase hexadecimal NUL-terminated text다.
```
char public_header_fingerprint[MATH_ENGINE_SHA256_HEX_CAPACITY];
```

Macro와 constant

`MATH_ENGINE_RUNTIME_INFO_VERSION_1`

math_engine_runtime_info_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_RUNTIME_INFO_VERSION_1 UINT32_C(1)

`MATH_ENGINE_SHA256_HEX_CAPACITY`

64자리 lowercase SHA-256 hexadecimal text와 trailing NUL을 담는 배열 용량이다.

#define MATH_ENGINE_SHA256_HEX_CAPACITY UINT32_C(65)

`MATH_ENGINE_SOURCE_REVISION_CAPACITY`

최대 64자리 hexadecimal source revision과 trailing NUL을 담는 배열 용량이다.

#define MATH_ENGINE_SOURCE_REVISION_CAPACITY UINT32_C(65)

`MATH_ENGINE_STRUCT_VERSION_1`

공통 versioned public POD의 최초 안정 layout version이다.

#define MATH_ENGINE_STRUCT_VERSION_1 UINT32_C(1)

`MATH_ENGINE_VALUE_WIRE_SIZE`

Tagged scalar wire representation의 고정 byte 수다.

#define MATH_ENGINE_VALUE_WIRE_SIZE UINT64_C(16)

Function

`math_engine_value_encode`

Tagged scalar를 명시 byte order의 16-byte wire value로 encode한다.

매개변수 value: 유효한 size/version/tag를 가진 input value.
매개변수 byte_order: little 또는 big endian.
매개변수 output: caller-owned output span. Input과 overlap할 수 없다.
매개변수 out_required_size: nullable required-size output. Output span 내부와 alias할 수 없다.
반환: 성공 시 OK. 작은 output에서는 content를 보존하고 required size만 16으로 쓴다.
Math Engine ownership: value=borrowed output=caller out_required_size=caller
Math Engine nullable: value=false output=capacity_zero_only out_required_size=true
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_value_encode(
    const math_engine_value_t* value,
    math_engine_byte_order_t byte_order,
    math_engine_mutable_byte_span_t output,
    uint64_t* out_required_size);

`math_engine_value_decode`

명시 byte order의 16-byte wire value를 tagged scalar로 decode한다.

매개변수 input: 최소 16-byte caller-owned input. out_value 와 overlap할 수 없다.
매개변수 byte_order: little 또는 big endian.
매개변수 out_value: 성공 시 commit되는 caller-owned output.
반환: 성공 시 OK. 모든 실패에서 out_value 를 보존한다.
Math Engine ownership: input=borrowed out_value=caller
Math Engine nullable: input=capacity_zero_only out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_value_decode(
    math_engine_const_byte_span_t input,
    math_engine_byte_order_t byte_order,
    math_engine_value_t* out_value);

`math_engine_string_buffer_write`

명시 길이의 UTF-8 byte를 caller-owned string buffer에 복사한다.

매개변수 buffer: size/version/data/capacity를 caller가 초기화한 buffer.
매개변수 utf8: NUL을 제외한 input byte. utf8_size 0이면 NULL 가능하다.
매개변수 utf8_size: NUL을 제외한 byte 수.
반환: 성공 시 OK. 작은 buffer에서는 data/size를 보존하고 required size만 갱신한다.
Math Engine ownership: buffer=caller utf8=borrowed
Math Engine nullable: buffer=false utf8=count_zero_only
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_string_buffer_write(
    math_engine_string_buffer_t* buffer,
    const char* utf8,
    uint64_t utf8_size);

`math_engine_workspace_validate`

Workspace header, capacity, alignment와 reserved flags를 검증한다.

매개변수 workspace: 검증할 borrowed workspace. 내부 data는 읽거나 변경하지 않는다.
반환: 유효하면 OK. NULL/잘못된 정렬은 INVALID_ARGUMENT, size 불일치는

INVALID_SIZE, 알 수 없는 version/flag는 UNSUPPORTED다.

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

MATH_ENGINE_API math_engine_status_t math_engine_workspace_validate(
    const math_engine_workspace_t* workspace);

`math_engine_runtime_info_get`

현재 loaded library의 version, revision과 public header fingerprint를 조회한다.

매개변수 out_info: caller가 struct_size 와 struct_version 을 설정한 output.
반환: 성공 시 OK. Size/version 불일치와 NULL에서 output을 보존한다.
Math Engine ownership: out_info=caller
Math Engine nullable: out_info=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_runtime_info_get(
    math_engine_runtime_info_t* out_info);

Math Engine Reference: Abi

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_scalar_tag_t

math_engine_byte_order_t

math_engine_scalar_storage_t

math_engine_value_t

math_engine_const_byte_span_t

math_engine_mutable_byte_span_t

math_engine_string_buffer_t

math_engine_workspace_t

math_engine_runtime_info_t

Macro와 constant

MATH_ENGINE_RUNTIME_INFO_VERSION_1

MATH_ENGINE_SHA256_HEX_CAPACITY

MATH_ENGINE_SOURCE_REVISION_CAPACITY

MATH_ENGINE_STRUCT_VERSION_1

MATH_ENGINE_VALUE_WIRE_SIZE