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

- cmp
Experimental Traits for comparing and ordering vectors. - num
Experimental Traits for vectors with numeric elements. - prelude
Experimental The portable SIMD prelude. - ptr
Experimental Traits for vectors of pointers.

## Macros§

- simd_
swizzle Experimental Constructs a new SIMD vector by copying elements from selected elements in other vectors.

## Structs§

- Lane
Count Experimental Specifies the number of lanes in a SIMD vector as a type. - Mask
Experimental A SIMD vector mask for`N`

elements of width specified by`Element`

. - Simd
Experimental A SIMD vector with the shape of`[T; N]`

but the operations of`T`

.

## Traits§

- Mask
Element Experimental Marker trait for types that may be used as SIMD mask elements. - Simd
Cast Experimental Supporting trait for`Simd::cast`

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

. - Supported
Lane Count Experimental Statically guarantees that a lane count is marked as supported. - Swizzle
Experimental Creates a vector from the elements of another vector. - ToBytes
Experimental Converts SIMD vectors to vectors of bytes

## Type Aliases§

- f32x1
Experimental A SIMD vector with one element of type`f32`

. - f32x2
Experimental A SIMD vector with two elements of type`f32`

. - f32x4
Experimental A SIMD vector with four elements of type`f32`

. - f32x8
Experimental A SIMD vector with eight elements of type`f32`

. - f32x16
Experimental A SIMD vector with 16 elements of type`f32`

. - f32x32
Experimental A SIMD vector with 32 elements of type`f32`

. - f32x64
Experimental A SIMD vector with 64 elements of type`f32`

. - f64x1
Experimental A SIMD vector with one element of type`f64`

. - f64x2
Experimental A SIMD vector with two elements of type`f64`

. - f64x4
Experimental A SIMD vector with four elements of type`f64`

. - f64x8
Experimental A SIMD vector with eight elements of type`f64`

. - f64x16
Experimental A SIMD vector with 16 elements of type`f64`

. - f64x32
Experimental A SIMD vector with 32 elements of type`f64`

. - f64x64
Experimental A SIMD vector with 64 elements of type`f64`

. - i8x1
Experimental A SIMD vector with one element of type`i8`

. - i8x2
Experimental A SIMD vector with two elements of type`i8`

. - i8x4
Experimental A SIMD vector with four elements of type`i8`

. - i8x8
Experimental A SIMD vector with eight elements of type`i8`

. - i8x16
Experimental A SIMD vector with 16 elements of type`i8`

. - i8x32
Experimental A SIMD vector with 32 elements of type`i8`

. - i8x64
Experimental A SIMD vector with 64 elements of type`i8`

. - i16x1
Experimental A SIMD vector with one element of type`i16`

. - i16x2
Experimental A SIMD vector with two elements of type`i16`

. - i16x4
Experimental A SIMD vector with four elements of type`i16`

. - i16x8
Experimental A SIMD vector with eight elements of type`i16`

. - i16x16
Experimental A SIMD vector with 16 elements of type`i16`

. - i16x32
Experimental A SIMD vector with 32 elements of type`i16`

. - i16x64
Experimental A SIMD vector with 64 elements of type`i16`

. - i32x1
Experimental A SIMD vector with one element of type`i32`

. - i32x2
Experimental A SIMD vector with two elements of type`i32`

. - i32x4
Experimental A SIMD vector with four elements of type`i32`

. - i32x8
Experimental A SIMD vector with eight elements of type`i32`

. - i32x16
Experimental A SIMD vector with 16 elements of type`i32`

. - i32x32
Experimental A SIMD vector with 32 elements of type`i32`

. - i32x64
Experimental A SIMD vector with 64 elements of type`i32`

. - i64x1
Experimental A SIMD vector with one element of type`i64`

. - i64x2
Experimental A SIMD vector with two elements of type`i64`

. - i64x4
Experimental A SIMD vector with four elements of type`i64`

. - i64x8
Experimental A SIMD vector with eight elements of type`i64`

. - i64x16
Experimental A SIMD vector with 16 elements of type`i64`

. - i64x32
Experimental A SIMD vector with 32 elements of type`i64`

. - i64x64
Experimental A SIMD vector with 64 elements of type`i64`

. - isizex1
Experimental A SIMD vector with one element of type`isize`

. - isizex2
Experimental A SIMD vector with two elements of type`isize`

. - isizex4
Experimental A SIMD vector with four elements of type`isize`

. - isizex8
Experimental A SIMD vector with eight elements of type`isize`

. - isizex16
Experimental A SIMD vector with 16 elements of type`isize`

. - isizex32
Experimental A SIMD vector with 32 elements of type`isize`

. - isizex64
Experimental A SIMD vector with 64 elements of type`isize`

