HAIDOX
HAIDOX Help

Math Engine Reference: Precision Decimal

개요

호출자 workspace를 사용하는 가변 정밀도 10진 backend C ABI.

구현은 backend 객체, C++ 형식, 예외와 allocator를 ABI에 노출하지 않는다. 값은 context에 속한 opaque handle이며 모든 숫자 storage는 context 초기화 때 전달한 workspace 안에 있다. 이 계층은 금융 원장용 math_engine_decimal_fixed_t 를 대체하지 않는다.

공개 API

Header 사용 시작

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

#include <math_engine/math_engine_precision_decimal.h>

Type과 callback

math_engine_precision_text_format_t

Backend가 지원하는 text 출력 형식. 

typedef enum math_engine_precision_text_format {
    MATH_ENGINE_PRECISION_TEXT_FORMAT_INVALID = 0, /**< Uninitialized or unsupported format sentinel. */
    MATH_ENGINE_PRECISION_TEXT_FORMAT_SCIENTIFIC = 1, /**< One leading digit and an explicit base-10 exponent. */
    MATH_ENGINE_PRECISION_TEXT_FORMAT_FIXED = 2 /**< Decimal point placed according to the stored exponent. */
} math_engine_precision_text_format_t;
  • math_engine_precision_text_format_t.MATH_ENGINE_PRECISION_TEXT_FORMAT_INVALID

    Uninitialized or unsupported format sentinel. 

    MATH_ENGINE_PRECISION_TEXT_FORMAT_INVALID = 0,
  • math_engine_precision_text_format_t.MATH_ENGINE_PRECISION_TEXT_FORMAT_SCIENTIFIC

    One leading digit and an explicit base-10 exponent. 

    MATH_ENGINE_PRECISION_TEXT_FORMAT_SCIENTIFIC = 1,
  • math_engine_precision_text_format_t.MATH_ENGINE_PRECISION_TEXT_FORMAT_FIXED

    Decimal point placed according to the stored exponent. 

    MATH_ENGINE_PRECISION_TEXT_FORMAT_FIXED = 2,

math_engine_precision_operation_t

감사 결과에 기록되는 가변 정밀도 연산. 

typedef enum math_engine_precision_operation {
    MATH_ENGINE_PRECISION_OPERATION_INVALID = 0, /**< No decimal operation was committed. */
    MATH_ENGINE_PRECISION_OPERATION_PARSE = 1, /**< Strict ASCII decimal parse. */
    MATH_ENGINE_PRECISION_OPERATION_ADD = 2, /**< Aligned decimal addition. */
    MATH_ENGINE_PRECISION_OPERATION_SUBTRACT = 3, /**< Aligned decimal subtraction. */
    MATH_ENGINE_PRECISION_OPERATION_MULTIPLY = 4, /**< Exact coefficient multiplication followed by rounding. */
    MATH_ENGINE_PRECISION_OPERATION_DIVIDE = 5 /**< Long division followed by configured rounding. */
} math_engine_precision_operation_t;
  • math_engine_precision_operation_t.MATH_ENGINE_PRECISION_OPERATION_INVALID

    No decimal operation was committed. 

    MATH_ENGINE_PRECISION_OPERATION_INVALID = 0,
  • math_engine_precision_operation_t.MATH_ENGINE_PRECISION_OPERATION_PARSE

    Strict ASCII decimal parse. 

    MATH_ENGINE_PRECISION_OPERATION_PARSE = 1,
  • math_engine_precision_operation_t.MATH_ENGINE_PRECISION_OPERATION_ADD

    Aligned decimal addition. 

    MATH_ENGINE_PRECISION_OPERATION_ADD = 2,
  • math_engine_precision_operation_t.MATH_ENGINE_PRECISION_OPERATION_SUBTRACT

    Aligned decimal subtraction. 

    MATH_ENGINE_PRECISION_OPERATION_SUBTRACT = 3,
  • math_engine_precision_operation_t.MATH_ENGINE_PRECISION_OPERATION_MULTIPLY

    Exact coefficient multiplication followed by rounding. 

    MATH_ENGINE_PRECISION_OPERATION_MULTIPLY = 4,
  • math_engine_precision_operation_t.MATH_ENGINE_PRECISION_OPERATION_DIVIDE

    Long division followed by configured rounding. 

    MATH_ENGINE_PRECISION_OPERATION_DIVIDE = 5,

math_engine_precision_escalation_reason_t

정밀도 승격을 선택한 직접 원인. 

