source: pacpussensors/trunk/Vislab/lib3dv-1.2.0/lib3dv/eigen/doc/UnalignedArrayAssert.dox

Last change on this file was 136, checked in by ldecherf, 8 years ago

Doc

File size: 6.1 KB
Line 
1namespace Eigen {
2
3/** \eigenManualPage TopicUnalignedArrayAssert Explanation of the assertion on unaligned arrays
4
5Hello! You are seeing this webpage because your program terminated on an assertion failure like this one:
6<pre>
7my_program: path/to/eigen/Eigen/src/Core/DenseStorage.h:44:
8Eigen::internal::matrix_array<T, Size, MatrixOptions, Align>::internal::matrix_array()
9[with T = double, int Size = 2, int MatrixOptions = 2, bool Align = true]:
10Assertion `(reinterpret_cast<size_t>(array) & (sizemask)) == 0 && "this assertion
11is explained here: http://eigen.tuxfamily.org/dox/group__TopicUnalignedArrayAssert.html
12**** READ THIS WEB PAGE !!! ****"' failed.
13</pre>
14
15There are 4 known causes for this issue. Please read on to understand them and learn how to fix them.
16
17\eigenAutoToc
18
19\section where Where in my own code is the cause of the problem?
20
21First of all, you need to find out where in your own code this assertion was triggered from. At first glance, the error message doesn't look helpful, as it refers to a file inside Eigen! However, since your program crashed, if you can reproduce the crash, you can get a backtrace using any debugger. For example, if you're using GCC, you can use the GDB debugger as follows:
22\code
23$ gdb ./my_program # Start GDB on your program
24> run # Start running your program
25... # Now reproduce the crash!
26> bt # Obtain the backtrace
27\endcode
28Now that you know precisely where in your own code the problem is happening, read on to understand what you need to change.
29
30\section c1 Cause 1: Structures having Eigen objects as members
31
32If you have code like this,
33
34\code
35class Foo
36{
37 //...
38 Eigen::Vector2d v;
39 //...
40};
41//...
42Foo *foo = new Foo;
43\endcode
44
45then you need to read this separate page: \ref TopicStructHavingEigenMembers "Structures Having Eigen Members".
46
47Note that here, Eigen::Vector2d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types".
48
49\section c2 Cause 2: STL Containers or manual memory allocation
50
51If you use STL Containers such as std::vector, std::map, ..., with %Eigen objects, or with classes containing %Eigen objects, like this,
52
53\code
54std::vector<Eigen::Matrix2f> my_vector;
55struct my_class { ... Eigen::Matrix2f m; ... };
56std::map<int, my_class> my_map;
57\endcode
58
59then you need to read this separate page: \ref TopicStlContainers "Using STL Containers with Eigen".
60
61Note that here, Eigen::Matrix2f is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref TopicStructHavingEigenMembers "structures having such Eigen objects as member".
62
63The same issue will be exhibited by any classes/functions by-passing operator new to allocate memory, that is, by performing custom memory allocation followed by calls to the placement new operator. This is for instance typically the case of \c std::make_shared or \c std::allocate_shared for which is the solution is to use an \ref aligned_allocator "aligned allocator" as detailed in the \ref TopicStlContainers "solution for STL containers".
64
65\section c3 Cause 3: Passing Eigen objects by value
66
67If some function in your code is getting an Eigen object passed by value, like this,
68
69\code
70void func(Eigen::Vector4d v);
71\endcode
72
73then you need to read this separate page: \ref TopicPassingByValue "Passing Eigen objects by value to functions".
74
75Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types".
76
77\section c4 Cause 4: Compiler making a wrong assumption on stack alignment (for instance GCC on Windows)
78
79This is a must-read for people using GCC on Windows (like MinGW or TDM-GCC). If you have this assertion failure in an innocent function declaring a local variable like this:
80
81\code
82void foo()
83{
84 Eigen::Quaternionf q;
85 //...
86}
87\endcode
88
89then you need to read this separate page: \ref TopicWrongStackAlignment "Compiler making a wrong assumption on stack alignment".
90
91Note that here, Eigen::Quaternionf is only used as an example, more generally the issue arises for all \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types".
92
93\section explanation General explanation of this assertion
94
95\ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen objects" must absolutely be created at 16-byte-aligned locations, otherwise SIMD instructions adressing them will crash.
96
97Eigen normally takes care of these alignment issues for you, by setting an alignment attribute on them and by overloading their "operator new".
98
99However there are a few corner cases where these alignment settings get overridden: they are the possible causes for this assertion.
100
101\section getrid I don't care about vectorization, how do I get rid of that stuff?
102
103Two possibilities:
104<ul>
105 <li>Define EIGEN_DONT_ALIGN_STATICALLY. That disables all 128-bit static alignment code, while keeping 128-bit heap alignment. This has the effect of
106 disabling vectorization for fixed-size objects (like Matrix4d) while keeping vectorization of dynamic-size objects
107 (like MatrixXd). But do note that this breaks ABI compatibility with the default behavior of 128-bit static alignment.</li>
108 <li>Or define both EIGEN_DONT_VECTORIZE and EIGEN_DISABLE_UNALIGNED_ARRAY_ASSERT. This keeps the
109 128-bit alignment code and thus preserves ABI compatibility, but completely disables vectorization.</li>
110</ul>
111
112If you want to know why defining EIGEN_DONT_VECTORIZE does not by itself disable 128-bit alignment and the assertion, here's the explanation:
113
114It doesn't disable the assertion, because otherwise code that runs fine without vectorization would suddenly crash when enabling vectorization.
115It doesn't disable 128bit alignment, because that would mean that vectorized and non-vectorized code are not mutually ABI-compatible. This ABI compatibility is very important, even for people who develop only an in-house application, as for instance one may want to have in the same application a vectorized path and a non-vectorized path.
116
117*/
118
119}
Note: See TracBrowser for help on using the repository browser.