/usr/share/doc/libeigen3-dev/html/TopicUnalignedArrayAssert.html is in libeigen3-doc 3.3.4-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<title>Eigen: Explanation of the assertion on unaligned arrays</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="eigendoxy.css" rel="stylesheet" type="text/css">
<!-- -->
<script type="text/javascript" src="eigen_navtree_hacks.js"></script>
<!-- <script type="text/javascript"> -->
<!-- </script> -->
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!-- <a name="top"></a> -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="Eigen_Silly_Professor_64x64.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname"><a href="http://eigen.tuxfamily.org">Eigen</a>
 <span id="projectnumber">3.3.4</span>
</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__TopicUnalignedArrayAssert.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Explanation of the assertion on unaligned arrays<div class="ingroups"><a class="el" href="group__DenseMatrixManipulation__chapter.html">Dense matrix and array manipulation</a> » <a class="el" href="group__DenseMatrixManipulation__Alignement.html">Alignment issues</a></div></div> </div>
</div><!--header-->
<div class="contents">
<p>Hello! You are seeing this webpage because your program terminated on an assertion failure like this one: </p><pre>
my_program: path/to/eigen/Eigen/src/Core/DenseStorage.h:44:
Eigen::internal::matrix_array<T, Size, MatrixOptions, Align>::internal::matrix_array()
[with T = double, int Size = 2, int MatrixOptions = 2, bool Align = true]:
Assertion `(reinterpret_cast<size_t>(array) & (sizemask)) == 0 && "this assertion
is explained here: <a href="http://eigen.tuxfamily.org/dox-devel/group__TopicUnalignedArrayAssert.html">http://eigen.tuxfamily.org/dox-devel/group__TopicUnalignedArrayAssert.html</a>
READ THIS WEB PAGE !!! ****"' failed.
</pre><p>There are 4 known causes for this issue. Please read on to understand them and learn how to fix them.</p>
<h1><a class="anchor" id="where"></a>
Where in my own code is the cause of the problem?</h1>
<p>First 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: </p><div class="fragment"><div class="line">$ gdb ./my_program # Start GDB on your program</div><div class="line">> run # Start running your program</div><div class="line">... # Now reproduce the crash!</div><div class="line">> bt # Obtain the backtrace</div></div><!-- fragment --><p> Now that you know precisely where in your own code the problem is happening, read on to understand what you need to change.</p>
<h1><a class="anchor" id="c1"></a>
Cause 1: Structures having Eigen objects as members</h1>
<p>If you have code like this,</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div><div class="line">{</div><div class="line"> <span class="comment">//...</span></div><div class="line"> <a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector2d</a> v;</div><div class="line"> <span class="comment">//...</span></div><div class="line">};</div><div class="line"><span class="comment">//...</span></div><div class="line">Foo *foo = <span class="keyword">new</span> Foo;</div></div><!-- fragment --><p>then you need to read this separate page: <a class="el" href="group__TopicStructHavingEigenMembers.html">Structures Having Eigen Members</a>.</p>
<p>Note that here, <a class="el" href="group__matrixtypedefs.html#ga6c206cbf6f8f3b74bc63ecd362fc2ad6">Eigen::Vector2d</a> is only used as an example, more generally the issue arises for all <a class="el" href="group__TopicFixedSizeVectorizable.html">fixed-size vectorizable Eigen types</a>.</p>
<h1><a class="anchor" id="c2"></a>
Cause 2: STL Containers or manual memory allocation</h1>
<p>If you use STL Containers such as std::vector, std::map, ..., with Eigen objects, or with classes containing Eigen objects, like this,</p>
<div class="fragment"><div class="line">std::vector<Eigen::Matrix2f> my_vector;</div><div class="line"><span class="keyword">struct </span>my_class { ... <a class="code" href="classEigen_1_1Matrix.html">Eigen::Matrix2f</a> m; ... };</div><div class="line">std::map<int, my_class> my_map;</div></div><!-- fragment --><p>then you need to read this separate page: <a class="el" href="group__TopicStlContainers.html">Using STL Containers with Eigen</a>.</p>
<p>Note that here, <a class="el" href="group__matrixtypedefs.html#ga36b8989b6aa63020139fc36bae6979e0">Eigen::Matrix2f</a> is only used as an example, more generally the issue arises for all <a class="el" href="group__TopicFixedSizeVectorizable.html">fixed-size vectorizable Eigen types</a> and <a class="el" href="group__TopicStructHavingEigenMembers.html">structures having such Eigen objects as member</a>.</p>
<p>The 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 <code>std::make_shared</code> or <code>std::allocate_shared</code> for which is the solution is to use an <a class="el" href="classEigen_1_1aligned__allocator.html">aligned allocator</a> as detailed in the <a class="el" href="group__TopicStlContainers.html">solution for STL containers</a>.</p>
<h1><a class="anchor" id="c3"></a>
Cause 3: Passing Eigen objects by value</h1>
<p>If some function in your code is getting an <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> object passed by value, like this,</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> func(<a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector4d</a> v);</div></div><!-- fragment --><p>then you need to read this separate page: <a class="el" href="group__TopicPassingByValue.html">Passing Eigen objects by value to functions</a>.</p>
<p>Note that here, <a class="el" href="group__matrixtypedefs.html#ga9b2fcb53776a2829871f8a49009bef0b">Eigen::Vector4d</a> is only used as an example, more generally the issue arises for all <a class="el" href="group__TopicFixedSizeVectorizable.html">fixed-size vectorizable Eigen types</a>.</p>
<h1><a class="anchor" id="c4"></a>
Cause 4: Compiler making a wrong assumption on stack alignment (for instance GCC on Windows)</h1>
<p>This 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:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> foo()</div><div class="line">{</div><div class="line"> <a class="code" href="classEigen_1_1Quaternion.html">Eigen::Quaternionf</a> q;</div><div class="line"> <span class="comment">//...</span></div><div class="line">}</div></div><!-- fragment --><p>then you need to read this separate page: <a class="el" href="group__TopicWrongStackAlignment.html">Compiler making a wrong assumption on stack alignment</a>.</p>
<p>Note that here, <a class="el" href="group__Geometry__Module.html#ga66aa915a26d698c60ed206818c3e4c9b">Eigen::Quaternionf</a> is only used as an example, more generally the issue arises for all <a class="el" href="group__TopicFixedSizeVectorizable.html">fixed-size vectorizable Eigen types</a>.</p>
<h1><a class="anchor" id="explanation"></a>
General explanation of this assertion</h1>
<p><a class="el" href="group__TopicFixedSizeVectorizable.html">fixed-size vectorizable Eigen objects</a> must absolutely be created at 16-byte-aligned locations, otherwise SIMD instructions addressing them will crash.</p>
<p><a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> normally takes care of these alignment issues for you, by setting an alignment attribute on them and by overloading their "operator new".</p>
<p>However there are a few corner cases where these alignment settings get overridden: they are the possible causes for this assertion.</p>
<h1><a class="anchor" id="getrid"></a>
I don't care about optimal vectorization, how do I get rid of that stuff?</h1>
<p>Three possibilities: </p><ul>
<li>
Use the <code>DontAlign</code> option to <a class="el" href="classEigen_1_1Matrix.html" title="The matrix class, also used for vectors and row-vectors. ">Matrix</a>, <a class="el" href="classEigen_1_1Array.html" title="General-purpose arrays with easy API for coefficient-wise operations. ">Array</a>, <a class="el" href="classEigen_1_1Quaternion.html" title="The quaternion class used to represent 3D orientations and rotations. ">Quaternion</a>, etc. objects that gives you trouble. This way <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> won't try to align them, and thus won"t assume any special alignment. On the down side, you will pay the cost of unaligned loads/stores for them, but on modern CPUs, the overhead is either null or marginal. See <a class="el" href="group__TopicStructHavingEigenMembers.html#StructHavingEigenMembers_othersolutions">here </a> for an example. </li>
<li>
Define <a class="el" href="TopicPreprocessorDirectives.html#TopicPreprocessorDirectivesPerformance">EIGEN_DONT_ALIGN_STATICALLY </a>. That disables all 16-byte (and above) static alignment code, while keeping 16-byte (or above) heap alignment. This has the effect of vectorizing fixed-size objects (like Matrix4d) through unaligned stores (as controlled by <a class="el" href="TopicPreprocessorDirectives.html#TopicPreprocessorDirectivesPerformance">EIGEN_UNALIGNED_VECTORIZE </a>), while keeping unchanged the vectorization of dynamic-size objects (like MatrixXd). But do note that this breaks ABI compatibility with the default behavior of static alignment. </li>
<li>
Or define both <a class="el" href="TopicPreprocessorDirectives.html#TopicPreprocessorDirectivesPerformance">EIGEN_DONT_VECTORIZE </a> and EIGEN_DISABLE_UNALIGNED_ARRAY_ASSERT. This keeps the 16-byte alignment code and thus preserves ABI compatibility, but completely disables vectorization. </li>
</ul>
<p>If you want to know why defining EIGEN_DONT_VECTORIZE does not by itself disable 16-byte alignment and the assertion, here's the explanation:</p>
<p>It doesn't disable the assertion, because otherwise code that runs fine without vectorization would suddenly crash when enabling vectorization. It doesn't disable 16-byte 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. </p>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
</ul>
</div>
</body>
</html>
|