[Python-checkins] gh-96997: Clarify the contract of PyMem_SetAllocator() (GH-98977)

[miss-islington]

https://github.com/python/cpython/commit/6cf30c6cc464c428f454038b80c084d13475730d
commit: 6cf30c6cc464c428f454038b80c084d13475730d
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-11-02T14:56:14-07:00
summary:

gh-96997: Clarify the contract of PyMem_SetAllocator() (GH-98977)

(cherry picked from commit c053284e3930027847d5adf99efcb1aa5ccbacd1)

Co-authored-by: Pablo Galindo Salgado <Pablogsal at gmail.com>

files:
M Doc/c-api/memory.rst

diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 1372dc45d782..046719c3790f 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -95,6 +95,8 @@ for the I/O buffer escapes completely the Python memory manager.
 Allocator Domains
 =================
 
+.. _allocator-domains:
+
 All allocating functions belong to one of three different "domains" (see also
 :c:type:`PyMemAllocatorDomain`). These domains represent different allocation
 strategies and are optimized for different purposes. The specific details on
@@ -477,6 +479,25 @@ Customize Memory Allocators
    debug hooks on top on the new allocator.
 
 
+   .. warning::
+
+       :c:func:`PyMem_SetAllocator` does have the following contract:
+
+        * It can be called after :c:func:`Py_PreInitialize` and before
+          :c:func:`Py_InitializeFromConfig` to install a custom memory
+          allocator. There are no restrictions over the installed allocator
+          other than the ones imposed by the domain (for instance, the Raw
+          Domain allows the allocator to be called without the GIL held). See
+          :ref:`the section on allocator domains <allocator-domains>` for more
+          information.
+
+        * If called after Python has finish initializing (after
+          :c:func:`Py_InitializeFromConfig` has been called) the allocator
+          **must** wrap the existing allocator. Substituting the current
+          allocator for some other arbitrary one is **not supported**.
+
+
+
 .. c:function:: void PyMem_SetupDebugHooks(void)
 
    Setup :ref:`debug hooks in the Python memory allocators <pymem-debug-hooks>`