Crate safe_unaligned_simd 

Safe wrappers for unaligned SIMD load and store operations.

Overview

The goal of this crate is to remove the need for “unnecessary unsafe” code when using vector intrinsics to access memory, with no alignment requirements.

Platform-intrinsics that take raw pointers have been wrapped in functions that receive Rust reference types as arguments.

Safely using platform intrinsics

Users are responsible for ensuring that the CPU supports the intended target feature.

Feature detection can be done at compile-time by using #[cfg] attributes on functions or at runtime using an is_[arch]_feature_detected! macro from std::arch.

unsafe is needed to call into functions annotated with #[target_feature], but it’s safe to call other functions with the same target features.

See the std::arch module documentation for a full explanation and the rustc 1.87 release notes for a simple example of runtime feature detection with fallback.

Supported target architectures

x86 / x86_64

• sse, sse2, avx, avx512f, avx512vl, avx512bw, avx512vbmi2

Some functions have variants that are generic over Cell array types, which allow for mutation of shared references.

Currently, there is no plan to implement gather/scatter or avx2 masked load/store intrinsics for this platform.

aarch64, arm64ec

• neon

Intrinsics that load / store individual lanes are not designed yet.

wasm32

• simd128

A note on creating mutable array references from slices

tl;dr: Use as_mut_array to avoid this bug, stable since 1.93.

Beware of accidentally creating mutable references to temporary arrays.

Rust will implicitly clone an array from a slice and return a mutable reference to that clone if not wrapped properly in parentheses.

// Valid mutable array reference creation
let out_data: &mut [u8; 4] = chunk[..4].as_mut_array().unwrap(); // since 1.93
let out_data: &mut [u8; 4] = (&mut chunk[..4]).try_into().unwrap();
let out_data = TryInto::<&mut [u8; 4]>::try_into(&mut chunk[..4]).unwrap();

// Incorrect creation of a mutable reference: this clones the chunk and returns
// a mutable reference to the copy. If we modify `out_data` after this point,
// the changes will not reflect back in our original `chunk` slice.
// 🚫🈲⛔❌ - Do not use the following line
let out_data = &mut chunk[..4].try_into().unwrap();

The now-stable as_mut_array sidesteps this issue entirely.

Modules

x86_64

Platform-specific intrinsics for x86_64.