typedef enum math_engine_precision_escalation_reason {
    MATH_ENGINE_PRECISION_ESCALATION_NONE = 0, /**< Initial precision remains sufficient. */
    MATH_ENGINE_PRECISION_ESCALATION_USER_REQUEST = 1, /**< Caller explicitly requested more precision. */
    MATH_ENGINE_PRECISION_ESCALATION_ERROR_BOUND = 2, /**< Observed error exceeded its positive target. */
    MATH_ENGINE_PRECISION_ESCALATION_CANCELLATION = 3, /**< Cancellation depth requested compensating precision. */
    /** Artifact lacks the required arbitrary-precision capability or range. */
    MATH_ENGINE_PRECISION_ESCALATION_CAPABILITY_MISSING = 4,
    MATH_ENGINE_PRECISION_ESCALATION_MEMORY_BUDGET = 5 /**< Required workspace exceeds the caller budget. */
} math_engine_precision_escalation_reason_t;
  • math_engine_precision_escalation_reason_t.MATH_ENGINE_PRECISION_ESCALATION_NONE

    Initial precision remains sufficient. 

    MATH_ENGINE_PRECISION_ESCALATION_NONE = 0,
  • math_engine_precision_escalation_reason_t.MATH_ENGINE_PRECISION_ESCALATION_USER_REQUEST

    Caller explicitly requested more precision. 

    MATH_ENGINE_PRECISION_ESCALATION_USER_REQUEST = 1,
  • math_engine_precision_escalation_reason_t.MATH_ENGINE_PRECISION_ESCALATION_ERROR_BOUND

    Observed error exceeded its positive target. 

    MATH_ENGINE_PRECISION_ESCALATION_ERROR_BOUND = 2,
  • math_engine_precision_escalation_reason_t.MATH_ENGINE_PRECISION_ESCALATION_CANCELLATION

    Cancellation depth requested compensating precision. 

    MATH_ENGINE_PRECISION_ESCALATION_CANCELLATION = 3,
  • math_engine_precision_escalation_reason_t.MATH_ENGINE_PRECISION_ESCALATION_CAPABILITY_MISSING

    Artifact lacks the required arbitrary-precision capability or range. 

    /** Artifact lacks the required arbitrary-precision capability or range. */
    MATH_ENGINE_PRECISION_ESCALATION_CAPABILITY_MISSING = 4,
  • math_engine_precision_escalation_reason_t.MATH_ENGINE_PRECISION_ESCALATION_MEMORY_BUDGET

    Required workspace exceeds the caller budget. 

    MATH_ENGINE_PRECISION_ESCALATION_MEMORY_BUDGET = 5,

math_engine_precision_backend_info_t

버전, 한계, 이름과 license를 포함하는 immutable backend 설명이다. 

typedef struct math_engine_precision_backend_info {
    uint32_t struct_size; /**< Exact byte size supplied by the caller. */
    uint32_t struct_version; /**< =MATH_ENGINE_PRECISION_BACKEND_INFO_VERSION_1=. */
    uint32_t backend_version; /**< Portable decimal algorithm version; currently 1. */
    uint32_t flags; /**< Backend capability bits; version 1 writes 0. */
    uint32_t minimum_precision_bits; /**< Inclusive supported minimum, currently 64 bits. */
    uint32_t maximum_precision_bits; /**< Inclusive supported maximum, currently 4096 bits. */
    int32_t minimum_exponent; /**< Inclusive minimum scientific decimal exponent. */
    int32_t maximum_exponent; /**< Inclusive maximum scientific decimal exponent. */
    uint32_t maximum_values; /**< Maximum simultaneously acquired slots per context; currently 64. */
    uint32_t reserved32; /**< Reserved for ABI growth; written as 0. */
    uint64_t backend_fingerprint; /**< Stable identity of algorithm, limits and representation. */
    char backend_name[32]; /**< Inline NUL-terminated backend name; no borrowed pointer or lifetime. */
    char license_id[32]; /**< Inline NUL-terminated SPDX-style license identifier. */
} math_engine_precision_backend_info_t;
  • math_engine_precision_backend_info_t.struct_size

    Exact byte size supplied by the caller. 

    uint32_t struct_size;
  • math_engine_precision_backend_info_t.struct_version

    MATH_ENGINE_PRECISION_BACKEND_INFO_VERSION_1. 

    uint32_t struct_version;
  • math_engine_precision_backend_info_t.backend_version

    Portable decimal algorithm version; currently 1. 

    uint32_t backend_version;
  • math_engine_precision_backend_info_t.flags

    Backend capability bits; version 1 writes 0. 

    uint32_t flags;
  • math_engine_precision_backend_info_t.minimum_precision_bits

    Inclusive supported minimum, currently 64 bits. 

    uint32_t minimum_precision_bits;
  • math_engine_precision_backend_info_t.maximum_precision_bits

    Inclusive supported maximum, currently 4096 bits. 

    uint32_t maximum_precision_bits;
  • math_engine_precision_backend_info_t.minimum_exponent

    Inclusive minimum scientific decimal exponent. 

    int32_t minimum_exponent;
  • math_engine_precision_backend_info_t.maximum_exponent

    Inclusive maximum scientific decimal exponent. 

    int32_t maximum_exponent;
  • math_engine_precision_backend_info_t.maximum_values

    Maximum simultaneously acquired slots per context; currently 64. 

    uint32_t maximum_values;
  • math_engine_precision_backend_info_t.reserved32

    Reserved for ABI growth; written as 0. 

    uint32_t reserved32;
  • math_engine_precision_backend_info_t.backend_fingerprint

    Stable identity of algorithm, limits and representation. 

    uint64_t backend_fingerprint;
  • math_engine_precision_backend_info_t.backend_name

    Inline NUL-terminated backend name; no borrowed pointer or lifetime. 

    char backend_name[32];
  • math_engine_precision_backend_info_t.license_id

    Inline NUL-terminated SPDX-style license identifier. 

    char license_id[32];

math_engine_precision_context_config_t

Context의 정밀도, 지수, 반올림, slot 수와 memory budget 요청이다. 

