`portable_simd`

#86656)## Expand description

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`

^{1} 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.

`_mm_min_ps(x, y)`

is equivalent to`x.simd_lt(y).select(x, y)`

↩

## Modules§

- cmpExperimentalTraits for comparing and ordering vectors.
- numExperimentalTraits for vectors with numeric elements.
- preludeExperimentalThe portable SIMD prelude.
- ptrExperimentalTraits for vectors of pointers.

## Macros§

- simd_swizzleExperimentalConstructs a new SIMD vector by copying elements from selected elements in other vectors.

## Structs§

- LaneCountExperimentalSpecifies the number of lanes in a SIMD vector as a type.
- MaskExperimentalA SIMD vector mask for
`N`

elements of width specified by`Element`

. - SimdExperimentalA SIMD vector with the shape of
`[T; N]`

but the operations of`T`

.

## Traits§

- MaskElementExperimentalMarker trait for types that may be used as SIMD mask elements.
- SimdCastExperimentalSupporting trait for
`Simd::cast`

. Typically doesn’t need to be used directly. - SimdElementExperimentalMarker trait for types that may be used as SIMD vector elements.
- StdFloatExperimentalThis 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`

. - SupportedLaneCountExperimentalStatically guarantees that a lane count is marked as supported.
- SwizzleExperimentalCreate a vector from the elements of another vector.
- ToBytesExperimentalConvert SIMD vectors to vectors of bytes

## Type Aliases§

- f32x1ExperimentalA SIMD vector with one element of type
`f32`

. - f32x2ExperimentalA SIMD vector with two elements of type
`f32`

. - f32x4ExperimentalA SIMD vector with four elements of type
`f32`

. - f32x8ExperimentalA SIMD vector with eight elements of type
`f32`

. - f32x16ExperimentalA SIMD vector with 16 elements of type
`f32`

. - f32x32ExperimentalA SIMD vector with 32 elements of type
`f32`

. - f32x64ExperimentalA SIMD vector with 64 elements of type
`f32`

. - f64x1ExperimentalA SIMD vector with one element of type
`f64`

. - f64x2ExperimentalA SIMD vector with two elements of type
`f64`

. - f64x4ExperimentalA SIMD vector with four elements of type
`f64`

. - f64x8ExperimentalA SIMD vector with eight elements of type
`f64`

. - f64x16ExperimentalA SIMD vector with 16 elements of type
`f64`

. - f64x32ExperimentalA SIMD vector with 32 elements of type
`f64`

. - f64x64ExperimentalA SIMD vector with 64 elements of type
`f64`

. - i8x1ExperimentalA SIMD vector with one element of type
`i8`

. - i8x2ExperimentalA SIMD vector with two elements of type
`i8`

. - i8x4ExperimentalA SIMD vector with four elements of type
`i8`

. - i8x8ExperimentalA SIMD vector with eight elements of type
`i8`

. - i8x16ExperimentalA SIMD vector with 16 elements of type
`i8`

. - i8x32ExperimentalA SIMD vector with 32 elements of type
`i8`

. - i8x64ExperimentalA SIMD vector with 64 elements of type
`i8`

. - i16x1ExperimentalA SIMD vector with one element of type
`i16`

. - i16x2ExperimentalA SIMD vector with two elements of type
`i16`

. - i16x4ExperimentalA SIMD vector with four elements of type
`i16`

. - i16x8ExperimentalA SIMD vector with eight elements of type
`i16`

. - i16x16ExperimentalA SIMD vector with 16 elements of type
`i16`

. - i16x32ExperimentalA SIMD vector with 32 elements of type
`i16`

. - i16x64ExperimentalA SIMD vector with 64 elements of type
`i16`

. - i32x1ExperimentalA SIMD vector with one element of type
`i32`

. - i32x2ExperimentalA SIMD vector with two elements of type
`i32`

. - i32x4ExperimentalA SIMD vector with four elements of type
`i32`

. - i32x8ExperimentalA SIMD vector with eight elements of type
`i32`

. - i32x16ExperimentalA SIMD vector with 16 elements of type
`i32`

. - i32x32ExperimentalA SIMD vector with 32 elements of type
`i32`

. - i32x64ExperimentalA SIMD vector with 64 elements of type
`i32`

. - i64x1ExperimentalA SIMD vector with one element of type
`i64`

. - i64x2ExperimentalA SIMD vector with two elements of type
`i64`

. - i64x4ExperimentalA SIMD vector with four elements of type
`i64`

. - i64x8ExperimentalA SIMD vector with eight elements of type
`i64`

. - i64x16ExperimentalA SIMD vector with 16 elements of type
`i64`

. - i64x32ExperimentalA SIMD vector with 32 elements of type
`i64`

. - i64x64ExperimentalA SIMD vector with 64 elements of type
`i64`

. - isizex1ExperimentalA SIMD vector with one element of type
`isize`

. - isizex2ExperimentalA SIMD vector with two elements of type
`isize`

. - isizex4ExperimentalA SIMD vector with four elements of type
`isize`

. - isizex8ExperimentalA SIMD vector with eight elements of type
`isize`

. - isizex16ExperimentalA SIMD vector with 16 elements of type
`isize`

. - isizex32ExperimentalA SIMD vector with 32 elements of type
`isize`

. - isizex64ExperimentalA SIMD vector with 64 elements of type
`isize`

