token.invoke_rite() — closure-based #[target_feature] entry without proc macros

[lilith]

Summary

Add a invoke_rite() method to all tokens that wraps a closure in the
appropriate #[target_feature] boundary, providing #[arcane]-like
functionality without proc macros.

Motivation

jxl-rs's SimdDescriptor::call() pattern demonstrates a clean way to
create a #[target_feature] boundary using only a method + closure:

if let Some(token) = Desktop64::summon() {
    token.invoke_rite(|t| process_simd(t, data))
}

This is useful when:

• A proc-macro dependency is undesirable (lightweight crates)
• Inline one-off dispatch is cleaner than a named #[arcane] function
• Users want to experiment without pulling in archmage-macros

#[arcane] remains the recommended approach for named entry points.
invoke_rite() fills the gap for inline/closure use cases.

Design Sketch

impl Desktop64 {
    pub fn invoke_rite<R>(self, f: impl FnOnce(Self) -> R) -> R {
        #[target_feature(enable = "avx2,fma,bmi1,bmi2,f16c")]
        unsafe fn inner<R>(
            token: Desktop64,
            f: impl FnOnce(Desktop64) -> R,
        ) -> R {
            f(token)
        }
        // SAFETY: Token existence proves CPU features are available.
        unsafe { inner(self, f) }
    }
}

Generated per-token by xtask from token-registry.toml, like everything else.

Open Questions

• Naming: invoke_rite(), call(), enter(), cast()?
  Thematic preference leans toward invoke_rite or cast.
• Trait vs inherent: Should this be on the SimdToken trait or per-token inherent methods?
  Trait method would require GATs or boxing; inherent methods are simpler.
• Inlining: Should the generated code use #[inline(never)] (like jxl-rs) or
  #[inline]? jxl-rs uses #[inline(never)] to prevent the
  feature-enabled code from inlining back into the non-feature caller.
  This matches #[arcane] semantics (optimization boundary at entry).

Prior Art

• jxl-rs SimdDescriptor::call() — same pattern, #[inline(never)]
• archmage #[arcane] — proc-macro version of the same idea

[lilith]

we don't need unsafe before fn. we are calling it with unsafe without matching target features. we rely on compiler to catch mismatch in target features and make f() fail at compile time if it doesn't have rite... hmm, if itis a closure though, that won't work???

[lilith]

Weighing In on the Open Questions

Naming: invoke_rite

I'd go with invoke_rite. Rationale:

• call() is too generic and conflicts with Fn::call() mentally
• enter() implies a scope/context manager that you later exit — misleading for a one-shot closure
• cast() conflicts with type casting vocabulary everywhere in Rust
• invoke_rite() says exactly what it does in the archmage idiom: "invoke a rite" (a ceremony that enables your powers). It parallels #[rite] which is the attribute form of the same concept

The _rite suffix also signals to users that this creates the same #[target_feature] boundary that #[rite] does — an optimization boundary at the entry point.

For ScalarToken, invoke_rite() is a no-op passthrough (no #[target_feature] to add). This is correct — scalar "rites" have no special requirements.

Trait vs inherent: Inherent methods, generated by xtask

Each token needs different #[target_feature(enable = "...")] on its inner function. You can't express that with a single trait method — the feature string varies per token. Generated inherent impl blocks are the only path.

Stubs on wrong-arch get a trivial invoke_rite that calls unreachable!() — the token can never exist there, so the method can never be called. This matches how #[arcane] generates unreachable stubs cross-arch.

Inlining: Match #[arcane] semantics (no #[inline(never)])

jxl-rs uses #[inline(never)] on its call() inner function, but that's unnecessary. The #[target_feature] attribute already prevents LLVM from inlining a feature-enabled function into a non-feature-enabled caller — that's the whole point of the attribute. LLVM respects feature mismatches and won't inline across them.

#[arcane] generates its inner function with no explicit inlining attribute (neither #[inline] nor #[inline(never)]). The outer wrapper has no #[inline] either. This is the right default:

• The inner function's #[target_feature] creates the optimization boundary
• LLVM decides inlining based on cost analysis
• #[inline(never)] would pessimize cases where the caller does have matching features

So: match #[arcane] — no explicit #[inline] / #[inline(never)] on the inner function.

[lilith]

Resolved in 4fb3da0. Added invoke_rite() to all 16 tokens + ScalarToken.

Generates per-token from token-registry.toml. Each token gets a method that wraps a closure in the correct #[target_feature] boundary:

if let Some(token) = Desktop64::summon() {
    token.invoke_rite(|t| process_simd(t, data))
}

7 tests cover: scalar passthrough, state capture, V1/V3 basic use, complex return types, token passthrough, nested invoke_rite.

[lilith]

Closing as won't-fix — this design is fundamentally unsound.

invoke_rite was intended to provide #[arcane] semantics without proc macros: wrap a closure in a #[target_feature] boundary so intrinsics become safe inside. After implementation and review, we discovered this cannot work in Rust's type system. The feature has been removed in 88eb32c.

The three dead ends

1. Closures don't inherit #[target_feature] from their call site.

Closures inherit #[target_feature] from the function where they're defined, not where they're called. The closure passed to invoke_rite is defined in the caller's scope (no #[target_feature]). Calling it from inside __invoke_rite_inner (which has #[target_feature]) doesn't retroactively apply features to the closure body.

token.invoke_rite(|_t| {
    _mm256_setzero_ps()  // NOT safe — closure was defined outside #[target_feature]
});

2. #[target_feature] functions don't implement Fn traits.

rust-lang/rust#73306 intentionally prevents #[target_feature] functions from implementing Fn/FnOnce/FnMut to prevent them from escaping into contexts where CPU features aren't available. This means you can't pass a #[rite] function to invoke_rite either.

#[rite]
fn my_kernel(t: X64V3Token) -> f32 { ... }

// COMPILE ERROR: #[target_feature] functions do not implement the Fn traits
token.invoke_rite(my_kernel);

3. No viable alternative exists.

Approach	Has #[target_feature]?	Implements FnOnce?	Can capture?
Regular closure	No	Yes	Yes
Closure inside #[target_feature] fn	Yes	No	Yes
#[rite] named function	Yes	No	No
Regular named function	No	Yes	No

No row has all three. macro_rules! can't help either — the expansion still occurs at the caller's scope, and fn items can't capture variables or infer return types.

Why #[arcane] works and this can't

#[arcane] is a proc macro that rewrites your code into a #[target_feature] inner function body. Your code is the inner function — it's not passed in from outside. That's the only way to get #[target_feature] applied to user code without the user writing it themselves.

There is no runtime, library-level, or macro_rules! mechanism that can retroactively apply #[target_feature] to code defined in a different compilation context.