Module testing 

Available on crate feature std only.

Test utilities for exhaustive SIMD token permutation testing.

for_each_token_permutation runs a closure once for every unique combination of SIMD tokens disabled on the current CPU. This verifies that dispatch code (via incant! or manual summon() checks) correctly handles all fallback tiers.

Token disabling is process-wide, so a mutex serializes all permutation runs and manual disable/enable calls. Use lock_token_testing when calling dangerously_disable_token_process_wide directly, or when you need to observe stable summon() results alongside parallel permutation tests.

Example

use archmage::testing::{for_each_token_permutation, CompileTimePolicy};

#[test]
fn dispatch_works_at_all_tiers() {
    let report = for_each_token_permutation(CompileTimePolicy::Warn, |perm| {
        let result = my_simd_function(&data);
        assert_eq!(result, expected, "failed at: {perm}");
    });
    eprintln!("{report}");
}

Compile-time guaranteed tokens

When compiled with -Ctarget-cpu=native (or similar), some tokens become compile-time guaranteed and can’t be disabled at runtime. The CompileTimePolicy parameter controls behavior:

• Warn: exclude those tokens silently (warnings in report)
• WarnStderr: same, but also prints to stderr
• Fail: panic — use in CI with the testable_dispatch feature enabled for full coverage

Structs

PermutationReport

Summary of a complete permutation run.

TokenPermutation

Describes one permutation’s disabled-token state.

TokenTestGuard

RAII guard for the token testing lock. While held, no other thread can manipulate token disable state via for_each_token_permutation or another lock_token_testing call.

Enums

CompileTimePolicy

What to do when a token’s features are compile-time guaranteed (can’t be disabled).

Functions

for_each_token_permutation

Run f once for every unique combination of available SIMD tokens disabled.

lock_token_testing

Acquire the process-wide token testing lock.