. - mask8x1ExperimentalA SIMD mask with one element for vectors with 8-bit element types.
- mask8x2ExperimentalA SIMD mask with two elements for vectors with 8-bit element types.
- mask8x4ExperimentalA SIMD mask with four elements for vectors with 8-bit element types.
- mask8x8ExperimentalA SIMD mask with eight elements for vectors with 8-bit element types.
- mask8x16ExperimentalA SIMD mask with 16 elements for vectors with 8-bit element types.
- mask8x32ExperimentalA SIMD mask with 32 elements for vectors with 8-bit element types.
- mask8x64ExperimentalA SIMD mask with 64 elements for vectors with 8-bit element types.
- mask16x1ExperimentalA SIMD mask with one element for vectors with 16-bit element types.
- mask16x2ExperimentalA SIMD mask with two elements for vectors with 16-bit element types.
- mask16x4ExperimentalA SIMD mask with four elements for vectors with 16-bit element types.
- mask16x8ExperimentalA SIMD mask with eight elements for vectors with 16-bit element types.
- mask16x16ExperimentalA SIMD mask with 16 elements for vectors with 16-bit element types.
- mask16x32ExperimentalA SIMD mask with 32 elements for vectors with 16-bit element types.
- mask16x64ExperimentalA SIMD mask with 64 elements for vectors with 16-bit element types.
- mask32x1ExperimentalA SIMD mask with one element for vectors with 32-bit element types.
- mask32x2ExperimentalA SIMD mask with two elements for vectors with 32-bit element types.
- mask32x4ExperimentalA SIMD mask with four elements for vectors with 32-bit element types.
- mask32x8ExperimentalA SIMD mask with eight elements for vectors with 32-bit element types.
- mask32x16ExperimentalA SIMD mask with 16 elements for vectors with 32-bit element types.
- mask32x32ExperimentalA SIMD mask with 32 elements for vectors with 32-bit element types.
- mask32x64ExperimentalA SIMD mask with 64 elements for vectors with 32-bit element types.
- mask64x1ExperimentalA SIMD mask with one element for vectors with 64-bit element types.
- mask64x2ExperimentalA SIMD mask with two elements for vectors with 64-bit element types.
- mask64x4ExperimentalA SIMD mask with four elements for vectors with 64-bit element types.
- mask64x8ExperimentalA SIMD mask with eight elements for vectors with 64-bit element types.
- mask64x16ExperimentalA SIMD mask with 16 elements for vectors with 64-bit element types.
- mask64x32ExperimentalA SIMD mask with 32 elements for vectors with 64-bit element types.
- mask64x64ExperimentalA SIMD mask with 64 elements for vectors with 64-bit element types.
- masksizex1ExperimentalA SIMD mask with one element for vectors with pointer-sized element types.
- masksizex2ExperimentalA SIMD mask with two elements for vectors with pointer-sized element types.
- masksizex4ExperimentalA SIMD mask with four elements for vectors with pointer-sized element types.
- masksizex8ExperimentalA SIMD mask with eight elements for vectors with pointer-sized element types.
- masksizex16ExperimentalA SIMD mask with 16 elements for vectors with pointer-sized element types.
- masksizex32ExperimentalA SIMD mask with 32 elements for vectors with pointer-sized element types.
- masksizex64ExperimentalA SIMD mask with 64 elements for vectors with pointer-sized element types.
- u8x1ExperimentalA SIMD vector with one element of type
`u8`

. - u8x2ExperimentalA SIMD vector with two elements of type
`u8`

. - u8x4ExperimentalA SIMD vector with four elements of type
`u8`

. - u8x8ExperimentalA SIMD vector with eight elements of type
`u8`

. - u8x16ExperimentalA SIMD vector with 16 elements of type
`u8`

. - u8x32ExperimentalA SIMD vector with 32 elements of type
`u8`

. - u8x64ExperimentalA SIMD vector with 64 elements of type
`u8`

. - u16x1ExperimentalA SIMD vector with one element of type
`u16`

. - u16x2ExperimentalA SIMD vector with two elements of type
`u16`

. - u16x4ExperimentalA SIMD vector with four elements of type
`u16`

. - u16x8ExperimentalA SIMD vector with eight elements of type
`u16`

. - u16x16ExperimentalA SIMD vector with 16 elements of type
`u16`

. - u16x32ExperimentalA SIMD vector with 32 elements of type
`u16`

. - u16x64ExperimentalA SIMD vector with 64 elements of type
`u16`

. - u32x1ExperimentalA SIMD vector with one element of type
`u32`

. - u32x2ExperimentalA SIMD vector with two elements of type
`u32`

. - u32x4ExperimentalA SIMD vector with four elements of type
`u32`

. - u32x8ExperimentalA SIMD vector with eight elements of type
`u32`

. - u32x16ExperimentalA SIMD vector with 16 elements of type
`u32`

. - u32x32ExperimentalA SIMD vector with 32 elements of type
`u32`

. - u32x64ExperimentalA SIMD vector with 64 elements of type
`u32`

. - u64x1ExperimentalA SIMD vector with one element of type
`u64`

. - u64x2ExperimentalA SIMD vector with two elements of type
`u64`

. - u64x4ExperimentalA SIMD vector with four elements of type
`u64`

. - u64x8ExperimentalA SIMD vector with eight elements of type
`u64`

. - u64x16ExperimentalA SIMD vector with 16 elements of type
`u64`

. - u64x32ExperimentalA SIMD vector with 32 elements of type
`u64`

. - u64x64ExperimentalA SIMD vector with 64 elements of type
`u64`

. - usizex1ExperimentalA SIMD vector with one element of type
`usize`

. - usizex2ExperimentalA SIMD vector with two elements of type
`usize`

. - usizex4ExperimentalA SIMD vector with four elements of type
`usize`

. - usizex8ExperimentalA SIMD vector with eight elements of type
`usize`

. - usizex16ExperimentalA SIMD vector with 16 elements of type
`usize`

. - usizex32ExperimentalA SIMD vector with 32 elements of type
`usize`

. - usizex64ExperimentalA SIMD vector with 64 elements of type
`usize`

.