1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220
// This file is part of faster, the SIMD library for humans. // Copyright 2017 Adam Niederer <adam.niederer@gmail.com> // This Source Code Form is subject to the terms of the Mozilla Public // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. //! The SIMD library for humans. //! Faster allows convenient application of explicit SIMD to existing code. It //! allows you to write explicit SIMD code once and compile it for any target, //! regardless of architecture, SIMD capability, or age. //! # SIMD Iterators //! //! SIMD iterators are formed using [`simd_iter`], [`simd_iter_mut`], and //! [`into_simd_iter`], which return types which allow the usage of the //! [`simd_map`] and [`simd_reduce`] functions. These functions automatically //! pack your iterator's data into SIMD vectors and allow you to transparently //! operate on them in a closure. //! //! [`simd_iter`]: iters/trait.IntoSIMDIterator.html#tymethod.into_simd_iter //! [`simd_iter_mut`]: iters/trait.IntoSIMDIterator.html#tymethod.simd_iter //! [`into_simd_iter`]: iters/trait.IntoSIMDRefMutIterator.html#tymethod.simd_iter_mut //! [`simd_map`]: iters/trait.SIMDIterator.html#tymethod.simd_map //! [`simd_reduce`]: iters/trait.SIMDIterator.html#tymethod.simd_reduce //! //! # SIMD Polyfills //! //! Once your data is packed into a SIMD vector, you may perform many common //! SIMD operations on it. These operations have names and behavior independent //! of any vendor-specific ISA, and have non-SIMD polyfills for machines which //! cannot perform these operations in a single cycle. See the [`intrin`] module //! for all available operations. //! //! [`intrin`]: intrin/index.html //! //! # Examples //! //! Faster is currently capable of mapping and reductive operations in SIMD. //! //! ## Mapping //! //! The simplest example of a computation with `faster` is a single map //! operation. //! //! ``` //! extern crate faster; //! use faster::*; //! //! # #[cfg(not(feature = "std"))] //! # fn main() { } //! //! # #[cfg(feature = "std")] //! # fn main() { //! let lots_of_10s = [-10i8; 3000].simd_iter(i8s(0)) //! .simd_map(|v| v.abs()) //! .scalar_collect(); //! assert_eq!(lots_of_10s, vec![10u8; 3000]); //! # } //! ``` //! //! In this example, a vector of type [`i8s`] is passed into the closure. The //! exact type of [`i8s`] is dependent on compilation target, but it will always //! implement the same operations. Because taking the absolute value of a vector //! converts it to [`u8s`], the closure will return [`u8s`]. //! //! [`scalar_collect`] takes the iterator of [`u8s`] and converts it into a //! `Vec<u8>`. //! //! [`i8s`]: vecs/type.i8s.html //! [`u8s`]: vecs/type.u8s.html //! [`scalar_collect`]: iters/trait.IntoScalar.html#tymethod.scalar_collect //! //! ## Reduction //! //! Faster can perform reductive operations with similar power to mapping //! operations: //! //! ``` //! #![feature(rust_2018_preview, stdsimd)] //! extern crate faster; //! use faster::*; //! //! # fn main() { //! let two_hundred = [2.0f32; 100].simd_iter(f32s(0.0)) //! .simd_reduce(f32s(0.0), |acc, v| acc + v) //! .sum(); //! assert_eq!(two_hundred, 200.0f32); //! # } //! ``` //! //! This example sums every number in the collection. The first parameter to //! simd_reduce is the default value of the accumulator, just like any //! other reduction. The second value is used if the collection being reduced //! over doesn't fit evenly into your system's vectors - it is the default value //! of the last vector, and each element of the vector is used only if it isn't //! filled by an element of the collection. Typically, a value of 0 or 1 is a //! suitable default. //! //! Minding portability is very important when performing reductive //! operations. See below for some tips on keeping your code portable across all //! architectures. //! //! ## Multiple collections //! //! Faster supports vectorized lockstep iteration over multiple collections. //! Simply [`zip`] them up, and proceed as normal. //! //! [`zip`]: zip/trait.IntoSIMDZip.html //! //! ``` //! extern crate faster; //! use faster::*; //! //! # #[cfg(not(feature = "std"))] //! # fn main() { } //! //! # #[cfg(feature = "std")] //! # fn main() { //! let sevens = ([4i32; 200].simd_iter(i32s(0)), [3i32; 200].simd_iter(i32s(0))) //! .zip() //! .simd_map(|(a, b)| a + b) //! .scalar_collect(); //! # } //! ``` //! //! ## Striping Collections //! //! Reading every nth element of a collection can be vectorized on most //! machines. Simply call [`stride`], or one of the slightly-faster tuple-based //! functions, such as [`stride_two`]. //! //! [`stride`]: iters/struct.SIMDRefIter.html#method.stride //! [`stride_two`]: iters/struct.SIMDRefIter.html#method.stride_two //! //! ``` //! extern crate faster; //! use faster::*; //! //! # #[cfg(not(feature = "std"))] //! # fn main() { } //! //! # #[cfg(feature = "std")] //! # fn main() { //! // Computes the determinant of matrices arranged as [a, b, c, d, a, b, c...] //! let slice: &[f32] = &[1.0f32; 1024]; //! let determinant = slice.stride_four(tuplify!(4, f32s(0.0))).zip() //! .simd_map(|(a, b, c, d)| a * d - b * c) //! .scalar_collect(); //! # } //! ``` //! //! # Portability //! //! While `faster` does most of the work ensuring your code stays portable //! across platforms, a user of this library must still understand that it is //! very possible to write non-portable algorithms using this library. Anything //! which relies on vector width, anything which is impure, and anything which //! uses constants in reductive operations is inherently nonportable. Some //! examples below: //! //! ``` //! extern crate faster; //! use faster::*; //! //! # #[cfg(not(feature = "std"))] //! # fn main() { } //! //! # #[cfg(feature = "std")] //! # fn main() { //! let mut flip = true; //! let impure = [1i8; 3000].simd_iter(i8s(0)) //! .simd_map(|v| { flip = !flip; if flip { v + i8s(1) } else { v } }) //! .scalar_collect(); //! // Depending on the width of your target's SIMD vectors, `impure` could be //! // [1, 1, 1, 1, 2, 2, 2, 2, 1, 1, 1, 1, 2, 2, 2, 2, ...] or //! // [1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, ...], etc. //! # } //! ``` //! //! ``` //! extern crate faster; //! use faster::*; //! //! # fn main() { //! let length_dependent = [0i8; 10].simd_iter(i8s(0)) //! .simd_reduce(i8s(0), |acc, v| acc + v + i8s(1)).sum(); //! // `length_dependent` could be a different number on a different target! //! # } //! ``` //! //! As a precaution, it is best practice to keep all functions pure, and only //! operate on SIMD vectors in your SIMD-enabled closures unless you know //! exactly what is happening under the hood. It's also important to remember //! that these problems will crop up even if you only support x86; the width //! difference between AVX and SSE is the primary source of these issues! #![cfg_attr(feature = "no-std", no_std)] #![cfg_attr(test, feature(test))] #![feature(rust_2018_preview, stdsimd)] // , mmx_target_feature, sse4a_target_feautre, tbm_target_feature #[cfg(not(feature = "std"))] pub use ::core as std; extern crate vektor; #[macro_use] pub(crate) mod debug; #[macro_use] pub mod zip; #[macro_use] pub mod vecs; pub mod vec_patterns; pub mod iters; pub mod into_iters; #[macro_use] pub mod intrin; #[macro_use] pub mod arch; pub mod prelude; pub mod stride_zip; pub mod stride; pub use crate::prelude::*;