muuuch improved documentation for the unaligned array assert.

also split into several pages for better reusability (more generally useful than
just for this assert)

5 files changed, 315 insertions, 160 deletions

diff --git a/doc/FixedSizeVectorizable.dox b/doc/FixedSizeVectorizable.dox
new file mode 100644
index 000000000..f53a6ef02
--- /dev/null
+++ b/doc/FixedSizeVectorizable.dox
@@ -0,0 +1,36 @@
+namespace Eigen {
+
+/** \page FixedSizeVectorizable Fixed-size vectorizable Eigen objects
+
+The goal of this page is to explain what we mean by "fixed-size vectorizable".
+
+\section summary Executive Summary
+
+An Eigen object is called "fixed-size vectorizable" if it has fixed size and that size is a multiple of 16 bytes.
+
+Examples include:
+\li Eigen::Vector2d
+\li Eigen::Vector4d
+\li Eigen::Vector4f
+\li Eigen::Matrix2d
+\li Eigen::Matrix2f
+\li Eigen::Matrix4d
+\li Eigen::Matrix4f
+\li Eigen::Transform3d
+\li Eigen::Transform3f
+
+\section explanation Explanation
+
+First, "fixed-size" should be clear: an Eigen object has fixed size if its number of rows and its number of columns are fixed at compile-time. So for example Matrix3f has fixed size, but MatrixXf doesn't (the opposite of fixed-size is dynamic-size).
+
+The array of coefficients of a fixed-size Eigen object is a plain "static array", it is not dynamically allocated. For example, the data behind a Matrix4f is just a "float array[16]".
+
+Fixed-size objects are typically very small, which means that we want to handle them with zero runtime overhead -- both in terms of memory usage and of speed.
+
+Now, vectorization (both SSE and AltiVec) works with 128-bit packets. Moreover, for performance reasons, these packets need to be have 128-bit alignment.
+
+So it turns out that the only way that fixed-size Eigen objects can be vectorized, is if their size is a multiple of 128 bits, or 16 bytes. Eigen will then request 16-byte alignment for these object, and henceforth rely on these objects being aligned so no runtime check for alignment is performed.
+
+*/
+
+}
diff --git a/doc/PassingByValue.dox b/doc/PassingByValue.dox
new file mode 100644
index 000000000..6eaf9ccb9
--- /dev/null
+++ b/doc/PassingByValue.dox
@@ -0,0 +1,40 @@
+namespace Eigen {
+
+/** \page PassingByValue Passing Eigen objects by value to functions
+
+Passing objects by value is almost always a very bad idea in C++, as this means useless copies, and one should pass them by reference instead.
+
+With Eigen, this is even more important: passing \ref FixedSizeVectorizable "fixed-size vectorizable Eigen objects" by value is not only inefficient, it can be illegal or make your program crash! And the reason is that these Eigen objects have alignment modifiers that aren't respected when they are passed by value.
+
+So for example, a function like this, where v is passed by value:
+
+\code
+void my_function(Eigen::Vector2d v);
+\endcode
+
+needs to be rewritten as follows, passing v by reference:
+
+\code
+void my_function(const Eigen::Vector2d& v);
+\endcode
+
+Likewise if you have a class having a Eigen object as member:
+
+\code
+struct Foo
+{
+  Eigen::Vector2d v;
+};
+void my_function(Foo v);
+\endcode
+
+This function also needs to be rewritten like this:
+\code
+void my_function(const Foo& v);
+\endcode
+
+Note that on the other hand, there is no problem with functions that return objects by value.
+
+*/
+
+}
diff --git a/doc/StlContainers.dox b/doc/StlContainers.dox
new file mode 100644
index 000000000..07420ab28
--- /dev/null
+++ b/doc/StlContainers.dox
@@ -0,0 +1,52 @@
+namespace Eigen {
+
+/** \page StlContainers Using STL Containers with Eigen
+
+\b Table \b of \b contents
+  - \ref summary
+  - \ref allocator
+  - \ref vector
+
+\section summary Executive summary
+
+Using STL containers on \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types" requires taking the following two steps:
+
+\li A 16-byte-aligned allocator must be used. Eigen does provide one ready for use: aligned_allocator.
+\li If you want to use the std::vector container, you need to #include <Eigen/StdVector>.
+
+These issues happen only with \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types". For other Eigen types, such as Vector3f or MatrixXd, no special care is needed when using STL containers.
+
+\section allocator Using an aligned allocator
+
+STL containers take an optional template parameter, the allocator type. When using STL containers on \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types", you need tell the container to use an allocator that will always allocate memory at 16-byte-aligned locations. Fortunately, Eigen does provide such an allocator: Eigen::aligned_allocator.
+
+For example, instead of
+\code
+std::map<int, Eigen::Vector4f>
+\endcode
+you need to use
+\code
+std::map<int, Eigen::Vector4f, std::less<int>, Eigen::aligned_allocator<Eigen::Vector4f> >
+\endcode
+Note that here, the 3rd parameter "std::less<int>" is just the default value, we only had to specify it because we needed to specify the allocator type, that is the 4th parameter.
+
+\section vector The case of std::vector
+
+The situation with std::vector was even worse (explanation below) so we had to specialize it for Eigen types. The upside is that our specialization takes care of specifying the aligned allocator, so you don't need to worry about it. All you need to do is to #include <Eigen/StdVector>.
+
+So as soon as you have
+\code
+#include<Eigen/StdVector>
+\endcode
+you can simply use
+\code
+std::vector<Eigen::Vector4f>
+\endcode
+without having to worry about anything.
+
+<span class="note">\b Explanation: The resize() method of std::vector takes a value_type argument (defaulting to value_type()). So with std::vector<Eigen::Vector4f>, some Eigen::Vector4f objects will be passed by value, which discards any alignment modifiers, so a Eigen::Vector4f can be created at an unaligned location. In order to avoid that, the only solution we saw was to specialize std::vector to make it work on a slight modification of, here, Eigen::Vector4f, that is able to deal properly with this situation.
+</span>
+
+*/
+
+}
diff --git a/doc/StructHavingEigenMembers.dox b/doc/StructHavingEigenMembers.dox
new file mode 100644
index 000000000..afa197900
--- /dev/null
+++ b/doc/StructHavingEigenMembers.dox
@@ -0,0 +1,149 @@
+namespace Eigen {
+
+/** \page StructHavingEigenMembers Structures Having Eigen Members
+
+\b Table \b of \b contents
+  - \ref summary
+  - \ref what
+  - \ref how
+  - \ref why
+  - \ref movetotop
+  - \ref bugineigen
+  - \ref conditional
+
+\section summary Executive Summary
+
+If you define a structure having members of \ref FixedSizeVectorizable "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.
+
+\section what What kind of code needs to be changed?
+
+The kind of code that needs to be changed is this:
+
+\code
+class Foo
+{
+  ...
+  Eigen::Vector2d v;
+  ...
+};
+
+...
+
+Foo *foo = new Foo;
+\endcode
+
+In other words: you have a class that has as a member a \ref FixedSizeVectorizable "fixed-size vectorizable Eigen object", and then you dynamically create an object of that class.
+
+\section how How should such code be modified?
+
+Very easy, you just need to put a EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro in a public part of your class, like this:
+
+\code
+class Foo
+{
+  ...
+  Eigen::Vector2d v;
+  ...
+public:
+  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
+};
+
+...
+
+Foo *foo = new Foo;
+\endcode
+
+This macro makes "new Foo" always return an aligned pointer.
+
+\section why Why is this needed?
+
+OK let's say that your code looks like this:
+
+\code
+class Foo
+{
+  ...
+  Eigen::Vector2d v;
+  ...
+};
+
+...
+
+Foo *foo = new Foo;
+\endcode
+
+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.
+
+For this reason, Eigen takes care by itself to require 128-bit alignment for Eigen::Vector2d, by doing two things:
+\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))).
+\li Eigen overloads the "operator new" of Eigen::Vector2d so it will always return 128-bit aligned pointers.
+
+Thus, normally, you don't have to worry about anything, Eigen handles alignment for you...
+
+... 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.
+
+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!
+
+The solution is to let class Foo have an aligned "operator new", as we showed in the previous section.
+
+\section movetotop Should I then put all the members of Eigen types at the beginning of my class?
+
+No, that's not needed. Since Eigen takes care of declaring 128-bit alignment, all members that need it are automatically 128-bit aligned relatively to the class. So when you have code like
+
+\code
+class Foo
+{
+  double x;
+  Eigen::Vector2d v;
+public:
+  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
+};
+\endcode
+
+it will work just fine. You do \b not need to rewrite it as
+
+\code
+class Foo
+{
+  Eigen::Vector2d v;
+  double x;
+public:
+  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
+};
+\endcode
+
+\section dynamicsize What about dynamic-size matrices and vectors?
+
+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 fixed-size matrices and vectors.
+
+\section bugineigen So is this a bug in Eigen?
+
+No, it's not our bug. It's more like an inherent problem of the C++ language -- though it must be said that any other existing language probably has the same problem. The problem is that there is no way that you can specify an aligned "operator new" that would propagate to classes having you as member data.
+
+\section conditional What if I want to do this conditionnally (depending on template parameters) ?
+
+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.
+
+Example:
+
+\code
+template<int n> class Foo
+{
+  typedef Eigen::Matrix<float,n,1> Vector;
+  enum { NeedsToAlign = (sizeof(Vector)%16)==0 };
+  ...
+  Vector v;
+  ...
+public:
+  EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign)
+};
+
+...
+
+Foo<4> *foo4 = new Foo<4>; // foo4 is guaranteed to be 128bit-aligned
+Foo<3> *foo3 = new Foo<3>; // foo3 has only the system default alignment guarantee
+\endcode
+
+*/
+
+}
diff --git a/doc/UnalignedArrayAssert.dox b/doc/UnalignedArrayAssert.dox
index 64ac6432f..a04db5ae1 100644
--- a/doc/UnalignedArrayAssert.dox
+++ b/doc/UnalignedArrayAssert.dox
@@ -2,197 +2,75 @@ namespace Eigen {
 
 /** \page UnalignedArrayAssert Explanation of the assertion on unaligned arrays
 
-\b Table \b of \b contents
-  - \ref what
-  - \ref how
-  - \ref why
-  - \ref stillstuck
-  - \ref stillstillstuck
-  - \ref movetotop
-  - \ref bugineigen
-  - \ref conditional
-<hr>
-
-\section what What kind of code made this assertion fail?
-
-If you saw the assertion failure that links to this page, then you probably have done something like that in your code:
-
-\code
-class Foo
-{
-  ...
-  Eigen::Vector2d v;
-  ...
-};
-
-...
-
-Foo *foo = new Foo;
-\endcode
-
-In other words: you have probably in your code a class that has as a member a vectorizable fixed-size Eigen object, and you then dynamically allocated an object of that class.
-
-By "vectorizable fixed-size Eigen object" we mean an Eigen matrix or vector of fixed size, and whose size is a multiple of 128 bits. Examples include:
-\li Eigen::Vector2d
-\li Eigen::Vector4d
-\li Eigen::Vector4f
-\li Eigen::Matrix2d
-\li Eigen::Matrix2f
-\li Eigen::Matrix4d
-\li Eigen::Matrix4f
-\li Eigen::Transform3d
-\li Eigen::Transform3f
-
-\section how How to fix this bug?
-
-Very easy, you just need to put a EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro in a public part of your class, like this:
-
-\code
-class Foo
-{
-  ...
-  Eigen::Vector2d v;
-  ...
-public:
-  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
-};
-
-...
-
-Foo *foo = new Foo;
-\endcode
+Hello! You are seeing this webpage because your program terminated on an assertion failure like this one:
+<pre>
+my_program: path/to/eigen2/Eigen/src/Core/MatrixStorage.h:44:
+Eigen::ei_matrix_array<T, Size, MatrixOptions, Align>::ei_matrix_array()
+[with T = double, int Size = 2, int MatrixOptions = 2, bool Align = true]:
+Assertion `(reinterpret_cast<size_t>(array) & 0xf) == 0 && "this assertion
+is explained here: http://eigen.tuxfamily.org/api/UnalignedArrayAssert.html
+**** READ THIS WEB PAGE !!! ****"' failed.
+</pre>
+
+There are 3 known causes for this issue. Please read on to understand them and learn how to fix them.
 
-With this, you should be out of trouble.
+\b Table \b of \b contents
+ - \ref c1
+ - \ref c2
+ - \ref c3
+ - \ref explanation
 
-\section why So can you explain what's happening here?
+\section c1 Cause 1: Structures having Eigen objects as members
 
-OK let's say that your code looks like this:
+If you have code like this,
 
 \code
 class Foo
 {
-  ...
+  //...
   Eigen::Vector2d v;
-  ...
+  //...
 };
-
-...
-
+//...
 Foo *foo = new Foo;
 \endcode
 
-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.
-
-For this reason, Eigen takes care by itself to require 128-bit alignment for Eigen::Vector2d, by doing two things:
-\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))).
-\li Eigen overloads the "operator new" of Eigen::Vector2d so it will always return 128-bit aligned pointers.
-
-Thus, normally, you don't have to worry about anything, Eigen handles alignment for you...
-
-... 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.
-
-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!
-
-The solution is to let class Foo have an aligned "operator new", as we showed in the previous section.
-
-\section stillstuck It still doesn't work!
-
-If you followed these instructions and you still get this assertion failure, the most likely cause is that you are passing some Eigen objects (or classes containing Eigen objects) by value. Something like
-
-\code
-void my_function(Eigen::Vector2d v);
-\endcode
-
-This will easily make this assertion fail because when the parameter v is passed to the function, it is copied onto the stack at a location that may be unaligned. Normally the compiler will catch that (since v has an alignment modifier) but we have seen cases where MSVC let that compile without catching this error.
+then you need to read this separate page: \ref StructHavingEigenMembers "Structures Having Eigen Members".
 
-Anyway, the solution is then to pass the parameter by reference instead of passing it by value:
+Note that here, Eigen::Vector2d is only used as an example, more generally the issue arises for all \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types".
 
-\code
-void my_function(const Eigen::Vector2d& v);
-\endcode
+\section c2 Cause 2: STL Containers
 
-Likewise if you have a class having a Eigen object as member:
-
-\code
-struct Foo
-{
-  Eigen::Vector2d v;
-};
-void my_function(Foo v);
-\endcode
+If you use STL Containers such as std::vector, std::map, ..., with Eigen objects, like this,
 
-This function also needs to be rewritten like this:
 \code
-void my_function(const Foo& v);
+std::vector<Eigen::Matrix2f> my_vector;
+std::map<int, Eigen::Matrix2f> my_map;
 \endcode
 
-Notice that passing objects by value is always a bad idea, as it is inefficient to copy the parameters onto the stack. So this change is something that you should do anyway.
-
-On the other hand, there is no problem with functions that return objects by value.
+then you need to read this separate page: \ref StlContainers "Using STL Containers with Eigen".
 
-\section stillstillstuck It still, STILL doesn't work!
+Note that here, Eigen::Matrix2f is only used as an example, more generally the issue arises for all \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types".
 
-Then you may have found a bug in Eigen. Please report it to our mailing list. Ideally, you would attach to your report a self-contained test case.
-
-\section movetotop Should I then put all the members of Eigen types at the beginning of my class?
-
-No, that's not needed. Since Eigen takes care of declaring 128-bit alignment, all members that need it are automatically 128-bit aligned relatively to the class. So when you have code like
-
-\code
-class Foo
-{
-  double x;
-  Eigen::Vector2d v;
-public:
-  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
-};
-\endcode
+\section c3 Cause 3: Passing Eigen objects by value
 
-it will work just fine. You do \b not need to rewrite it as
+If some function in your code is getting an Eigen object passed by value, like this,
 
 \code
-class Foo
-{
-  Eigen::Vector2d v;
-  double x;
-public:
-  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
-};
+void func(Eigen::Vector4d v);
 \endcode
 
-\section dynamicsize What about dynamic-size matrices and vectors?
+then you need to read this separate page: \ref PassingByValue "Passing Eigen objects by value to functions".
 
-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 bug. The bug discussed here is only with fixed-size matrices and vectors.
+Note that here, Eigen::Vector4d is only used as an example, more generally the issue arises for all \ref FixedSizeVectorizable "fixed-size vectorizable Eigen types".
 
-\section bugineigen So is this a bug in Eigen?
+\section explanation General explanation of this assertion
 
-No, it's not our bug. It's more like an inherent problem of the C++ language -- though it must be said that any other existing language probably has the same problem. The problem is that there is no way that you can specify an aligned "operator new" that would propagate to classes having you as member data.
+\ref FixedSizeVectorizable "fixed-size vectorizable Eigen objects" must absolutely be created at 16-byte-aligned locations, otherwise SIMD instructions adressing them will crash.
 
-\section conditional What if I want to do this conditionnally (depending on template parameters) ?
-
-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.
-
-Example:
-
-\code
-template<int n> class Foo
-{
-  typedef Eigen::Matrix<float,n,1> Vector;
-  enum { NeedsToAlign = (sizeof(Vector)%16)==0 };
-  ...
-  Vector v;
-  ...
-public:
-  EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign)
-};
-
-...
-
-Foo<4> *foo4 = new Foo<4>; // foo4 is guaranteed to be 128bit-aligned
-Foo<3> *foo3 = new Foo<3>; // foo3 has only the system default alignment guarantee
-\endcode
+Eigen normally takes care of these alignment issues for you, by setting an alignment attribute on them and by overloading their "operator new".
 
-Nore that the argument of EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF must depend on some template parameter(s). Passing an argument that does not depend on any template parameter will give a compilation error. Anyway if the argument does not depend on any template parameter, you could use EIGEN_MAKE_ALIGNED_OPERATOR_NEW instead.
+However there are a few corner cases where these alignment settings get overridden: they are the possible causes for this assertion.
 
 */