1namespace Eigen {
2
3/** \eigenManualPage TopicStructHavingEigenMembers Structures Having Eigen Members
4
5\eigenAutoToc
6
7\section StructHavingEigenMembers_summary Executive Summary
8
9If 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.
10
11\section StructHavingEigenMembers_what What kind of code needs to be changed?
12
13The kind of code that needs to be changed is this:
14
15\code
16class Foo
17{
18  ...
19  Eigen::Vector2d v;
20  ...
21};
22
23...
24
25Foo *foo = new Foo;
26\endcode
27
28In 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.
29
30\section StructHavingEigenMembers_how How should such code be modified?
31
32Very easy, you just need to put a EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro in a public part of your class, like this:
33
34\code
35class Foo
36{
37  ...
38  Eigen::Vector2d v;
39  ...
40public:
41  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
42};
43
44...
45
46Foo *foo = new Foo;
47\endcode
48
49This macro makes "new Foo" always return an aligned pointer.
50
51If this approach is too intrusive, see also the \ref StructHavingEigenMembers_othersolutions "other solutions".
52
53\section StructHavingEigenMembers_why Why is this needed?
54
55OK let's say that your code looks like this:
56
57\code
58class Foo
59{
60  ...
61  Eigen::Vector2d v;
62  ...
63};
64
65...
66
67Foo *foo = new Foo;
68\endcode
69
70A 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.
71
72For this reason, Eigen takes care by itself to require 128-bit alignment for Eigen::Vector2d, by doing two things:
73\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))).
74\li Eigen overloads the "operator new" of Eigen::Vector2d so it will always return 128-bit aligned pointers.
75
76Thus, normally, you don't have to worry about anything, Eigen handles alignment for you...
77
78... 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.
79
80The 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!
81
82The solution is to let class Foo have an aligned "operator new", as we showed in the previous section.
83
84\section StructHavingEigenMembers_movetotop Should I then put all the members of Eigen types at the beginning of my class?
85
86That'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:
87
88\code
89class Foo
90{
91  double x;
92  Eigen::Vector2d v;
93public:
94  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
95};
96\endcode
97
98\section StructHavingEigenMembers_dynamicsize What about dynamic-size matrices and vectors?
99
100Dynamic-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".
101
102\section StructHavingEigenMembers_bugineigen So is this a bug in Eigen?
103
104No, 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>.
105
106\section StructHavingEigenMembers_conditional What if I want to do this conditionnally (depending on template parameters) ?
107
108For 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.
109
110Example:
111
112\code
113template<int n> class Foo
114{
115  typedef Eigen::Matrix<float,n,1> Vector;
116  enum { NeedsToAlign = (sizeof(Vector)%16)==0 };
117  ...
118  Vector v;
119  ...
120public:
121  EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign)
122};
123
124...
125
126Foo<4> *foo4 = new Foo<4>; // foo4 is guaranteed to be 128bit-aligned
127Foo<3> *foo3 = new Foo<3>; // foo3 has only the system default alignment guarantee
128\endcode
129
130
131\section StructHavingEigenMembers_othersolutions Other solutions
132
133In case putting the EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro everywhere is too intrusive, there exists at least two other solutions.
134
135\subsection othersolutions1 Disabling alignment
136
137The first is to disable alignment requirement for the fixed size members:
138\code
139class Foo
140{
141  ...
142  Eigen::Matrix<double,2,1,Eigen::DontAlign> v;
143  ...
144};
145\endcode
146This has for effect to disable vectorization when using \c v.
147If a function of Foo uses it several times, then it still possible to re-enable vectorization by copying it into an aligned temporary vector:
148\code
149void Foo::bar()
150{
151  Eigen::Vector2d av(v);
152  // use av instead of v
153  ...
154  // if av changed, then do:
155  v = av;
156}
157\endcode
158
159\subsection othersolutions2 Private structure
160
161The 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:
162
163\code
164struct Foo_d
165{
166  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
167  Vector2d v;
168  ...
169};
170
171
172struct Foo {
173  Foo() { init_d(); }
174  ~Foo() { delete d; }
175  void bar()
176  {
177    // use d->v instead of v
178    ...
179  }
180private:
181  void init_d() { d = new Foo_d; }
182  Foo_d* d;
183};
184\endcode
185
186The clear advantage here is that the class Foo remains unchanged regarding alignment issues. The drawback is that a heap allocation will be required whatsoever.
187
188*/
189
190}
191