typedef struct math_engine_precision_context_config {
    uint32_t struct_size; /**< Exact byte size of this configuration. */
    uint32_t struct_version; /**< =MATH_ENGINE_PRECISION_CONTEXT_CONFIG_VERSION_1=. */
    uint32_t precision_bits; /**< Requested binary precision in inclusive [64, 4096]. */
    int32_t exponent_min; /**< Inclusive decimal exponent floor in [-1024, 0]. */
    int32_t exponent_max; /**< Inclusive decimal exponent ceiling in [0, 1024], above the floor. */
    uint32_t rounding; /**< One valid =math_engine_decimal_rounding_t= except INVALID. */
    uint32_t max_values; /**< Number of value slots to allocate, in inclusive [1, 64]. */
    uint32_t flags; /**< Reserved policy bits; version 1 requires 0. */
    uint64_t memory_budget_bytes; /**< Positive upper bound for context workspace consumption. */
    uint64_t reserved; /**< Reserved for ABI growth; must be 0. */
} math_engine_precision_context_config_t;
  • math_engine_precision_context_config_t.struct_size

    Exact byte size of this configuration. 

    uint32_t struct_size;
  • math_engine_precision_context_config_t.struct_version

    MATH_ENGINE_PRECISION_CONTEXT_CONFIG_VERSION_1. 

    uint32_t struct_version;
  • math_engine_precision_context_config_t.precision_bits

    Requested binary precision in inclusive [64, 4096]. 

    uint32_t precision_bits;
  • math_engine_precision_context_config_t.exponent_min

    Inclusive decimal exponent floor in [-1024, 0]. 

    int32_t exponent_min;
  • math_engine_precision_context_config_t.exponent_max

    Inclusive decimal exponent ceiling in [0, 1024], above the floor. 

    int32_t exponent_max;
  • math_engine_precision_context_config_t.rounding

    One valid math_engine_decimal_rounding_t except INVALID. 

    uint32_t rounding;
  • math_engine_precision_context_config_t.max_values

    Number of value slots to allocate, in inclusive [1, 64]. 

    uint32_t max_values;
  • math_engine_precision_context_config_t.flags

    Reserved policy bits; version 1 requires 0. 

    uint32_t flags;
  • math_engine_precision_context_config_t.memory_budget_bytes

    Positive upper bound for context workspace consumption. 

    uint64_t memory_budget_bytes;
  • math_engine_precision_context_config_t.reserved

    Reserved for ABI growth; must be 0. 

    uint64_t reserved;

math_engine_precision_context_t

구현 세부를 workspace 뒤에 숨기는 caller-owned context adapter다. 

