1. Attune a Kernel

Generate a callable dispatcher around a complete loop

#[attune(dispatch)] gives your function a normal call interface and generates its CPU-specific implementations. Put the whole loop in that function.

Legacy equivalent: #[autoversion(v3, neon, wasm128, scalar)] provides the same dispatcher role; generated variant names and visibility differ.

Install

This guide uses the stable 0.9.31 API:

[dependencies]
archmage = "=0.9.31"

Write and call a kernel

#![forbid(unsafe_code)]
use archmage::prelude::*;

#[attune(dispatch)]
pub fn scale(values: &mut [f32], factor: f32) {
    for value in values {
        *value *= factor;
    }
}

let mut values = [2.0, 4.0, 6.0];
scale(&mut values, 0.5);
assert_eq!(values, [1.0, 2.0, 3.0]);

Callers pass ordinary data. They do not need to select a tier, summon a token, or write unsafe.

Compare the source with its expansion to see the public dispatcher and private feature bodies.

Archmage generates implementations for V3 (AVX2 and FMA), NEON, WASM SIMD128, and scalar, omitting variants for other architectures. The dispatcher chooses an available tier and calls its body. Scalar is the fallback. AVX-512 is an explicit addition, not part of this default set.

The loop is still ordinary Rust: LLVM decides whether to vectorize it. Explicit vectors give you lane-wise operations when you want to write them yourself. Neither form guarantees a speedup; measure the complete kernel on your inputs.

Names, imports, and explicit tiers

This guide uses use archmage::prelude::*; and bare macro names. Explicit imports or fully qualified archmage::attuned! calls also work; keep the call macro in scope inside annotated bodies too.

For a single helper, #[attune] fn helper_v3(...) infers a V3 feature body; helper_v3_t(...) infers a token-taking proof wrapper. A Token parameter alone does not select the tier. Use #[attune(v3)] when you want an arbitrary name, or #[attune(wrap)] to derive features from a concrete proof parameter.

For default families, prefer attuned!(helper(...)): it considers V3, NEON, WASM SIMD128, then scalar, filtered by architecture and availability. Use an explicit list for AVX-512 or a smaller family. See which AVX-512 tier and the per-tier width split. If migrating direct calls to legacy suffixed variants, read preserving those callers before switching to dispatcher-only output.

Keep the boundary around the work

Call scale once for the slice. Calling a dispatcher once per element adds selection and call boundaries to the inner loop. Helpers inside the selected body can keep that context and be eligible for inlining.

Next: Stay in context.

Found an error or it needs a clarification? Open an issue on GitHub.
Substantiated corrections will be incorporated with attribution.