Enum Level 

#[non_exhaustive]
pub enum Level {
    Fallback(Fallback),
    Sse2(Sse2),
    Sse4_2(Sse4_2),
    Avx512(Avx512),
    Avx2(Avx2),
}

The level enum with the specific SIMD capabilities available.

The contained values serve as a proof that the associated target feature is available.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Fallback(Fallback)

Available on crate feature force_support_fallback or neither AArch64 and target feature neon, nor target feature fxsr and target feature sse2 and (x86 or x86-64), nor WebAssembly and target feature simd128 only.

Scalar fallback level, i.e. no supported SIMD features are to be used.

This variant is absent on targets that supports a higher baseline (aarch64-*, i686-*, x86_64-*, WASM with SIMD) unless the force_support_fallback Cargo feature is enabled. Instead of matching on this variant, call is_fallback which is always available.

This can be created with Level::fallback.

Sse2(Sse2)

Available on x86 or x86-64 only.

The SSE2 instruction set on (32 and 64 bit) x86.

This is the baseline for i686 and x86-64 targets.

Sse4_2(Sse4_2)

Available on x86 or x86-64 only.

The SSE4.2 instruction set on (32 and 64 bit) x86, plus popcnt and cmpxchg16b. Also known as x86-64-v2.

All production CPUs with SSE4.2 also support the other two extensions, so it is safe to require them.

Avx512(Avx512)

Available on x86 or x86-64 only.

Ice Lake-class AVX-512 on (32 and 64 bit) x86.

Avx2(Avx2)

Available on x86 or x86-64 only.

The x86-64-v3 instruction set on (32 and 64 bit) x86, including AVX2 and FMA.

Implementations

impl Level

pub fn new() -> Self

Available on WebAssembly or crate feature std only.

Return the best SIMD level available on the CPU. This value should be passed to dispatch.

On x86 and x86-64 targets, this detects the available CPU features on the first call and caches the result. Other targets return their strongest statically supported level. This may change in the future if runtime-detected levels for other platforms are added.

This function requires the standard library on targets other than wasm32. On wasm32, the available level is known statically, so the standard library isn’t required.

On x86-64, it is sometimes possible to detect the available features on #[no_std] by parsing the output of cpuid instruction, but this function does not do that. If you do this, you can create the SIMD token via assume_supported and then get the level from it.

Libraries that use SIMD on #[no_std] should let the user pass the appropriate SIMD level the user detected through other means (e.g. cpuid), to avoid using the fallback level when a better SIMD level is available in hardware.

Examples found in repository

examples/srgb.rs (line 89)

fn main() {
    let level = Level::new();
    let rgba = [0.1, -0.2, 0.001, 0.4];
    let srgb = dispatch!(level, simd=> to_srgb(simd, rgba));
    println!("{srgb:?}");
}

examples/disable_avx2_for_one_function.rs (line 39)

fn main() {
    let level = Level::new();
    let inp = [
        0.1, -0.2, 0.001, 0.4, 1., 2., 3., 4., 5., 6., 7., 8., 9., 10., 11., 12.,
    ];
    let mut out = [0.; 16];
    dispatch!(level, simd => disable_avx2(simd, &inp, &mut out));

    println!("{out:?}");
}

examples/sigmoid.rs (line 37)

fn main() {
    let level = Level::new();
    let inp = [
        0.1, -0.2, 0.001, 0.4, 1., 2., 3., 4., 5., 6., 7., 8., 9., 10., 11., 12., 13., 14.,
    ];
    let mut out = [0.; 18];
    // dispatch! selects the best implementation for the CPU we're running on
    dispatch!(level, simd => sigmoid(simd, &inp, &mut out));

    println!("{out:?}");
}

examples/sigmoid_generic.rs (line 44)

fn main() {
    let level = Level::new();
    let input_f32 = [
        0.1_f32, -0.2, 0.001, 0.4, 1., 2., 3., 4., 5., 6., 7., 8., 9., 10., 11., 12., 13.,
    ];
    let input_f64 = input_f32.map(f64::from);
    let mut output_f32 = [0.0; 17];
    let mut output_f64 = [0.0; 17];

    sigmoid(level, &input_f32, &mut output_f32);
    sigmoid(level, &input_f64, &mut output_f64);

    println!("f32: {output_f32:?}");
    println!("f64: {output_f64:?}");
}

examples/gain_generic.rs (line 15)

fn main() {
    let level = Level::new();
    dispatch!(level, simd => {
        // f32 vectors can be any length
        let samples = f32x4::from_slice(simd, &[0.1, -0.2, 0.3, -0.4]);
        let output = apply_gain(samples, 0.5);
        println!("f32x4: {output:?}");

        let samples = f32x16::from_slice(
            simd,
            &[
                0.1, -0.2, 0.3, -0.4, 0.5, -0.6, 0.7, -0.8,
                0.9, -1.0, 1.1, -1.2, 1.3, -1.4, 1.5, -1.6,
            ],
        );
        let output = apply_gain(samples, 0.5);
        println!("f32x16: {output:?}");

        // f64 vectors work too through the same helper
        let samples = f64x2::from_slice(simd, &[0.1, -0.2]);
        let output = apply_gain(samples, 0.5);
        println!("f64x2: {output:?}");
    });
}

