Crate archmage 

archmage

Guide · Intrinsics browser · Archmage API · Magetypes API

Archmage provides CPU-capability tokens, feature-enabled functions, and dispatch. The #[magetypes] attribute belongs to archmage; the magetypes crate provides the vectors. Start with the complete portable kernel and generic specialization.

For a direct-intrinsic specialization, keep the full loop behind an entry:

use archmage::prelude::*;
#[arcane(import_intrinsics)]
fn multiply_v3(_token: X64V3Token, data: &[f32; 8]) -> [f32; 8] {
    let v = _mm256_loadu_ps(data);
    let mut out = [0.0; 8];
    _mm256_storeu_ps(&mut out, _mm256_mul_ps(v, _mm256_set1_ps(2.0)));
    out
}
fn multiply_scalar(_token: ScalarToken, data: &[f32; 8]) -> [f32; 8] {
    data.map(|v| v * 2.0)
}
pub fn multiply(data: &[f32; 8]) -> [f32; 8] {
    incant!(multiply(data), [v3, scalar])
}
assert_eq!(multiply(&[3.0; 8]), [6.0; 8]);

Use default #[magetypes] for generated portable entry variants, #[arcane] for individual entries, and matching #[rite] or inline generic helpers inside. Generics are statically dispatched; an inline attribute alone does not enable features. A CPU token does not justify arbitrary pointers or unchecked indexing.

Tokens from an existing feature context

When a helper already has target features, from_context() constructs a token without runtime detection. Rust checks that the caller’s features cover the token’s requirements. It is not a baseline-callable unchecked constructor.

use archmage::prelude::*;
#[rite(v3)]
fn helper() -> bool {
    let _token = X64V3Token::from_context();
    true
}
#[arcane]
fn entry(_token: X64V3Token) -> bool { helper() }
#[cfg(target_arch = "x86_64")]
if let Some(token) = X64V3Token::summon() { assert!(entry(token)); }

Added in 0.9.29. See from_context and token extraction. Use .v3() to extract a V3 token from a stronger proof; as_x64v3() instead checks whether the held token is exactly a V3 token.

Safety

Using archmage takes no unsafe in your code: you call intrinsics inside #[arcane] and #[rite] functions, and your crate can keep #![forbid(unsafe_code)]. A token is the proof that the CPU has its features; safe code gets one only once the features are confirmed, normally by summon(). The single unsafe block in each #[arcane] expansion is generated by the macro, and the token parameter is what makes it sound. The safety model explains the expansion, what it relies on, and how it is checked.

Features

std is enabled by default. avx512 enables native intrinsic-wrapper and macro support. Token names and macros are always available; unsupported tokens cannot be summoned. testable_dispatch enables the tier-testing facilities. It makes every summon() read a cache, even the x86-64 baseline token’s, which is otherwise a constant, and Cargo turns it on for the whole build graph. Enable it from [dev-dependencies] or a dev-only feature, never from [dependencies].

Re-exports

pub use tokens::CompileTimeGuaranteedError;

pub use tokens::DisableAllSimdError;

pub use tokens::IntoConcreteToken;

pub use tokens::SimdToken;

pub use tokens::dangerously_disable_tokens_except_wasm;

pub use tokens::Has128BitSimd;Deprecated

pub use tokens::Has256BitSimd;Deprecated

pub use tokens::Has512BitSimd;Deprecated

pub use tokens::HasX64V2;

pub use tokens::HasX64V4;

pub use tokens::HasArm64V2;

pub use tokens::HasArm64V3;

pub use tokens::HasNeon;

pub use tokens::HasNeonAes;

pub use tokens::HasNeonSha3;

pub use tokens::Arm64;

pub use tokens::Arm64V2Token;

pub use tokens::Arm64V3Token;

pub use tokens::Avx2FmaToken;Deprecated

pub use tokens::Desktop64;

pub use tokens::NeonAesToken;

pub use tokens::NeonCrcToken;

pub use tokens::NeonSha3Token;

pub use tokens::NeonToken;

pub use tokens::ScalarToken;

pub use tokens::Sse2Token;Deprecated

pub use tokens::Wasm128RelaxedToken;

pub use tokens::Wasm128Token;

pub use tokens::X64CryptoToken;

pub use tokens::X64V1Token;

pub use tokens::X64V2Token;

pub use tokens::X64V3CryptoToken;

pub use tokens::X64V3GfniCryptoToken;

pub use tokens::X64V3Token;

pub use tokens::Avx512Fp16Token;

pub use tokens::Avx512Token;

pub use tokens::Server64;

pub use tokens::X64V4Token;

pub use tokens::X64V4xToken;

Modules

detectAArch64 or x86 or x86-64

Optimized feature detection macros.

intrinsics

Combined intrinsics: core::arch + safe_unaligned_simd in one namespace.

prelude

One import for everything you need to write SIMD with archmage.

testingstd

Test utilities for exhaustive SIMD token permutation testing.

tokens

SIMD capability tokens

Macros

attuned

Invoke a family using the enclosing attune feature context, or runtime proof entries outside one. Explicit tier lists never acquire an implicit fallback. Annotated callers can reuse a named concrete token or an IntoConcreteToken parameter without CPU detection. Covered calls remain direct. using(token) overrides inference and is required to supply proof in unannotated callers.

dispatch_variant

Descriptive alias for incant!.

incant

Dispatch to platform-specific SIMD variants.

is_aarch64_feature_availableAArch64 or x86 or x86-64

Checks if an AArch64 CPU feature is available, with compile-time optimization.

is_x86_feature_availableAArch64 or x86 or x86-64

Checks if an x86 CPU feature is available, with compile-time optimization.

reattune

Explicitly reconsider stronger tiers at runtime, retaining a guaranteed fallback covered by the caller’s feature context (or scalar outside one).

simd_route

Legacy alias for incant!.

Attribute Macros

arcane

Mark a function as an arcane SIMD function.

attune

Establish a feature context or generate explicit direct/proof/dispatch outputs.

autoversion

Let the compiler auto-vectorize scalar code for each architecture.

magetypes

Generate platform-specific variants from a function by replacing Token.

rite

Annotate inner SIMD helpers called from #[arcane] functions.

token_target_features

Descriptive alias for [rite].

token_target_features_boundary

Descriptive alias for [arcane].