Math Engine Reference: Number Theory

Checked callback이 요청하는 동기 action이다.

typedef enum math_engine_number_theory_emit_action {
    MATH_ENGINE_NUMBER_THEORY_EMIT_CONTINUE = 0, /**< 다음 factor/prime을 계속 열거하고 terminal result를 아직 commit하지 않는다. */
    MATH_ENGINE_NUMBER_THEORY_EMIT_STOP = 1, /**< 정상 상태 OK로 partial cursor/result를 commit하고 즉시 중단한다. */
    MATH_ENGINE_NUMBER_THEORY_EMIT_ERROR = 2 /**< Partial cursor/result를 commit하고 INTERNAL_ERROR로 중단한다. */
} math_engine_number_theory_emit_action_t;

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

• 매개변수 user_data: control.cancel_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

Operation caller thread에서 각 tracked step 전에 최대 한 번 호출된다. Engine은 callback과 user_data 를 반환 뒤 보관하지 않으며 C++ exception은 C ABI 경계를 넘어서는 안 된다.

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

Production algorithm과 private generated asset의 안정된 identity다.

typedef struct math_engine_number_theory_algorithm_info {
    uint32_t struct_size; /**< Caller가 exact info byte 크기로 미리 설정하고 library가 같은 값을 기록한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_NUMBER_THEORY_ALGORITHM_INFO_VERSION_1=이어야 한다. */
    uint32_t primality_algorithm_id; /**< 현재 =MILLER_RABIN_U32= stable ID다. */
    uint32_t primality_algorithm_version; /**< 현재 primality algorithm semantics version 1이다. */
    uint32_t factor_algorithm_id; /**< 현재 =TRIAL_DIVISION_U32= stable ID다. */
    uint32_t factor_algorithm_version; /**< 현재 factor algorithm semantics version 1이다. */
    uint32_t sieve_algorithm_id; /**< 현재 =ODD_SEGMENTED_U32= stable ID다. */
    uint32_t sieve_algorithm_version; /**< 현재 sieve algorithm semantics version 1이다. */
    uint32_t flags; /**< Caller-owned/deterministic/no-heap/table 구성 info bit의 유효한 OR다. */
    uint32_t generated_prime_count; /**< Optional private asset의 prime element 수이며 V1 asset은 6542다. */
    uint32_t generated_last_prime; /**< Generated asset의 마지막 포함 prime이며 V1 asset은 65521이다. */
    uint32_t reserved32; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 slot이다. */
    uint64_t generated_asset_fingerprint; /**< Ordered generated-prime payload의 stable 64-bit fingerprint다. */
    uint64_t maximum_end_exclusive; /**< Segmented API가 허용하는 제외 상한 =2^32= (=4294967296=)이다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 word다. */
} math_engine_number_theory_algorithm_info_t;

Bounded operation의 work budget과 동기 cancellation callback이다.

typedef struct math_engine_number_theory_control {
    uint32_t struct_size; /**< Exact control byte 크기 =sizeof(math_engine_number_theory_control_t)=다. */
    uint32_t struct_version; /**< =MATH_ENGINE_NUMBER_THEORY_CONTROL_VERSION_1=이어야 한다. */
    uint64_t iteration_budget; /**< 허용 tracked step의 포함 최대 수; 0이면 첫 step 전에 BUDGET_EXHAUSTED다. */
    math_engine_number_theory_cancel_fn cancel; /**< Nullable borrowed 동기 callback; operation 호출 동안 유효하고 library가 보관하지 않는다. */
    void* cancel_user_data; /**< Nullable caller-owned opaque state; =cancel==NULL=이면 반드시 NULL이고 callback 동안만 borrowed다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두어야 하고 control validator가 검사하는 ABI 확장 word다. */
} math_engine_number_theory_control_t;

Primality/next-prime의 versioned result다.

typedef struct math_engine_number_theory_u32_result {
    uint32_t struct_size; /**< Caller가 exact result byte 크기로 미리 설정한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_NUMBER_THEORY_U32_RESULT_VERSION_1=이어야 한다. */
    uint32_t flags; /**< Next-prime 성공은 VALUE, 표현 가능한 prime 부재는 MISS인 공통 result bit다. */
    uint32_t value; /**< VALUE이면 입력 이상 최소 prime, MISS이면 0이다. */
    uint64_t iterations; /**< Miller–Rabin과 candidate search에서 소비한 tracked step 누계다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 word다. */
} math_engine_number_theory_u32_result_t;