. - mask8x1
Experimental A SIMD mask with one element for vectors with 8-bit element types. - mask8x2
Experimental A SIMD mask with two elements for vectors with 8-bit element types. - mask8x4
Experimental A SIMD mask with four elements for vectors with 8-bit element types. - mask8x8
Experimental A SIMD mask with eight elements for vectors with 8-bit element types. - mask8x16
Experimental A SIMD mask with 16 elements for vectors with 8-bit element types. - mask8x32
Experimental A SIMD mask with 32 elements for vectors with 8-bit element types. - mask8x64
Experimental A SIMD mask with 64 elements for vectors with 8-bit element types. - mask16x1
Experimental A SIMD mask with one element for vectors with 16-bit element types. - mask16x2
Experimental A SIMD mask with two elements for vectors with 16-bit element types. - mask16x4
Experimental A SIMD mask with four elements for vectors with 16-bit element types. - mask16x8
Experimental A SIMD mask with eight elements for vectors with 16-bit element types. - mask16x16
Experimental A SIMD mask with 16 elements for vectors with 16-bit element types. - mask16x32
Experimental A SIMD mask with 32 elements for vectors with 16-bit element types. - mask16x64
Experimental A SIMD mask with 64 elements for vectors with 16-bit element types. - mask32x1
Experimental A SIMD mask with one element for vectors with 32-bit element types. - mask32x2
Experimental A SIMD mask with two elements for vectors with 32-bit element types. - mask32x4
Experimental A SIMD mask with four elements for vectors with 32-bit element types. - mask32x8
Experimental A SIMD mask with eight elements for vectors with 32-bit element types. - mask32x16
Experimental A SIMD mask with 16 elements for vectors with 32-bit element types. - mask32x32
Experimental A SIMD mask with 32 elements for vectors with 32-bit element types. - mask32x64
Experimental A SIMD mask with 64 elements for vectors with 32-bit element types. - mask64x1
Experimental A SIMD mask with one element for vectors with 64-bit element types. - mask64x2
Experimental A SIMD mask with two elements for vectors with 64-bit element types. - mask64x4
Experimental A SIMD mask with four elements for vectors with 64-bit element types. - mask64x8
Experimental A SIMD mask with eight elements for vectors with 64-bit element types. - mask64x16
Experimental A SIMD mask with 16 elements for vectors with 64-bit element types. - mask64x32
Experimental A SIMD mask with 32 elements for vectors with 64-bit element types. - mask64x64
Experimental A SIMD mask with 64 elements for vectors with 64-bit element types. - masksizex1
Experimental A SIMD mask with one element for vectors with pointer-sized element types. - masksizex2
Experimental A SIMD mask with two elements for vectors with pointer-sized element types. - masksizex4
Experimental A SIMD mask with four elements for vectors with pointer-sized element types. - masksizex8
Experimental A SIMD mask with eight elements for vectors with pointer-sized element types. - masksizex16
Experimental A SIMD mask with 16 elements for vectors with pointer-sized element types. - masksizex32
Experimental A SIMD mask with 32 elements for vectors with pointer-sized element types. - masksizex64
Experimental A SIMD mask with 64 elements for vectors with pointer-sized element types. - u8x1
Experimental A SIMD vector with one element of type`u8`

. - u8x2
Experimental A SIMD vector with two elements of type`u8`

. - u8x4
Experimental A SIMD vector with four elements of type`u8`

. - u8x8
Experimental A SIMD vector with eight elements of type`u8`

. - u8x16
Experimental A SIMD vector with 16 elements of type`u8`

. - u8x32
Experimental A SIMD vector with 32 elements of type`u8`

. - u8x64
Experimental A SIMD vector with 64 elements of type`u8`

. - u16x1
Experimental A SIMD vector with one element of type`u16`

. - u16x2
Experimental A SIMD vector with two elements of type`u16`

. - u16x4
Experimental A SIMD vector with four elements of type`u16`

. - u16x8
Experimental A SIMD vector with eight elements of type`u16`

. - u16x16
Experimental A SIMD vector with 16 elements of type`u16`

. - u16x32
Experimental A SIMD vector with 32 elements of type`u16`

. - u16x64
Experimental A SIMD vector with 64 elements of type`u16`

. - u32x1
Experimental A SIMD vector with one element of type`u32`

. - u32x2
Experimental A SIMD vector with two elements of type`u32`

. - u32x4
Experimental A SIMD vector with four elements of type`u32`

. - u32x8
Experimental A SIMD vector with eight elements of type`u32`

. - u32x16
Experimental A SIMD vector with 16 elements of type`u32`

. - u32x32
Experimental A SIMD vector with 32 elements of type`u32`

. - u32x64
Experimental A SIMD vector with 64 elements of type`u32`

. - u64x1
Experimental A SIMD vector with one element of type`u64`

. - u64x2
Experimental A SIMD vector with two elements of type`u64`

. - u64x4
Experimental A SIMD vector with four elements of type`u64`

. - u64x8
Experimental A SIMD vector with eight elements of type`u64`

. - u64x16
Experimental A SIMD vector with 16 elements of type`u64`

. - u64x32
Experimental A SIMD vector with 32 elements of type`u64`

. - u64x64
Experimental A SIMD vector with 64 elements of type`u64`

. - usizex1
Experimental A SIMD vector with one element of type`usize`

. - usizex2
Experimental A SIMD vector with two elements of type`usize`

. - usizex4
Experimental A SIMD vector with four elements of type`usize`

. - usizex8
Experimental A SIMD vector with eight elements of type`usize`

. - usizex16
Experimental A SIMD vector with 16 elements of type`usize`

. - usizex32
Experimental A SIMD vector with 32 elements of type`usize`

. - usizex64
Experimental A SIMD vector with 64 elements of type`usize`

.