Math Engine Reference: Rng

Uniform floating sample에서 하한과 상한의 포함 여부를 선택한다.

typedef enum math_engine_rng_float_interval {
    MATH_ENGINE_RNG_INTERVAL_INVALID = 0, /**< 유효 endpoint 정책이 없는 zero/sentinel 값이다. */
    MATH_ENGINE_RNG_INTERVAL_CLOSED_OPEN = 1, /**< 정규화한 bound의 반열린 범위 =[min,max)=를 생성한다. */
    MATH_ENGINE_RNG_INTERVAL_OPEN_OPEN = 2, /**< 양 endpoint를 제외한 열린 범위 =(min,max)=를 생성한다. */
    MATH_ENGINE_RNG_INTERVAL_OPEN_CLOSED = 3, /**< 하한을 제외하고 상한을 포함하는 =(min,max]= 범위다. */
    MATH_ENGINE_RNG_INTERVAL_CLOSED_CLOSED = 4 /**< 양 endpoint를 포함하는 닫힌 범위 =[min,max]=다. */
} math_engine_rng_float_interval_t;

Bounded distribution request가 선택할 수 있는 sample 종류다.

typedef enum math_engine_rng_distribution_kind {
    MATH_ENGINE_RNG_DISTRIBUTION_INVALID = 0, /**< Sample distribution이 지정되지 않은 sentinel이다. */
    MATH_ENGINE_RNG_DISTRIBUTION_UNIFORM_F64 = 1, /**< =parameters[0:2]= bound 사이의 [min,max) binary64 sample이다. */
    MATH_ENGINE_RNG_DISTRIBUTION_NORMAL_F64 = 2, /**< =parameters=(mean,stddev,ignored)=인 Gaussian binary64 sample이다. */
    MATH_ENGINE_RNG_DISTRIBUTION_EXPONENTIAL_F64 = 3, /**< Positive rate =parameters[0]=의 exponential binary64 sample이다. */
    MATH_ENGINE_RNG_DISTRIBUTION_TRIANGULAR_F64 = 4, /**< 두 bound와 그 사이 mode를 쓰는 triangular binary64 sample이다. */
    MATH_ENGINE_RNG_DISTRIBUTION_BERNOULLI = 5, /**< =[0,1]= probability로 0 또는 1을 생성한다. */
    MATH_ENGINE_RNG_DISTRIBUTION_POISSON_U32 = 6 /**< =(0,64]= lambda의 nonnegative Poisson integer를 생성한다. */
} math_engine_rng_distribution_kind_t;

안정된 algorithm identity다. Field 의미를 바꾸려면 새 algorithm version이 필요하다.

typedef struct math_engine_rng_algorithm_info {
    uint32_t struct_size; /**< Caller가 exact info byte 크기로 미리 설정하고 library가 같은 값을 기록한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_RNG_ALGORITHM_INFO_VERSION_1=이어야 한다. */
    uint32_t algorithm_id; /**< =MATH_ENGINE_RNG_ALGORITHM_PCG32_XSH_RR_64_32= stable ID다. */
    uint32_t algorithm_version; /**< PCG32 sequence/output semantics version 1이다. */
    uint32_t state_size_bytes; /**< Caller-owned =math_engine_rng_t= storage의 exact byte 크기다. */
    uint32_t snapshot_wire_size_bytes; /**< Snapshot wire capacity 요구값 40 byte다. */
    uint32_t flags; /**< Caller-owned/deterministic/stable/non-cryptographic info bit의 OR다. */
    uint32_t reserved32; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 slot이다. */
    uint64_t multiplier; /**< LCG transition에 쓰는 고정 multiplier =6364136223846793005=다. */
    uint64_t default_stream_id; /**< =math_engine_rng_init=이 선택하는 unsigned stream ID 1이다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 word다. */
} math_engine_rng_algorithm_info_t;

Pointer-free process snapshot이다. 저장·전송에는 encode/decode wire format을 사용한다.

typedef struct math_engine_rng_snapshot {
    uint32_t struct_size; /**< Exact snapshot POD byte 크기 =sizeof(math_engine_rng_snapshot_t)=다. */
    uint32_t struct_version; /**< =MATH_ENGINE_RNG_SNAPSHOT_VERSION_1=이어야 한다. */
    uint32_t algorithm_id; /**< Snapshot state를 해석할 PCG32 stable algorithm ID 1이다. */
    uint32_t algorithm_version; /**< Snapshot sequence semantics를 고정하는 algorithm version 1이다. */
    uint64_t state; /**< 다음 output을 결정하는 unsigned 64-bit PCG LCG state다. */
    uint64_t increment; /**< Stream selector에서 만든 odd LCG increment; even 값은 invalid다. */
    uint64_t reserved[2]; /**< Producer는 0으로 쓰고 restore/encode validator가 nonzero를 거부한다. */
} math_engine_rng_snapshot_t;

Bounded RNG operation이 다음 작업 전에 동기적으로 호출하는 cancellation callback이다.

• 매개변수 user_data: 호출자가 전달한 borrowed context.
• 반환: 0이면 계속하고 0이 아니면 MATH_ENGINE_STATUS_CANCELLED 로 중단한다.
• Math Engine ownership: user_data=borrowed
• Math Engine nullable: user_data=true
• Math Engine thread_safety: caller_serialized
• Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