Factor callback stop/cancel 뒤의 재개 가능한 remaining value를 포함한다.

typedef struct math_engine_number_theory_factor_result {
    uint32_t struct_size; /**< Caller가 exact factor-result byte 크기로 미리 설정한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_NUMBER_THEORY_FACTOR_RESULT_VERSION_1=이어야 한다. */
    uint32_t flags; /**< 전체 분해 VALUE, 0/1 EMPTY 또는 재개 가능한 PARTIAL 공통 result bit다. */
    uint32_t remaining_value; /**< 아직 emit하지 않은 factor product; 완료 시 1, PARTIAL이면 다음 호출의 input이다. */
    uint64_t emitted_count; /**< Callback에 성공적으로 전달한 distinct prime record 수다. */
    uint64_t iterations; /**< Trial/search에서 소비한 tracked step 누계다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 word다. */
} math_engine_number_theory_factor_result_t;

Base-prime output과 odd-only sieve scratch의 exact capacity 요구량이다.

typedef struct math_engine_number_theory_workspace_requirements {
    uint32_t struct_size; /**< Caller가 exact requirements byte 크기로 미리 설정한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_NUMBER_THEORY_WORKSPACE_REQUIREMENTS_VERSION_1=이어야 한다. */
    uint32_t limit_inclusive; /**< 요청 end의 =floor(sqrt(end_inclusive))= 닫힌 base-prime 상한이다. */
    uint32_t reserved32; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 slot이다. */
    uint64_t primes_capacity_required; /**< =primes_out=에 필요한 uint16 element 수다. */
    uint64_t workspace_bytes_required; /**< Odd-only sieve scratch에 필요한 정확한 byte capacity다. */
    uint64_t workspace_alignment; /**< =sieve_bits= 주소의 byte alignment 요구값이며 V1은 1이다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 word다. */
} math_engine_number_theory_workspace_requirements_t;

Segmented enumeration의 completed/partial cursor와 사용 work를 기록한다.

typedef struct math_engine_number_theory_sieve_result {
    uint32_t struct_size; /**< Caller가 exact sieve-result byte 크기로 미리 설정한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_NUMBER_THEORY_SIEVE_RESULT_VERSION_1=이어야 한다. */
    uint32_t flags; /**< Prime을 emit하면 VALUE, 빈 범위는 EMPTY, 중단 시 PARTIAL인 공통 result bit다. */
    uint32_t reserved32; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 slot이다. */
    uint64_t emitted_count; /**< 이 호출에서 callback에 전달한 prime element 수다. */
    uint64_t iterations; /**< Base 검증, marking과 candidate scan의 tracked step 누계다. */
    uint64_t next_value; /**< PARTIAL 재개 포함 하한; 완료 시 =end_exclusive=다. */
    uint64_t end_exclusive; /**< 요청한 반열린 search range의 보존된 제외 상한이며 최대 =2^32=다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 word다. */
} math_engine_number_theory_sieve_result_t;

Checked factorization이 발견한 factor와 multiplicity를 전달하는 동기 callback이다.

• 매개변수 prime: 오름차순으로 발견한 소인수.
• 매개변수 multiplicity: 해당 소인수의 1 이상 중복 횟수.
• 매개변수 user: 호출자가 함수에 전달한 borrowed context.
• 반환: 계속, 정상 partial stop 또는 오류 중단을 나타내는 emit action.
• Math Engine ownership: user=borrowed
• Math Engine nullable: user=true
• Math Engine thread_safety: caller_serialized
• Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

Factor를 찾을 때 caller thread에서 record당 정확히 한 번 호출하며 pointer를 보관하지 않는다. C++ exception은 C ABI 경계를 넘어서는 안 된다.

typedef math_engine_number_theory_emit_action_t (*math_engine_factor_emit_u32_checked_fn)(
    uint32_t prime, uint32_t multiplicity, void* user);

Checked segmented sieve가 발견한 소수를 전달하는 동기 callback이다.

• 매개변수 prime: 검색 범위에서 오름차순으로 발견한 소수.
• 매개변수 user: 호출자가 함수에 전달한 borrowed context.
• 반환: 계속, 정상 partial stop 또는 오류 중단을 나타내는 emit action.
• Math Engine ownership: user=borrowed
• Math Engine nullable: user=true
• Math Engine thread_safety: caller_serialized
• Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

Prime을 찾을 때 caller thread에서 element당 정확히 한 번 호출하며 pointer를 보관하지 않는다. C++ exception은 C ABI 경계를 넘어서는 안 된다.

