Difference between revisions of "Pit Falls"

From Eigen
Jump to: navigation, search
(Initial Pit Fall writeup)
 
(Alignment Issues (crash))
Line 1: Line 1:
 
= Pit Falls =
 
= Pit Falls =
  
== Alignment Issues (crash) ==
+
== Alignment Issues (runtime assertion) ==
Eigen has made some trade offs in favor of performance that have some costs in the use of the library.
+
  
Specifically there are a class of pit-falls related to alignment that are important to understand before choosing Eigen.
+
Eigen does explicit vectorization, and while that is appreciated by many users, that also leads to some issues in special situations where data alignment is compromised. Indeed, C++98 doesn't have quite good enough support for explicit data alignment (that's coming in C++1x). In that case your program hits an assertion failure (that is, a "controlled crash") with a message that tells you to consult this page:
  
You can read more about them [http://eigen.tuxfamily.org/dox/UnalignedArrayAssert.html| here] but in short they are:
+
  [http://eigen.tuxfamily.org/dox/UnalignedArrayAssert.html http://eigen.tuxfamily.org/dox/UnalignedArrayAssert.html]
 
+
* [http://eigen.tuxfamily.org/dox/StructHavingEigenMembers.html| You cannot safely pass-by-value] (crash)
+
* If you have members of classes that are Eigen types be sure to [http://eigen.tuxfamily.org/dox/StructHavingEigenMembers.html| use the included macro] that defines a new 'new' operator to fix alignment (crash)
+
* Using Eigen types with STL containers [http://eigen.tuxfamily.org/dox/StlContainers.html| requires use of special allocators] (crash)
+
** This probably implies a whole class of issues that may result from using Eigen types with templates that allocate memory (''does anyone know if this is true'')
+
* If you are using GCC on windows you must use [http://eigen.tuxfamily.org/dox/WrongStackAlignment.html| special considerations and fixes] to make it work (crash)
+
  
 +
Have a look at it and see for yourself if that's something that can cope with. It contains detailed information about how to deal with each known cause for that issue.
  
 +
Now what if you don't care about vectorization and so don't want to be annoyed with these alignment issues? The easiest is that you define these two preprocessor symbols: EIGEN_DONT_VECTORIZE and EIGEN_DISABLE_UNALIGNED_ARRAY_ASSERT. If you use the development branch, it's even easier, just define EIGEN_DONT_ALIGN.
  
 
== Header Issues (failure to compile) ==
 
== Header Issues (failure to compile) ==

Revision as of 20:30, 17 September 2009

Pit Falls

Alignment Issues (runtime assertion)

Eigen does explicit vectorization, and while that is appreciated by many users, that also leads to some issues in special situations where data alignment is compromised. Indeed, C++98 doesn't have quite good enough support for explicit data alignment (that's coming in C++1x). In that case your program hits an assertion failure (that is, a "controlled crash") with a message that tells you to consult this page:

 http://eigen.tuxfamily.org/dox/UnalignedArrayAssert.html

Have a look at it and see for yourself if that's something that can cope with. It contains detailed information about how to deal with each known cause for that issue.

Now what if you don't care about vectorization and so don't want to be annoyed with these alignment issues? The easiest is that you define these two preprocessor symbols: EIGEN_DONT_VECTORIZE and EIGEN_DISABLE_UNALIGNED_ARRAY_ASSERT. If you use the development branch, it's even easier, just define EIGEN_DONT_ALIGN.

Header Issues (failure to compile)

Eigen has split the functionality of individual types across header files which can cause confusion. Just because you can instantiate a type does not mean that you have access to all of it's functionality. To concisely illustrate the issue consider the following:

#include <Eigen/Core>
int main()
{
	Eigen::Vector3d vec1, vec2;
	vec1.cross( vec2 );
	return 0;
}

Compiling this will an error in line 5 (vec1.cross...):

undefined reference to `Eigen::Matrix<double, 3, 1, 2, 3, 1> Eigen::MatrixBase<Eigen::Matrix<double, 3, 1, 2, 3, 1> >::cross<Eigen::Matrix<double, 3, 1, 2, 3, 1> >(Eigen::MatrixBase<Eigen::Matrix<double, 3, 1, 2, 3, 1> > const&) const'

...because the cross product functionality is in another header(Eigen/Geometry).