doc

Author: d-a-v

doc/reference.rst

@@ -222,22 +222,29 @@ C++
 - About C++ `new` operator and return value
 
   The C++ standard says the following about the `new` operator behavior when encountering heap shortage (memory full):
+
   - has to throw a std::bad_alloc C++ exception
+
   - throw an unhandled exception, which means calling abort()
 
   There are several reasons for the first point above, among which are:
+
   - guarantee that the return of new is never a nullptr
+
   - guarantee full construction of the top level object plus all member subobjects
+
   - guarantee that any subobjects partially constructed get destroyed, and in the correct order, if oom is encountered midway through construction
 
   When C++ exceptions are disabled, or when using new(nothrow), the above guarantees can't be upheld, so the second point above is the only viable solution.
 
   Historically in Arduino environments, `new` is overloaded to simply return the equivalent `malloc()` which in turn can return `nullptr`. In other cores, and up to our core version 2.5.2, that is considered as acceptable.
 
   However, this behavior is not C++ standard, and there is good reason for that: there are hidden and very bad side effects. The class and member constructors are always called, even when memory is full (`this`=`nullptr`). In addition, the memory allocation for the top object could succeed, but allocation required for some member object could fail, leaving construction in an undefined state. So the historical behavior of Ardudino's `new`, when faced with insufficient memory, will lead to bad crashes sooner or later, sometimes unexplainable, generally due to memory corruption even when the returned value is checked and managed.
- 
+  
   As of core 2.6.0, we are sticking to the C++ standard. There are two clear cases when `new` encounters oom:
+
   - C++ exceptions are disabled (default build): `new` causes an exception, which in turn calls `abort()` and will "cleanly" crash, because there is no way to honor memory allocation or to recover gracefully.
+
   - C++ exceptions are enabled (menu option): `new` throws a std::bad_alloc C++ exception, which can be caught and handled gracefully. This assures correct behavior, including handling of all subobjects, which guarantees stability.
 
   To allow previous behavior, a new optional global allocator is introduced with a different semantic. It is similar to `new` but will return `nullptr` without side effects (if `std::new` is not used in constructors), as expected in arduino world. Syntax is slightly different:
@@ -257,7 +264,7 @@ C++
 
   .. code:: cpp
   
-      SomeClass* sc = new0<SomeClass>(arg1, arg2, ...);
+      SomeClass* sc = new SomeClass(arg1, arg2, ...);
       // abort() is never called, an exception is not thrown even if they are enabled
       if (sc == nullptr)
       {