MAINT: changes from review

numpy · seberg · Oct 25, 2021 · Oct 11, 2020 · Oct 16, 2020 · Oct 18, 2020
commit de22327d7adf121b9210a3abb46ed2f1cf8c1d1d
diff --git a/doc/source/reference/c-api/data_memory.rst b/doc/source/reference/c-api/data_memory.rst
@@ -1,24 +1,52 @@
-Memory management
------------------
+Memory management in NumPy
+==========================
 
-The `numpy.ndarray` is a python class. It requires additinal memory allocations
+The `numpy.ndarray` is a python class. It requires additional memory allocations
 to hold `numpy.ndarray.strides`, `numpy.ndarray.shape` and
-``numpy.ndarray.data`` attributes. These attributes are specially allocated
+`numpy.ndarray.data` attributes. These attributes are specially allocated
 after creating the python object in `__new__`. The ``strides`` and
-``dimensions`` are stored in a piece of memory allocated internally.
+``shape`` are stored in a piece of memory allocated internally.
 
 These allocations are small relative to the ``data``, the homogeneous chunk of
 memory used to store the actual array values (which could be pointers in the
-case of ``object`` arrays). Users may wish to override the internal data
-memory routines with ones of their own. They can do this by using
-``PyDataMem_SetHandler``, which uses a ``PyDataMem_Handler`` structure to hold
-pointers to functions used to manage the data memory. The calls are wrapped
-by internal routines to call :c:func:`PyTraceMalloc_Track`,
-:c:func:`PyTraceMalloc_Untrack`, and will use the `PyDataMem_EventHookFunc`
-mechanism. Since the functions may change during the lifetime of the process,
-each `ndarray` carries with it the functions used at the time of its
-instantiation, and these will be used to reallocate or free the data memory of
-the instance.
+case of ``object`` arrays). Since that memory can be significantly large, NumPy
+has provided interfaces to manage it. This document details how those
+interfaces work.
+
+Historical overview
+-------------------
+
+Since version 1.7.0, NumPy has exposed a set of ``PyDataMem_*`` functions
+(:c:func:`PyDataMem_NEW`, :c:func:`PyDataMem_FREE`, :c:func:`PyDataMem_RENEW`)
+which are backed by `alloc`, `free`, `realloc` respectively. In that version
+NumPy also exposed the `PyDataMem_EventHook` function described below, which
+wrap the OS-level calls.
+
+Python also improved its memory management capabilities, and began providing
+various :ref:`management policies <memoryoverview>` beginning in version
+3.4. These routines are divided into a set of domains, each domain has a
+:c:type:`PyMemAllocatorEx` structure of routines for memory management. Python also
+added a `tracemalloc` module to trace calls to the various routines. These
+tracking hooks were added to the NumPy ``PyDataMem_*`` routines.
+
+Configurable memory routines in NumPy
+-------------------------------------
+
+Users may wish to override the internal data memory routines with ones of their
+own. Since NumPy does not use the Python domain strategy to manage data memory,
+it provides an alternative set of C-APIs to change memory routines. There are
+no Python domain-wide strategies for large chunks of object data, so those are
+less suited to NumPy's needs. User who wish to change the NumPy data memory
+management routines can use :c:func:`PyDataMem_SetHandler`, which uses a
+:c:type:`PyDataMem_Handler` structure to hold pointers to functions used to
+manage the data memory. The calls are still wrapped by internal routines to
+call :c:func:`PyTraceMalloc_Track`, :c:func:`PyTraceMalloc_Untrack`, and will
+use the :c:func:`PyDataMem_EventHookFunc` mechanism. Since the functions may
+change during the lifetime of the process, each ``ndarray`` carries with it the
+functions used at the time of its instantiation, and these will be used to
+reallocate or free the data memory of the instance. As of NumPy version 1.20,
+the copy functions are not yet implemented, all memory copies are handled by
+calls to ``memcpy``.
 
 .. c:type:: PyDataMem_Handler
 
@@ -62,7 +90,7 @@ the instance.
    will be used to allocate data for the next PyArrayObject
 
 For an example of setting up and using the PyDataMem_Handler, see the test in
-``numpy/core/tests/test_mem_policy.py``
+:file:`numpy/core/tests/test_mem_policy.py`
 
 .. c:function:: typedef void (PyDataMem_EventHookFunc)(void *inp, void *outp,
                             size_t size, void *user_data);

diff --git a/numpy/core/include/numpy/ndarraytypes.h b/numpy/core/include/numpy/ndarraytypes.h
@@ -674,7 +674,7 @@ typedef void *(PyDataMem_ReallocFunc)(void *ptr, size_t size);
 typedef void *(PyDataMem_CopyFunc)(void *dst, const void *src, size_t size);
 
 typedef struct {
-    char name[128];  /* multiple of 64 to keep the struct unaligned */
+    char name[128];  /* multiple of 64 to keep the struct aligned */
     PyDataMem_AllocFunc *alloc;
     PyDataMem_ZeroedAllocFunc *zeroed_alloc;
     PyDataMem_FreeFunc *free;

diff --git a/numpy/core/src/multiarray/alloc.c b/numpy/core/src/multiarray/alloc.c
@@ -326,7 +326,7 @@ PyDataMem_RENEW(void *ptr, size_t size)
 }
 
 /* Memory handler global default */
-static PyDataMem_Handler default_allocator = {
+PyDataMem_Handler default_allocator = {
     "default_allocator",
     npy_alloc_cache,      /* alloc */
     npy_alloc_cache_zero, /* zeroed_alloc */

diff --git a/numpy/core/src/multiarray/alloc.h b/numpy/core/src/multiarray/alloc.h
@@ -40,6 +40,7 @@ npy_free_cache_dim_array(PyArrayObject * arr)
 }
 
 extern PyDataMem_Handler *current_allocator;
+extern PyDataMem_Handler default_allocator;
 
 #define PyArray_HANDLER(arr) ((PyArrayObject_fields*)(arr))->mem_handler
 

diff --git a/numpy/core/src/multiarray/ctors.c b/numpy/core/src/multiarray/ctors.c
@@ -804,10 +804,10 @@ PyArray_NewFromDescr_int(
         fa->flags |= NPY_ARRAY_C_CONTIGUOUS|NPY_ARRAY_F_CONTIGUOUS;
     }
 
-    /* Store the functions in case the global hander is modified */
-    fa->mem_handler = current_allocator;
 
     if (data == NULL) {
+        /* Store the functions in case the global hander is modified */
+        fa->mem_handler = current_allocator;
         /*
          * Allocate something even for zero-space arrays
          * e.g. shape=(0,) -- otherwise buffer exposure
@@ -836,6 +836,8 @@ PyArray_NewFromDescr_int(
         fa->flags |= NPY_ARRAY_OWNDATA;
     }
     else {
+        /* The handlers should never be called in this case, but just in case */
+        fa->mem_handler = &default_allocator;
         /*
          * If data is passed in, this object won't own it by default.
          * Caller must arrange for this to be reset if truly desired
-Original file line number
+Diff line change
@@ Expand Up / @@ -40,6 +40,7 @@ npy_free_cache_dim_array(PyArrayObject * arr) @@
     }
     extern PyDataMem_Handler *current_allocator;
+    extern PyDataMem_Handler default_allocator;
     #define PyArray_HANDLER(arr) ((PyArrayObject_fields*)(arr))->mem_handler
@@ Expand Down @@