Distribution draw 또는 shuffle step 전에 caller thread에서 호출되며 library는 callback이나 user_data 를 보관하지 않는다. C++ exception은 C ABI 경계를 넘어서는 안 된다.

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

Distribution kind별 parameter, draw budget와 동기 cancellation을 담는 versioned request다.

typedef struct math_engine_rng_distribution_request {
    uint32_t struct_size; /**< Exact request byte 크기 =sizeof(math_engine_rng_distribution_request_t)=다. */
    uint32_t struct_version; /**< =MATH_ENGINE_RNG_DISTRIBUTION_REQUEST_VERSION_1=이어야 한다. */
    uint32_t distribution_kind; /**< 수행할 non-INVALID =math_engine_rng_distribution_kind_t= 값이다. */
    uint32_t flags; /**< V1 request에는 정의된 bit가 없어 반드시 0이다. */
    double parameters[3]; /**< Kind별 finite tuple: uniform bounds, normal mean/stddev, rate, triangular bounds/mode, p 또는 lambda다. */
    uint64_t iteration_budget; /**< 허용 random draw 수; 0이면 non-degenerate 요청은 draw 전에 BUDGET_EXHAUSTED다. */
    math_engine_rng_cancel_fn cancel; /**< Nullable borrowed 동기 callback; sample 호출 동안 유효하고 보관되지 않는다. */
    void* cancel_user_data; /**< Nullable caller-owned opaque state; 각 cancel 호출 동안 borrowed되며 cancel이 NULL이면 무시된다. */
    uint64_t reserved[4]; /**< Caller가 0으로 두어야 하고 V1 request validator가 검사하는 ABI 확장 word다. */
} math_engine_rng_distribution_request_t;

성공 시 RNG state와 함께 commit되는 auditable distribution result다.

typedef struct math_engine_rng_distribution_result {
    uint32_t struct_size; /**< Caller가 exact result byte 크기로 미리 설정한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_RNG_DISTRIBUTION_RESULT_VERSION_1=이어야 한다. */
    uint32_t distribution_kind; /**< 완료된 request와 같은 distribution kind다. */
    uint32_t flags; /**< Deterministic/budget와 선택적 bound-swap/integer result bit의 OR다. */
    uint64_t iterations; /**< 성공 sample을 만드는 데 실제 소비한 random draw 수다. */
    double value_f64; /**< 모든 kind의 finite numeric 결과; integer kind도 exact-convert 가능한 값을 복제한다. */
    uint64_t value_u64; /**< Bernoulli/Poisson의 canonical integer 결과이며 floating kind에서는 0이다. */
    uint64_t state_fingerprint; /**< 성공 후 commit한 =state/increment=의 결정적 64-bit hash다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 word다. */
} math_engine_rng_distribution_result_t;

복사 가능한 PCG32 state와 stream selector storage다.

math_engine_rng_init 으로 초기화한 뒤 사용한다. POD 복사는 sequence snapshot과 동일하며 두 복사본은 이후 독립적으로 진행한다. Field를 직접 변경한 state의 결과는 계약하지 않는다.

typedef struct math_engine_rng {
    uint64_t state; /**< 다음 PCG32 output과 transition을 결정하는 mutable unsigned LCG state다. */
    uint64_t increment; /**< =(stream_id<<1)|1=인 mutable odd stream increment; even이면 invalid state다. */
} math_engine_rng_t;

Bit 0 (0x01): 모든 mutable RNG state와 output storage를 caller가 소유한다.

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

Bit 1 (0x02): 같은 state와 호출 순서가 같은 bit sequence를 생성한다.

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

Bit 3 (0x08): Algorithm을 암호학적 보안 용도로 사용하면 안 된다.

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

Bit 2 (0x04): Versioned 40-byte snapshot wire replay 계약을 제공한다.

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

math_engine_rng_algorithm_info_t.struct_version 의 최초 unsigned ABI 값 1이다.

#define MATH_ENGINE_RNG_ALGORITHM_INFO_VERSION_1 UINT32_C(1)

PCG32 public short alias이며 수치상 algorithm ID 1과 같다.

#define MATH_ENGINE_RNG_ALGORITHM_PCG32 MATH_ENGINE_RNG_ALGORITHM_PCG32_XSH_RR_64_32

PCG XSH-RR 64-bit state/32-bit output algorithm의 stable unsigned ID 1이다.

#define MATH_ENGINE_RNG_ALGORITHM_PCG32_XSH_RR_64_32 UINT32_C(1)

PCG multiplier, output permutation과 seeding 의미를 고정하는 algorithm version 1이다.

#define MATH_ENGINE_RNG_ALGORITHM_VERSION_PCG32_XSH_RR_64_32 UINT32_C(1)

Distribution request POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_RNG_DISTRIBUTION_REQUEST_VERSION_1 UINT32_C(1)

Distribution result POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_RNG_DISTRIBUTION_RESULT_VERSION_1 UINT32_C(1)

Bit 2 (0x04): Uniform/triangular의 입력 bound 순서를 min/max로 교환했다.

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

Bit 1 (0x02): 모든 random draw 전에 request iteration budget을 적용했다.

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

Bit 0 (0x01): 동일 request와 initial state가 동일 result/state를 만든다.

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