pub fn try_detect() -> Option<Self>

Get the target feature level suitable for this run.

Should be used in libraries if they wish to handle the case where target features cannot be detected at runtime. Most users should prefer new. This is discussed in more detail in new’s documentation.

pub fn is_fallback(self) -> bool

Check whether this is the Fallback level; that is, whether no better feature level could be statically or dynamically detected. This is useful if there’s a scalarized version of your algorithm that runs faster if SIMD isn’t supported.

This method is always available, even when the fallback backend is not compiled. In that case, it always returns false.

pub fn as_sse2(self) -> Option<Sse2>

Available on x86 or x86-64 only.

If this is a proof that SSE2 (or better) is available, access that instruction set.

See Sse2::assume_supported for the exact list of CPU features this token enables.

This method should be preferred over matching against the Sse2 variant of self, because if the CPU supports a superset of SSE2 (e.g. SSE4.2, AVX2, or AVX-512), this method will return the SSE2 token even if that “better” instruction set is available.

This can be used in combination with the kernel macro to safely access level-specific SIMD intrinsics.

pub fn as_sse4_2(self) -> Option<Sse4_2>

Available on x86 or x86-64 only.

If this is a proof that x86-64-v2 feature set (or better) is available, access that instruction set.

See Sse4_2::assume_supported for the exact list of CPU features this token enables.

This method should be preferred over matching against the Sse4_2 variant of self, because if the CPU supports a superset of SSE4.2 (e.g. AVX2 or AVX-512), this method will return the SSE4.2 token even if that “better” instruction set is available.

This can be used in combination with the kernel macro to safely access level-specific SIMD intrinsics.

Examples found in repository

examples/disable_avx2_for_one_function.rs (line 16)

fn disable_avx2<S: Simd>(simd: S, x: &[f32], out: &mut [f32]) {
    let level = simd.level();
    match level {
        #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
        // Downgrade AVX2 to SSE4.2 when calling `sigmoid()`
        Level::Avx2(_) => sigmoid(level.as_sse4_2().unwrap(), x, out),
        _ => sigmoid(simd, x, out),
    }
}

examples/srgb.rs (line 55)

fn copy_alpha<S: Simd>(a: f32x4<S>, b: f32x4<S>) -> f32x4<S> {
    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
    if let Some(sse4_2) = a.simd.level().as_sse4_2() {
        return copy_alpha_sse4_2(sse4_2, a.into(), b.into()).simd_into(a.simd);
    }

    #[cfg(target_arch = "aarch64")]
    if let Some(neon) = a.simd.level().as_neon() {
        return copy_alpha_neon(neon, a.into(), b.into()).simd_into(a.simd);
    }

    let mut result = a;
    result[3] = b[3];
    result
}

pub fn as_avx2(self) -> Option<Avx2>

Available on x86 or x86-64 only.

If this is a proof that the x86-64-v3 feature set (or better) is available, access that instruction set.

See Avx2::assume_supported for the exact list of CPU features this token enables.

This method should be preferred over matching against the Avx2 variant of self, because if the CPU supports a superset of AVX2 (e.g. AVX-512), this method will return the AVX2 token even if that “better” instruction set is available.

This can be used in combination with the kernel macro to safely access level-specific SIMD intrinsics.

pub fn as_avx512(self) -> Option<Avx512>

Available on x86 or x86-64 only.

If this is a proof that the Ice Lake AVX-512 feature set is available, access that instruction set.

See Avx512::assume_supported for the exact list of CPU features this token enables.

This can be used in combination with the kernel macro to safely access level-specific SIMD intrinsics.

pub const fn baseline() -> Self

Get the strongest statically supported SIMD level.

That is, if your compilation run ambiently declares that a target feature is enabled, this method will take that into account. In most cases, you should use Level::new or Level::try_detect. This method is mainly useful for libraries, where:

1. Your crate features request that you not use the standard library, i.e. doesn’t enable your "std" crate feature reason (so you can’t use Level::new and Level::try_detect returns None); AND
2. Your caller does not provide a Level; AND
3. The library doesn’t want to panic when it can’t find a SIMD level.

Note that in these cases, the library should clearly inform the integrator that it is using a fallback and so not getting optimal performance (e.g. by panicking if debug_assertions are enabled, and emitting a log with the “error” level otherwise). The messages given should also provide actionable fixes, such as pointing to the entry-point which provides a Level, or your "std" feature.

Note that this is unaffected by the force-support-fallback feature. Instead, you should use Level::fallback if you require the fallback level.

pub const fn fallback() -> Self

Available on crate feature force_support_fallback only.

Create a scalar fallback level, which uses no SIMD instructions.

This is primarily intended for tests; most users should prefer Level::new or Level::baseline.

Note that enabling the scalar fallback does not mean that the fallback branch will not contain SIMD instructions. This is because the “ambient” compilation environment has SIMD instructions available, which may be utilised by LLVM to auto-vectorise that path.

Trait Implementations

impl Clone for Level

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Level

impl Debug for Level

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.