1 namespace Eigen { 2 3 /** \page TopicStructHavingEigenMembers Structures Having Eigen Members 4 5 \b Table \b of \b contents 6 - \ref summary 7 - \ref what 8 - \ref how 9 - \ref why 10 - \ref movetotop 11 - \ref bugineigen 12 - \ref conditional 13 - \ref othersolutions 14 15 \section summary Executive Summary 16 17 If you define a structure having members of \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you must overload its "operator new" so that it generates 16-bytes-aligned pointers. Fortunately, Eigen provides you with a macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW that does that for you. 18 19 \section what What kind of code needs to be changed? 20 21 The kind of code that needs to be changed is this: 22 23 \code 24 class Foo 25 { 26 ... 27 Eigen::Vector2d v; 28 ... 29 }; 30 31 ... 32 33 Foo *foo = new Foo; 34 \endcode 35 36 In other words: you have a class that has as a member a \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen object", and then you dynamically create an object of that class. 37 38 \section how How should such code be modified? 39 40 Very easy, you just need to put a EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro in a public part of your class, like this: 41 42 \code 43 class Foo 44 { 45 ... 46 Eigen::Vector2d v; 47 ... 48 public: 49 EIGEN_MAKE_ALIGNED_OPERATOR_NEW 50 }; 51 52 ... 53 54 Foo *foo = new Foo; 55 \endcode 56 57 This macro makes "new Foo" always return an aligned pointer. 58 59 If this approach is too intrusive, see also the \ref othersolutions. 60 61 \section why Why is this needed? 62 63 OK let's say that your code looks like this: 64 65 \code 66 class Foo 67 { 68 ... 69 Eigen::Vector2d v; 70 ... 71 }; 72 73 ... 74 75 Foo *foo = new Foo; 76 \endcode 77 78 A Eigen::Vector2d consists of 2 doubles, which is 128 bits. Which is exactly the size of a SSE packet, which makes it possible to use SSE for all sorts of operations on this vector. But SSE instructions (at least the ones that Eigen uses, which are the fast ones) require 128-bit alignment. Otherwise you get a segmentation fault. 79 80 For this reason, Eigen takes care by itself to require 128-bit alignment for Eigen::Vector2d, by doing two things: 81 \li Eigen requires 128-bit alignment for the Eigen::Vector2d's array (of 2 doubles). With GCC, this is done with a __attribute__ ((aligned(16))). 82 \li Eigen overloads the "operator new" of Eigen::Vector2d so it will always return 128-bit aligned pointers. 83 84 Thus, normally, you don't have to worry about anything, Eigen handles alignment for you... 85 86 ... except in one case. When you have a class Foo like above, and you dynamically allocate a new Foo as above, then, since Foo doesn't have aligned "operator new", the returned pointer foo is not necessarily 128-bit aligned. 87 88 The alignment attribute of the member v is then relative to the start of the class, foo. If the foo pointer wasn't aligned, then foo->v won't be aligned either! 89 90 The solution is to let class Foo have an aligned "operator new", as we showed in the previous section. 91 92 \section movetotop Should I then put all the members of Eigen types at the beginning of my class? 93 94 That's not required. Since Eigen takes care of declaring 128-bit alignment, all members that need it are automatically 128-bit aligned relatively to the class. So code like this works fine: 95 96 \code 97 class Foo 98 { 99 double x; 100 Eigen::Vector2d v; 101 public: 102 EIGEN_MAKE_ALIGNED_OPERATOR_NEW 103 }; 104 \endcode 105 106 \section dynamicsize What about dynamic-size matrices and vectors? 107 108 Dynamic-size matrices and vectors, such as Eigen::VectorXd, allocate dynamically their own array of coefficients, so they take care of requiring absolute alignment automatically. So they don't cause this issue. The issue discussed here is only with \ref TopicFixedSizeVectorizable "fixed-size vectorizable matrices and vectors". 109 110 \section bugineigen So is this a bug in Eigen? 111 112 No, it's not our bug. It's more like an inherent problem of the C++98 language specification, and seems to be taken care of in the upcoming language revision: <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf">see this document</a>. 113 114 \section conditional What if I want to do this conditionnally (depending on template parameters) ? 115 116 For this situation, we offer the macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign). It will generate aligned operators like EIGEN_MAKE_ALIGNED_OPERATOR_NEW if NeedsToAlign is true. It will generate operators with the default alignment if NeedsToAlign is false. 117 118 Example: 119 120 \code 121 template<int n> class Foo 122 { 123 typedef Eigen::Matrix<float,n,1> Vector; 124 enum { NeedsToAlign = (sizeof(Vector)%16)==0 }; 125 ... 126 Vector v; 127 ... 128 public: 129 EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign) 130 }; 131 132 ... 133 134 Foo<4> *foo4 = new Foo<4>; // foo4 is guaranteed to be 128bit-aligned 135 Foo<3> *foo3 = new Foo<3>; // foo3 has only the system default alignment guarantee 136 \endcode 137 138 139 \section othersolutions Other solutions 140 141 In case putting the EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro everywhere is too intrusive, there exists at least two other solutions. 142 143 \subsection othersolutions1 Disabling alignment 144 145 The first is to disable alignment requirement for the fixed size members: 146 \code 147 class Foo 148 { 149 ... 150 Eigen::Matrix<double,2,1,Eigen::DontAlign> v; 151 ... 152 }; 153 \endcode 154 This has for effect to disable vectorization when using \c v. 155 If a function of Foo uses it several times, then it still possible to re-enable vectorization by copying it into an aligned temporary vector: 156 \code 157 void Foo::bar() 158 { 159 Eigen::Vector2d av(v); 160 // use av instead of v 161 ... 162 // if av changed, then do: 163 v = av; 164 } 165 \endcode 166 167 \subsection othersolutions2 Private structure 168 169 The second consist in storing the fixed-size objects into a private struct which will be dynamically allocated at the construction time of the main object: 170 171 \code 172 struct Foo_d 173 { 174 EIGEN_MAKE_ALIGNED_OPERATOR_NEW 175 Vector2d v; 176 ... 177 }; 178 179 180 struct Foo { 181 Foo() { init_d(); } 182 ~Foo() { delete d; } 183 void bar() 184 { 185 // use d->v instead of v 186 ... 187 } 188 private: 189 void init_d() { d = new Foo_d; } 190 Foo_d* d; 191 }; 192 \endcode 193 194 The clear advantage here is that the class Foo remains unchanged regarding alignment issues. The drawback is that a heap allocation will be required whatsoever. 195 196 */ 197 198 } 199
