blob: 4c970936b7bd31e26b298592aacf30f8dd04fe37 [file] [log] [blame]
Benoit Jacob294f5f12009-01-12 14:41:12 +00001namespace Eigen {
2
Gael Guennebaud93ee82b2013-01-05 16:37:11 +01003/** \eigenManualPage TopicStructHavingEigenMembers Structures Having Eigen Members
Benoit Jacob294f5f12009-01-12 14:41:12 +00004
Gael Guennebaud93ee82b2013-01-05 16:37:11 +01005\eigenAutoToc
Benoit Jacob294f5f12009-01-12 14:41:12 +00006
Christoph Hertzberg28a4c922015-05-01 22:10:41 +02007\section StructHavingEigenMembers_summary Executive Summary
Benoit Jacob294f5f12009-01-12 14:41:12 +00008
Gael Guennebaud844e5442019-02-20 13:54:04 +01009
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.
Benoit Jacob294f5f12009-01-12 14:41:12 +000015
Christoph Hertzberg28a4c922015-05-01 22:10:41 +020016\section StructHavingEigenMembers_what What kind of code needs to be changed?
Benoit Jacob294f5f12009-01-12 14:41:12 +000017
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
Gael Guennebaud41ea92d2010-07-04 10:14:47 +020033In 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 Jacob294f5f12009-01-12 14:41:12 +000034
Christoph Hertzberg28a4c922015-05-01 22:10:41 +020035\section StructHavingEigenMembers_how How should such code be modified?
Benoit Jacob294f5f12009-01-12 14:41:12 +000036
Gael Guennebaud844e5442019-02-20 13:54:04 +010037Very easy, you just need to put a `EIGEN_MAKE_ALIGNED_OPERATOR_NEW` macro in a public part of your class, like this:
Benoit Jacob294f5f12009-01-12 14:41:12 +000038
39\code
40class Foo
41{
42 ...
Gael Guennebaud844e5442019-02-20 13:54:04 +010043 Eigen::Vector4d v;
Benoit Jacob294f5f12009-01-12 14:41:12 +000044 ...
45public:
46 EIGEN_MAKE_ALIGNED_OPERATOR_NEW
47};
48
49...
50
51Foo *foo = new Foo;
52\endcode
53
Gael Guennebaud844e5442019-02-20 13:54:04 +010054This macro makes `new Foo` always return an aligned pointer.
55
56In \cpp17, this macro is empty.
Benoit Jacob294f5f12009-01-12 14:41:12 +000057
Gael Guennebaud29bb5992015-12-30 16:04:24 +010058If this approach is too intrusive, see also the \ref StructHavingEigenMembers_othersolutions "other solutions".
Gael Guennebaudf56316f2011-11-25 13:46:48 +010059
Christoph Hertzberg28a4c922015-05-01 22:10:41 +020060\section StructHavingEigenMembers_why Why is this needed?
Benoit Jacob294f5f12009-01-12 14:41:12 +000061
62OK let's say that your code looks like this:
63
64\code
65class Foo
66{
67 ...
Gael Guennebaud844e5442019-02-20 13:54:04 +010068 Eigen::Vector4d v;
Benoit Jacob294f5f12009-01-12 14:41:12 +000069 ...
70};
71
72...
73
74Foo *foo = new Foo;
75\endcode
76
Gael Guennebaud844e5442019-02-20 13:54:04 +010077A 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.
Benoit Jacob294f5f12009-01-12 14:41:12 +000081
Gael Guennebaud844e5442019-02-20 13:54:04 +010082For this reason, %Eigen takes care by itself to require 256-bit alignment for Eigen::Vector4d, by doing two things:
Erik Schultheis89c6ab22022-01-29 11:16:04 +020083\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 Guennebaud844e5442019-02-20 13:54:04 +010084\li %Eigen overloads the `operator new` of Eigen::Vector4d so it will always return 256-bit aligned pointers. (removed in \cpp17)
Benoit Jacob294f5f12009-01-12 14:41:12 +000085
Gael Guennebaud844e5442019-02-20 13:54:04 +010086Thus, normally, you don't have to worry about anything, %Eigen handles alignment of operator new for you...
Benoit Jacob294f5f12009-01-12 14:41:12 +000087
Gael Guennebaud844e5442019-02-20 13:54:04 +010088... 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 Jacob294f5f12009-01-12 14:41:12 +000089
Gael Guennebaud844e5442019-02-20 13:54:04 +010090The 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 Jacob294f5f12009-01-12 14:41:12 +000091
Gael Guennebaud844e5442019-02-20 13:54:04 +010092The 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).
Benoit Jacob294f5f12009-01-12 14:41:12 +000095
Christoph Hertzberg28a4c922015-05-01 22:10:41 +020096\section StructHavingEigenMembers_movetotop Should I then put all the members of Eigen types at the beginning of my class?
Benoit Jacob294f5f12009-01-12 14:41:12 +000097
Gael Guennebaud844e5442019-02-20 13:54:04 +010098That'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 Jacob294f5f12009-01-12 14:41:12 +000099
100\code
101class Foo
102{
103 double x;
Gael Guennebaud844e5442019-02-20 13:54:04 +0100104 Eigen::Vector4d v;
Benoit Jacob294f5f12009-01-12 14:41:12 +0000105public:
106 EIGEN_MAKE_ALIGNED_OPERATOR_NEW
107};
108\endcode
109
Gael Guennebaud844e5442019-02-20 13:54:04 +0100110That 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
Christoph Hertzberg28a4c922015-05-01 22:10:41 +0200114\section StructHavingEigenMembers_dynamicsize What about dynamic-size matrices and vectors?
Benoit Jacob294f5f12009-01-12 14:41:12 +0000115
Gael Guennebaud41ea92d2010-07-04 10:14:47 +0200116Dynamic-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 Jacob294f5f12009-01-12 14:41:12 +0000117
Gael Guennebaud844e5442019-02-20 13:54:04 +0100118
Christoph Hertzberg28a4c922015-05-01 22:10:41 +0200119\section StructHavingEigenMembers_bugineigen So is this a bug in Eigen?
Benoit Jacob294f5f12009-01-12 14:41:12 +0000120
Gael Guennebaud844e5442019-02-20 13:54:04 +0100121No, 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 Jacob294f5f12009-01-12 14:41:12 +0000122
Benoit Jacob294f5f12009-01-12 14:41:12 +0000123
Gael Guennebaud844e5442019-02-20 13:54:04 +0100124\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.
Benoit Jacob294f5f12009-01-12 14:41:12 +0000130
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
Gael Guennebaudf56316f2011-11-25 13:46:48 +0100151
Christoph Hertzberg28a4c922015-05-01 22:10:41 +0200152\section StructHavingEigenMembers_othersolutions Other solutions
Gael Guennebaudf56316f2011-11-25 13:46:48 +0100153
Gael Guennebaud844e5442019-02-20 13:54:04 +0100154In case putting the `EIGEN_MAKE_ALIGNED_OPERATOR_NEW` macro everywhere is too intrusive, there exists at least two other solutions.
Gael Guennebaudf56316f2011-11-25 13:46:48 +0100155
156\subsection othersolutions1 Disabling alignment
157
158The first is to disable alignment requirement for the fixed size members:
159\code
160class Foo
161{
162 ...
Gael Guennebaud844e5442019-02-20 13:54:04 +0100163 Eigen::Matrix<double,4,1,Eigen::DontAlign> v;
Gael Guennebaudf56316f2011-11-25 13:46:48 +0100164 ...
165};
166\endcode
Gael Guennebaud844e5442019-02-20 13:54:04 +0100167This `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
Gael Guennebaudf56316f2011-11-25 13:46:48 +0100170
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
Gael Guennebaud844e5442019-02-20 13:54:04 +0100179 Vector4d v;
Gael Guennebaudf56316f2011-11-25 13:46:48 +0100180 ...
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
Gael Guennebaud844e5442019-02-20 13:54:04 +0100198The 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.
Gael Guennebaudf56316f2011-11-25 13:46:48 +0100200
Benoit Jacob294f5f12009-01-12 14:41:12 +0000201*/
202
203}