Bit 3 (0x08): Canonical 결과가 value_u64 에 있는 Bernoulli/Poisson 정수다.

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

math_engine_rng_snapshot_t.struct_version 의 최초 unsigned ABI 값 1이다.

#define MATH_ENGINE_RNG_SNAPSHOT_VERSION_1 UINT32_C(1)

Snapshot wire format v1의 고정 byte 크기 40이다.

#define MATH_ENGINE_RNG_SNAPSHOT_WIRE_SIZE UINT64_C(40)

Snapshot wire schema header에 기록하는 최초 unsigned format version 1이다.

#define MATH_ENGINE_RNG_SNAPSHOT_WIRE_VERSION_1 UINT32_C(1)

PCG32 algorithm identity와 snapshot capability를 조회한다.

• 매개변수 out_info: 호출 전에 struct_size 와 struct_version 을 설정하고 info를 받을 output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. NULL·size·version 오류면 해당 status를 반환하고 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_rng_algorithm_info_get(
    math_engine_rng_algorithm_info_t* out_info);

Seed와 stream ID로 caller-owned PCG32 state를 deterministic하게 초기화한다.

• 매개변수 out_rng: 초기화한 state를 받을 caller-owned output.
• 매개변수 seed: 재현 가능한 unsigned 64-bit seed.
• 매개변수 stream_id: 독립 sequence를 선택하는 unsigned 64-bit stream ID.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK, out_rng 이 NULL이면 MATH_ENGINE_STATUS_INVALID_ARGUMENT.
• Math Engine ownership: out_rng=caller
• Math Engine nullable: out_rng=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_init_stream_checked(
    math_engine_rng_t* out_rng, uint64_t seed, uint64_t stream_id);

RNG state의 PCG increment가 유효한 odd 값인지 검증한다.

• 매개변수 rng: 호출 동안만 읽는 RNG state.
• 반환: 유효하면 MATH_ENGINE_STATUS_OK, NULL 또는 even increment면 MATH_ENGINE_STATUS_INVALID_ARGUMENT.
• Math Engine ownership: rng=borrowed
• Math Engine nullable: rng=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rng_validate(
    const math_engine_rng_t* rng);

현재 RNG state를 pointer-free versioned snapshot으로 복사한다.

• 매개변수 rng: 호출 동안만 읽는 유효한 RNG state.
• 매개변수 out_snapshot: 호출 전에 size/version을 설정하고 snapshot을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Invalid state·pointer·overlap·size·version 오류면 해당 status를 반환하고 out_snapshot 을 보존한다.
• Math Engine ownership: rng=borrowed out_snapshot=caller
• Math Engine nullable: rng=false out_snapshot=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_snapshot_get(
    const math_engine_rng_t* rng, math_engine_rng_snapshot_t* out_snapshot);

검증한 snapshot에서 caller-owned RNG state를 복원한다.

• 매개변수 snapshot: 호출 동안만 읽는 version·algorithm·reserved field가 유효한 snapshot.
• 매개변수 out_rng: 복원한 state를 받을 caller-owned output. snapshot 과 겹치면 안 된다.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Snapshot 검증, NULL 또는 overlap 실패 시 해당 status를 반환하고 out_rng 을 보존한다.
• Math Engine ownership: snapshot=borrowed out_rng=caller
• Math Engine nullable: snapshot=false out_rng=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rng_snapshot_restore(
    const math_engine_rng_snapshot_t* snapshot, math_engine_rng_t* out_rng);

Snapshot을 선택 byte order의 고정 40-byte wire format으로 encode한다.

• 매개변수 snapshot: 호출 동안만 읽는 유효한 snapshot.
• 매개변수 byte_order: little-endian 또는 big-endian wire byte order.
• 매개변수 output: caller-owned mutable byte span. size 는 byte capacity다.
• 매개변수 out_size: 성공 시 기록한 byte 수, buffer 부족 시 필요한 byte 수를 받을 output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Capacity가 40 byte보다 작으면 output buffer를 보존하고 out_size 에 40을 쓴 뒤 MATH_ENGINE_STATUS_INSUFFICIENT_BUFFER 를 반환한다. 그 밖의 검증 실패는 buffer와 out_size 를 보존한다.

Snapshot, output byte 범위와 out_size 는 서로 겹치면 안 된다.

• Math Engine ownership: snapshot=borrowed out_size=caller
• Math Engine nullable: snapshot=false out_size=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rng_snapshot_encode(
    const math_engine_rng_snapshot_t* snapshot, math_engine_byte_order_t byte_order,
    math_engine_mutable_byte_span_t output, uint64_t* out_size);

정확한 40-byte wire snapshot을 검증하고 versioned POD로 decode한다.

• 매개변수 input: 호출 동안만 읽는 40-byte snapshot span.
• 매개변수 byte_order: input에 사용된 little-endian 또는 big-endian byte order.
• 매개변수 out_snapshot: 호출 전에 size/version을 설정하고 decode 결과를 받을 output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Size, magic, version, algorithm, state fingerprint, pointer 또는 overlap 검증 실패 시 해당 status를 반환하고 output을 보존한다.
• Math Engine ownership: out_snapshot=caller
• Math Engine nullable: out_snapshot=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rng_snapshot_decode(
    math_engine_const_byte_span_t input, math_engine_byte_order_t byte_order,
    math_engine_rng_snapshot_t* out_snapshot);

