PEP 445

pep-0445.txt

@@ -67,6 +67,10 @@ API changes
 
   - ``void PyMem_SetupDebugHooks(void)``
 
+
+Use these new APIs
+------------------
+
 * ``PyMem_Malloc()`` and ``PyMem_Realloc()`` now always call ``malloc()`` and
   ``realloc()``, instead of calling ``PyObject_Malloc()`` and
   ``PyObject_Realloc()`` in debug mode
@@ -76,6 +80,12 @@ API changes
   ``PyObject_Realloc()`` falls back on ``PyMem_Realloc()`` instead of
   ``realloc()``
 
+* Replace direct calls to ``malloc()`` with ``PyMem_Malloc()``, or
+  ``PyMem_RawMalloc()`` if the GIL is not held
+
+* Configure external libraries like zlib or OpenSSL to use
+  ``PyMem_RawMalloc()``
+
 
 Examples
 ========
@@ -137,7 +147,7 @@ Setup your custom memory allocators, keeping pymalloc::
     }
 
 .. warning::
-   Remove the call ``PyMem_SetRawAllocators(&alloc);`` if the new allocators
+   Remove the call ``PyMem_SetRawAllocators(&alloc)`` if the new allocators
    are not thread-safe.
 
 
@@ -185,7 +195,7 @@ bytes) with a short liftime, you can replace override pymalloc (replace
     }
 
 .. warning::
-   Remove the call ``PyMem_SetRawAllocators(&alloc);`` if the new allocators
+   Remove the call ``PyMem_SetRawAllocators(&alloc)`` if the new allocators
    are not thread-safe.
 
 
@@ -255,9 +265,13 @@ Setup hooks on memory allocators::
         PyObject_SetAllocators(&alloc);
     }
 
+.. warning::
+   Remove the call ``PyMem_SetRawAllocators(&alloc)`` if hooks are not
+   thread-safe.
+
 .. note::
-   No need to call ``PyMem_SetupDebugHooks()``: it is already installed by
-   default.
+   ``PyMem_SetupDebugHooks()`` does not need to be called: Python debug hooks
+   are installed automatically at startup.
 
 
 Performances
@@ -339,7 +353,28 @@ The context is a convenient way to reuse the same allocator for different APIs
 PyMem_Malloc() GIL-free
 -----------------------
 
-There is no real reason to require the GIL when calling PyMem_Malloc().
+There is no real reason to require the GIL when calling ``PyMem_Malloc()``.
+
+Allowing to call ``PyMem_Malloc()`` without holding the GIL might break
+applications which setup their own allocator or their allocator hooks. Holding
+the GIL is very convinient to develop a custom allocator or a hook (no need to
+care of other threads, no need to handle mutexes, etc.).
+
+
+Don't add PyMem_RawMalloc()
+---------------------------
+
+Replace ``malloc()`` with ``PyMem_Malloc()``, but if the GIL is not held: keep
+``malloc()`` unchanged.
+
+The ``PyMem_Malloc()`` is sometimes already misused. For example, the
+``main()`` and ``Py_Main()`` functions of Python call ``PyMem_Malloc()``
+whereas the GIL do not exist yet. In this case, ``PyMem_Malloc()`` should
+be replaced with ``malloc()``.
+
+If an hook is used to the track memory usage, the ``malloc()`` memory will not
+be seen. Remaining ``malloc()`` may allocate a lot of memory and so would be
+missed in reports.
 
 
 CCP API