Multiversion

Function multiversioning attribute macros for Rust.

What is function multiversioning?

Many CPU architectures have a variety of instruction set extensions that provide additional functionality. Common examples are single instruction, multiple data (SIMD) extensions such as SSE and AVX on x86/x86-64 and NEON on ARM/AArch64. When available, these extended features can provide significant speed improvements to some functions. These optional features cannot be haphazardly compiled into programs--executing an unsupported instruction will result in a crash.

Function multiversioning is the practice of compiling multiple versions of a function with various features enabled and safely detecting which version to use at runtime.

Features

Dynamic dispatching, using runtime CPU feature detection
Static dispatching, avoiding repeated feature detection for nested multiversioned functions (and allowing inlining!)
Support for generic and async functions

Limitations

No support for member functions or associated functions (or any other functions not at module-level)
No support for impl Trait

Example

Automatic function multiversioning with the target_clones attribute, similar to GCC's target_clones attribute:

use multiversion::target_clones;

#[target_clones("[x86|x86_64]+avx", "x86+sse")]
fn square(x: &mut [f32]) {
    for v in x {
        *v *= *v;
    }
}

Manual function multiversioning with the multiversion and target attributes:

use multiversion::{multiversion, target};

#[target("[x86|x86_64]+avx")]
unsafe fn square_avx(x: &mut [f32]) {
    for v in x {
        *v *= *v;
    }
}

#[target("x86+sse")]
unsafe fn square_sse(x: &mut [f32]) {
    for v in x {
        *v *= *v;
    }
}

#[multiversion(
    "[x86|x86_64]+avx" => square_avx,
    "x86+sse" => square_sse
)]
fn square(x: &mut [f32]) {
    for v in x {
        *v *= *v;
    }
}

License

Multiversion is distributed under the terms of both the MIT license and the Apache License (Version 2.0).