RNG state에서 다음 32-bit 값을 failure-atomic하게 생성한다.

• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 out_value: 생성값을 받을 caller-owned output. rng 과 겹치면 안 된다.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. 검증 실패 시 state와 output을 모두 보존한다.
• Math Engine ownership: rng=caller out_value=caller
• Math Engine nullable: rng=false out_value=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_u32_checked(
    math_engine_rng_t* rng, uint32_t* out_value);

연속된 두 32-bit draw로 다음 64-bit 값을 failure-atomic하게 생성한다.

• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 out_value: 생성값을 받을 caller-owned output. rng 과 겹치면 안 된다.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. 검증 실패 시 state와 output을 모두 보존한다.
• Math Engine ownership: rng=caller out_value=caller
• Math Engine nullable: rng=false out_value=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_u64_checked(
    math_engine_rng_t* rng, uint64_t* out_value);

Rejection sampling으로 =[0,exclusive_max)=의 unbiased 32-bit 값을 생성한다.

• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 exclusive_max: 0이 아닌 제외 상한.
• 매개변수 iteration_budget: 이 호출에서 허용하는 최대 candidate draw 수.
• 매개변수 out_value: 생성값을 받을 caller-owned output. rng 과 겹치면 안 된다.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Budget 소진을 포함한 모든 실패에서 state와 output을 보존한다.
• Math Engine ownership: rng=caller out_value=caller
• Math Engine nullable: rng=false out_value=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_range_u32_checked(
    math_engine_rng_t* rng, uint32_t exclusive_max, uint64_t iteration_budget,
    uint32_t* out_value);

Rejection sampling으로 =[0,exclusive_max)=의 unbiased 64-bit 값을 생성한다.

• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 exclusive_max: 0이 아닌 제외 상한.
• 매개변수 iteration_budget: 이 호출에서 허용하는 최대 candidate draw 수.
• 매개변수 out_value: 생성값을 받을 caller-owned output. rng 과 겹치면 안 된다.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Budget 소진을 포함한 모든 실패에서 state와 output을 보존한다.
• Math Engine ownership: rng=caller out_value=caller
• Math Engine nullable: rng=false out_value=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_range_u64_checked(
    math_engine_rng_t* rng, uint64_t exclusive_max, uint64_t iteration_budget,
    uint64_t* out_value);

전체 signed 64-bit 경계를 지원하는 반열린 범위의 unbiased 값을 생성한다.

• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 inclusive_min: 포함 하한.
• 매개변수 exclusive_max: 제외 상한. inclusive_min 보다 커야 한다.
• 매개변수 iteration_budget: 이 호출에서 허용하는 최대 candidate draw 수.
• 매개변수 out_value: 생성값을 받을 caller-owned output. rng 과 겹치면 안 된다.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Budget 소진을 포함한 모든 실패에서 state와 output을 보존한다.
• Math Engine ownership: rng=caller out_value=caller
• Math Engine nullable: rng=false out_value=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_range_i64_checked(
    math_engine_rng_t* rng, int64_t inclusive_min, int64_t exclusive_max,
    uint64_t iteration_budget, int64_t* out_value);

두 finite bound 사이에서 endpoint 정책을 지정한 uniform double을 생성한다.

• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 first_bound: 첫 bound.
• 매개변수 second_bound: 둘째 bound. 더 작으면 두 bound를 정규화해 교환한다.
• 매개변수 interval: closed/open endpoint 조합.
• 매개변수 out_value: 생성값을 받을 caller-owned output. rng 과 겹치면 안 된다.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Bound가 같으면 state를 소비하지 않고 그 값을 쓴다. Non-finite·invalid interval·overflow 등 실패 시 state와 output을 보존한다.
• Math Engine ownership: rng=caller out_value=caller
• Math Engine nullable: rng=false out_value=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_uniform_f64_checked(
    math_engine_rng_t* rng, double first_bound, double second_bound,
    math_engine_rng_float_interval_t interval, double* out_value);

연속된 count 개의 32-bit draw를 caller buffer에 기록한다.

• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 output: 결과를 받을 caller-owned 배열. =count==0=일 때만 NULL일 수 있다.
• 매개변수 capacity: output 의 32-bit 원소 capacity.
• 매개변수 count: 생성할 32-bit 원소 수.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Capacity, byte-size overflow와 RNG/output overlap은 mutation 전에 검사하며 실패 시 state와 output을 보존한다.
• Math Engine ownership: rng=caller output=caller
• Math Engine nullable: rng=false output=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_fill_u32_checked(
    math_engine_rng_t* rng, uint32_t* output, uint64_t capacity,
    uint64_t count);

Bounded Fisher–Yates 방식으로 arbitrary fixed-size 원소 배열을 in-place shuffle한다.

