1namespace Eigen { 2 3/** \eigenManualPage TopicStructHavingEigenMembers Structures Having Eigen Members 4 5\eigenAutoToc 6 7\section StructHavingEigenMembers_summary Executive Summary 8 9 10If you define a structure having members of \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you must ensure that calling operator new on it allocates properly aligned buffers. 11If you're compiling in \cpp17 mode only with a sufficiently recent compiler (e.g., GCC>=7, clang>=5, MSVC>=19.12), then everything is taken care by the compiler and you can stop reading. 12 13Otherwise, you have to overload its `operator new` so that it generates properly aligned pointers (e.g., 32-bytes-aligned for Vector4d and AVX). 14Fortunately, %Eigen provides you with a macro `EIGEN_MAKE_ALIGNED_OPERATOR_NEW` that does that for you. 15 16\section StructHavingEigenMembers_what What kind of code needs to be changed? 17 18The kind of code that needs to be changed is this: 19 20\code 21class Foo 22{ 23 ... 24 Eigen::Vector2d v; 25 ... 26}; 27 28... 29 30Foo *foo = new Foo; 31\endcode 32 33In 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. 34 35\section StructHavingEigenMembers_how How should such code be modified? 36 37Very easy, you just need to put a `EIGEN_MAKE_ALIGNED_OPERATOR_NEW` macro in a public part of your class, like this: 38 39\code 40class Foo 41{ 42 ... 43 Eigen::Vector4d v; 44 ... 45public: 46 EIGEN_MAKE_ALIGNED_OPERATOR_NEW 47}; 48 49... 50 51Foo *foo = new Foo; 52\endcode 53 54This macro makes `new Foo` always return an aligned pointer. 55 56In \cpp17, this macro is empty. 57 58If this approach is too intrusive, see also the \ref StructHavingEigenMembers_othersolutions "other solutions". 59 60\section StructHavingEigenMembers_why Why is this needed? 61 62OK let's say that your code looks like this: 63 64\code 65class Foo 66{ 67 ... 68 Eigen::Vector4d v; 69 ... 70}; 71 72... 73 74Foo *foo = new Foo; 75\endcode 76 77A Eigen::Vector4d consists of 4 doubles, which is 256 bits. 78This is exactly the size of an AVX register, which makes it possible to use AVX for all sorts of operations on this vector. 79But AVX instructions (at least the ones that %Eigen uses, which are the fast ones) require 256-bit alignment. 80Otherwise you get a segmentation fault. 81 82For this reason, %Eigen takes care by itself to require 256-bit alignment for Eigen::Vector4d, by doing two things: 83\li %Eigen requires 256-bit alignment for the Eigen::Vector4d's array (of 4 doubles). With \cpp11 this is done with the <a href="https://en.cppreference.com/w/cpp/keyword/alignas">alignas</a> keyword, or compiler's extensions for c++98/03. 84\li %Eigen overloads the `operator new` of Eigen::Vector4d so it will always return 256-bit aligned pointers. (removed in \cpp17) 85 86Thus, normally, you don't have to worry about anything, %Eigen handles alignment of operator new for you... 87 88... 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 256-bit aligned. 89 90The 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! 91 92The solution is to let `class Foo` have an aligned `operator new`, as we showed in the previous section. 93 94This explanation also holds for SSE/NEON/MSA/Altivec/VSX targets, which require 16-bytes alignment, and AVX512 which requires 64-bytes alignment for fixed-size objects multiple of 64 bytes (e.g., Eigen::Matrix4d). 95 96\section StructHavingEigenMembers_movetotop Should I then put all the members of Eigen types at the beginning of my class? 97 98That's not required. Since %Eigen takes care of declaring adequate alignment, all members that need it are automatically aligned relatively to the class. So code like this works fine: 99 100\code 101class Foo 102{ 103 double x; 104 Eigen::Vector4d v; 105public: 106 EIGEN_MAKE_ALIGNED_OPERATOR_NEW 107}; 108\endcode 109 110That said, as usual, it is recommended to sort the members so that alignment does not waste memory. 111In the above example, with AVX, the compiler will have to reserve 24 empty bytes between `x` and `v`. 112 113 114\section StructHavingEigenMembers_dynamicsize What about dynamic-size matrices and vectors? 115 116Dynamic-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". 117 118 119\section StructHavingEigenMembers_bugineigen So is this a bug in Eigen? 120 121No, it's not our bug. It's more like an inherent problem of the c++ language specification that has been solved in c++17 through the feature known as <a href="http://wg21.link/p0035r4">dynamic memory allocation for over-aligned data</a>. 122 123 124\section StructHavingEigenMembers_conditional What if I want to do this conditionally (depending on template parameters) ? 125 126For this situation, we offer the macro `EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign)`. 127It will generate aligned operators like `EIGEN_MAKE_ALIGNED_OPERATOR_NEW` if `NeedsToAlign` is true. 128It will generate operators with the default alignment if `NeedsToAlign` is false. 129In \cpp17, this macro is empty. 130 131Example: 132 133\code 134template<int n> class Foo 135{ 136 typedef Eigen::Matrix<float,n,1> Vector; 137 enum { NeedsToAlign = (sizeof(Vector)%16)==0 }; 138 ... 139 Vector v; 140 ... 141public: 142 EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign) 143}; 144 145... 146 147Foo<4> *foo4 = new Foo<4>; // foo4 is guaranteed to be 128bit-aligned 148Foo<3> *foo3 = new Foo<3>; // foo3 has only the system default alignment guarantee 149\endcode 150 151 152\section StructHavingEigenMembers_othersolutions Other solutions 153 154In case putting the `EIGEN_MAKE_ALIGNED_OPERATOR_NEW` macro everywhere is too intrusive, there exists at least two other solutions. 155 156\subsection othersolutions1 Disabling alignment 157 158The first is to disable alignment requirement for the fixed size members: 159\code 160class Foo 161{ 162 ... 163 Eigen::Matrix<double,4,1,Eigen::DontAlign> v; 164 ... 165}; 166\endcode 167This `v` is fully compatible with aligned Eigen::Vector4d. 168This has only for effect to make load/stores to `v` more expensive (usually slightly, but that's hardware dependent). 169 170 171\subsection othersolutions2 Private structure 172 173The 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: 174 175\code 176struct Foo_d 177{ 178 EIGEN_MAKE_ALIGNED_OPERATOR_NEW 179 Vector4d v; 180 ... 181}; 182 183 184struct Foo { 185 Foo() { init_d(); } 186 ~Foo() { delete d; } 187 void bar() 188 { 189 // use d->v instead of v 190 ... 191 } 192private: 193 void init_d() { d = new Foo_d; } 194 Foo_d* d; 195}; 196\endcode 197 198The clear advantage here is that the class `Foo` remains unchanged regarding alignment issues. 199The drawback is that an additional heap allocation will be required whatsoever. 200 201*/ 202 203} 204