From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> Date: Wed, 2 Nov 2022 21:56:14 +0000 (-0700) Subject: gh-96997: Clarify the contract of PyMem_SetAllocator() (GH-98977) X-Git-Tag: v3.10.9~89 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=6cf30c6cc464c428f454038b80c084d13475730d;p=thirdparty%2FPython%2Fcpython.git gh-96997: Clarify the contract of PyMem_SetAllocator() (GH-98977) (cherry picked from commit c053284e3930027847d5adf99efcb1aa5ccbacd1) Co-authored-by: Pablo Galindo Salgado --- 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 ` 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 `