• 매개변수 buffer: caller-owned 배열의 시작 주소. =count==0=일 때만 NULL일 수 있다.
• 매개변수 buffer_size: buffer 의 byte capacity.
• 매개변수 count: shuffle할 원소 수.
• 매개변수 element_size: 0보다 큰 원소 하나의 byte 크기.
• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 iteration_budget: 전체 호출에서 rejection sampling에 허용하는 최대 candidate draw 수.
• 매개변수 cancel: 각 swap step 전에 동기 호출할 optional cancellation callback.
• 매개변수 cancel_user_data: cancel 에 전달하고 호출 뒤 보관하지 않는 borrowed context.
• 매개변수 out_steps_completed: 완료한 Fisher–Yates swap step 수를 받을 caller-owned output.
• 반환: 전체 shuffle을 마치면 MATH_ENGINE_STATUS_OK. Budget 소진 또는 cancellation이면 이미 수행한 swap prefix, 소비한 RNG state와 step 수를 commit하고 해당 status를 반환한다. 검증·capacity·overflow 실패에서는 모든 state와 output을 보존한다.

Required buffer byte 수는 count*element_size 다. Buffer, RNG와 step output의 byte 범위는 서로 겹치면 안 된다. count<2 이면 RNG를 소비하지 않고 step 수 0으로 성공한다.

• Math Engine ownership: buffer=caller rng=caller cancel=borrowed cancel_user_data=borrowed out_steps_completed=caller
• Math Engine nullable: buffer=true rng=false cancel=true cancel_user_data=true out_steps_completed=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_shuffle_checked(
    void* buffer, uint64_t buffer_size, uint64_t count, uint64_t element_size,
    math_engine_rng_t* rng, uint64_t iteration_budget,
    math_engine_rng_cancel_fn cancel, void* cancel_user_data,
    uint64_t* out_steps_completed);

Unsigned 32-bit weight 합에 비례하는 zero-based index를 선택한다.

• 매개변수 weights: 호출 동안만 읽는 count 개 weight 배열. 0 weight는 선택되지 않는다.
• 매개변수 count: 0보다 큰 weights 원소 수.
• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 iteration_budget: rejection sampling에 허용하는 최대 candidate draw 수.
• 매개변수 out_index: 선택한 [0,count) index를 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. 전체 weight가 0이면 MATH_ENGINE_STATUS_DEGENERATE, 합계 overflow면 MATH_ENGINE_STATUS_OVERFLOW 다. Budget과 검증 실패를 포함한 모든 실패에서 RNG와 output을 보존한다.

Weight 배열, RNG와 output의 byte 범위는 서로 겹치면 안 된다.

• Math Engine ownership: weights=borrowed rng=caller out_index=caller
• Math Engine nullable: weights=false rng=false out_index=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_weighted_index_u32_checked(
    const uint32_t* weights, uint64_t count, math_engine_rng_t* rng,
    uint64_t iteration_budget, uint64_t* out_index);

Versioned request에 따라 bounded distribution sample 하나를 생성한다.

• 매개변수 request: 호출 동안만 읽는 distribution kind, parameter, budget와 callback request.
• 매개변수 rng: 변경할 유효한 caller-owned state.
• 매개변수 out_result: 호출 전에 size/version을 설정하고 value·iteration·fingerprint를 받을 output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. 검증, domain, budget, cancellation 또는 overflow 실패 시 RNG와 out_result 를 모두 보존한다.

Parameter는 uniform (bound1,bound2), normal (mean,stddev>=0), exponential (rate>0), triangular (bound1,bound2,mode), Bernoulli (probability in [0,1]), Poisson (lambda in (0,64]) 순서다. iteration_budget 은 최대 random draw 수이며 cancellation callback은 각 draw 전에 동기 호출되고 보관되지 않는다. Request, RNG와 output은 서로 겹치면 안 된다. Deterministic degenerate case는 draw 없이 성공할 수 있다.

• Math Engine ownership: request=borrowed rng=caller out_result=caller
• Math Engine nullable: request=false rng=false out_result=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_rng_distribution_sample(
    const math_engine_rng_distribution_request_t* request,
    math_engine_rng_t* rng,
    math_engine_rng_distribution_result_t* out_result);

Default stream에서 RNG state를 초기화한다.

• 매개변수 rng: 초기화할 caller-owned state. NULL이면 아무 작업도 하지 않는다.
• 매개변수 seed: 재현 가능한 64-bit seed.
• 반환: 반환값 없음.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_init(math_engine_rng_t* rng, uint64_t seed);

현재 state를 seed material로 사용해 지정 stream으로 전환한다.

• 매개변수 rng: 초기화된 caller-owned state. NULL이면 아무 작업도 하지 않는다.
• 매개변수 stream_id: 재현 가능한 stream 식별자.
• 반환: 반환값 없음.

호출은 state를 변경한다. 원래 seed와 stream의 직접 조합이 필요하면 먼저 같은 seed로 math_engine_rng_init 한 뒤 한 번 호출한다.

• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_set_stream(math_engine_rng_t* rng, uint64_t stream_id);

다음 32-bit 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 반환: 생성값. rng 이 NULL이면 0.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API uint32_t math_engine_rng_u32(math_engine_rng_t* rng);

연속된 두 32-bit draw로 다음 64-bit 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 반환: 생성값. rng 이 NULL이면 0.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API uint64_t math_engine_rng_u64(math_engine_rng_t* rng);

편향 없이 반열린 범위 =[0, max)=의 32-bit 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 매개변수 max: 제외 상한.
• 반환: 생성값. rng 이 NULL이거나 =max==0=이면 state를 변경하지 않고 0.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API uint32_t math_engine_rng_range_u32(math_engine_rng_t* rng, uint32_t max);

