Trait Vector 

pub trait Vector: Copy + Debug {
    type Mask: MoveMask;

    const BYTES: usize;
    const ALIGN: usize;

    // Required methods
    fn splat(byte: u8) -> Self;
    unsafe fn load_aligned(data: *const u8) -> Self;
    unsafe fn load_unaligned(data: *const u8) -> Self;
    fn movemask(self) -> Self::Mask;
    fn cmpeq(self, vector2: Self) -> Self;
    fn or(self, vector2: Self) -> Self;
    fn add(self, vector2: Self) -> Self;
    fn gt(self, vector2: Self) -> Self;

    // Provided method
    fn movemask_will_have_non_zero(self) -> bool { ... }
}

A trait for describing vector operations used by vectorized searchers.

The trait is highly constrained to low level vector operations needed. In general, it was invented mostly to be generic over x86’s __m128i and __m256i types. At time of writing, it also supports wasm and aarch64 128-bit vector types as well.

Safety

All methods are not safe since they are intended to be implemented using vendor intrinsics, which are also not safe. Callers must ensure that the appropriate target features are enabled in the calling function, and that the current CPU supports them. All implementations should avoid marking the routines with #[target_feature] and instead mark them as #[\inline(always)] to ensure they get appropriately inlined. (inline(always) cannot be used with target_feature.)

Required Associated Constants

const BYTES: usize

The number of bytes in the vector. That is, this is the size of the vector in memory.

const ALIGN: usize

The bits that must be zero in order for a *const u8 pointer to be correctly aligned to read vector values.

Required Associated Types

type Mask: MoveMask

The type of the value returned by Vector::movemask.

This supports abstracting over the specific representation used in order to accommodate different representations in different ISAs.

Required Methods

fn splat(byte: u8) -> Self

Create a vector with 8-bit lanes with the given byte repeated into each lane.

unsafe fn load_aligned(data: *const u8) -> Self

Read a vector-size number of bytes from the given pointer. The pointer must be aligned to the size of the vector.

Safety

Callers must guarantee that at least BYTES bytes are readable from data and that data is aligned to a BYTES boundary.

unsafe fn load_unaligned(data: *const u8) -> Self

Read a vector-size number of bytes from the given pointer. The pointer does not need to be aligned.

Safety

Callers must guarantee that at least BYTES bytes are readable from data.

fn movemask(self) -> Self::Mask

Convert the vector to a mask.

fn cmpeq(self, vector2: Self) -> Self

Compare two vectors for equality.

fn or(self, vector2: Self) -> Self

Bitwise OR of two vectors.

fn add(self, vector2: Self) -> Self

Add two vectors.

fn gt(self, vector2: Self) -> Self

Compare two vectors for greater than.

Provided Methods

fn movemask_will_have_non_zero(self) -> bool

Returns true if and only if Self::movemask would return a mask that contains at least one non-zero bit.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl Vector for ()

Noop implementation for types that don’t support vectorization.

const BYTES: usize = 0

const ALIGN: usize = 0

type Mask = ()

fn splat(_byte: u8) -> Self

unsafe fn load_aligned(_data: *const u8) -> Self

unsafe fn load_unaligned(_data: *const u8) -> Self

fn movemask(self) -> Self::Mask

fn cmpeq(self, _vector2: Self) -> Self

fn or(self, _vector2: Self) -> Self

fn add(self, _vector2: Self) -> Self

fn gt(self, _vector2: Self) -> Self

impl Vector for int8x16_t

fn movemask_will_have_non_zero(self) -> bool

This is the only interesting implementation of this routine. Basically, instead of doing the “shift right narrow” dance, we use adjacent folding max to determine whether there are any non-zero bytes in our mask. If there are, then we’ll do the “shift right narrow” dance. In benchmarks, this does lead to slightly better throughput, but the win doesn’t appear huge.

const BYTES: usize = 16

const ALIGN: usize

type Mask = NeonMoveMask

fn splat(byte: u8) -> Self

unsafe fn load_aligned(data: *const u8) -> Self

unsafe fn load_unaligned(data: *const u8) -> Self

fn movemask(self) -> NeonMoveMask

fn cmpeq(self, vector2: Self) -> Self

fn or(self, vector2: Self) -> Self

fn add(self, vector2: Self) -> Self

fn gt(self, vector2: Self) -> Self

Implementors