update to match NEP 49

numpy · seberg · Oct 25, 2021 · Oct 11, 2020 · Oct 16, 2020 · Oct 18, 2020
commit 9e7c3ed40bcf51a0cdbc46dc1dfcb9550bded991
diff --git a/doc/source/reference/c-api/data_memory.rst b/doc/source/reference/c-api/data_memory.rst
@@ -7,11 +7,10 @@ to hold `numpy.ndarray.strides`, `numpy.ndarray.shape` and
 after creating the python object in `__new__`. The ``strides`` and
 ``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). Since that memory can be significantly large, NumPy
-has provided interfaces to manage it. This document details how those
-interfaces work.
+The ``data`` allocation used to store the actual array values (which could be
+pointers in the case of ``object`` arrays) can be very large, so NumPy has
+provided interfaces to manage its allocation and release. This document details
+how those interfaces work.
 
 Historical overview
 -------------------
@@ -22,15 +21,23 @@ 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
+Since those early days, 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
--------------------------------------
+NumPy added a small cache of allocated memory in its internal
+``npy_alloc_cache``, ``npy_alloc_cache_zero``, and ``npy_free_cache``
+functions. These wrap ``alloc``, ``alloc-and-memset(0)`` and ``free``
+respectively, but when ``npy_free_cache`` is called, it adds the pointer to a
+short list of available blocks marked by size. These blocks can be re-used by
+subsequent calls to ``npy_alloc*``, avoiding memory thrashing.
+
+Configurable memory routines in NumPy (NEP 49)
+----------------------------------------------
 
 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,
@@ -44,9 +51,7 @@ 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.21,
-the copy functions are not yet implemented, all memory copies are handled by
-calls to ``memcpy``.
+reallocate or free the data memory of the instance.
 
 .. c:type:: PyDataMem_Handler
 
@@ -55,14 +60,11 @@ calls to ``memcpy``.
     .. code-block:: c
 
         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;
             PyDataMem_ReallocFunc *realloc;
-            PyDataMem_CopyFunc *host2obj;  /* copy from the host python */
-            PyDataMem_CopyFunc *obj2host;  /* copy to the host python */
-            PyDataMem_CopyFunc *obj2obj;  /* copy between two objects */
         } PyDataMem_Handler;
 
     where the function's signatures are
@@ -73,40 +75,38 @@ calls to ``memcpy``.
         typedef void *(PyDataMem_ZeroedAllocFunc)(size_t nelems, size_t elsize);
         typedef void (PyDataMem_FreeFunc)(void *ptr, size_t size);
         typedef void *(PyDataMem_ReallocFunc)(void *ptr, size_t size);
-        typedef void *(PyDataMem_CopyFunc)(void *dst, const void *src, size_t size);
 
 .. c:function:: const PyDataMem_Handler * PyDataMem_SetHandler(PyDataMem_Handler *handler)
 
-   Sets a new allocation policy. If the input value is NULL, will reset
-   the policy to the default. Returns the previous policy, NULL if the
+   Sets a new allocation policy. If the input value is ``NULL``, will reset
+   the policy to the default. Returns the previous policy, ``NULL`` if the
    previous policy was the default. We wrap the user-provided functions
    so they will still call the python and numpy memory management callback
    hooks.
 
 .. c:function:: const char * PyDataMem_GetHandlerName(PyArrayObject *obj)
 
-   Return the const char name of the PyDataMem_Handler used by the
-   PyArrayObject. If NULL, return the name of the current global policy that
-   will be used to allocate data for the next PyArrayObject
+   Return the const char name of the `PyDataMem_Handler` used by the
+   ``PyArrayObject``. If ``NULL``, return the name of the current global policy
+   that 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
 :file:`numpy/core/tests/test_mem_policy.py`
 
 .. c:function:: void PyDataMem_EventHookFunc(void *inp, void *outp, size_t size, void *user_data);
 
-    This function will be cal
AD86
led on NEW,FREE,RENEW calls in data memory
-    manipulation
+    This function will be called during data memory manipulation
 
 
 
 .. c:function:: PyDataMem_EventHookFunc * PyDataMem_SetEventHook(PyDataMem_EventHookFunc *newhook, void *user_data, void **old_data)
 
     Sets the allocation event hook for numpy array data.
 
-    Returns a pointer to the previous hook or NULL.  If old_data is
-    non-NULL, the previous user_data pointer will be copied to it.
+    Returns a pointer to the previous hook or ``NULL``.  If old_data is
+    non-``NULL``, the previous user_data pointer will be copied to it.
 
-    If not NULL, hook will be called at the end of each PyDataMem_NEW/FREE/RENEW:
+    If not ``NULL``, hook will be called at the end of each ``PyDataMem_NEW/FREE/RENEW``:
 
     .. code-block:: c
 

diff --git a/numpy/core/include/numpy/ndarraytypes.h b/numpy/core/include/numpy/ndarraytypes.h
@@ -671,7 +671,6 @@ typedef void *(PyDataMem_AllocFunc)(size_t size);
 typedef void *(PyDataMem_ZeroedAllocFunc)(size_t nelems, size_t elsize);
 typedef void (PyDataMem_FreeFunc)(void *ptr, size_t size);
 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 aligned */