편향 없이 반열린 범위 =[0, max)=의 64-bit 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 매개변수 max: 제외 상한.
• 반환: 생성값. rng 이 NULL이거나 =max==0=이면 state를 변경하지 않고 0.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API uint64_t math_engine_rng_range_u64(math_engine_rng_t* rng, uint64_t max);

반열린 범위 =[0, 1)=의 24-bit precision float 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 반환: 생성값. rng 이 NULL이면 0.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API float math_engine_rng_f32(math_engine_rng_t* rng);

반열린 범위 =[0, 1)=의 53-bit precision double 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 반환: 생성값. rng 이 NULL이면 0.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API double math_engine_rng_f64(math_engine_rng_t* rng);

반열린 범위 =[min, max)=의 float 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 매개변수 min: 포함 하한.
• 매개변수 max: 제외 상한.
• 반환: 생성값. rng 이 NULL이거나 max<=min 이면 state를 변경하지 않고 min.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API float math_engine_rng_range_f32(
    math_engine_rng_t* rng, float min, float max);

두 finite bound 사이의 반열린 double 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 매개변수 min: 첫 bound.
• 매개변수 max: 둘째 bound. max<min 이면 두 bound를 교환한다.
• 반환: 정규화한 [min, max) 결과. rng 이 NULL이면 입력 min.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API double math_engine_rng_range_f64(
    math_engine_rng_t* rng, double min, double max);

반열린 범위 =[min, max)=의 signed 32-bit 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 매개변수 min: 포함 하한.
• 매개변수 max: 제외 상한.
• 반환: 생성값. rng 이 NULL이거나 max<=min 이면 state를 변경하지 않고 min.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API int32_t math_engine_rng_range_i32(
    math_engine_rng_t* rng, int32_t min, int32_t max);

반열린 범위 =[min, max)=의 signed 64-bit 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 매개변수 min: 포함 하한.
• 매개변수 max: 제외 상한.
• 반환: 생성값. rng 이 NULL이거나 max<=min 이면 state를 변경하지 않고 min.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API int64_t math_engine_rng_range_i64(
    math_engine_rng_t* rng, int64_t min, int64_t max);

균등한 boolean 값을 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 반환: 생성값. rng 이 NULL이면 false.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API bool math_engine_rng_bool(math_engine_rng_t* rng);

지정 확률로 true를 생성한다.

• 매개변수 rng: 변경할 caller-owned state.
• 매개변수 probability: true 확률. 0 이하는 false, 1 이상은 true로 clamp한다.
• 반환: Bernoulli 결과. rng 이 NULL이면 false.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API bool math_engine_rng_chance_f64(math_engine_rng_t* rng, double probability);

count 개의 32-bit draw를 배열에 기록한다.

• 매개변수 rng: 변경할 caller-owned state.
• 매개변수 out: 결과를 받는 caller-owned 배열.
• 매개변수 count: out 의 원소 수.
• 반환: 반환값 없음.

rng 또는 out 이 NULL이면 state와 output을 변경하지 않는다. Output은 RNG state와 겹치지 않아야 한다.

• Math Engine ownership: rng=caller out=caller
• Math Engine nullable: rng=true out=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_fill_u32(
    math_engine_rng_t* rng, uint32_t* out, size_t count);

@brief math_engine_rng_fill_u32 의 64-bit 배열 variant다.

• 매개변수 rng: 변경할 caller-owned state. @param out caller-owned 결과 배열.
• 매개변수 count: out 의 원소 수.
• 반환: 반환값 없음.
• Math Engine ownership: rng=caller out=caller
• Math Engine nullable: rng=true out=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_fill_u64(
    math_engine_rng_t* rng, uint64_t* out, size_t count);

@brief 각 원소를 편향 없이 =[0, max)=의 32-bit 값으로 채운다.

• 매개변수 rng: 변경할 caller-owned state. @param out caller-owned 결과 배열.
• 매개변수 count: out 의 원소 수. @param max 제외 상한. 0이면 모든 원소에 0을 쓴다.
• 반환: 반환값 없음.
• Math Engine ownership: rng=caller out=caller
• Math Engine nullable: rng=true out=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_fill_range_u32(
    math_engine_rng_t* rng, uint32_t* out, size_t count, uint32_t max);

@brief 각 원소를 편향 없이 =[0, max)=의 64-bit 값으로 채운다.

• 매개변수 rng: 변경할 caller-owned state. @param out caller-owned 결과 배열.
• 매개변수 count: out 의 원소 수. @param max 제외 상한. 0이면 모든 원소에 0을 쓴다.
• 반환: 반환값 없음.
• Math Engine ownership: rng=caller out=caller
• Math Engine nullable: rng=true out=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_fill_range_u64(
    math_engine_rng_t* rng, uint64_t* out, size_t count, uint64_t max);

@brief 각 원소를 반열린 범위 =[0, 1)=의 float 값으로 채운다.

• 매개변수 rng: 변경할 caller-owned state. @param out caller-owned 결과 배열.
• 매개변수 count: out 의 원소 수.
• 반환: 반환값 없음.
• Math Engine ownership: rng=caller out=caller
• Math Engine nullable: rng=true out=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_fill_f32(
    math_engine_rng_t* rng, float* out, size_t count);