typedef math_engine_number_theory_emit_action_t (*math_engine_prime_emit_u32_checked_fn)(
    uint32_t prime, void* user);

발견한 소인수와 중복 횟수를 받는 callback이다.

• 매개변수 prime: 소인수.
• 매개변수 multiplicity: 소인수의 중복 횟수. 1 이상이다.
• 매개변수 user: 호출자가 전달한 borrowed context.
• 반환: 계속하려면 true, 즉시 중단하려면 false.
• Math Engine ownership: user=borrowed
• Math Engine nullable: user=true
• Math Engine thread_safety: caller_serialized
• Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

Legacy factor API가 발견 record마다 caller thread에서 동기 호출하고 반환 후 아무 pointer도 보관하지 않는다. C++ exception은 C ABI 경계를 넘어서는 안 된다.

typedef bool (*math_engine_factor_emit_u32_fn)(
    uint32_t prime, uint32_t multiplicity, void* user);

발견한 소수를 받는 callback이다.

• 매개변수 prime: 오름차순으로 발견한 소수.
• 매개변수 user: 호출자가 전달한 borrowed context.
• 반환: 계속하려면 true, 즉시 중단하려면 false.
• Math Engine ownership: user=borrowed
• Math Engine nullable: user=true
• Math Engine thread_safety: caller_serialized
• Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

Legacy sieve가 발견 prime마다 caller thread에서 동기 호출하고 반환 후 아무 pointer도 보관하지 않는다. C++ exception은 C ABI 경계를 넘어서는 안 된다.

typedef bool (*math_engine_prime_emit_u32_fn)(uint32_t prime, void* user);

Algorithm-info POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_NUMBER_THEORY_ALGORITHM_INFO_VERSION_1 UINT32_C(1)

Control POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_NUMBER_THEORY_CONTROL_VERSION_1 UINT32_C(1)

Unsigned 32-bit trial-division factorization algorithm ID 1이다.

#define MATH_ENGINE_NUMBER_THEORY_FACTOR_ALGORITHM_TRIAL_DIVISION_U32 UINT32_C(1)

Trial-division ordering/budget 의미를 고정하는 algorithm version 1이다.

#define MATH_ENGINE_NUMBER_THEORY_FACTOR_ALGORITHM_VERSION_1 UINT32_C(1)

Factor result POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_NUMBER_THEORY_FACTOR_RESULT_VERSION_1 UINT32_C(1)

Bit 0 (0x01): 모든 mutable output/workspace를 caller가 소유한다.

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

Bit 1 (0x02): 같은 입력·budget·callback action에 같은 순서와 결과를 낸다.

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

Bit 2 (0x04): Production algorithm이 heap allocation을 수행하지 않는다.

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

Bit 4 (0x10): 같은 계약의 optional generated prime asset build를 지원한다.

#define MATH_ENGINE_NUMBER_THEORY_FLAG_OPTIONAL_GENERATED_TABLE (UINT32_C(1) << 4u)

Bit 3 (0x08): 현재 core가 generated prime table 없이 동작한다.

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

전체 uint32 domain용 deterministic Miller–Rabin primality algorithm ID 1이다.

#define MATH_ENGINE_NUMBER_THEORY_PRIMALITY_ALGORITHM_MILLER_RABIN_U32 UINT32_C(1)

Miller–Rabin base/iteration 의미를 고정하는 algorithm version 1이다.

#define MATH_ENGINE_NUMBER_THEORY_PRIMALITY_ALGORITHM_VERSION_1 UINT32_C(1)

Odd-only segmented uint32 sieve algorithm ID 1이다.

#define MATH_ENGINE_NUMBER_THEORY_SIEVE_ALGORITHM_ODD_SEGMENTED_U32 UINT32_C(1)

Segmentation/cursor 의미를 고정하는 sieve algorithm version 1이다.

#define MATH_ENGINE_NUMBER_THEORY_SIEVE_ALGORITHM_VERSION_1 UINT32_C(1)

Segmented-sieve result POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_NUMBER_THEORY_SIEVE_RESULT_VERSION_1 UINT32_C(1)

Primality/next-prime result POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_NUMBER_THEORY_U32_RESULT_VERSION_1 UINT32_C(1)

Workspace-requirements POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_NUMBER_THEORY_WORKSPACE_REQUIREMENTS_VERSION_1 UINT32_C(1)

Production number-theory algorithm과 generated asset identity를 조회한다.