typedef struct math_engine_precision_context {
    uint32_t struct_size; /**< Exact byte size of this context adapter. */
    uint32_t struct_version; /**< =MATH_ENGINE_PRECISION_CONTEXT_VERSION_1=. */
    /**
     * Non-null caller-owned writable storage whose =size= is the initialized byte count.
     * Data remains alive, exclusive and unmoved for the complete context lifetime.
     */
    math_engine_mutable_byte_span_t workspace;
    uint64_t context_id; /**< Nonzero identity binding every handle to this workspace instance. */
    uint64_t context_fingerprint; /**< Deterministic fingerprint of precision, range, rounding and slot count. */
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_precision_context_t;
  • math_engine_precision_context_t.struct_size

    Exact byte size of this context adapter. 

    uint32_t struct_size;
  • math_engine_precision_context_t.struct_version

    MATH_ENGINE_PRECISION_CONTEXT_VERSION_1. 

    uint32_t struct_version;
  • math_engine_precision_context_t.workspace

    Non-null caller-owned writable storage whose size is the initialized byte count. Data remains alive, exclusive and unmoved for the complete context lifetime. 

    /**
     * Non-null caller-owned writable storage whose =size= is the initialized byte count.
     * Data remains alive, exclusive and unmoved for the complete context lifetime.
     */
    math_engine_mutable_byte_span_t workspace;
  • math_engine_precision_context_t.context_id

    Nonzero identity binding every handle to this workspace instance. 

    uint64_t context_id;
  • math_engine_precision_context_t.context_fingerprint

    Deterministic fingerprint of precision, range, rounding and slot count. 

    uint64_t context_fingerprint;
  • math_engine_precision_context_t.reserved

    Reserved words; both elements must be 0. 

    uint64_t reserved[2];

math_engine_precision_decimal_t

Context slot을 식별하는 pointer-free opaque value handle이다. 

typedef struct math_engine_precision_decimal {
    uint64_t context_id; /**< Must equal the owning live context's nonzero identity. */
    uint32_t slot; /**< Zero-based slot index below the context's =max_values=. */
    uint32_t generation; /**< Reuse generation that rejects released or stale handles. */
} math_engine_precision_decimal_t;
  • math_engine_precision_decimal_t.context_id

    Must equal the owning live context's nonzero identity. 

    uint64_t context_id;
  • math_engine_precision_decimal_t.slot

    Zero-based slot index below the context's max_values. 

    uint32_t slot;
  • math_engine_precision_decimal_t.generation

    Reuse generation that rejects released or stale handles. 

    uint32_t generation;

math_engine_precision_result_t

연산 정밀도, 반올림, 비용과 재현 fingerprint를 기록하는 결과다. 

typedef struct math_engine_precision_result {
    uint32_t struct_size; /**< Exact byte size supplied by the caller. */
    uint32_t struct_version; /**< =MATH_ENGINE_PRECISION_RESULT_VERSION_1=. */
    uint32_t operation; /**< One =math_engine_precision_operation_t= that produced the value. */
    uint32_t rounding; /**< Decimal rounding policy copied from the owning context. */
    uint32_t flags; /**< Bitwise OR of =MATH_ENGINE_PRECISION_RESULT_FLAG_*= diagnostics. */
    uint32_t requested_precision_bits; /**< Context binary precision used for the operation. */
    uint32_t effective_decimal_digits; /**< Decimal coefficient digit capacity derived from precision bits. */
    int32_t result_exponent; /**< Stored base-10 exponent of the least-significant coefficient digit. */
    uint64_t discarded_decimal_digits; /**< Count of exact trailing digits removed by precision rounding. */
    uint64_t work_units; /**< Deterministic algorithm-specific elementary-work count. */
    uint64_t operation_fingerprint; /**< FNV identity of operation, policy, operands and committed result. */
    uint64_t reserved[2]; /**< Reserved words; written as 0. */
} math_engine_precision_result_t;
  • math_engine_precision_result_t.struct_size

    Exact byte size supplied by the caller. 

    uint32_t struct_size;
  • math_engine_precision_result_t.struct_version

    MATH_ENGINE_PRECISION_RESULT_VERSION_1. 

    uint32_t struct_version;
  • math_engine_precision_result_t.operation

    One math_engine_precision_operation_t that produced the value. 

    uint32_t operation;
  • math_engine_precision_result_t.rounding

    Decimal rounding policy copied from the owning context. 

    uint32_t rounding;
  • math_engine_precision_result_t.flags

    Bitwise OR of MATH_ENGINE_PRECISION_RESULT_FLAG_* diagnostics. 

    uint32_t flags;
  • math_engine_precision_result_t.requested_precision_bits

    Context binary precision used for the operation. 

    uint32_t requested_precision_bits;
  • math_engine_precision_result_t.effective_decimal_digits

    Decimal coefficient digit capacity derived from precision bits. 

    uint32_t effective_decimal_digits;
  • math_engine_precision_result_t.result_exponent

    Stored base-10 exponent of the least-significant coefficient digit. 

    int32_t result_exponent;
  • math_engine_precision_result_t.discarded_decimal_digits

    Count of exact trailing digits removed by precision rounding. 

    uint64_t discarded_decimal_digits;
  • math_engine_precision_result_t.work_units

    Deterministic algorithm-specific elementary-work count. 

    uint64_t work_units;
  • math_engine_precision_result_t.operation_fingerprint

    FNV identity of operation, policy, operands and committed result. 

    uint64_t operation_fingerprint;
  • math_engine_precision_result_t.reserved

    Reserved words; written as 0. 

    uint64_t reserved[2];

math_engine_precision_escalation_request_t

Binary 결과를 재계산할지 판단하는 명시적 승격 요청이다. 

typedef struct math_engine_precision_escalation_request {
    uint32_t struct_size; /**< Exact byte size of this escalation request. */
    uint32_t struct_version; /**< =MATH_ENGINE_PRECISION_ESCALATION_REQUEST_VERSION_1=. */
    uint32_t mode; /**< =MATH_ENGINE_MODE_PC_PRECISION= or =MATH_ENGINE_MODE_FULL=. */
    uint32_t initial_precision_bits; /**< Positive precision of the original binary calculation. */
    uint32_t requested_precision_bits; /**< Explicit target bits; 0 means no direct user target. */
    uint32_t cancellation_bits; /**< Lost-significance estimate in bits; 0 means no cancellation trigger. */
    uint32_t max_values; /**< Planned context slot count in inclusive [1, 64]. */
    uint32_t flags; /**< Reserved request policy bits; version 1 requires 0. */
    double observed_error_bound; /**< Finite nonnegative error bound from the initial calculation. */
    double target_error_bound; /**< Finite nonnegative acceptable bound; 0 disables this trigger. */
    uint64_t memory_budget_bytes; /**< Maximum bytes available to the planned decimal context. */
    uint64_t reserved; /**< Reserved for ABI growth; must be 0. */
} math_engine_precision_escalation_request_t;
  • math_engine_precision_escalation_request_t.struct_size

    Exact byte size of this escalation request. 

    uint32_t struct_size;
  • math_engine_precision_escalation_request_t.struct_version

    MATH_ENGINE_PRECISION_ESCALATION_REQUEST_VERSION_1. 

    uint32_t struct_version;
  • math_engine_precision_escalation_request_t.mode

    MATH_ENGINE_MODE_PC_PRECISION or MATH_ENGINE_MODE_FULL. 

    uint32_t mode;
  • math_engine_precision_escalation_request_t.initial_precision_bits

    Positive precision of the original binary calculation. 

    uint32_t initial_precision_bits;
  • math_engine_precision_escalation_request_t.requested_precision_bits

    Explicit target bits; 0 means no direct user target. 

    uint32_t requested_precision_bits;
  • math_engine_precision_escalation_request_t.cancellation_bits

    Lost-significance estimate in bits; 0 means no cancellation trigger. 

    uint32_t cancellation_bits;
  • math_engine_precision_escalation_request_t.max_values

    Planned context slot count in inclusive [1, 64]. 

    uint32_t max_values;
  • math_engine_precision_escalation_request_t.flags

    Reserved request policy bits; version 1 requires 0. 

    uint32_t flags;
  • math_engine_precision_escalation_request_t.observed_error_bound

    Finite nonnegative error bound from the initial calculation. 

    double observed_error_bound;
  • math_engine_precision_escalation_request_t.target_error_bound

    Finite nonnegative acceptable bound; 0 disables this trigger. 

    double target_error_bound;
  • math_engine_precision_escalation_request_t.memory_budget_bytes

    Maximum bytes available to the planned decimal context. 

    uint64_t memory_budget_bytes;
  • math_engine_precision_escalation_request_t.reserved

    Reserved for ABI growth; must be 0. 

    uint64_t reserved;

math_engine_precision_escalation_trace_t

승격 가능 여부, 최종 정밀도, workspace와 판정 fingerprint를 기록한다. 

typedef struct math_engine_precision_escalation_trace {
    uint32_t struct_size; /**< Exact byte size supplied by the caller. */
    uint32_t struct_version; /**< =MATH_ENGINE_PRECISION_ESCALATION_TRACE_VERSION_1=. */
    int32_t execution_status; /**< Planned execution status; planning itself may still return OK. */
    uint32_t escalation_reason; /**< Dominant =math_engine_precision_escalation_reason_t=. */
    uint32_t initial_precision_bits; /**< Input precision copied from the request. */
    uint32_t final_precision_bits; /**< Selected precision after all triggers and bounds. */
    uint32_t effective_decimal_digits; /**< Decimal digit capacity at =final_precision_bits=. */
    uint32_t flags; /**< Bitwise =MATH_ENGINE_PRECISION_ESCALATION_FLAG_*= diagnostics. */
    double observed_error_bound; /**< Finite nonnegative observed bound copied from the request. */
    double target_error_bound; /**< Finite nonnegative target bound copied from the request. */
    uint64_t required_workspace_bytes; /**< Planned context byte requirement; 0 when no escalation is needed. */
    uint64_t memory_budget_bytes; /**< Available byte budget copied from the request. */
    uint64_t trace_fingerprint; /**< Deterministic FNV identity of decision inputs and outcome. */
    uint64_t reserved[2]; /**< Reserved words; written as 0. */
} math_engine_precision_escalation_trace_t;
  • math_engine_precision_escalation_trace_t.struct_size

    Exact byte size supplied by the caller. 

    uint32_t struct_size;
  • math_engine_precision_escalation_trace_t.struct_version

    MATH_ENGINE_PRECISION_ESCALATION_TRACE_VERSION_1. 

    uint32_t struct_version;
  • math_engine_precision_escalation_trace_t.execution_status

    Planned execution status; planning itself may still return OK. 

    int32_t execution_status;
  • math_engine_precision_escalation_trace_t.escalation_reason

    Dominant math_engine_precision_escalation_reason_t. 

    uint32_t escalation_reason;
  • math_engine_precision_escalation_trace_t.initial_precision_bits

    Input precision copied from the request. 

    uint32_t initial_precision_bits;
  • math_engine_precision_escalation_trace_t.final_precision_bits

    Selected precision after all triggers and bounds. 

    uint32_t final_precision_bits;
  • math_engine_precision_escalation_trace_t.effective_decimal_digits

    Decimal digit capacity at final_precision_bits. 

    uint32_t effective_decimal_digits;
  • math_engine_precision_escalation_trace_t.flags

    Bitwise MATH_ENGINE_PRECISION_ESCALATION_FLAG_* diagnostics. 

    uint32_t flags;
  • math_engine_precision_escalation_trace_t.observed_error_bound

    Finite nonnegative observed bound copied from the request. 

    double observed_error_bound;
  • math_engine_precision_escalation_trace_t.target_error_bound

    Finite nonnegative target bound copied from the request. 

    double target_error_bound;
  • math_engine_precision_escalation_trace_t.required_workspace_bytes

    Planned context byte requirement; 0 when no escalation is needed. 

    uint64_t required_workspace_bytes;
  • math_engine_precision_escalation_trace_t.memory_budget_bytes

    Available byte budget copied from the request. 

    uint64_t memory_budget_bytes;
  • math_engine_precision_escalation_trace_t.trace_fingerprint

    Deterministic FNV identity of decision inputs and outcome. 

    uint64_t trace_fingerprint;
  • math_engine_precision_escalation_trace_t.reserved

    Reserved words; written as 0. 

    uint64_t reserved[2];

Macro와 constant

MATH_ENGINE_PRECISION_BACKEND_INFO_VERSION_1

Initial layout version for math_engine_precision_backend_info_t. 

#define MATH_ENGINE_PRECISION_BACKEND_INFO_VERSION_1 UINT32_C(1)

MATH_ENGINE_PRECISION_CONTEXT_CONFIG_VERSION_1

Initial layout version for math_engine_precision_context_config_t. 

#define MATH_ENGINE_PRECISION_CONTEXT_CONFIG_VERSION_1 UINT32_C(1)

MATH_ENGINE_PRECISION_CONTEXT_VERSION_1

Initial layout version for math_engine_precision_context_t. 

#define MATH_ENGINE_PRECISION_CONTEXT_VERSION_1 UINT32_C(1)

MATH_ENGINE_PRECISION_ESCALATION_FLAG_DETERMINISTIC

Escalation decision and trace fingerprint are deterministic. 

#define MATH_ENGINE_PRECISION_ESCALATION_FLAG_DETERMINISTIC (UINT32_C(1) << 1u)

MATH_ENGINE_PRECISION_ESCALATION_FLAG_ESCALATED

Escalation planning selected a final precision above the initial precision. 

#define MATH_ENGINE_PRECISION_ESCALATION_FLAG_ESCALATED (UINT32_C(1) << 0u)

MATH_ENGINE_PRECISION_ESCALATION_REQUEST_VERSION_1

Initial layout version for math_engine_precision_escalation_request_t. 

#define MATH_ENGINE_PRECISION_ESCALATION_REQUEST_VERSION_1 UINT32_C(1)

MATH_ENGINE_PRECISION_ESCALATION_TRACE_VERSION_1

Initial layout version for math_engine_precision_escalation_trace_t. 

#define MATH_ENGINE_PRECISION_ESCALATION_TRACE_VERSION_1 UINT32_C(1)

MATH_ENGINE_PRECISION_EXPONENT_MAX

Inclusive maximum supported scientific decimal exponent. 

#define MATH_ENGINE_PRECISION_EXPONENT_MAX INT32_C(1024)

MATH_ENGINE_PRECISION_EXPONENT_MIN

Inclusive minimum supported scientific decimal exponent. 

#define MATH_ENGINE_PRECISION_EXPONENT_MIN INT32_C(-1024)

MATH_ENGINE_PRECISION_MAX_BITS

Inclusive maximum supported binary precision, in bits. 

#define MATH_ENGINE_PRECISION_MAX_BITS UINT32_C(4096)

MATH_ENGINE_PRECISION_MIN_BITS

Inclusive minimum supported binary precision, in bits. 

#define MATH_ENGINE_PRECISION_MIN_BITS UINT32_C(64)

MATH_ENGINE_PRECISION_RESULT_FLAG_DETERMINISTIC

Identical context and operands produce the same value and fingerprint. 

#define MATH_ENGINE_PRECISION_RESULT_FLAG_DETERMINISTIC (UINT32_C(1) << 3u)

MATH_ENGINE_PRECISION_RESULT_FLAG_EXACT

Result coefficient and exponent are exact; no decimal digit was discarded. 

#define MATH_ENGINE_PRECISION_RESULT_FLAG_EXACT (UINT32_C(1) << 0u)

MATH_ENGINE_PRECISION_RESULT_FLAG_INEXACT

One or more decimal digits were discarded, so the committed value is inexact. 

#define MATH_ENGINE_PRECISION_RESULT_FLAG_INEXACT (UINT32_C(1) << 1u)

MATH_ENGINE_PRECISION_RESULT_FLAG_ROUNDED

Configured decimal rounding changed or truncated the exact intermediate. 

#define MATH_ENGINE_PRECISION_RESULT_FLAG_ROUNDED (UINT32_C(1) << 2u)

MATH_ENGINE_PRECISION_RESULT_VERSION_1

Initial layout version for math_engine_precision_result_t. 

#define MATH_ENGINE_PRECISION_RESULT_VERSION_1 UINT32_C(1)

Function

math_engine_precision_backend_info_get

연결된 가변 정밀도 backend 설명을 조회한다.

  • 매개변수 out_info: 호출자가 size/version을 초기화한 결과.
  • 반환: 성공하면 OK, 포인터는 INVALID_ARGUMENT, 크기는 INVALID_SIZE, 버전은 UNSUPPORTED.

@note 실패하면 out_info 를 변경하지 않는다.

  • 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_precision_backend_info_get(
    math_engine_precision_backend_info_t* out_info);

math_engine_precision_workspace_size

Config를 검증하고 context에 필요한 workspace 크기를 계산한다.

  • 매개변수 config: 읽기 전용 context 설정.
  • 매개변수 out_size: 호출자 소유 필요 크기. 단위는 byte.
  • 반환: 성공하면 OK, 잘못된 설정은 INVALID_ARGUMENT, 버전은 UNSUPPORTED.

@note 실패하면 out_size 를 변경하지 않는다.

  • Math Engine ownership: config=caller
  • Math Engine ownership: out_size=caller
  • Math Engine nullable: config=false
  • Math Engine nullable: out_size=false
  • Math Engine thread_safety: safe
MATH_ENGINE_API math_engine_status_t math_engine_precision_workspace_size(
    const math_engine_precision_context_config_t* config,
    uint64_t* out_size);

math_engine_precision_context_init

Caller workspace 위에 가변 정밀도 context를 초기화한다.

  • 매개변수 config: 검증된 설정.
  • 매개변수 workspace: context lifetime 동안 caller가 유지할 writable byte span.
  • 매개변수 out_context: 호출자가 size/version을 초기화한 context.
  • 반환: 성공하면 OK, 작은 workspace는 INSUFFICIENT_WORKSPACE, 작은 memory budget은 BUDGET_EXHAUSTED.

@note 실패하면 workspace와 out_context 를 변경하지 않는다. 같은 workspace를 동시에 다른 context에 제공하면 안 된다.

  • Math Engine ownership: config=caller
  • Math Engine ownership: workspace=caller
  • Math Engine ownership: out_context=caller
  • Math Engine nullable: config=false
  • Math Engine nullable: workspace.data=false
  • Math Engine nullable: out_context=false
  • Math Engine thread_safety: separate_contexts
MATH_ENGINE_API math_engine_status_t math_engine_precision_context_init(
    const math_engine_precision_context_config_t* config,
    math_engine_mutable_byte_span_t workspace,
    math_engine_precision_context_t* out_context);

math_engine_precision_context_validate

Context adapter와 workspace header의 일치를 검증한다.

  • 매개변수 context: 검사할 읽기 전용 context.
  • 반환: 유효하면 OK, 크기는 INVALID_SIZE, 버전은 UNSUPPORTED, 나머지 위반은 INVALID_ARGUMENT.
  • Math Engine ownership: context=caller
  • Math Engine nullable: context=false
  • Math Engine thread_safety: separate_contexts
MATH_ENGINE_API math_engine_status_t math_engine_precision_context_validate(
    const math_engine_precision_context_t* context);

math_engine_precision_value_acquire

Context에서 값 slot 하나를 획득하고 0으로 초기화한다.

  • 매개변수 context: 변경할 context.
  • 매개변수 out_value: 호출자 소유 opaque handle.
  • 반환: 성공하면 OK, 빈 slot이 없으면 INSUFFICIENT_WORKSPACE.

@note 실패하면 out_value 를 변경하지 않는다.

  • Math Engine ownership: context=caller
  • Math Engine ownership: out_value=caller
  • Math Engine nullable: context=false
  • Math Engine nullable: out_value=false
  • Math Engine thread_safety: external_synchronization
MATH_ENGINE_API math_engine_status_t math_engine_precision_value_acquire(
    math_engine_precision_context_t* context,
    math_engine_precision_decimal_t* out_value);

math_engine_precision_value_release

값 slot을 해제하고 이전 handle을 무효화한다.

  • 매개변수 context: 값을 소유한 context.
  • 매개변수 value: 해제할 handle.
  • 반환: 성공하면 OK, 다른 context나 stale handle이면 INVALID_ARGUMENT.
  • Math Engine ownership: context=caller
  • Math Engine nullable: context=false
  • Math Engine thread_safety: external_synchronization
MATH_ENGINE_API math_engine_status_t math_engine_precision_value_release(
    math_engine_precision_context_t* context,
    math_engine_precision_decimal_t value);

math_engine_precision_decimal_parse

부호, 소수점과 선택적 10진 지수를 가진 strict ASCII를 값에 저장한다.

  • 매개변수 context: 값을 소유한 context.
  • 매개변수 text: 길이가 text_size 인 읽기 전용 ASCII. NUL 종료는 요구하지 않는다.
  • 매개변수 text_size: 입력 크기. 단위는 byte.
  • 매개변수 out_value: 이미 획득한 결과 handle.
  • 매개변수 out_result: 호출자가 size/version을 초기화한 감사 결과.
  • 반환: 성공하면 OK, 문법은 INVALID_ARGUMENT, 지수는 OUT_OF_RANGE, 정밀도·반올림으로 표현할 수 없으면 OVERFLOW.

@note 성공 시에만 값과 결과를 함께 commit한다.

  • Math Engine ownership: context=caller
  • Math Engine ownership: text=caller
  • Math Engine ownership: out_result=caller
  • Math Engine nullable: context=false
  • Math Engine nullable: text=false
  • Math Engine nullable: out_result=false
  • Math Engine thread_safety: external_synchronization
MATH_ENGINE_API math_engine_status_t math_engine_precision_decimal_parse(
    math_engine_precision_context_t* context,
    const char* text,
    uint64_t text_size,
    math_engine_precision_decimal_t out_value,
    math_engine_precision_result_t* out_result);

math_engine_precision_decimal_format

저장 값을 scientific 또는 fixed ASCII로 출력한다.

  • 매개변수 context: 값을 소유한 context.
  • 매개변수 value: 출력할 handle.
  • 매개변수 format: 출력 형식.
  • 매개변수 buffer: caller-owned 출력 버퍼. capacity 0에서만 null 가능.
  • 매개변수 capacity: 버퍼 크기. 단위는 byte이며 NUL 공간을 포함한다.
  • 매개변수 out_size: 필요 문자열 길이. 단위는 byte이며 NUL은 제외한다.
  • 반환: 성공하면 OK, 작은 버퍼는 INSUFFICIENT_BUFFER.

@note 작은 버퍼에서도 out_size 만 갱신하고 buffer는 보존한다.

  • Math Engine ownership: context=caller
  • Math Engine ownership: buffer=caller
  • Math Engine ownership: out_size=caller
  • Math Engine nullable: context=false
  • Math Engine nullable: buffer=capacity_zero_only
  • Math Engine nullable: out_size=false
  • Math Engine thread_safety: external_synchronization
MATH_ENGINE_API math_engine_status_t math_engine_precision_decimal_format(
    const math_engine_precision_context_t* context,
    math_engine_precision_decimal_t value,
    math_engine_precision_text_format_t format,
    char* buffer,
    uint64_t capacity,
    uint64_t* out_size);

math_engine_precision_decimal_compare

Context 안의 두 값을 정확히 비교한다.

  • 매개변수 context: 두 값을 소유한 context.
  • 매개변수 lhs: 왼쪽 handle.
  • 매개변수 rhs: 오른쪽 handle.
  • 매개변수 out_order: lhs가 작으면 -1, 같으면 0, 크면 1.
  • 반환: 성공하면 OK, context 또는 handle이 잘못되면 INVALID_ARGUMENT.

@note 실패하면 out_order 를 변경하지 않는다.

  • Math Engine ownership: context=caller
  • Math Engine ownership: out_order=caller
  • Math Engine nullable: context=false
  • Math Engine nullable: out_order=false
  • Math Engine thread_safety: external_synchronization
MATH_ENGINE_API math_engine_status_t math_engine_precision_decimal_compare(
    const math_engine_precision_context_t* context,
    math_engine_precision_decimal_t lhs,
    math_engine_precision_decimal_t rhs,
    int32_t* out_order);

math_engine_precision_decimal_add

두 값을 정확히 정렬해 더한 뒤 context 정밀도로 한 번만 반올림한다.

  • 매개변수 context: 모든 handle을 소유한 context.
  • 매개변수 lhs: 왼쪽 입력 handle.
  • 매개변수 rhs: 오른쪽 입력 handle.
  • 매개변수 out_value: 이미 획득한 결과 handle. 입력 handle과 같아도 된다.
  • 매개변수 out_result: 호출자가 size/version을 초기화한 감사 결과.
  • 반환: 성공하면 OK, 잘못된 context·handle은 INVALID_ARGUMENT, 지수는 OUT_OF_RANGE.

@note 성공 시에만 out_value 와 out_result 를 함께 commit한다.

  • Math Engine ownership: context=caller
  • Math Engine ownership: out_result=caller
  • Math Engine nullable: context=false
  • Math Engine nullable: out_result=false
  • Math Engine thread_safety: external_synchronization
MATH_ENGINE_API math_engine_status_t math_engine_precision_decimal_add(
    math_engine_precision_context_t* context,
    math_engine_precision_decimal_t lhs,
    math_engine_precision_decimal_t rhs,
    math_engine_precision_decimal_t out_value,
    math_engine_precision_result_t* out_result);

math_engine_precision_decimal_subtract

두 값을 정확히 정렬해 뺀 뒤 context 정밀도로 한 번만 반올림한다.

  • 매개변수 context: 모든 handle을 소유한 context.
  • 매개변수 lhs: 왼쪽 입력 handle.
  • 매개변수 rhs: 오른쪽 입력 handle.
  • 매개변수 out_value: 이미 획득한 결과 handle. 입력 handle과 같아도 된다.
  • 매개변수 out_result: 호출자가 size/version을 초기화한 감사 결과.
  • 반환: 성공하면 OK, 잘못된 context·handle은 INVALID_ARGUMENT, 지수는 OUT_OF_RANGE.

@note 성공 시에만 out_value 와 out_result 를 함께 commit한다.

  • Math Engine ownership: context=caller
  • Math Engine ownership: out_result=caller
  • Math Engine nullable: context=false
  • Math Engine nullable: out_result=false
  • Math Engine thread_safety: external_synchronization
MATH_ENGINE_API math_engine_status_t math_engine_precision_decimal_subtract(
    math_engine_precision_context_t* context,
    math_engine_precision_decimal_t lhs,
    math_engine_precision_decimal_t rhs,
    math_engine_precision_decimal_t out_value,
    math_engine_precision_result_t* out_result);

math_engine_precision_decimal_multiply

10진 계수를 정확히 곱한 뒤 context 정밀도로 한 번만 반올림한다.

  • 매개변수 context: 모든 handle을 소유한 context.
  • 매개변수 lhs: 왼쪽 입력 handle.
  • 매개변수 rhs: 오른쪽 입력 handle.
  • 매개변수 out_value: 이미 획득한 결과 handle. 입력 handle과 같아도 된다.
  • 매개변수 out_result: 호출자가 size/version을 초기화한 감사 결과.
  • 반환: 성공하면 OK, scratch 범위는 OVERFLOW, 결과 지수는 OUT_OF_RANGE.

@note 성공 시에만 out_value 와 out_result 를 함께 commit한다.

  • Math Engine ownership: context=caller
  • Math Engine ownership: out_result=caller
  • Math Engine nullable: context=false
  • Math Engine nullable: out_result=false
  • Math Engine thread_safety: external_synchronization
MATH_ENGINE_API math_engine_status_t math_engine_precision_decimal_multiply(
    math_engine_precision_context_t* context,
    math_engine_precision_decimal_t lhs,
    math_engine_precision_decimal_t rhs,
    math_engine_precision_decimal_t out_value,
    math_engine_precision_result_t* out_result);

math_engine_precision_decimal_divide

정확한 정수 long division으로 나눈 뒤 context 정밀도에서 반올림한다.

  • 매개변수 context: 모든 handle을 소유한 context.
  • 매개변수 lhs: 분자 handle.
  • 매개변수 rhs: 분모 handle.
  • 매개변수 out_value: 이미 획득한 결과 handle. 입력 handle과 같아도 된다.
  • 매개변수 out_result: 호출자가 size/version을 초기화한 감사 결과.
  • 반환: 성공하면 OK, 분모 0은 DIVIDE_BY_ZERO, 결과 지수는 OUT_OF_RANGE.

@note 성공 시에만 out_value 와 out_result 를 함께 commit한다.

  • Math Engine ownership: context=caller
  • Math Engine ownership: out_result=caller
  • Math Engine nullable: context=false
  • Math Engine nullable: out_result=false
  • Math Engine thread_safety: external_synchronization
MATH_ENGINE_API math_engine_status_t math_engine_precision_decimal_divide(
    math_engine_precision_context_t* context,
    math_engine_precision_decimal_t lhs,
    math_engine_precision_decimal_t rhs,
    math_engine_precision_decimal_t out_value,
    math_engine_precision_result_t* out_result);

math_engine_precision_escalation_plan

Error bound, cancellation, 요청 정밀도와 memory budget으로 재계산을 계획한다.

  • 매개변수 request: 호출자가 초기화한 승격 입력.
  • 매개변수 capabilities: 실제 linked artifact capability.
  • 매개변수 out_trace: 호출자가 size/version을 초기화한 판정 결과.
  • 반환: 입력 ABI가 유효하면 OK. 실행 가능 여부는 out_trace.execution_status 에 기록한다.

@note Finance money의 backend 선택은 이 함수가 아니라 fixed decimal mode 계약이 소유한다.

  • Math Engine ownership: request=caller
  • Math Engine ownership: capabilities=caller
  • Math Engine ownership: out_trace=caller
  • Math Engine nullable: request=false
  • Math Engine nullable: capabilities=false
  • Math Engine nullable: out_trace=false
  • Math Engine thread_safety: safe
MATH_ENGINE_API math_engine_status_t math_engine_precision_escalation_plan(
    const math_engine_precision_escalation_request_t* request,
    const math_engine_capability_descriptor_t* capabilities,
    math_engine_precision_escalation_trace_t* out_trace);