1 /* This file is part of the Vc library. {{{ 2 Copyright © 2014-2015 Matthias Kretz <kretz@kde.org> 3 4 Redistribution and use in source and binary forms, with or without 5 modification, are permitted provided that the following conditions are met: 6 * Redistributions of source code must retain the above copyright 7 notice, this list of conditions and the following disclaimer. 8 * Redistributions in binary form must reproduce the above copyright 9 notice, this list of conditions and the following disclaimer in the 10 documentation and/or other materials provided with the distribution. 11 * Neither the names of contributing organizations nor the 12 names of its contributors may be used to endorse or promote products 13 derived from this software without specific prior written permission. 14 15 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 16 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY 19 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 22 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 24 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 26 }}}*/ 27 28 #ifndef Vc_CURRENT_CLASS_NAME 29 #error "incorrect use of common/gatherinterface.h: Vc_CURRENT_CLASS_NAME must be defined to the current class name for declaring constructors." 30 #endif 31 32 /////////////////////////////////////////////////////////////////////////////////////////// 33 // gathers 34 // A gather takes the following arguments: 35 // 1. A const pointer to memory of any type that can convert to EntryType 36 // 2. An indexes “vector”. The requirement is that the type implements the subscript operator, 37 // stores «Size» valid index values, and each offset to the pointer above yields a valid 38 // memory location for reading. 39 // 3. Optionally the third argument may be a mask. The mask disables several memory reads and 40 // thus removes the requirements in (2.) for the disabled entries. 41 42 private: 43 /**\internal 44 * This function implements a gather given a pointer to memory \p mem and some 45 * container object storing the gather \p indexes. 46 * 47 * \param mem This pointer must be aligned correctly for the type \p MT. This is the 48 * natural behavior of C++, so this is typically the case. 49 * \param indexes This object contains at least \VSize{T} indexes that denote the 50 * offset in \p mem where the components for the current vector should be copied from. 51 * The offset is not in Bytes, but in multiples of `sizeof(MT)`. 52 */ 53 // enable_if<std::can_convert<MT, EntryType>::value && 54 // has_subscript_operator<IT>::value> 55 template <class MT, class IT, int Scale = 1> 56 inline void gatherImplementation(const Common::GatherArguments<MT, IT, Scale> &); 57 58 /**\internal 59 * This overload of the above function adds a \p mask argument to disable memory 60 * accesses at the \p indexes offsets where \p mask is \c false. 61 */ 62 template <class MT, class IT, int Scale = 1> 63 inline void gatherImplementation(const Common::GatherArguments<MT, IT, Scale> &, 64 MaskArgument mask); 65 66 public: 67 #define Vc_ASSERT_GATHER_PARAMETER_TYPES_ \ 68 static_assert( \ 69 std::is_convertible<MT, EntryType>::value, \ 70 "The memory pointer needs to point to a type that can be converted to the " \ 71 "EntryType of this SIMD vector type."); \ 72 static_assert( \ 73 Vc::Traits::has_subscript_operator<IT>::value, \ 74 "The indexes argument must be a type that implements the subscript operator."); \ 75 static_assert( \ 76 !Traits::is_simd_vector<IT>::value || \ 77 Traits::simd_vector_size<IT>::value >= Size, \ 78 "If you use a SIMD vector for the indexes parameter, the index vector must " \ 79 "have at least as many entries as this SIMD vector."); \ 80 static_assert( \ 81 !std::is_array<T>::value || \ 82 (std::rank<T>::value == 1 && \ 83 (std::extent<T>::value == 0 || std::extent<T>::value >= Size)), \ 84 "If you use a simple array for the indexes parameter, the array must have " \ 85 "at least as many entries as this SIMD vector.") 86 87 /** 88 * \name Gather constructors and member functions 89 * 90 * Constructs or loads a vector from the objects at `mem[indexes[0]]`, 91 * `mem[indexes[1]]`, `mem[indexes[2]]`, ... 92 * 93 * All gather functions optionally take a mask as last argument. In that case only the 94 * entries that are selected in the mask are accessed in memory and copied to the 95 * vector. This enables invalid indexes in the \p indexes vector if those are masked 96 * off in \p mask. 97 * 98 * Gathers from structured data (AoS: arrays of struct) are possible via a special 99 * subscript operator of the container (array). You can use \ref Vc::array and \ref 100 * Vc::vector as drop-in replacements for \c std::array and \c std::vector. These 101 * container classes contain the necessary subscript operator overload. Example: 102 * \code 103 * Vc::vector<float> data(100); 104 * std::iota(data.begin(), data.end(), 0.f); // fill with values 0, 1, 2, ... 105 * auto indexes = float_v::IndexType::IndexesFromZero(); 106 * float_v gathered = data[indexes]; // gathered == [0, 1, 2, ...] 107 * \endcode 108 * 109 * This also works for gathers into arrays of structures: 110 * \code 111 * struct Point { float x, y, z; }; 112 * Vc::array<Point, 100> points; 113 * // fill points ... 114 * auto indexes = float_v::IndexType::IndexesFromZero(); 115 * float_v xs = data[indexes][&Point::x]; // [points[0].x, points[1].x, points[2].x, ...] 116 * float_v ys = data[indexes][&Point::y]; // [points[0].y, points[1].y, points[2].y, ...] 117 * float_v zs = data[indexes][&Point::z]; // [points[0].z, points[1].z, points[2].z, ...] 118 * \endcode 119 * 120 * Alternatively, you can use Vc::Common::AdaptSubscriptOperator to extend a given 121 * container class with the necessary subscript operator. Example: 122 * \code 123 * template <typename T, typename Allocator = std::allocator<T>> 124 * using my_vector = Vc::Common::AdaptSubscriptOperator<std::vector<T, Allocator>>; 125 * \endcode 126 * 127 * \param mem A pointer to memory which contains objects of type \p MT at the offsets 128 * given by \p indexes. 129 * \param indexes A container/vector of offsets into \p mem. 130 * The type of \p indexes (\p IT) may either be a pointer to integers 131 * (C-array) or a vector of integers (preferrably IndexType). 132 * \param mask If a mask is given, only the active entries will be copied from memory. 133 * 134 * \note If you use a masked gather constructor the masked-off entries of the vector 135 * are zero-initilized. 136 */ 137 ///@{ 138 139 /// Gather constructor 140 template <typename MT, typename IT, 141 typename = enable_if<Traits::has_subscript_operator<IT>::value>> Vc_CURRENT_CLASS_NAME(const MT * mem,const IT & indexes)142 Vc_INTRINSIC Vc_CURRENT_CLASS_NAME(const MT *mem, const IT &indexes) 143 { 144 Vc_ASSERT_GATHER_PARAMETER_TYPES_; 145 gatherImplementation( 146 Common::make_gather<1>(mem, Common::convertIndexVector(indexes))); 147 } 148 149 template <class MT, class IT, int Scale> Vc_CURRENT_CLASS_NAME(const Common::GatherArguments<MT,IT,Scale> & args)150 Vc_INTRINSIC Vc_CURRENT_CLASS_NAME(const Common::GatherArguments<MT, IT, Scale> &args) 151 { 152 Vc_ASSERT_GATHER_PARAMETER_TYPES_; 153 gatherImplementation(args); 154 } 155 156 /// Masked gather constructor 157 template <typename MT, typename IT, 158 typename = enable_if<Vc::Traits::has_subscript_operator<IT>::value>> Vc_CURRENT_CLASS_NAME(const MT * mem,const IT & indexes,MaskArgument mask)159 Vc_INTRINSIC Vc_CURRENT_CLASS_NAME(const MT *mem, const IT &indexes, 160 MaskArgument mask) 161 { 162 Vc_ASSERT_GATHER_PARAMETER_TYPES_; 163 gatherImplementation( 164 Common::make_gather<1>(mem, Common::convertIndexVector(indexes)), mask); 165 } 166 167 template <class MT, class IT, int Scale> Vc_CURRENT_CLASS_NAME(const Common::GatherArguments<MT,IT,Scale> & args,MaskArgument mask)168 Vc_INTRINSIC Vc_CURRENT_CLASS_NAME(const Common::GatherArguments<MT, IT, Scale> &args, 169 MaskArgument mask) 170 { 171 Vc_ASSERT_GATHER_PARAMETER_TYPES_; 172 gatherImplementation(args, mask); 173 } 174 175 /// Gather function 176 template <typename MT, typename IT, 177 typename = enable_if<Vc::Traits::has_subscript_operator<IT>::value>> gather(const MT * mem,const IT & indexes)178 Vc_INTRINSIC void gather(const MT *mem, const IT &indexes) 179 { 180 Vc_ASSERT_GATHER_PARAMETER_TYPES_; 181 gatherImplementation( 182 Common::make_gather<1>(mem, Common::convertIndexVector(indexes))); 183 } 184 185 /// Masked gather function 186 template <typename MT, typename IT, 187 typename = enable_if<Vc::Traits::has_subscript_operator<IT>::value>> gather(const MT * mem,const IT & indexes,MaskArgument mask)188 Vc_INTRINSIC void gather(const MT *mem, const IT &indexes, MaskArgument mask) 189 { 190 Vc_ASSERT_GATHER_PARAMETER_TYPES_; 191 gatherImplementation( 192 Common::make_gather<1>(mem, Common::convertIndexVector(indexes)), mask); 193 } 194 ///@} 195 196 #include "gatherinterface_deprecated.h" 197 198 /**\internal 199 * \name Gather function to use from Vc::Common::subscript_operator 200 * 201 * \param args 202 * \param mask 203 */ 204 ///@{ 205 template <class MT, class IT, int Scale> gather(const Common::GatherArguments<MT,IT,Scale> & args)206 Vc_INTRINSIC void gather(const Common::GatherArguments<MT, IT, Scale> &args) 207 { 208 Vc_ASSERT_GATHER_PARAMETER_TYPES_; 209 gatherImplementation(args); 210 } 211 212 template <class MT, class IT, int Scale> gather(const Common::GatherArguments<MT,IT,Scale> & args,MaskArgument mask)213 Vc_INTRINSIC void gather(const Common::GatherArguments<MT, IT, Scale> &args, 214 MaskArgument mask) 215 { 216 Vc_ASSERT_GATHER_PARAMETER_TYPES_; 217 gatherImplementation(args, mask); 218 } 219 ///@} 220 221 #undef Vc_ASSERT_GATHER_PARAMETER_TYPES_ 222