• 매개변수 out_info: 호출 전에 struct_size 와 struct_version 을 설정하고 info를 받을 caller-owned 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_number_theory_algorithm_info_get(
    math_engine_number_theory_algorithm_info_t* out_info);

전체 uint32_t domain에서 deterministic Miller–Rabin으로 소수 여부를 판정한다.

• 매개변수 value: 판정할 unsigned 32-bit 값.
• 매개변수 control: 호출 동안만 읽는 필수 budget/cancellation control.
• 매개변수 out_is_prime: 성공 시 소수 여부를 받을 caller-owned output.
• 매개변수 out_iterations: 성공 시 소비한 bounded iteration 수를 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Budget 0 또는 소진은 MATH_ENGINE_STATUS_BUDGET_EXHAUSTED, callback cancellation은 MATH_ENGINE_STATUS_CANCELLED 이며 모든 실패에서 두 output을 보존한다.

Output끼리 또는 control 과 겹치면 invalid argument다. Cancellation callback과 context는 동기적으로만 사용하고 호출이 끝난 뒤 보관하지 않는다.

• Math Engine ownership: control=borrowed out_is_prime=caller out_iterations=caller
• Math Engine nullable: control=false out_is_prime=false out_iterations=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_is_prime_u32_checked(
    uint32_t value,
    const math_engine_number_theory_control_t* control,
    bool* out_is_prime,
    uint64_t* out_iterations);

입력 이상인 가장 작은 uint32_t 소수를 bounded search로 찾는다.

• 매개변수 value: 검색을 시작할 포함 하한.
• 매개변수 control: 호출 동안만 읽는 필수 budget/cancellation control.
• 매개변수 out_result: 호출 전에 size/version을 설정하고 value·flag·iteration을 받을 output.
• 반환: 검색을 마치면 MATH_ENGINE_STATUS_OK. Prime을 찾으면 VALUE flag, 표현 가능한 prime이 없으면 MISS flag와 value 0을 기록한다. Budget·cancel·검증 실패 시 output을 보존한다.
• Math Engine ownership: control=borrowed out_result=caller
• Math Engine nullable: control=false out_result=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_next_prime_u32_checked(
    uint32_t value,
    const math_engine_number_theory_control_t* control,
    math_engine_number_theory_u32_result_t* out_result);

Unsigned 32-bit 값을 bounded trial division으로 소인수분해한다.

• 매개변수 value: 분해할 값. 0과 1은 EMPTY 결과로 완료된다.
• 매개변수 control: 호출 동안만 읽는 필수 budget/cancellation control.
• 매개변수 emit: factor와 multiplicity를 오름차순으로 받는 필수 동기 callback.
• 매개변수 user: emit 에 그대로 전달하며 호출 뒤 보관하지 않는 borrowed context.
• 매개변수 out_result: 호출 전에 size/version을 설정하고 진행 상태를 받을 caller-owned output.
• 반환: 전체 완료 또는 callback STOP이면 MATH_ENGINE_STATUS_OK. STOP은 PARTIAL, ERROR는 MATH_ENGINE_STATUS_INTERNAL_ERROR 다. 실행을 시작한 뒤 budget/cancel이면 해당 status와 PARTIAL을 기록하고, 실행 전 검증·budget 실패는 output을 보존한다.

이미 전달한 factor는 취소하지 않는다. PARTIAL의 remaining_value 를 새 호출의 value 로 사용해 나머지 분해를 재개할 수 있다.

• Math Engine ownership: control=borrowed emit=borrowed user=borrowed out_result=caller
• Math Engine nullable: control=false emit=false user=true out_result=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_factor_u32_checked(
    uint32_t value,
    const math_engine_number_theory_control_t* control,
    math_engine_factor_emit_u32_checked_fn emit,
    void* user,
    math_engine_number_theory_factor_result_t* out_result);

닫힌 상한을 처리하는 base-prime 배열과 odd-only sieve workspace의 정확한 요구량을 구한다.

• 매개변수 end_inclusive: 이후 segmented sieve가 처리할 unsigned 32-bit 닫힌 상한.
• 매개변수 out_requirements: 호출 전에 size/version을 설정하고 요구량을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK 와 floor(sqrt(end_inclusive)) 기준 요구량을 기록한다. Output 검증 실패 시 해당 status를 반환하고 output을 보존한다.
• Math Engine ownership: out_requirements=caller
• Math Engine nullable: out_requirements=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_base_primes_u32_requirements(
    uint32_t end_inclusive,
    math_engine_number_theory_workspace_requirements_t* out_requirements);

