Module std::simd

🔬This is a nightly-only experimental API. (portable_simd #86656)

Portable SIMD module.

This module offers a portable abstraction for SIMD operations that is not bound to any particular hardware architecture.

What is “portable”?

This module provides a SIMD implementation that is fast and predictable on any target.

Portable SIMD works on every target

Unlike target-specific SIMD in std::arch, portable SIMD compiles for every target. In this regard, it is just like “regular” Rust.

Portable SIMD is consistent between targets

A program using portable SIMD can expect identical behavior on any target. In most regards, Simd<T, N> can be thought of as a parallelized [T; N] and operates like a sequence of T.

This has one notable exception: a handful of older architectures (e.g. armv7 and powerpc) flush subnormal f32 values to zero. On these architectures, subnormal f32 input values are replaced with zeros, and any operation producing subnormal f32 values produces zeros instead. This doesn’t affect most architectures or programs.

Operations use the best instructions available

Operations provided by this module compile to the best available SIMD instructions.

Portable SIMD is not a low-level vendor library, and operations in portable SIMD do not necessarily map to a single instruction. Instead, they map to a reasonable implementation of the operation for the target.

Consistency between targets is not compromised to use faster or fewer instructions. In some cases, std::arch will provide a faster function that has slightly different behavior than the std::simd equivalent. For example, _mm_min_ps¹ can be slightly faster than SimdFloat::simd_min, but does not conform to the IEEE standard also used by f32::min. When necessary, Simd<T, N> can be converted to the types provided by std::arch to make use of target-specific functions.

Many targets simply don’t have SIMD, or don’t support SIMD for a particular element type. In those cases, regular scalar operations are generated instead.

---

1. _mm_min_ps(x, y) is equivalent to x.simd_lt(y).select(x, y) ↩

Modules

• cmpExperimental
  Traits for comparing and ordering vectors.
• numExperimental
  Traits for vectors with numeric elements.
• preludeExperimental
  The portable SIMD prelude.
• ptrExperimental
  Traits for vectors of pointers.

Macros

• simd_swizzleExperimental
  Constructs a new SIMD vector by copying elements from selected elements in other vectors.

Structs

• LaneCountExperimental
  Specifies the number of lanes in a SIMD vector as a type.
• MaskExperimental
  A SIMD vector mask for N elements of width specified by Element.
• SimdExperimental
  A SIMD vector with the shape of [T; N] but the operations of T.

Traits

• MaskElementExperimental
  Marker trait for types that may be used as SIMD mask elements.
• SimdCastExperimental
  Supporting trait for Simd::cast. Typically doesn’t need to be used directly.
• SimdElementExperimental
  Marker trait for types that may be used as SIMD vector elements.
• StdFloatExperimental
  This trait provides a possibly-temporary implementation of float functions that may, in the absence of hardware support, canonicalize to calling an operating system’s math.h dynamically-loaded library (also known as a shared object). As these conditionally require runtime support, they should only appear in binaries built assuming OS support: std.
• SupportedLaneCountExperimental
  Statically guarantees that a lane count is marked as supported.
• SwizzleExperimental
  Create a vector from the elements of another vector.
• ToBytesExperimental
  Convert SIMD vectors to vectors of bytes

Type Aliases

• f32x1Experimental
  A SIMD vector with one element of type f32.
• f32x2Experimental
  A SIMD vector with two elements of type f32.
• f32x4Experimental
  A SIMD vector with four elements of type f32.
• f32x8Experimental
  A SIMD vector with eight elements of type f32.
• f32x16Experimental
  A SIMD vector with 16 elements of type f32.
• f32x32Experimental
  A SIMD vector with 32 elements of type f32.
• f32x64Experimental
  A SIMD vector with 64 elements of type f32.
• f64x1Experimental
  A SIMD vector with one element of type f64.
• f64x2Experimental
  A SIMD vector with two elements of type f64.
• f64x4Experimental
  A SIMD vector with four elements of type f64.
• f64x8Experimental
  A SIMD vector with eight elements of type f64.
• f64x16Experimental
  A SIMD vector with 16 elements of type f64.
• f64x32Experimental
  A SIMD vector with 32 elements of type f64.
• f64x64Experimental
  A SIMD vector with 64 elements of type f64.
• i8x1Experimental
  A SIMD vector with one element of type i8.
• i8x2Experimental
  A SIMD vector with two elements of type i8.
• i8x4Experimental
  A SIMD vector with four elements of type i8.
• i8x8Experimental
  A SIMD vector with eight elements of type i8.
• i8x16Experimental
  A SIMD vector with 16 elements of type i8.
• i8x32Experimental
  A SIMD vector with 32 elements of type i8.
• i8x64Experimental
  A SIMD vector with 64 elements of type i8.
• i16x1Experimental
  A SIMD vector with one element of type i16.
• i16x2Experimental
  A SIMD vector with two elements of type i16.
• i16x4Experimental
  A SIMD vector with four elements of type i16.
• i16x8Experimental
  A SIMD vector with eight elements of type i16.
• i16x16Experimental
  A SIMD vector with 16 elements of type i16.
• i16x32Experimental
  A SIMD vector with 32 elements of type i16.
• i16x64Experimental
  A SIMD vector with 64 elements of type i16.
• i32x1Experimental
  A SIMD vector with one element of type i32.
• i32x2Experimental
  A SIMD vector with two elements of type i32.
• i32x4Experimental
  A SIMD vector with four elements of type i32.
• i32x8Experimental
  A SIMD vector with eight elements of type i32.
• i32x16Experimental
  A SIMD vector with 16 elements of type i32.
• i32x32Experimental
  A SIMD vector with 32 elements of type i32.
• i32x64Experimental
  A SIMD vector with 64 elements of type i32.
• i64x1Experimental
  A SIMD vector with one element of type i64.
• i64x2Experimental
  A SIMD vector with two elements of type i64.
• i64x4Experimental
  A SIMD vector with four elements of type i64.
• i64x8Experimental
  A SIMD vector with eight elements of type i64.
• i64x16Experimental
  A SIMD vector with 16 elements of type i64.
• i64x32Experimental
  A SIMD vector with 32 elements of type i64.
• i64x64Experimental
  A SIMD vector with 64 elements of type i64.
• isizex1Experimental
  A SIMD vector with one element of type isize.
• isizex2Experimental
  A SIMD vector with two elements of type isize.
• isizex4Experimental
  A SIMD vector with four elements of type isize.
• isizex8Experimental
  A SIMD vector with eight elements of type isize.
• isizex16Experimental
  A SIMD vector with 16 elements of type isize.
• isizex32Experimental
  A SIMD vector with 32 elements of type isize.
• isizex64Experimental
  A SIMD vector with 64 elements of type isize.
• mask8x1Experimental
  A SIMD mask with one element for vectors with 8-bit element types.
• mask8x2Experimental
  A SIMD mask with two elements for vectors with 8-bit element types.
• mask8x4Experimental
  A SIMD mask with four elements for vectors with 8-bit element types.
• mask8x8Experimental
  A SIMD mask with eight elements for vectors with 8-bit element types.
• mask8x16Experimental
  A SIMD mask with 16 elements for vectors with 8-bit element types.
• mask8x32Experimental
  A SIMD mask with 32 elements for vectors with 8-bit element types.
• mask8x64Experimental
  A SIMD mask with 64 elements for vectors with 8-bit element types.
• mask16x1Experimental
  A SIMD mask with one element for vectors with 16-bit element types.
• mask16x2Experimental
  A SIMD mask with two elements for vectors with 16-bit element types.
• mask16x4Experimental
  A SIMD mask with four elements for vectors with 16-bit element types.
• mask16x8Experimental
  A SIMD mask with eight elements for vectors with 16-bit element types.
• mask16x16Experimental
  A SIMD mask with 16 elements for vectors with 16-bit element types.
• mask16x32Experimental
  A SIMD mask with 32 elements for vectors with 16-bit element types.
• mask16x64Experimental
  A SIMD mask with 64 elements for vectors with 16-bit element types.
• mask32x1Experimental
  A SIMD mask with one element for vectors with 32-bit element types.
• mask32x2Experimental
  A SIMD mask with two elements for vectors with 32-bit element types.
• mask32x4Experimental
  A SIMD mask with four elements for vectors with 32-bit element types.
• mask32x8Experimental
  A SIMD mask with eight elements for vectors with 32-bit element types.
• mask32x16Experimental
  A SIMD mask with 16 elements for vectors with 32-bit element types.
• mask32x32Experimental
  A SIMD mask with 32 elements for vectors with 32-bit element types.
• mask32x64Experimental
  A SIMD mask with 64 elements for vectors with 32-bit element types.
• mask64x1Experimental
  A SIMD mask with one element for vectors with 64-bit element types.
• mask64x2Experimental
  A SIMD mask with two elements for vectors with 64-bit element types.
• mask64x4Experimental
  A SIMD mask with four elements for vectors with 64-bit element types.
• mask64x8Experimental
  A SIMD mask with eight elements for vectors with 64-bit element types.
• mask64x16Experimental
  A SIMD mask with 16 elements for vectors with 64-bit element types.
• mask64x32Experimental
  A SIMD mask with 32 elements for vectors with 64-bit element types.
• mask64x64Experimental
  A SIMD mask with 64 elements for vectors with 64-bit element types.
• masksizex1Experimental
  A SIMD mask with one element for vectors with pointer-sized element types.
• masksizex2Experimental
  A SIMD mask with two elements for vectors with pointer-sized element types.
• masksizex4Experimental
  A SIMD mask with four elements for vectors with pointer-sized element types.
• masksizex8Experimental
  A SIMD mask with eight elements for vectors with pointer-sized element types.
• masksizex16Experimental
  A SIMD mask with 16 elements for vectors with pointer-sized element types.
• masksizex32Experimental
  A SIMD mask with 32 elements for vectors with pointer-sized element types.
• masksizex64Experimental
  A SIMD mask with 64 elements for vectors with pointer-sized element types.
• u8x1Experimental
  A SIMD vector with one element of type u8.
• u8x2Experimental
  A SIMD vector with two elements of type u8.
• u8x4Experimental
  A SIMD vector with four elements of type u8.
• u8x8Experimental
  A SIMD vector with eight elements of type u8.
• u8x16Experimental
  A SIMD vector with 16 elements of type u8.
• u8x32Experimental
  A SIMD vector with 32 elements of type u8.
• u8x64Experimental
  A SIMD vector with 64 elements of type u8.
• u16x1Experimental
  A SIMD vector with one element of type u16.
• u16x2Experimental
  A SIMD vector with two elements of type u16.
• u16x4Experimental
  A SIMD vector with four elements of type u16.
• u16x8Experimental
  A SIMD vector with eight elements of type u16.
• u16x16Experimental
  A SIMD vector with 16 elements of type u16.
• u16x32Experimental
  A SIMD vector with 32 elements of type u16.
• u16x64Experimental
  A SIMD vector with 64 elements of type u16.
• u32x1Experimental
  A SIMD vector with one element of type u32.
• u32x2Experimental
  A SIMD vector with two elements of type u32.
• u32x4Experimental
  A SIMD vector with four elements of type u32.
• u32x8Experimental
  A SIMD vector with eight elements of type u32.
• u32x16Experimental
  A SIMD vector with 16 elements of type u32.
• u32x32Experimental
  A SIMD vector with 32 elements of type u32.
• u32x64Experimental
  A SIMD vector with 64 elements of type u32.
• u64x1Experimental
  A SIMD vector with one element of type u64.
• u64x2Experimental
  A SIMD vector with two elements of type u64.
• u64x4Experimental
  A SIMD vector with four elements of type u64.
• u64x8Experimental
  A SIMD vector with eight elements of type u64.
• u64x16Experimental
  A SIMD vector with 16 elements of type u64.
• u64x32Experimental
  A SIMD vector with 32 elements of type u64.
• u64x64Experimental
  A SIMD vector with 64 elements of type u64.
• usizex1Experimental
  A SIMD vector with one element of type usize.
• usizex2Experimental
  A SIMD vector with two elements of type usize.
• usizex4Experimental
  A SIMD vector with four elements of type usize.
• usizex8Experimental
  A SIMD vector with eight elements of type usize.
• usizex16Experimental
  A SIMD vector with 16 elements of type usize.
• usizex32Experimental
  A SIMD vector with 32 elements of type usize.
• usizex64Experimental
  A SIMD vector with 64 elements of type usize.