@brief 각 원소를 반열린 범위 =[0, 1)=의 double 값으로 채운다.

• 매개변수 rng: 변경할 caller-owned state. @param out caller-owned 결과 배열.
• 매개변수 count: out 의 원소 수.
• 반환: 반환값 없음.
• Math Engine ownership: rng=caller out=caller
• Math Engine nullable: rng=true out=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_fill_f64(
    math_engine_rng_t* rng, double* out, size_t count);

@brief 두 finite bound 사이의 반열린 double 값으로 배열을 채운다.

• 매개변수 rng: 변경할 caller-owned state. @param out caller-owned 결과 배열.
• 매개변수 count: out 의 원소 수. @param min 첫 bound. @param max 둘째 bound.
• 반환: 반환값 없음.

max<min 이면 교환하며 같은 값이면 state를 변경하지 않고 그 값을 채운다.

• Math Engine ownership: rng=caller out=caller
• Math Engine nullable: rng=true out=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_fill_range_f64(
    math_engine_rng_t* rng, double* out, size_t count, double min, double max);

@brief 반열린 범위 =[min, max)=의 signed 32-bit 값으로 배열을 채운다.

• 매개변수 rng: 변경할 caller-owned state. @param out caller-owned 결과 배열.
• 매개변수 count: out 의 원소 수. @param min 포함 하한. @param max 제외 상한.
• 반환: 반환값 없음.

max<=min 이면 state를 변경하지 않고 모든 원소에 min 을 쓴다.

• Math Engine ownership: rng=caller out=caller
• Math Engine nullable: rng=true out=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_fill_range_i32(
    math_engine_rng_t* rng, int32_t* out, size_t count, int32_t min, int32_t max);

@brief 반열린 범위 =[min, max)=의 signed 64-bit 값으로 배열을 채운다.

• 매개변수 rng: 변경할 caller-owned state. @param out caller-owned 결과 배열.
• 매개변수 count: out 의 원소 수. @param min 포함 하한. @param max 제외 상한.
• 반환: 반환값 없음.

max<=min 이면 state를 변경하지 않고 모든 원소에 min 을 쓴다.

• Math Engine ownership: rng=caller out=caller
• Math Engine nullable: rng=true out=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_rng_fill_range_i64(
    math_engine_rng_t* rng, int64_t* out, size_t count, int64_t min, int64_t max);

지정 면 수의 공을 한 번 굴려 닫힌 범위 [1, sides] 값을 만든다.

• 매개변수 rng: 변경할 caller-owned state. @param sides 면 수.
• 반환: 결과. rng 이 NULL이거나 =sides==0=이면 0.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API uint32_t math_engine_roll(math_engine_rng_t* rng, uint32_t sides);

정수 배열에서 한 값을 균등하게 선택한다.

• 매개변수 values: borrowed 입력 배열. @param count 원소 수.
• 매개변수 rng: 변경할 caller-owned state.
• 반환: 선택값. Pointer가 NULL이거나 =count==0=이면 0.
• Math Engine ownership: values=borrowed rng=caller
• Math Engine nullable: values=true rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API int32_t math_engine_roll_pick(
    const int32_t* values, size_t count, math_engine_rng_t* rng);

음이 아닌 정수 weight에 비례해 배열 값을 선택한다.

• 매개변수 values: borrowed 값 배열. @param weights borrowed weight 배열.
• 매개변수 count: 두 배열의 원소 수. @param rng 변경할 caller-owned state.
• 반환: 선택값. Invalid pointer·빈 배열·전체 weight 0이면 0.

두 입력 배열은 각각 최소 count 개 원소를 가져야 하며 함수는 변경하지 않는다.

• Math Engine ownership: values=borrowed weights=borrowed rng=caller
• Math Engine nullable: values=true weights=true rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API int32_t math_engine_roll_pick_weighted(
    const int32_t* values,
    const uint32_t* weights,
    size_t count,
    math_engine_rng_t* rng);

정수 percent 확률로 true를 생성한다.

• 매개변수 rng: 변경할 caller-owned state. @param percent 0..100 범위의 확률.
• 반환: 0이면 false, 100 이상이면 true, 그 외에는 random 결과. NULL state는 false.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API bool math_engine_roll_check_percent(
    math_engine_rng_t* rng, uint32_t percent);

Mutable pool에서 값을 균등 선택하고 swap-remove한다.

• 매개변수 pool: caller-owned 값 배열. @param count 입출력 active 원소 수.
• 매개변수 rng: 변경할 caller-owned state.
• 반환: 제거한 값. Invalid pointer 또는 빈 pool이면 state·pool·count를 보존하고 0.
• Math Engine ownership: pool=caller count=caller rng=caller
• Math Engine nullable: pool=true count=true rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API int32_t math_engine_roll_take(
    int32_t* pool, size_t* count, math_engine_rng_t* rng);

Mutable weighted pool에서 값을 선택하고 값·weight를 함께 swap-remove한다.