Caller storage에 floor(sqrt(end_inclusive)) 이하 base prime을 생성한다.

• 매개변수 end_inclusive: 이후 segmented sieve가 처리할 unsigned 32-bit 닫힌 상한.
• 매개변수 primes_out: 오름차순 uint16_t prime을 받을 caller-owned 배열.
• 매개변수 primes_capacity: primes_out 의 원소 capacity.
• 매개변수 sieve_bits: odd-only sieve가 변경해 사용하는 caller-owned byte workspace.
• 매개변수 sieve_bits_bytes: sieve_bits 의 byte capacity.
• 매개변수 control: 호출 동안만 읽는 필수 budget/cancellation control.
• 매개변수 out_count: 성공 시 생성된 prime 원소 수를 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. 부족한 prime 배열과 workspace는 각각 MATH_ENGINE_STATUS_INSUFFICIENT_BUFFER 와 MATH_ENGINE_STATUS_INSUFFICIENT_WORKSPACE 다. 실패 시 prime output과 out_count 를 보존하지만 실행을 시작한 뒤의 workspace byte는 scratch로 간주한다.

Capacity와 pointer overlap은 scratch 변경 전에 검사한다. 요구량이 0인 배열만 NULL일 수 있으며 cancellation callback과 context는 동기적으로만 사용한다.

• Math Engine ownership: primes_out=caller sieve_bits=caller control=borrowed out_count=caller
• Math Engine nullable: primes_out=true sieve_bits=true control=false out_count=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_make_base_primes_u32_checked(
    uint32_t end_inclusive,
    uint16_t* primes_out,
    uint64_t primes_capacity,
    uint8_t* sieve_bits,
    uint64_t sieve_bits_bytes,
    const math_engine_number_theory_control_t* control,
    uint64_t* out_count);

반열린 범위 =[start,end_exclusive)=의 소수를 bounded segmented sieve로 열거한다.

• 매개변수 start: 검색을 시작할 포함 하한.
• 매개변수 end_exclusive: 제외 상한. 최대 =2^32=까지 허용한다.
• 매개변수 base_primes: floor(sqrt(end_exclusive-1)) 이하 모든 소수를 정확한 오름차순 prefix로 포함하는 borrowed uint16_t 배열.
• 매개변수 base_prime_count: base_primes 의 원소 수. 최대 6542이며 완전한 prime superset도 허용한다.
• 매개변수 window_bits: segment marking에 사용하는 caller-owned byte workspace.
• 매개변수 window_bits_bytes: window_bits 의 byte capacity. Non-empty 범위에서는 1 이상, 최대 536870912이다.
• 매개변수 control: 호출 동안만 읽는 필수 budget/cancellation control.
• 매개변수 emit: 발견한 소수를 오름차순으로 받는 필수 동기 callback.
• 매개변수 user: emit 에 그대로 전달하며 호출 뒤 보관하지 않는 borrowed context.
• 매개변수 out_result: 호출 전에 size/version을 설정하고 cursor·iteration·count를 받을 output.
• 반환: 전체 완료 또는 callback STOP이면 MATH_ENGINE_STATUS_OK. STOP, 실행 중 budget/cancel, callback ERROR는 PARTIAL cursor를 commit한다. 실행 전 검증 또는 base-source 검증 실패는 output을 보존하며, 실행이 시작된 workspace byte는 scratch로 간주한다.

Base 배열, window, control과 output의 금지된 overlap은 invalid argument다. PARTIAL의 next_value 를 다음 호출의 start 로 사용해 이미 전달한 prime 이후부터 재개할 수 있다.

• Math Engine ownership: base_primes=borrowed window_bits=caller control=borrowed emit=borrowed user=borrowed out_result=caller
• Math Engine nullable: base_primes=true window_bits=true control=false emit=false user=true out_result=false
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API math_engine_status_t math_engine_segmented_primes_u32_checked(
    uint32_t start,
    uint64_t end_exclusive,
    const uint16_t* base_primes,
    uint64_t base_prime_count,
    uint8_t* window_bits,
    uint64_t window_bits_bytes,
    const math_engine_number_theory_control_t* control,
    math_engine_prime_emit_u32_checked_fn emit,
    void* user,
    math_engine_number_theory_sieve_result_t* out_result);

32-bit unsigned 정수가 소수인지 판정한다.

