Skip to main content

Crate multiversion

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

The cargo feature std is 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.

The target-features feature enables selected_target! and adds the optional target-features dependency.

The nightly feature adds nightly-only targets to targets = "simd". On affected targets, the consuming crate must also enable the corresponding *_target_feature and stdarch_*_feature_detection nightly compiler features.

§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"

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)
  • "arm+neon" (matches the arm architecture with the "neon" feature

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.