blob: 3f395053d090ac565181ad675a798855f266a54f [file] [log] [blame]
Gael Guennebaudaba8c9e2015-09-02 11:23:55 +02001namespace Eigen {
2
3/** \page TopicPitfalls Common pitfalls
4
Gael Guennebaud6af14332018-05-29 22:37:47 +02005
Gael Guennebaudaba8c9e2015-09-02 11:23:55 +02006\section TopicPitfalls_template_keyword Compilation error with template methods
7
8See this \link TopicTemplateKeyword page \endlink.
9
Gael Guennebaud6af14332018-05-29 22:37:47 +020010\section TopicPitfalls_aliasing Aliasing
11
12Don't miss this \link TopicAliasing page \endlink on aliasing,
13especially if you got wrong results in statements where the destination appears on the right hand side of the expression.
14
Gael Guennebaudaba8c9e2015-09-02 11:23:55 +020015\section TopicPitfalls_auto_keyword C++11 and the auto keyword
16
17In short: do not use the auto keywords with Eigen's expressions, unless you are 100% sure about what you are doing. In particular, do not use the auto keyword as a replacement for a Matrix<> type. Here is an example:
18
19\code
20MatrixXd A, B;
21auto C = A*B;
22for(...) { ... w = C * v; ...}
23\endcode
24
25In this example, the type of C is not a MatrixXd but an abstract expression representing a matrix product and storing references to A and B. Therefore, the product of A*B will be carried out multiple times, once per iteration of the for loop. Moreover, if the coefficients of A or B change during the iteration, then C will evaluate to different values.
26
Gael Guennebaudbe5e2ec2015-09-02 13:04:30 +020027Here is another example leading to a segfault:
28\code
29auto C = ((A+B).eval()).transpose();
30// do something with C
31\endcode
32The problem is that eval() returns a temporary object (in this case a MatrixXd) which is then referenced by the Transpose<> expression. However, this temporary is deleted right after the first line, and there the C expression reference a dead object. The same issue might occur when sub expressions are automatically evaluated by Eigen as in the following example:
33\code
34VectorXd u, v;
35auto C = u + (A*v).normalized();
36// do something with C
37\endcode
38where the normalized() method has to evaluate the expensive product A*v to avoid evaluating it twice. On the other hand, the following example is perfectly fine:
39\code
40auto C = (u + (A*v).normalized()).eval();
41\endcode
42In this case, C will be a regular VectorXd object.
Gael Guennebaudaba8c9e2015-09-02 11:23:55 +020043*/
44}