| lib.rs |
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](target_features::docs).
[`target`]: attr.target.html
[`multiversion`]: attr.multiversion.html
[`target_arch`]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_arch
[`target_feature`]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_feature |
9695 |
- |