• 매개변수 pool: caller-owned 값 배열. @param weights caller-owned weight 배열.
• 매개변수 count: 입출력 active 원소 수. @param rng 변경할 caller-owned state.
• 반환: 제거한 값. Invalid pointer·빈 pool·전체 weight 0이면 모든 입출력을 보존하고 0.
• Math Engine ownership: pool=caller weights=caller count=caller rng=caller
• Math Engine nullable: pool=true weights=true count=true rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API int32_t math_engine_roll_take_weighted(
    int32_t* pool, uint32_t* weights, size_t* count, math_engine_rng_t* rng);

고정 크기 원소 배열을 in-place Fisher–Yates 방식으로 섞는다.

• 매개변수 base: caller-owned 배열 시작 주소.
• 매개변수 count: 원소 수.
• 매개변수 element_size: 원소 하나의 byte 크기.
• 매개변수 rng: 변경할 caller-owned state.
• 반환: 반환값 없음.

base=·=rng 이 NULL, element_size==0 또는 count<2 이면 아무것도 변경하지 않는다. 배열 byte 범위는 RNG state와 겹치지 않아야 한다.

• Math Engine ownership: base=caller rng=caller
• Math Engine nullable: base=true rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_shuffle(
    void* base, size_t count, size_t element_size, math_engine_rng_t* rng);

@brief Signed 32-bit 배열을 in-place로 섞는다.

• 매개변수 values: caller-owned 배열. @param count 원소 수. @param rng 변경할 state.
• 반환: 반환값 없음.
• Math Engine ownership: values=caller rng=caller
• Math Engine nullable: values=true rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_shuffle_i32(
    int32_t* values, size_t count, math_engine_rng_t* rng);

@brief Unsigned 32-bit 배열을 in-place로 섞는다.

• 매개변수 values: caller-owned 배열. @param count 원소 수. @param rng 변경할 state.
• 반환: 반환값 없음.
• Math Engine ownership: values=caller rng=caller
• Math Engine nullable: values=true rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_shuffle_u32(
    uint32_t* values, size_t count, math_engine_rng_t* rng);

두 finite bound 사이의 continuous uniform sample을 생성한다.

• 매개변수 rng: 변경할 caller-owned state. @param min 첫 bound. @param max 둘째 bound.
• 반환: 정규화한 반열린 범위 결과. Bound가 같거나 rng 이 NULL이면 해당 bound.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API double math_engine_dist_uniform_f64(
    math_engine_rng_t* rng, double min, double max);

Box–Muller 변환으로 normal distribution sample을 생성한다.

• 매개변수 rng: 변경할 caller-owned state. @param mean 평균.
• 매개변수 standard_deviation: 표준편차. 0 이하면 state를 변경하지 않고 mean 을 반환한다.
• 반환: 생성 sample. rng 이 NULL이면 mean.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API double math_engine_dist_normal_f64(
    math_engine_rng_t* rng, double mean, double standard_deviation);

Rate lambda 의 exponential distribution sample을 생성한다.

• 매개변수 rng: 변경할 caller-owned state. @param lambda 양의 finite rate.
• 반환: 생성 sample. NULL state 또는 양수가 아닌 lambda 이면 0.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API double math_engine_dist_exponential_f64(
    math_engine_rng_t* rng, double lambda);

Triangular distribution sample을 생성한다.

• 매개변수 rng: 변경할 caller-owned state. @param a 첫 bound. @param b 둘째 bound.
• 매개변수 c: mode. 정렬한 bound 밖이면 가장 가까운 bound로 clamp한다.
• 반환: 생성 sample. 두 bound가 같거나 rng 이 NULL이면 정규화한 하한.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API double math_engine_dist_triangular_f64(
    math_engine_rng_t* rng, double a, double b, double c);

지정 확률의 Bernoulli sample을 생성한다.

• 매개변수 rng: 변경할 caller-owned state. @param probability 0..1로 clamp할 확률.
• 반환: 생성 sample. rng 이 NULL이면 false.
• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API bool math_engine_dist_bernoulli(
    math_engine_rng_t* rng, double probability);

Knuth algorithm으로 Poisson distribution sample을 생성한다.

• 매개변수 rng: 변경할 caller-owned state. @param lambda (0, 64] 범위의 finite 평균·rate.
• 반환: 생성 sample. NULL state 또는 지원 범위 밖의 lambda 이면 state를 변경하지 않고 0.

이 variant는 small/moderate lambda 용이며 호출 시간은 결과 크기에 비례한다.

• Math Engine ownership: rng=caller
• Math Engine nullable: rng=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API uint32_t math_engine_dist_poisson_u32(
    math_engine_rng_t* rng, double lambda);

RNG component semantic version 문자열을 반환한다.

• 반환: Process lifetime 동안 유효한 immutable NUL-terminated 문자열.
• Math Engine ownership: return=static
• Math Engine nullable: return=false
• Math Engine thread_safety: safe

MATH_ENGINE_API const char* math_engine_rng_version_string(void);

RNG component semantic version 숫자를 선택적으로 반환한다.

• 매개변수 major: major output 또는 NULL. @param minor minor output 또는 NULL.
• 매개변수 patch: patch output 또는 NULL.
• 반환: 반환값 없음.
• Math Engine ownership: major=caller minor=caller patch=caller
• Math Engine nullable: major=true minor=true patch=true
• Math Engine thread_safety: safe

MATH_ENGINE_API void math_engine_rng_version(int* major, int* minor, int* patch);