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