Bug 615 - "static" / local storage on stack
"static" / local storage on stack
Status: RESOLVED FIXED
Product: Eigen
Classification: Unclassified
Component: Documentation
3.0
All All
: Normal Unknown
Assigned To: Nobody
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2013-06-17 12:26 UTC by Enrico
Modified: 2013-06-18 15:36 UTC (History)
4 users (show)



Attachments

Description Enrico 2013-06-17 12:26:14 UTC
the static keyword  appears several times in the tutorial
for example,

http://eigen.tuxfamily.org/dox/TutorialMatrixClass.html
with a static float[9] 
Internally, a fixed-size Eigen matrix is just a plain static array
since Eigen will try to allocate the array as a static array

the author may want to express if a variable is defined in the scope of function, the allocation / deallocation on the stack will cost almost nothing.
However, it may lead to confusion since static has its special meaning in C/C++ language.
Comment 1 Gael Guennebaud 2013-06-17 21:25:20 UTC
yes, you are right, we should speak about stack-based allocation rather than static allocation.
Comment 2 Christoph Hertzberg 2013-06-18 12:31:01 UTC
Actually, we can't say much about allocation, because you can still allocate fixed-sized matrices on the heap, the stack or statically. 
Maybe "plain static-sized array" is the term we are looking for?
As an alternative, the std::array documentation here http://www.cplusplus.com/reference/array/array/ uses the phrase "ordinary array declared with the language's bracket syntax ([])". Maybe that is a bit too layman-ish but every C/C++ programmer should clearly understand that.
Comment 3 Jitse Niesen 2013-06-18 14:23:22 UTC
It's not easy to describe correctly and concisely. I guess the best term depends on the context. Going through the three cases flagged up, with my attempt to rewrite them:

OLD TEXT:

"A default constructor is always available, never performs any dynamic memory allocation, and never initializes the matrix coefficients. You can do:

Matrix3f a;
MatrixXf b;

Here,

 * a is a 3x3 matrix, with a static float[9] array of uninitialized
   coefficients,
 * b is a dynamic-size matrix whose size is currently 0x0, and whose array of
   coefficients hasn't yet been allocated at all."

REWRITE:

"[...] a is a 3x3 matrix whose array of coefficients is allocated automatically but not initialized, similar to when you write <code>float a[9]</code> [...]"

[ This ignores what happens when it is a global variable. I believe "automatic allocation" is a technical term but I'm not sure how widespread it is. ]

------------------------

OLD TEXT:

"Internally, a fixed-size Eigen matrix is just a plain static array, i.e. doing

Matrix4f mymatrix;

really amounts to just doing

float mymatrix[16];

so this really has zero runtime cost"

REWRITE:

Just remove "static", I think it's clear enough without it

------------------------

OLD TEXT:

"Worse, trying to create a very large matrix using fixed sizes could result in a stack overflow, since Eigen will try to allocate the array as a static array, which by default goes on the stack."

REWRITE:

"Worse, trying to create a very large matrix using fixed sizes inside a function could result in a stack overflow, since Eigen will try to allocate the array automatically as a local variable, and this is normally done on the stack."
Comment 4 Christoph Hertzberg 2013-06-18 14:39:14 UTC
(In reply to comment #3)
>  * a is a 3x3 matrix, with a static float[9] array of uninitialized
>    coefficients,
> 
> REWRITE:
> 
> "[...] a is a 3x3 matrix whose array of coefficients is allocated automatically
> but not initialized, similar to when you write <code>float a[9]</code> [...]"
> 
> [ This ignores what happens when it is a global variable. I believe "automatic
> allocation" is a technical term but I'm not sure how widespread it is. ]

How about just replacing "static" by "plain"?
To me "automatic allocation" sounds more as if the class calls new and free automatically (contradicting the part after the comma).

I agree on the other two.
Comment 5 Jitse Niesen 2013-06-18 15:36:32 UTC
Yes, I agree with that. I now pushed this change.

changeset:   5357:9d9a060aae44
date:        Tue Jun 18 14:35:12 2013 +0100
summary:     Avoid phrase "static allocation" for local storage on stack (bug 615).

Note You need to log in before you can comment on or make changes to this bug.