CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 445 – Add new APIs to customize Python memory allocators | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0445/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 445 – Add new APIs to customize Python memory allocators | peps.python.org'> <meta property="og:description" content="This PEP proposes new Application Programming Interfaces (API) to customize Python memory allocators. The only implementation required to conform to this PEP is CPython, but other implementations may choose to be compatible, or to re-use a similar scheme."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0445/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP proposes new Application Programming Interfaces (API) to customize Python memory allocators. The only implementation required to conform to this PEP is CPython, but other implementations may choose to be compatible, or to re-use a similar scheme."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 445</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 445 – Add new APIs to customize Python memory allocators</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Victor Stinner <vstinner at python.org></dd> <dt class="field-even">BDFL-Delegate:</dt> <dd class="field-even">Antoine Pitrou <solipsis at pitrou.net></dd> <dt class="field-odd">Status:</dt> <dd class="field-odd"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-even">Type:</dt> <dd class="field-even"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">15-Jun-2013</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.4</dd> <dt class="field-odd">Resolution:</dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2013-July/127222.html">Python-Dev message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#new-functions-and-structures">New Functions and Structures</a></li> <li><a class="reference internal" href="#redesign-debug-checks-on-memory-block-allocators-as-hooks">Redesign Debug Checks on Memory Block Allocators as Hooks</a></li> <li><a class="reference internal" href="#don-t-call-malloc-directly-anymore">Don’t call malloc() directly anymore</a></li> </ul> </li> <li><a class="reference internal" href="#examples">Examples</a><ul> <li><a class="reference internal" href="#use-case-1-replace-memory-allocators-keep-pymalloc">Use case 1: Replace Memory Allocators, keep pymalloc</a></li> <li><a class="reference internal" href="#use-case-2-replace-memory-allocators-override-pymalloc">Use case 2: Replace Memory Allocators, override pymalloc</a></li> <li><a class="reference internal" href="#use-case-3-setup-hooks-on-memory-block-allocators">Use case 3: Setup Hooks On Memory Block Allocators</a></li> </ul> </li> <li><a class="reference internal" href="#performances">Performances</a></li> <li><a class="reference internal" href="#rejected-alternatives">Rejected Alternatives</a><ul> <li><a class="reference internal" href="#more-specific-functions-to-get-set-memory-allocators">More specific functions to get/set memory allocators</a></li> <li><a class="reference internal" href="#make-pymem-malloc-reuse-pymem-rawmalloc-by-default">Make PyMem_Malloc() reuse PyMem_RawMalloc() by default</a></li> <li><a class="reference internal" href="#add-a-new-pydebugmalloc-environment-variable">Add a new PYDEBUGMALLOC environment variable</a></li> <li><a class="reference internal" href="#use-macros-to-get-customizable-allocators">Use macros to get customizable allocators</a></li> <li><a class="reference internal" href="#pass-the-c-filename-and-line-number">Pass the C filename and line number</a></li> <li><a class="reference internal" href="#gil-free-pymem-malloc">GIL-free PyMem_Malloc()</a></li> <li><a class="reference internal" href="#don-t-add-pymem-rawmalloc">Don’t add PyMem_RawMalloc()</a></li> <li><a class="reference internal" href="#use-existing-debug-tools-to-analyze-memory-use">Use existing debug tools to analyze memory use</a></li> <li><a class="reference internal" href="#add-a-msize-function">Add a msize() function</a></li> <li><a class="reference internal" href="#no-context-argument">No context argument</a></li> </ul> </li> <li><a class="reference internal" href="#external-libraries">External Libraries</a></li> <li><a class="reference internal" href="#memory-allocators">Memory Allocators</a></li> <li><a class="reference internal" href="#links">Links</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP proposes new Application Programming Interfaces (API) to customize Python memory allocators. The only implementation required to conform to this PEP is CPython, but other implementations may choose to be compatible, or to re-use a similar scheme. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> Use cases: <ul class="simple"> <li>Applications embedding Python which want to isolate Python memory from the memory of the application, or want to use a different memory allocator optimized for its Python usage</li> <li>Python running on embedded devices with low memory and slow CPU. A custom memory allocator can be used for efficiency and/or to get access all the memory of the device.</li> <li>Debug tools for memory allocators:<ul> <li>track the memory usage (find memory leaks)</li> <li>get the location of a memory allocation: Python filename and line number, and the size of a memory block</li> <li>detect buffer underflow, buffer overflow and misuse of Python allocator APIs (see <a class="reference internal" href="#redesign-debug-checks-on-memory-block-allocators-as-hooks">Redesign Debug Checks on Memory Block Allocators as Hooks</a>)</li> <li>force memory allocations to fail to test handling of the <code class="docutils literal notranslate">MemoryError</code> exception</li> </ul> </li> </ul> </section> <section id="proposal"> <h2><a class="toc-backref" href="#proposal" role="doc-backlink">Proposal</a></h2> <section id="new-functions-and-structures"> <h3><a class="toc-backref" href="#new-functions-and-structures" role="doc-backlink">New Functions and Structures</a></h3> <ul> <li>Add a new GIL-free (no need to hold the GIL) memory allocator:<ul class="simple"> <li><code class="docutils literal notranslate">void* PyMem_RawMalloc(size_t size)</code></li> <li><code class="docutils literal notranslate">void* PyMem_RawRealloc(void *ptr, size_t new_size)</code></li> <li><code class="docutils literal notranslate">void PyMem_RawFree(void *ptr)</code></li> <li>The newly allocated memory will not have been initialized in any way.</li> <li>Requesting zero bytes returns a distinct non-NULL pointer if possible, as if <code class="docutils literal notranslate">PyMem_Malloc(1)</code> had been called instead.</li> </ul> </li> <li>Add a new <code class="docutils literal notranslate">PyMemAllocator</code> structure:<div class="highlight-default notranslate"><div class="highlight"><pre>typedef struct { /* user context passed as the first argument to the 3 functions */ void *ctx; /* allocate a memory block */ void* (*malloc) (void *ctx, size_t size); /* allocate or resize a memory block */ void* (*realloc) (void *ctx, void *ptr, size_t new_size); /* release a memory block */ void (*free) (void *ctx, void *ptr); } PyMemAllocator; </pre></div> </div> </li> <li>Add a new <code class="docutils literal notranslate">PyMemAllocatorDomain</code> enum to choose the Python allocator domain. Domains:<ul class="simple"> <li><code class="docutils literal notranslate">PYMEM_DOMAIN_RAW</code>: <code class="docutils literal notranslate">PyMem_RawMalloc()</code>, <code class="docutils literal notranslate">PyMem_RawRealloc()</code> and <code class="docutils literal notranslate">PyMem_RawFree()</code></li> <li><code class="docutils literal notranslate">PYMEM_DOMAIN_MEM</code>: <code class="docutils literal notranslate">PyMem_Malloc()</code>, <code class="docutils literal notranslate">PyMem_Realloc()</code> and <code class="docutils literal notranslate">PyMem_Free()</code></li> <li><code class="docutils literal notranslate">PYMEM_DOMAIN_OBJ</code>: <code class="docutils literal notranslate">PyObject_Malloc()</code>, <code class="docutils literal notranslate">PyObject_Realloc()</code> and <code class="docutils literal notranslate">PyObject_Free()</code></li> </ul> </li> <li>Add new functions to get and set memory block allocators:<ul class="simple"> <li><code class="docutils literal notranslate">void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator)</code></li> <li><code class="docutils literal notranslate">void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator)</code></li> <li>The new allocator must return a distinct non-NULL pointer when requesting zero bytes</li> <li>For the <code class="docutils literal notranslate">PYMEM_DOMAIN_RAW</code> domain, the allocator must be thread-safe: the GIL is not held when the allocator is called.</li> </ul> </li> <li>Add a new <code class="docutils literal notranslate">PyObjectArenaAllocator</code> structure:<div class="highlight-default notranslate"><div class="highlight"><pre>typedef struct { /* user context passed as the first argument to the 2 functions */ void *ctx; /* allocate an arena */ void* (*alloc) (void *ctx, size_t size); /* release an arena */ void (*free) (void *ctx, void *ptr, size_t size); } PyObjectArenaAllocator; </pre></div> </div> </li> <li>Add new functions to get and set the arena allocator used by pymalloc:<ul class="simple"> <li><code class="docutils literal notranslate">void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)</code></li> <li><code class="docutils literal notranslate">void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)</code></li> </ul> </li> <li>Add a new function to reinstall the debug checks on memory allocators when a memory allocator is replaced with <code class="docutils literal notranslate">PyMem_SetAllocator()</code>:<ul class="simple"> <li><code class="docutils literal notranslate">void PyMem_SetupDebugHooks(void)</code></li> <li>Install the debug hooks on all memory block allocators. The function can be called more than once, hooks are only installed once.</li> <li>The function does nothing is Python is not compiled in debug mode.</li> </ul> </li> <li>Memory block allocators always return NULL if size is greater than <code class="docutils literal notranslate">PY_SSIZE_T_MAX</code>. The check is done before calling the inner function.</li> </ul> <div class="admonition note"> Note The pymalloc allocator is optimized for objects smaller than 512 bytes with a short lifetime. It uses memory mappings with a fixed size of 256 KB called “arenas”. </div> Here is how the allocators are set up by default: <ul class="simple"> <li><code class="docutils literal notranslate">PYMEM_DOMAIN_RAW</code>, <code class="docutils literal notranslate">PYMEM_DOMAIN_MEM</code>: <code class="docutils literal notranslate">malloc()</code>, <code class="docutils literal notranslate">realloc()</code> and <code class="docutils literal notranslate">free()</code>; call <code class="docutils literal notranslate">malloc(1)</code> when requesting zero bytes</li> <li><code class="docutils literal notranslate">PYMEM_DOMAIN_OBJ</code>: pymalloc allocator which falls back on <code class="docutils literal notranslate">PyMem_Malloc()</code> for allocations larger than 512 bytes</li> <li>pymalloc arena allocator: <code class="docutils literal notranslate">VirtualAlloc()</code> and <code class="docutils literal notranslate">VirtualFree()</code> on Windows, <code class="docutils literal notranslate">mmap()</code> and <code class="docutils literal notranslate">munmap()</code> when available, or <code class="docutils literal notranslate">malloc()</code> and <code class="docutils literal notranslate">free()</code></li> </ul> </section> <section id="redesign-debug-checks-on-memory-block-allocators-as-hooks"> <h3><a class="toc-backref" href="#redesign-debug-checks-on-memory-block-allocators-as-hooks" role="doc-backlink">Redesign Debug Checks on Memory Block Allocators as Hooks</a></h3> Since Python 2.3, Python implements different checks on memory allocators in debug mode: <ul class="simple"> <li>Newly allocated memory is filled with the byte <code class="docutils literal notranslate">0xCB</code>, freed memory is filled with the byte <code class="docutils literal notranslate">0xDB</code>.</li> <li>Detect API violations, ex: <code class="docutils literal notranslate">PyObject_Free()</code> called on a memory block allocated by <code class="docutils literal notranslate">PyMem_Malloc()</code></li> <li>Detect write before the start of the buffer (buffer underflow)</li> <li>Detect write after the end of the buffer (buffer overflow)</li> </ul> In Python 3.3, the checks are installed by replacing <code class="docutils literal notranslate">PyMem_Malloc()</code>, <code class="docutils literal notranslate">PyMem_Realloc()</code>, <code class="docutils literal notranslate">PyMem_Free()</code>, <code class="docutils literal notranslate">PyObject_Malloc()</code>, <code class="docutils literal notranslate">PyObject_Realloc()</code> and <code class="docutils literal notranslate">PyObject_Free()</code> using macros. The new allocator allocates a larger buffer and writes a pattern to detect buffer underflow, buffer overflow and use after free (by filling the buffer with the byte <code class="docutils literal notranslate">0xDB</code>). It uses the original <code class="docutils literal notranslate">PyObject_Malloc()</code> function to allocate memory. So <code class="docutils literal notranslate">PyMem_Malloc()</code> and <code class="docutils literal notranslate">PyMem_Realloc()</code> indirectly call <code class="docutils literal notranslate">PyObject_Malloc()</code> and <code class="docutils literal notranslate">PyObject_Realloc()</code>. This PEP redesigns the debug checks as hooks on the existing allocators in debug mode. Examples of call traces without the hooks: <ul class="simple"> <li><code class="docutils literal notranslate">PyMem_RawMalloc()</code> => <code class="docutils literal notranslate">_PyMem_RawMalloc()</code> => <code class="docutils literal notranslate">malloc()</code></li> <li><code class="docutils literal notranslate">PyMem_Realloc()</code> => <code class="docutils literal notranslate">_PyMem_RawRealloc()</code> => <code class="docutils literal notranslate">realloc()</code></li> <li><code class="docutils literal notranslate">PyObject_Free()</code> => <code class="docutils literal notranslate">_PyObject_Free()</code></li> </ul> Call traces when the hooks are installed (debug mode): <ul class="simple"> <li><code class="docutils literal notranslate">PyMem_RawMalloc()</code> => <code class="docutils literal notranslate">_PyMem_DebugMalloc()</code> => <code class="docutils literal notranslate">_PyMem_RawMalloc()</code> => <code class="docutils literal notranslate">malloc()</code></li> <li><code class="docutils literal notranslate">PyMem_Realloc()</code> => <code class="docutils literal notranslate">_PyMem_DebugRealloc()</code> => <code class="docutils literal notranslate">_PyMem_RawRealloc()</code> => <code class="docutils literal notranslate">realloc()</code></li> <li><code class="docutils literal notranslate">PyObject_Free()</code> => <code class="docutils literal notranslate">_PyMem_DebugFree()</code> => <code class="docutils literal notranslate">_PyObject_Free()</code></li> </ul> As a result, <code class="docutils literal notranslate">PyMem_Malloc()</code> and <code class="docutils literal notranslate">PyMem_Realloc()</code> now call <code class="docutils literal notranslate">malloc()</code> and <code class="docutils literal notranslate">realloc()</code> in both release mode and debug mode, instead of calling <code class="docutils literal notranslate">PyObject_Malloc()</code> and <code class="docutils literal notranslate">PyObject_Realloc()</code> in debug mode. When at least one memory allocator is replaced with <code class="docutils literal notranslate">PyMem_SetAllocator()</code>, the <code class="docutils literal notranslate">PyMem_SetupDebugHooks()</code> function must be called to reinstall the debug hooks on top on the new allocator. </section> <section id="don-t-call-malloc-directly-anymore"> <h3><a class="toc-backref" href="#don-t-call-malloc-directly-anymore" role="doc-backlink">Don’t call malloc() directly anymore</a></h3> <code class="docutils literal notranslate">PyObject_Malloc()</code> falls back on <code class="docutils literal notranslate">PyMem_Malloc()</code> instead of <code class="docutils literal notranslate">malloc()</code> if size is greater or equal than 512 bytes, and <code class="docutils literal notranslate">PyObject_Realloc()</code> falls back on <code class="docutils literal notranslate">PyMem_Realloc()</code> instead of <code class="docutils literal notranslate">realloc()</code> Direct calls to <code class="docutils literal notranslate">malloc()</code> are replaced with <code class="docutils literal notranslate">PyMem_Malloc()</code>, or <code class="docutils literal notranslate">PyMem_RawMalloc()</code> if the GIL is not held. External libraries like zlib or OpenSSL can be configured to allocate memory using <code class="docutils literal notranslate">PyMem_Malloc()</code> or <code class="docutils literal notranslate">PyMem_RawMalloc()</code>. If the allocator of a library can only be replaced globally (rather than on an object-by-object basis), it shouldn’t be replaced when Python is embedded in an application. For the “track memory usage” use case, it is important to track memory allocated in external libraries to have accurate reports, because these allocations can be large (e.g. they can raise a <code class="docutils literal notranslate">MemoryError</code> exception) and would otherwise be missed in memory usage reports. </section> </section> <section id="examples"> <h2><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h2> <section id="use-case-1-replace-memory-allocators-keep-pymalloc"> <h3><a class="toc-backref" href="#use-case-1-replace-memory-allocators-keep-pymalloc" role="doc-backlink">Use case 1: Replace Memory Allocators, keep pymalloc</a></h3> Dummy example wasting 2 bytes per memory block, and 10 bytes per pymalloc arena: <div class="highlight-default notranslate"><div class="highlight"><pre>#include <stdlib.h> size_t alloc_padding = 2; size_t arena_padding = 10; void* my_malloc(void *ctx, size_t size) { int padding = *(int *)ctx; return malloc(size + padding); } void* my_realloc(void *ctx, void *ptr, size_t new_size) { int padding = *(int *)ctx; return realloc(ptr, new_size + padding); } void my_free(void *ctx, void *ptr) { free(ptr); } void* my_alloc_arena(void *ctx, size_t size) { int padding = *(int *)ctx; return malloc(size + padding); } void my_free_arena(void *ctx, void *ptr, size_t size) { free(ptr); } void setup_custom_allocator(void) { PyMemAllocator alloc; PyObjectArenaAllocator arena; alloc.ctx = &alloc_padding; alloc.malloc = my_malloc; alloc.realloc = my_realloc; alloc.free = my_free; PyMem_SetAllocator(PYMEM_DOMAIN_RAW, &alloc); PyMem_SetAllocator(PYMEM_DOMAIN_MEM, &alloc); /* leave PYMEM_DOMAIN_OBJ unchanged, use pymalloc */ arena.ctx = &arena_padding; arena.alloc = my_alloc_arena; arena.free = my_free_arena; PyObject_SetArenaAllocator(&arena); PyMem_SetupDebugHooks(); } </pre></div> </div> </section> <section id="use-case-2-replace-memory-allocators-override-pymalloc"> <h3><a class="toc-backref" href="#use-case-2-replace-memory-allocators-override-pymalloc" role="doc-backlink">Use case 2: Replace Memory Allocators, override pymalloc</a></h3> If you have a dedicated allocator optimized for allocations of objects smaller than 512 bytes with a short lifetime, pymalloc can be overridden (replace <code class="docutils literal notranslate">PyObject_Malloc()</code>). Dummy example wasting 2 bytes per memory block: <div class="highlight-default notranslate"><div class="highlight"><pre>#include <stdlib.h> size_t padding = 2; void* my_malloc(void *ctx, size_t size) { int padding = *(int *)ctx; return malloc(size + padding); } void* my_realloc(void *ctx, void *ptr, size_t new_size) { int padding = *(int *)ctx; return realloc(ptr, new_size + padding); } void my_free(void *ctx, void *ptr) { free(ptr); } void setup_custom_allocator(void) { PyMemAllocator alloc; alloc.ctx = &padding; alloc.malloc = my_malloc; alloc.realloc = my_realloc; alloc.free = my_free; PyMem_SetAllocator(PYMEM_DOMAIN_RAW, &alloc); PyMem_SetAllocator(PYMEM_DOMAIN_MEM, &alloc); PyMem_SetAllocator(PYMEM_DOMAIN_OBJ, &alloc); PyMem_SetupDebugHooks(); } </pre></div> </div> The pymalloc arena does not need to be replaced, because it is no more used by the new allocator. </section> <section id="use-case-3-setup-hooks-on-memory-block-allocators"> <h3><a class="toc-backref" href="#use-case-3-setup-hooks-on-memory-block-allocators" role="doc-backlink">Use case 3: Setup Hooks On Memory Block Allocators</a></h3> Example to setup hooks on all memory block allocators: <div class="highlight-default notranslate"><div class="highlight"><pre>struct { PyMemAllocator raw; PyMemAllocator mem; PyMemAllocator obj; /* ... */ } hook; static void* hook_malloc(void *ctx, size_t size) { PyMemAllocator *alloc = (PyMemAllocator *)ctx; void *ptr; /* ... */ ptr = alloc->malloc(alloc->ctx, size); /* ... */ return ptr; } static void* hook_realloc(void *ctx, void *ptr, size_t new_size) { PyMemAllocator *alloc = (PyMemAllocator *)ctx; void *ptr2; /* ... */ ptr2 = alloc->realloc(alloc->ctx, ptr, new_size); /* ... */ return ptr2; } static void hook_free(void *ctx, void *ptr) { PyMemAllocator *alloc = (PyMemAllocator *)ctx; /* ... */ alloc->free(alloc->ctx, ptr); /* ... */ } void setup_hooks(void) { PyMemAllocator alloc; static int installed = 0; if (installed) return; installed = 1; alloc.malloc = hook_malloc; alloc.realloc = hook_realloc; alloc.free = hook_free; PyMem_GetAllocator(PYMEM_DOMAIN_RAW, &hook.raw); PyMem_GetAllocator(PYMEM_DOMAIN_MEM, &hook.mem); PyMem_GetAllocator(PYMEM_DOMAIN_OBJ, &hook.obj); alloc.ctx = &hook.raw; PyMem_SetAllocator(PYMEM_DOMAIN_RAW, &alloc); alloc.ctx = &hook.mem; PyMem_SetAllocator(PYMEM_DOMAIN_MEM, &alloc); alloc.ctx = &hook.obj; PyMem_SetAllocator(PYMEM_DOMAIN_OBJ, &alloc); } </pre></div> </div> <div class="admonition note"> Note <code class="docutils literal notranslate">PyMem_SetupDebugHooks()</code> does not need to be called because memory allocator are not replaced: the debug checks on memory block allocators are installed automatically at startup. </div> </section> </section> <section id="performances"> <h2><a class="toc-backref" href="#performances" role="doc-backlink">Performances</a></h2> The implementation of this PEP (issue #3329) has no visible overhead on the Python benchmark suite. Results of the <a class="reference external" href="http://hg.python.org/benchmarks">Python benchmarks suite</a> (-b 2n3): some tests are 1.04x faster, some tests are 1.04 slower. Results of pybench microbenchmark: “+0.1%” slower globally (diff between -4.9% and +5.6%). The full output of benchmarks is attached to the issue #3329. </section> <section id="rejected-alternatives"> <h2><a class="toc-backref" href="#rejected-alternatives" role="doc-backlink">Rejected Alternatives</a></h2> <section id="more-specific-functions-to-get-set-memory-allocators"> <h3><a class="toc-backref" href="#more-specific-functions-to-get-set-memory-allocators" role="doc-backlink">More specific functions to get/set memory allocators</a></h3> It was originally proposed a larger set of C API functions, with one pair of functions for each allocator domain: <ul class="simple"> <li><code class="docutils literal notranslate">void PyMem_GetRawAllocator(PyMemAllocator *allocator)</code></li> <li><code class="docutils literal notranslate">void PyMem_GetAllocator(PyMemAllocator *allocator)</code></li> <li><code class="docutils literal notranslate">void PyObject_GetAllocator(PyMemAllocator *allocator)</code></li> <li><code class="docutils literal notranslate">void PyMem_SetRawAllocator(PyMemAllocator *allocator)</code></li> <li><code class="docutils literal notranslate">void PyMem_SetAllocator(PyMemAllocator *allocator)</code></li> <li><code class="docutils literal notranslate">void PyObject_SetAllocator(PyMemAllocator *allocator)</code></li> </ul> This alternative was rejected because it is not possible to write generic code with more specific functions: code must be duplicated for each memory allocator domain. </section> <section id="make-pymem-malloc-reuse-pymem-rawmalloc-by-default"> <h3><a class="toc-backref" href="#make-pymem-malloc-reuse-pymem-rawmalloc-by-default" role="doc-backlink">Make PyMem_Malloc() reuse PyMem_RawMalloc() by default</a></h3> If <code class="docutils literal notranslate">PyMem_Malloc()</code> called <code class="docutils literal notranslate">PyMem_RawMalloc()</code> by default, calling <code class="docutils literal notranslate">PyMem_SetAllocator(PYMEM_DOMAIN_RAW, alloc)</code> would also patch <code class="docutils literal notranslate">PyMem_Malloc()</code> indirectly. This alternative was rejected because <code class="docutils literal notranslate">PyMem_SetAllocator()</code> would have a different behaviour depending on the domain. Always having the same behaviour is less error-prone. </section> <section id="add-a-new-pydebugmalloc-environment-variable"> <h3><a class="toc-backref" href="#add-a-new-pydebugmalloc-environment-variable" role="doc-backlink">Add a new PYDEBUGMALLOC environment variable</a></h3> It was proposed to add a new <code class="docutils literal notranslate">PYDEBUGMALLOC</code> environment variable to enable debug checks on memory block allocators. It would have had the same effect as calling the <code class="docutils literal notranslate">PyMem_SetupDebugHooks()</code>, without the need to write any C code. Another advantage is to allow to enable debug checks even in release mode: debug checks would always be compiled in, but only enabled when the environment variable is present and non-empty. This alternative was rejected because a new environment variable would make Python initialization even more complex. <a class="pep reference internal" href="../pep-0432/" title="PEP 432 – Restructuring the CPython startup sequence">PEP 432</a> tries to simplify the CPython startup sequence. </section> <section id="use-macros-to-get-customizable-allocators"> <h3><a class="toc-backref" href="#use-macros-to-get-customizable-allocators" role="doc-backlink">Use macros to get customizable allocators</a></h3> To have no overhead in the default configuration, customizable allocators would be an optional feature enabled by a configuration option or by macros. This alternative was rejected because the use of macros implies having to recompile extensions modules to use the new allocator and allocator hooks. Not having to recompile Python nor extension modules makes debug hooks easier to use in practice. </section> <section id="pass-the-c-filename-and-line-number"> <h3><a class="toc-backref" href="#pass-the-c-filename-and-line-number" role="doc-backlink">Pass the C filename and line number</a></h3> Define allocator functions as macros using <code class="docutils literal notranslate">__FILE__</code> and <code class="docutils literal notranslate">__LINE__</code> to get the C filename and line number of a memory allocation. Example of <code class="docutils literal notranslate">PyMem_Malloc</code> macro with the modified <code class="docutils literal notranslate">PyMemAllocator</code> structure: <div class="highlight-default notranslate"><div class="highlight"><pre>typedef struct { /* user context passed as the first argument to the 3 functions */ void *ctx; /* allocate a memory block */ void* (*malloc) (void *ctx, const char *filename, int lineno, size_t size); /* allocate or resize a memory block */ void* (*realloc) (void *ctx, const char *filename, int lineno, void *ptr, size_t new_size); /* release a memory block */ void (*free) (void *ctx, const char *filename, int lineno, void *ptr); } PyMemAllocator; void* _PyMem_MallocTrace(const char *filename, int lineno, size_t size); /* the function is still needed for the Python stable ABI */ void* PyMem_Malloc(size_t size); #define PyMem_Malloc(size) \ _PyMem_MallocTrace(__FILE__, __LINE__, size) </pre></div> </div> The GC allocator functions would also have to be patched. For example, <code class="docutils literal notranslate">_PyObject_GC_Malloc()</code> is used in many C functions and so objects of different types would have the same allocation location. This alternative was rejected because passing a filename and a line number to each allocator makes the API more complex: pass 3 new arguments (ctx, filename, lineno) to each allocator function, instead of just a context argument (ctx). Having to also modify GC allocator functions adds too much complexity for a little gain. </section> <section id="gil-free-pymem-malloc"> <h3><a class="toc-backref" href="#gil-free-pymem-malloc" role="doc-backlink">GIL-free PyMem_Malloc()</a></h3> In Python 3.3, when Python is compiled in debug mode, <code class="docutils literal notranslate">PyMem_Malloc()</code> indirectly calls <code class="docutils literal notranslate">PyObject_Malloc()</code> which requires the GIL to be held (it isn’t thread-safe). That’s why <code class="docutils literal notranslate">PyMem_Malloc()</code> must be called with the GIL held. This PEP changes <code class="docutils literal notranslate">PyMem_Malloc()</code>: it now always calls <code class="docutils literal notranslate">malloc()</code> rather than <code class="docutils literal notranslate">PyObject_Malloc()</code>. The “GIL must be held” restriction could therefore be removed from <code class="docutils literal notranslate">PyMem_Malloc()</code>. This alternative was rejected because allowing to call <code class="docutils literal notranslate">PyMem_Malloc()</code> without holding the GIL can break applications which setup their own allocators or allocator hooks. Holding the GIL is convenient to develop a custom allocator: no need to care about other threads. It is also convenient for a debug allocator hook: Python objects can be safely inspected, and the C API may be used for reporting. Moreover, calling <code class="docutils literal notranslate">PyGILState_Ensure()</code> in a memory allocator has unexpected behaviour, especially at Python startup and when creating of a new Python thread state. It is better to free custom allocators of the responsibility of acquiring the GIL. </section> <section id="don-t-add-pymem-rawmalloc"> <h3><a class="toc-backref" href="#don-t-add-pymem-rawmalloc" role="doc-backlink">Don’t add PyMem_RawMalloc()</a></h3> Replace <code class="docutils literal notranslate">malloc()</code> with <code class="docutils literal notranslate">PyMem_Malloc()</code>, but only if the GIL is held. Otherwise, keep <code class="docutils literal notranslate">malloc()</code> unchanged. The <code class="docutils literal notranslate">PyMem_Malloc()</code> is used without the GIL held in some Python functions. For example, the <code class="docutils literal notranslate">main()</code> and <code class="docutils literal notranslate">Py_Main()</code> functions of Python call <code class="docutils literal notranslate">PyMem_Malloc()</code> whereas the GIL do not exist yet. In this case, <code class="docutils literal notranslate">PyMem_Malloc()</code> would be replaced with <code class="docutils literal notranslate">malloc()</code> (or <code class="docutils literal notranslate">PyMem_RawMalloc()</code>). This alternative was rejected because <code class="docutils literal notranslate">PyMem_RawMalloc()</code> is required for accurate reports of the memory usage. When a debug hook is used to track the memory usage, the memory allocated by direct calls to <code class="docutils literal notranslate">malloc()</code> cannot be tracked. <code class="docutils literal notranslate">PyMem_RawMalloc()</code> can be hooked and so all the memory allocated by Python can be tracked, including memory allocated without holding the GIL. </section> <section id="use-existing-debug-tools-to-analyze-memory-use"> <h3><a class="toc-backref" href="#use-existing-debug-tools-to-analyze-memory-use" role="doc-backlink">Use existing debug tools to analyze memory use</a></h3> There are many existing debug tools to analyze memory use. Some examples: <a class="reference external" href="http://valgrind.org/">Valgrind</a>, <a class="reference external" href="http://ibm.com/software/awdtools/purify/">Purify</a>, <a class="reference external" href="http://code.google.com/p/address-sanitizer/">Clang AddressSanitizer</a>, <a class="reference external" href="http://www.nongnu.org/failmalloc/">failmalloc</a>, etc. The problem is to retrieve the Python object related to a memory pointer to read its type and/or its content. Another issue is to retrieve the source of the memory allocation: the C backtrace is usually useless (same reasoning than macros using <code class="docutils literal notranslate">__FILE__</code> and <code class="docutils literal notranslate">__LINE__</code>, see <a class="reference internal" href="#pass-the-c-filename-and-line-number">Pass the C filename and line number</a>), the Python filename and line number (or even the Python traceback) is more useful. This alternative was rejected because classic tools are unable to introspect Python internals to collect such information. Being able to setup a hook on allocators called with the GIL held allows to collect a lot of useful data from Python internals. </section> <section id="add-a-msize-function"> <h3><a class="toc-backref" href="#add-a-msize-function" role="doc-backlink">Add a msize() function</a></h3> Add another function to <code class="docutils literal notranslate">PyMemAllocator</code> and <code class="docutils literal notranslate">PyObjectArenaAllocator</code> structures: <div class="highlight-default notranslate"><div class="highlight"><pre>size_t msize(void *ptr); </pre></div> </div> This function returns the size of a memory block or a memory mapping. Return (size_t)-1 if the function is not implemented or if the pointer is unknown (ex: NULL pointer). On Windows, this function can be implemented using <code class="docutils literal notranslate">_msize()</code> and <code class="docutils literal notranslate">VirtualQuery()</code>. The function can be used to implement a hook tracking the memory usage. The <code class="docutils literal notranslate">free()</code> method of an allocator only gets the address of a memory block, whereas the size of the memory block is required to update the memory usage. The additional <code class="docutils literal notranslate">msize()</code> function was rejected because only few platforms implement it. For example, Linux with the GNU libc does not provide a function to get the size of a memory block. <code class="docutils literal notranslate">msize()</code> is not currently used in the Python source code. The function would only be used to track memory use, and make the API more complex. A debug hook can implement the function internally, there is no need to add it to <code class="docutils literal notranslate">PyMemAllocator</code> and <code class="docutils literal notranslate">PyObjectArenaAllocator</code> structures. </section> <section id="no-context-argument"> <h3><a class="toc-backref" href="#no-context-argument" role="doc-backlink">No context argument</a></h3> Simplify the signature of allocator functions, remove the context argument: <ul class="simple"> <li><code class="docutils literal notranslate">void* malloc(size_t size)</code></li> <li><code class="docutils literal notranslate">void* realloc(void *ptr, size_t new_size)</code></li> <li><code class="docutils literal notranslate">void free(void *ptr)</code></li> </ul> It is likely for an allocator hook to be reused for <code class="docutils literal notranslate">PyMem_SetAllocator()</code> and <code class="docutils literal notranslate">PyObject_SetAllocator()</code>, or even <code class="docutils literal notranslate">PyMem_SetRawAllocator()</code>, but the hook must call a different function depending on the allocator. The context is a convenient way to reuse the same custom allocator or hook for different Python allocators. In C++, the context can be used to pass this. </section> </section> <section id="external-libraries"> <h2><a class="toc-backref" href="#external-libraries" role="doc-backlink">External Libraries</a></h2> Examples of API used to customize memory allocators. Libraries used by Python: <ul class="simple"> <li>OpenSSL: <a class="reference external" href="http://git.openssl.org/gitweb/?p=openssl.git;a=blob;f=crypto/mem.c;h=f7984fa958eb1edd6c61f6667f3f2b29753be662;hb=HEAD#l124">CRYPTO_set_mem_functions()</a> to set memory management functions globally</li> <li>expat: <a class="reference external" href="http://hg.python.org/cpython/file/cc27d50bd91a/Modules/expat/xmlparse.c#l724">parserCreate()</a> has a per-instance memory handler</li> <li>zlib: <a class="reference external" href="http://www.zlib.net/manual.html#Usage">zlib 1.2.8 Manual</a>, pass an opaque pointer</li> <li>bz2: <a class="reference external" href="http://www.bzip.org/1.0.5/bzip2-manual-1.0.5.html">bzip2 and libbzip2, version 1.0.5</a>, pass an opaque pointer</li> <li>lzma: <a class="reference external" href="http://www.asawicki.info/news_1368_lzma_sdk_-_how_to_use.html">LZMA SDK - How to Use</a>, pass an opaque pointer</li> <li>lipmpdec: no opaque pointer (classic malloc API)</li> </ul> Other libraries: <ul class="simple"> <li>glib: <a class="reference external" href="http://developer.gnome.org/glib/unstable/glib-Memory-Allocation.html#g-mem-set-vtable">g_mem_set_vtable()</a></li> <li>libxml2: <a class="reference external" href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlGcMemSetup()</a>, global</li> <li>Oracle’s OCI: <a class="reference external" href="http://docs.oracle.com/cd/B10501_01/appdev.920/a96584/oci15re4.htm">Oracle Call Interface Programmer’s Guide, Release 2 (9.2)</a>, pass an opaque pointer</li> </ul> The new ctx parameter of this PEP was inspired by the API of zlib and Oracle’s OCI libraries. See also the <a class="reference external" href="http://www.gnu.org/software/libc/manual/html_node/Hooks-for-Malloc.html">GNU libc: Memory Allocation Hooks</a> which uses a different approach to hook memory allocators. </section> <section id="memory-allocators"> <h2><a class="toc-backref" href="#memory-allocators" role="doc-backlink">Memory Allocators</a></h2> The C standard library provides the well known <code class="docutils literal notranslate">malloc()</code> function. Its implementation depends on the platform and of the C library. The GNU C library uses a modified ptmalloc2, based on “Doug Lea’s Malloc” (dlmalloc). FreeBSD uses <a class="reference external" href="http://www.canonware.com/jemalloc/">jemalloc</a>. Google provides tcmalloc which is part of <a class="reference external" href="http://code.google.com/p/gperftools/">gperftools</a>. <code class="docutils literal notranslate">malloc()</code> uses two kinds of memory: heap and memory mappings. Memory mappings are usually used for large allocations (ex: larger than 256 KB), whereas the heap is used for small allocations. On UNIX, the heap is handled by <code class="docutils literal notranslate">brk()</code> and <code class="docutils literal notranslate">sbrk()</code> system calls, and it is contiguous. On Windows, the heap is handled by <code class="docutils literal notranslate">HeapAlloc()</code> and can be discontiguous. Memory mappings are handled by <code class="docutils literal notranslate">mmap()</code> on UNIX and <code class="docutils literal notranslate">VirtualAlloc()</code> on Windows, they can be discontiguous. Releasing a memory mapping gives back immediately the memory to the system. On UNIX, the heap memory is only given back to the system if the released block is located at the end of the heap. Otherwise, the memory will only be given back to the system when all the memory located after the released memory is also released. To allocate memory on the heap, an allocator tries to reuse free space. If there is no contiguous space big enough, the heap must be enlarged, even if there is more free space than required size. This issue is called the “memory fragmentation”: the memory usage seen by the system is higher than real usage. On Windows, <code class="docutils literal notranslate">HeapAlloc()</code> creates a new memory mapping with <code class="docutils literal notranslate">VirtualAlloc()</code> if there is not enough free contiguous memory. CPython has a pymalloc allocator for allocations smaller than 512 bytes. This allocator is optimized for small objects with a short lifetime. It uses memory mappings called “arenas” with a fixed size of 256 KB. Other allocators: <ul class="simple"> <li>Windows provides a <a class="reference external" href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa366750%28v=vs.85%29.aspx">Low-fragmentation Heap</a>.</li> <li>The Linux kernel uses <a class="reference external" href="http://en.wikipedia.org/wiki/Slab_allocation">slab allocation</a>.</li> <li>The glib library has a <a class="reference external" href="https://developer.gnome.org/glib/unstable/glib-Memory-Slices.html">Memory Slice API</a>: efficient way to allocate groups of equal-sized chunks of memory</li> </ul> This PEP allows to choose exactly which memory allocator is used for your application depending on its usage of the memory (number of allocations, size of allocations, lifetime of objects, etc.). </section> <section id="links"> <h2><a class="toc-backref" href="#links" role="doc-backlink">Links</a></h2> CPython issues related to memory allocation: <ul class="simple"> <li><a class="reference external" href="http://bugs.python.org/issue3329">Issue #3329: Add new APIs to customize memory allocators</a></li> <li><a class="reference external" href="http://bugs.python.org/issue13483">Issue #13483: Use VirtualAlloc to allocate memory arenas</a></li> <li><a class="reference external" href="http://bugs.python.org/issue16742">Issue #16742: PyOS_Readline drops GIL and calls PyOS_StdioReadline, which isn’t thread safe</a></li> <li><a class="reference external" href="http://bugs.python.org/issue18203">Issue #18203: Replace calls to malloc() with PyMem_Malloc() or PyMem_RawMalloc()</a></li> <li><a class="reference external" href="http://bugs.python.org/issue18227">Issue #18227: Use Python memory allocators in external libraries like zlib or OpenSSL</a></li> </ul> Projects analyzing the memory usage of Python applications: <ul class="simple"> <li><a class="reference external" href="https://pypi.python.org/pypi/pytracemalloc">pytracemalloc</a></li> <li><a class="reference external" href="https://pypi.python.org/pypi/meliae">Meliae: Python Memory Usage Analyzer</a></li> <li><a class="reference external" href="http://guppy-pe.sourceforge.net/">Guppy-PE: umbrella package combining Heapy and GSL</a></li> <li><a class="reference external" href="http://pysizer.8325.org/">PySizer (developed for Python 2.4)</a></li> </ul> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed into the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0445.rst">https://github.com/python/peps/blob/main/peps/pep-0445.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0445.rst">2025-02-01 08:59:27 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#new-functions-and-structures">New Functions and Structures</a></li> <li><a class="reference internal" href="#redesign-debug-checks-on-memory-block-allocators-as-hooks">Redesign Debug Checks on Memory Block Allocators as Hooks</a></li> <li><a class="reference internal" href="#don-t-call-malloc-directly-anymore">Don’t call malloc() directly anymore</a></li> </ul> </li> <li><a class="reference internal" href="#examples">Examples</a><ul> <li><a class="reference internal" href="#use-case-1-replace-memory-allocators-keep-pymalloc">Use case 1: Replace Memory Allocators, keep pymalloc</a></li> <li><a class="reference internal" href="#use-case-2-replace-memory-allocators-override-pymalloc">Use case 2: Replace Memory Allocators, override pymalloc</a></li> <li><a class="reference internal" href="#use-case-3-setup-hooks-on-memory-block-allocators">Use case 3: Setup Hooks On Memory Block Allocators</a></li> </ul> </li> <li><a class="reference internal" href="#performances">Performances</a></li> <li><a class="reference internal" href="#rejected-alternatives">Rejected Alternatives</a><ul> <li><a class="reference internal" href="#more-specific-functions-to-get-set-memory-allocators">More specific functions to get/set memory allocators</a></li> <li><a class="reference internal" href="#make-pymem-malloc-reuse-pymem-rawmalloc-by-default">Make PyMem_Malloc() reuse PyMem_RawMalloc() by default</a></li> <li><a class="reference internal" href="#add-a-new-pydebugmalloc-environment-variable">Add a new PYDEBUGMALLOC environment variable</a></li> <li><a class="reference internal" href="#use-macros-to-get-customizable-allocators">Use macros to get customizable allocators</a></li> <li><a class="reference internal" href="#pass-the-c-filename-and-line-number">Pass the C filename and line number</a></li> <li><a class="reference internal" href="#gil-free-pymem-malloc">GIL-free PyMem_Malloc()</a></li> <li><a class="reference internal" href="#don-t-add-pymem-rawmalloc">Don’t add PyMem_RawMalloc()</a></li> <li><a class="reference internal" href="#use-existing-debug-tools-to-analyze-memory-use">Use existing debug tools to analyze memory use</a></li> <li><a class="reference internal" href="#add-a-msize-function">Add a msize() function</a></li> <li><a class="reference internal" href="#no-context-argument">No context argument</a></li> </ul> </li> <li><a class="reference internal" href="#external-libraries">External Libraries</a></li> <li><a class="reference internal" href="#memory-allocators">Memory Allocators</a></li> <li><a class="reference internal" href="#links">Links</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0445.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>