gh-105766: Document that Custom Allocators Must Be Thread-Safe (gh-107519)

2 files changed, 13 insertions, 0 deletions

diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 8968b26..1df8c2b 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -476,6 +476,10 @@ Customize Memory Allocators
    thread-safe: the :term:`GIL <global interpreter lock>` is not held when the
    allocator is called.
 
+   For the remaining domains, the allocator must also be thread-safe:
+   the allocator may be called in different interpreters that do not
+   share a ``GIL``.
+
    If the new allocator is not a hook (does not call the previous allocator),
    the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the
    debug hooks on top on the new allocator.
@@ -500,6 +504,8 @@ Customize Memory Allocators
           **must** wrap the existing allocator. Substituting the current
           allocator for some other arbitrary one is **not supported**.
 
+   .. versionchanged:: 3.12
+      All allocators must be thread-safe.
 
 
 .. c:function:: void PyMem_SetupDebugHooks(void)
diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 0ac4a3d..a5cb325 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -1880,6 +1880,13 @@ Porting to Python 3.12
   * :c:func:`PyUnstable_Long_IsCompact`
   * :c:func:`PyUnstable_Long_CompactValue`
 
+* Custom allocators, set via :c:func:`PyMem_SetAllocator`, are now
+  required to be thread-safe, regardless of memory domain.  Allocators
+  that don't have their own state, including "hooks", are not affected.
+  If your custom allocator is not already thread-safe and you need
+  guidance then please create a new GitHub issue
+  and CC ``@ericsnowcurrently``.
+
 Deprecated
 ----------