https://github.com/python/cpython/commit/717ebd7a36c66d7c148e776b8bd638948424960a commit: 717ebd7a36c66d7c148e776b8bd638948424960a branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: lysnikolaou <[email protected]> date: 2026-03-11T15:28:11+01:00 summary:
[3.14] gh-142518: Improve mimalloc allocator docs (GH-145224) (#145823) (cherry picked from commit 7a1da4575b1d8fa87efb62334a8e99cd513d86e9) Co-authored-by: Lysandros Nikolaou <[email protected]> files: M Doc/c-api/memory.rst M Doc/using/cmdline.rst M Doc/using/configure.rst diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index a3be75a2a76d60..0dd57eaf37e6b3 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -208,8 +208,11 @@ The following function sets, modeled after the ANSI C standard, but specifying behavior when requesting zero bytes, are available for allocating and releasing memory from the Python heap. -The :ref:`default memory allocator <default-memory-allocators>` uses the -:ref:`pymalloc memory allocator <pymalloc>`. +In the GIL-enabled build (default build) the +:ref:`default memory allocator <default-memory-allocators>` uses the +:ref:`pymalloc memory allocator <pymalloc>`, whereas in the +:term:`free-threaded build`, the default is the +:ref:`mimalloc memory allocator <mimalloc>` instead. .. warning:: @@ -219,6 +222,11 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the The default allocator is now pymalloc instead of system :c:func:`malloc`. +.. versionchanged:: 3.13 + + In the :term:`free-threaded <free threading>` build, the default allocator + is now :ref:`mimalloc <mimalloc>`. + .. c:function:: void* PyMem_Malloc(size_t n) Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the @@ -344,7 +352,9 @@ memory from the Python heap. the :ref:`Customize Memory Allocators <customize-memory-allocators>` section. The :ref:`default object allocator <default-memory-allocators>` uses the -:ref:`pymalloc memory allocator <pymalloc>`. +:ref:`pymalloc memory allocator <pymalloc>`. In the +:term:`free-threaded <free threading>` build, the default is the +:ref:`mimalloc memory allocator <mimalloc>` instead. .. warning:: @@ -424,14 +434,16 @@ Default Memory Allocators Default memory allocators: -=============================== ==================== ================== ===================== ==================== -Configuration Name PyMem_RawMalloc PyMem_Malloc PyObject_Malloc -=============================== ==================== ================== ===================== ==================== -Release build ``"pymalloc"`` ``malloc`` ``pymalloc`` ``pymalloc`` -Debug build ``"pymalloc_debug"`` ``malloc`` + debug ``pymalloc`` + debug ``pymalloc`` + debug -Release build, without pymalloc ``"malloc"`` ``malloc`` ``malloc`` ``malloc`` -Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` + debug ``malloc`` + debug ``malloc`` + debug -=============================== ==================== ================== ===================== ==================== +=================================== ======================= ==================== ====================== ====================== +Configuration Name PyMem_RawMalloc PyMem_Malloc PyObject_Malloc +=================================== ======================= ==================== ====================== ====================== +Release build ``"pymalloc"`` ``malloc`` ``pymalloc`` ``pymalloc`` +Debug build ``"pymalloc_debug"`` ``malloc`` + debug ``pymalloc`` + debug ``pymalloc`` + debug +Release build, without pymalloc ``"malloc"`` ``malloc`` ``malloc`` ``malloc`` +Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` + debug ``malloc`` + debug ``malloc`` + debug +Free-threaded build ``"mimalloc"`` ``mimalloc`` ``mimalloc`` ``mimalloc`` +Free-threaded debug build ``"mimalloc_debug"`` ``mimalloc`` + debug ``mimalloc`` + debug ``mimalloc`` + debug +=================================== ======================= ==================== ====================== ====================== Legend: @@ -439,8 +451,7 @@ Legend: * ``malloc``: system allocators from the standard C library, C functions: :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. * ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`. -* ``mimalloc``: :ref:`mimalloc memory allocator <mimalloc>`. The pymalloc - allocator will be used if mimalloc support isn't available. +* ``mimalloc``: :ref:`mimalloc memory allocator <mimalloc>`. * "+ debug": with :ref:`debug hooks on the Python memory allocators <pymem-debug-hooks>`. * "Debug build": :ref:`Python build in debug mode <debug-build>`. @@ -733,9 +744,27 @@ The mimalloc allocator .. versionadded:: 3.13 -Python supports the mimalloc allocator when the underlying platform support is available. -mimalloc "is a general purpose allocator with excellent performance characteristics. -Initially developed by Daan Leijen for the runtime systems of the Koka and Lean languages." +Python supports the `mimalloc <https://github.com/microsoft/mimalloc/>`__ +allocator when the underlying platform support is available. +mimalloc is a general purpose allocator with excellent performance +characteristics, initially developed by Daan Leijen for the runtime systems +of the Koka and Lean languages. + +Unlike :ref:`pymalloc <pymalloc>`, which is optimized for small objects (512 +bytes or fewer), mimalloc handles allocations of any size. + +In the :term:`free-threaded <free threading>` build, mimalloc is the default +and **required** allocator for the :c:macro:`PYMEM_DOMAIN_MEM` and +:c:macro:`PYMEM_DOMAIN_OBJ` domains. It cannot be disabled in free-threaded +builds. The free-threaded build uses per-thread mimalloc heaps, which allows +allocation and deallocation to proceed without locking in most cases. + +In the default (non-free-threaded) build, mimalloc is available but not the +default allocator. It can be selected at runtime using +:envvar:`PYTHONMALLOC`\ ``=mimalloc`` (or ``mimalloc_debug`` to include +:ref:`debug hooks <pymem-debug-hooks>`). It can be disabled at build time +using the :option:`--without-mimalloc` configure option, but this option +cannot be combined with :option:`--disable-gil`. tracemalloc C API ================= diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 24541e84732faf..09be3af0abe1ce 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -1045,6 +1045,13 @@ conflict. * ``pymalloc_debug``: same as ``pymalloc`` but also install debug hooks. * ``mimalloc_debug``: same as ``mimalloc`` but also install debug hooks. + .. note:: + + In the :term:`free-threaded <free threading>` build, the ``malloc``, + ``malloc_debug``, ``pymalloc``, and ``pymalloc_debug`` values are not + supported. Only ``default``, ``debug``, ``mimalloc``, and + ``mimalloc_debug`` are accepted. + .. versionadded:: 3.6 .. versionchanged:: 3.7 @@ -1054,12 +1061,13 @@ conflict. .. envvar:: PYTHONMALLOCSTATS If set to a non-empty string, Python will print statistics of the - :ref:`pymalloc memory allocator <pymalloc>` every time a new pymalloc object - arena is created, and on shutdown. + :ref:`pymalloc memory allocator <pymalloc>` or the + :ref:`mimalloc memory allocator <mimalloc>` (whichever is in use) + every time a new object arena is created, and on shutdown. This variable is ignored if the :envvar:`PYTHONMALLOC` environment variable is used to force the :c:func:`malloc` allocator of the C library, or if - Python is configured without ``pymalloc`` support. + Python is configured without both ``pymalloc`` and ``mimalloc`` support. .. versionchanged:: 3.6 This variable can now also be used on Python compiled in release mode. diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 61e21fba74c3a0..7372ae71a4ba47 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -747,6 +747,9 @@ also be used to improve performance. Disable the fast :ref:`mimalloc <mimalloc>` allocator (enabled by default). + This option cannot be used together with :option:`--disable-gil` + because the :term:`free-threaded <free threading>` build requires mimalloc. + See also :envvar:`PYTHONMALLOC` environment variable. .. option:: --without-pymalloc _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
