Crate multiversion

source ·
Expand description

This crate provides the multiversion attribute for implementing 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.

§Cargo features

There is one cargo feature, std, enabled by default. When enabled, multiversion will use CPU feature detection at runtime to dispatch the appropriate function. Disabling this feature will only allow compile-time function dispatch using #[cfg(target_feature)] and can be used in #[no_std] crates.

§Capabilities

The intention of this crate is to allow nearly any function to be multiversioned. The following cases are not supported:

  • functions that use self or Self
  • impl Trait return types (arguments are fine)

If any other functions do not work please file an issue on GitHub.

§Target specification strings

Targets are specified as a combination of architecture (as specified in target_arch) and feature (as specified in target_feature).

A target can be specified as:

  • "arch"
  • "arch+feature"
  • "arch+feature1+feature2"

A particular CPU can also be specified with a slash:

  • "arch/cpu"
  • "arch/cpu+feature"

The following are some valid target specification strings:

  • "x86" (matches the "x86" architecture)
  • "x86_64+avx+avx2" (matches the "x86_64" architecture with the "avx" and "avx2" features)
  • "x86_64/x86-64-v2" (matches the "x86_64" architecture with the "x86-64-v2" CPU)
  • "x86/i686+avx" (matches the "x86" architecture with the "i686" CPU and "avx" feature)
  • "arm+neon" (matches the arm architecture with the "neon" feature

A complete list of available target features and CPUs is available in the target-features crate documentation.

Modules§

  • target
    Information related to the current target.

Attribute Macros§

  • inherit_target
    Inherit the target_feature attributes of the selected target in a multiversioned function.
  • multiversion
    Provides function multiversioning.
  • target
    Provides a less verbose equivalent to the cfg(target_arch) and target_feature attributes.