From e7812202a744dd6f252d15d3d2462b4fd1cdd141 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Salgado Date: Wed, 2 Nov 2022 21:49:12 +0000 Subject: [PATCH] gh-96997: Clarify the contract of PyMem_SetAllocator() (GH-98977) (cherry picked from commit c053284e3930027847d5adf99efcb1aa5ccbacd1) Co-authored-by: Pablo Galindo Salgado --- Doc/c-api/memory.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index 1372dc45d78234..046719c3790f60 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 ` 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 `