Guarded allocator: Document non-obvious initialization with MEM_new()

Initialization with `MEM_new()` depends a lot on the initialization rules
of C++, which are not obvious. Calling it with no arguments to be passed
to the constructor may cause the resulting object to be implicitly 0
initialized (or parts of it). This can have an impact on performance
sensitive code, so it's something to document.

Alternatively we could enforce default initialization (as opposed to the
value initalization that happens now), but this could cause
uninitialized memory in a way that isn't obvious either. This is a
possible source of bugs, so Jacques and I decided against it.

1 files changed, 6 insertions, 0 deletions

diff --git a/intern/guardedalloc/MEM_guardedalloc.h b/intern/guardedalloc/MEM_guardedalloc.h
index d071def2ca4..dccb7a32139 100644
--- a/intern/guardedalloc/MEM_guardedalloc.h
+++ b/intern/guardedalloc/MEM_guardedalloc.h
@@ -268,6 +268,12 @@ void MEM_use_guarded_allocator(void);
  * Allocate new memory for and constructs an object of type #T.
  * #MEM_delete should be used to delete the object. Just calling #MEM_freeN is not enough when #T
  * is not a trivial type.
+ *
+ * Note that when no arguments are passed, C++ will do recursive member-wise value initialization.
+ * That is because C++ differentiates between creating an object with `T` (default initialization)
+ * and `T()` (value initialization), whereby this function does the latter. Value initialization
+ * rules are complex, but for C-style structs, memory will be zero-initialized. So this doesn't
+ * match a `malloc()`, but a `calloc()` call in this case. See https://stackoverflow.com/a/4982720.
  */
 template<typename T, typename... Args>
 inline T *MEM_new(const char *allocation_name, Args &&...args)