• 매개변수 value: 판정할 값.
• 반환: 소수이면 true, 0·1 또는 합성수이면 false.

함수는 allocation과 callback을 수행하지 않으며 모든 입력에서 deterministic하다.

• Math Engine thread_safety: safe

MATH_ENGINE_API bool math_engine_is_prime_u32(uint32_t value);

입력 이상인 가장 작은 32-bit 소수를 찾는다.

• 매개변수 value: 검색 시작값.
• 반환: 찾은 소수. 표현 가능한 다음 소수가 없으면 0.
• Math Engine thread_safety: safe

MATH_ENGINE_API uint32_t math_engine_next_prime_u32(uint32_t value);

32-bit unsigned 정수를 소인수분해하여 callback으로 전달한다.

• 매개변수 value: 분해할 값. 0과 1은 빈 분해로 취급한다.
• 매개변수 emit: 소인수를 오름차순으로 받는 callback.
• 매개변수 user: callback에 그대로 전달할 borrowed context.
• 반환: 전체 분해를 전달했으면 true. emit 이 NULL이거나 callback이 중단하면 false.

Callback이 false를 반환하면 이미 전달한 항목은 취소하지 않는다. user 는 NULL일 수 있고 함수는 callback pointer 또는 context를 호출 뒤 보관하지 않는다.

• Math Engine ownership: emit=borrowed user=borrowed
• Math Engine nullable: emit=false user=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API bool math_engine_factor_u32_emit(
    uint32_t value, math_engine_factor_emit_u32_fn emit, void* user);

end_inclusive 의 제곱근 이하 base prime을 caller storage에 생성한다.

• 매개변수 end_inclusive: 이후 segmented sieve가 다룰 닫힌 상한.
• 매개변수 primes_out: 결과를 받는 caller-owned uint16_t 배열.
• 매개변수 primes_capacity: primes_out 의 원소 capacity.
• 매개변수 sieve_bits: odd-only sieve에 사용할 caller-owned byte workspace.
• 매개변수 sieve_bits_bytes: sieve_bits 의 byte capacity.
• 반환: 생성한 base prime 수. Pointer·capacity가 유효하지 않거나 workspace가 부족하면 0.

성공한 원소만 primes_out[0..return) 에 기록한다. 두 배열은 겹치지 않아야 한다. 이 함수는 allocation을 수행하지 않는다.

• Math Engine ownership: primes_out=caller sieve_bits=caller
• Math Engine nullable: primes_out=false sieve_bits=false
• Math Engine thread_safety: safe

MATH_ENGINE_API size_t math_engine_make_base_primes_u32(
    uint32_t end_inclusive,
    uint16_t* primes_out,
    size_t primes_capacity,
    uint8_t* sieve_bits,
    size_t sieve_bits_bytes);

반열린 범위 =[start, end_exclusive)=의 소수를 segmented sieve로 열거한다.

• 매개변수 start: 검색 시작값.
• 매개변수 end_exclusive: 검색에서 제외되는 상한.
• 매개변수 base_primes: sqrt(end_exclusive - 1) 까지 포함하는 오름차순 borrowed 배열.
• 매개변수 base_prime_count: base_primes 의 원소 수.
• 매개변수 window_bits: segment에 사용할 caller-owned byte workspace.
• 매개변수 window_bits_bytes: window_bits 의 byte capacity. 1 이상이어야 한다.
• 매개변수 emit: 발견한 소수를 오름차순으로 받는 callback.
• 매개변수 user: callback에 그대로 전달할 borrowed context.
• 반환: 반환값 없음. 유효하지 않은 입력과 빈 범위에서는 callback을 호출하지 않는다.

유효하지 않은 pointer·빈 범위에서는 아무 callback도 호출하지 않는다. Callback이 false를 반환하면 즉시 중단하며 이미 전달한 소수는 취소하지 않는다. 배열은 겹치지 않아야 하고 함수는 pointer를 호출 뒤 보관하지 않는다.

• Math Engine ownership: base_primes=borrowed window_bits=caller emit=borrowed user=borrowed
• Math Engine nullable: base_primes=false window_bits=false emit=false user=true
• Math Engine thread_safety: caller_serialized

MATH_ENGINE_API void math_engine_segmented_primes_u32_emit(
    uint32_t start,
    uint32_t end_exclusive,
    const uint16_t* base_primes,
    size_t base_prime_count,
    uint8_t* window_bits,
    size_t window_bits_bytes,
    math_engine_prime_emit_u32_fn emit,
    void* user);