/usr/share/doc/libeigen2-doc/html/StructHavingEigenMembers.html is in libeigen2-doc 2.0.17-1ubuntu1.
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 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Structures Having Eigen Members</title>
<link href="eigendoxy.css" rel="stylesheet" type="text/css">
<link href="eigendoxy_tabs.css" rel="stylesheet" type="text/css">
</head><body>
<a name="top"></a>
<a class="logo" href="http://eigen.tuxfamily.org/">
<img src="Eigen_Silly_Professor_64x64.png" width=64 height=64 alt="Eiegn's silly professor"
style="position:absolute; border:none" /></a>
<!-- Generated by Doxygen 1.8.6 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Structures Having Eigen Members </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><b>Table</b> <b>of</b> <b>contents</b> </p>
<ul>
<li><a class="el" href="StructHavingEigenMembers.html#summary">Executive Summary</a></li>
<li><a class="el" href="StructHavingEigenMembers.html#what">What kind of code needs to be changed?</a></li>
<li><a class="el" href="StructHavingEigenMembers.html#how">How should such code be modified?</a></li>
<li><a class="el" href="StructHavingEigenMembers.html#why">Why is this needed?</a></li>
<li><a class="el" href="StructHavingEigenMembers.html#movetotop">Should I then put all the members of Eigen types at the beginning of my class?</a></li>
<li><a class="el" href="StructHavingEigenMembers.html#bugineigen">So is this a bug in Eigen?</a></li>
<li><a class="el" href="StructHavingEigenMembers.html#conditional">What if I want to do this conditionnally (depending on template parameters) ?</a></li>
</ul>
<h1><a class="anchor" id="summary"></a>
Executive Summary</h1>
<p>If you define a structure having members of <a class="el" href="FixedSizeVectorizable.html">fixed-size vectorizable Eigen types</a>, 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.</p>
<h1><a class="anchor" id="what"></a>
What kind of code needs to be changed?</h1>
<p>The kind of code that needs to be changed is this:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line"> ...</div>
<div class="line"> <a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector2d</a> v;</div>
<div class="line"> ...</div>
<div class="line">};</div>
<div class="line"></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line">Foo *foo = <span class="keyword">new</span> Foo;</div>
</div><!-- fragment --><p>In other words: you have a class that has as a member a <a class="el" href="FixedSizeVectorizable.html">fixed-size vectorizable Eigen object</a>, and then you dynamically create an object of that class.</p>
<h1><a class="anchor" id="how"></a>
How should such code be modified?</h1>
<p>Very easy, you just need to put a EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro in a public part of your class, like this:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line"> ...</div>
<div class="line"> <a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector2d</a> v;</div>
<div class="line"> ...</div>
<div class="line">public:</div>
<div class="line"> EIGEN_MAKE_ALIGNED_OPERATOR_NEW</div>
<div class="line">};</div>
<div class="line"></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line">Foo *foo = <span class="keyword">new</span> Foo;</div>
</div><!-- fragment --><p>This macro makes "new Foo" always return an aligned pointer.</p>
<h1><a class="anchor" id="why"></a>
Why is this needed?</h1>
<p>OK let's say that your code looks like this:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line"> ...</div>
<div class="line"> <a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector2d</a> v;</div>
<div class="line"> ...</div>
<div class="line">};</div>
<div class="line"></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line">Foo *foo = <span class="keyword">new</span> Foo;</div>
</div><!-- fragment --><p>A 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.</p>
<p>For this reason, Eigen takes care by itself to require 128-bit alignment for Eigen::Vector2d, by doing two things: </p>
<ul>
<li>Eigen requires 128-bit alignment for the Eigen::Vector2d's array (of 2 doubles). With GCC, this is done with a <b>attribute</b> ((aligned(16))). </li>
<li>Eigen overloads the "operator new" of Eigen::Vector2d so it will always return 128-bit aligned pointers.</li>
</ul>
<p>Thus, normally, you don't have to worry about anything, Eigen handles alignment for you...</p>
<p>... 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.</p>
<p>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!</p>
<p>The solution is to let class Foo have an aligned "operator new", as we showed in the previous section.</p>
<h1><a class="anchor" id="movetotop"></a>
Should I then put all the members of Eigen types at the beginning of my class?</h1>
<p>That'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:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">double</span> x;</div>
<div class="line"> <a class="code" href="classEigen_1_1Matrix.html">Eigen::Vector2d</a> v;</div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line"> EIGEN_MAKE_ALIGNED_OPERATOR_NEW</div>
<div class="line">};</div>
</div><!-- fragment --><h1><a class="anchor" id="dynamicsize"></a>
What about dynamic-size matrices and vectors?</h1>
<p>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 <a class="el" href="FixedSizeVectorizable.html">fixed-size vectorizable matrices and vectors</a>.</p>
<h1><a class="anchor" id="bugineigen"></a>
So is this a bug in Eigen?</h1>
<p>No, 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>.</p>
<h1><a class="anchor" id="conditional"></a>
What if I want to do this conditionnally (depending on template parameters) ?</h1>
<p>For 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.</p>
<p>Example:</p>
<div class="fragment"><div class="line"><span class="keyword">template</span><<span class="keywordtype">int</span> n> <span class="keyword">class </span>Foo</div>
<div class="line">{</div>
<div class="line"> <span class="keyword">typedef</span> <a class="code" href="classEigen_1_1Matrix.html">Eigen::Matrix<float,n,1></a> Vector;</div>
<div class="line"> <span class="keyword">enum</span> { NeedsToAlign = (<span class="keyword">sizeof</span>(Vector)%16)==0 };</div>
<div class="line"> ...</div>
<div class="line"> Vector v;</div>
<div class="line"> ...</div>
<div class="line">public:</div>
<div class="line"> EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign)</div>
<div class="line">};</div>
<div class="line"></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line">Foo<4> *foo4 = <span class="keyword">new</span> Foo<4>; <span class="comment">// foo4 is guaranteed to be 128bit-aligned</span></div>
<div class="line">Foo<3> *foo3 = <span class="keyword">new</span> Foo<3>; <span class="comment">// foo3 has only the system default alignment guarantee</span></div>
</div><!-- fragment --> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Mar 21 2014 05:14:49 for Eigen by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>
|