Trait SimdToken

Source

pub trait SimdToken:
    Sealed
    + Copy
    + Clone
    + Send
    + Sync
    + 'static {
    const NAME: &'static str;
    const TARGET_FEATURES: &'static str;
    const ENABLE_TARGET_FEATURES: &'static str;
    const DISABLE_TARGET_FEATURES: &'static str;

    // Required methods
    fn compiled_with() -> Option<bool>;
    fn summon() -> Option<Self>;
    unsafe fn forge_token_dangerously() -> Self;

    // Provided methods
    fn guaranteed() -> Option<bool> { ... }
    fn attempt() -> Option<Self> { ... }
}

Expand description

Marker trait for SIMD capability tokens.

All tokens implement this trait, enabling generic code over different SIMD feature levels.

This trait is sealed — it cannot be implemented outside of archmage. Only tokens created by summon() or downcasting are valid.

§Token Lifecycle

Optionally check compiled_with() to see if runtime check is needed
Call summon() at runtime to detect CPU support
Pass the token through to #[arcane] functions — don’t forge new ones

§Example

use archmage::{X64V3Token, SimdToken};

fn process(data: &[f32]) -> f32 {
    if let Some(token) = X64V3Token::summon() {
        return process_avx2(token, data);
    }
    process_scalar(data)
}

Required Associated Constants§

Source

const NAME: &'static str

Human-readable name for diagnostics and error messages.

Source

const TARGET_FEATURES: &'static str

Comma-delimited target features (e.g., "sse,sse2,avx2,fma,bmi1,bmi2,f16c,lzcnt").

All features are listed, including baseline features like SSE/SSE2 for x86 tokens. For WASM, this is "simd128".

Empty for ScalarToken.

Source

const ENABLE_TARGET_FEATURES: &'static str

RUSTFLAGS to enable these features at compile time.

Example: "-Ctarget-feature=+avx2,+fma,+bmi1,+bmi2,+f16c,+lzcnt"

Empty for ScalarToken.

Source

const DISABLE_TARGET_FEATURES: &'static str

RUSTFLAGS to disable these features at compile time.

Example: "-Ctarget-feature=-avx2,-fma,-bmi1,-bmi2,-f16c,-lzcnt"

Useful in CompileTimeGuaranteedError messages to tell users how to recompile so that runtime disable works.

Empty for ScalarToken.

Required Methods§

Source

fn compiled_with() -> Option<bool>

Check if this binary was compiled with the required target features enabled.

Returns:

Some(true) — Features are compile-time enabled (e.g., -C target-cpu=haswell)
Some(false) — Wrong architecture, token can never be available
None — Might be available, call summon() to check at runtime

When compiled_with() returns Some(true), summon().unwrap() is safe and the compiler will elide the runtime check entirely.

§Example

match X64V3Token::compiled_with() {
    Some(true) => { /* summon().unwrap() is safe, no runtime check */ }
    Some(false) => { /* use fallback, this arch can't support it */ }
    None => { /* call summon() to check at runtime */ }
}

Source

fn summon() -> Option<Self>

Attempt to create a token with runtime feature detection.

Returns Some(token) if the CPU supports this feature, None otherwise.

§Example

if let Some(token) = X64V3Token::summon() {
    // Use AVX2+FMA operations
} else {
    // Fallback path
}

Source

unsafe fn forge_token_dangerously() -> Self

👎Deprecated since 0.5.0: Pass tokens through from summon() instead of forging

Create a token without any checks.

§Safety

Caller must guarantee the CPU feature is available. Using a forged token when the feature is unavailable causes undefined behavior.

§Deprecated

Do not use in new code. Pass tokens through from summon() instead. If you’re inside a #[cfg(target_feature = "...")] block where the feature is compile-time guaranteed, use summon().unwrap().