python-docs-fa/howto/free-threading-python.html at gh-pages · python/python-docs-fa

660 lines (613 loc) · 41.2 KB
<!DOCTYPE html>
<html lang="fa" data-content_root="../">
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Python support for free threading" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/howto/free-threading-python.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Starting with the 3.13 release, CPython has support for a build of Python called free threading where the global interpreter lock(GIL) is disabled. Free-threaded execution allows for full utilizati..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Starting with the 3.13 release, CPython has support for a build of Python called free threading where the global interpreter lock(GIL) is disabled. Free-threaded execution allows for full utilizati..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
    <title>Python support for free threading &#8212; مستندات Python3.14.6</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
    <script src="../_static/documentation_options.js?v=e254dbbb"></script>
    <script src="../_static/doctools.js?v=9bcbadda"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/translations.js?v=5df48d09"></script>
    <script src="../_static/sidebar.js"></script>
    <link rel="search" type="application/opensearchdescription+xml"
          title="جستجو در مستندات Python3.14.6"
          href="../_static/opensearch.xml"/>
    <link rel="author" title="درباره این مستندات" href="../about.html" />
    <link rel="index" title="فهرست" href="../genindex.html" />
    <link rel="search" title="جستجو" href="../search.html" />
    <link rel="copyright" title="حق چاپ" href="../copyright.html" />
    <link rel="next" title="C API Extension Support for Free Threading" href="free-threading-extensions.html" />
    <link rel="prev" title="The Python 2.3 Method Resolution Order" href="mro.html" />
      <link rel="canonical" href="https://docs.python.org/3/howto/free-threading-python.html">
    <style>
      @media only screen {
        table.full-width-table {
            width: 100%;
    </style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">
            <script type="text/javascript" src="../_static/copybutton.js"></script>
            <script type="text/javascript" src="../_static/menu.js"></script>
            <script type="text/javascript" src="../_static/search-focus.js"></script>
            <script type="text/javascript" src="../_static/themetoggle.js"></script> 
            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>
            <meta name="readthedocs-addons-api-version" content="1">
<div class="mobile-nav">
    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
    <nav class="nav-content" role="navigation">
        <label for="menuToggler" class="toggler__label">
            <span></span>
        </label>
        <span class="nav-items-wrapper">
            <a href="https://www.python.org/" class="nav-logo">
                <img src="../_static/py.svg" alt="Python logo">
            </a>
            <span class="version_switcher_placeholder"></span>
            <form role="search" class="search" action="../search.html" method="get">
                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
                </svg>
                <input placeholder="جستجو سریع" aria-label="جستجو سریع" type="search" name="q">
                <input type="submit" value="برو">
            </form>
        </span>
    <div class="menu-wrapper">
        <nav class="menu" role="navigation" aria-label="main navigation">
            <div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
    <select class="theme-selector" oninput="activateTheme(this.value)">
        <option value="auto" selected>Auto</option>
        <option value="light">Light</option>
        <option value="dark">Dark</option>
    </select>
    <h3><a href="../contents.html">فهرست عناوین</a></h3>
<li><a class="reference internal" href="#">Python support for free threading</a><ul>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#identifying-free-threaded-python">Identifying free-threaded Python</a></li>
<li><a class="reference internal" href="#the-global-interpreter-lock-in-free-threaded-python">The global interpreter lock in free-threaded Python</a></li>
<li><a class="reference internal" href="#thread-safety">Thread safety</a></li>
<li><a class="reference internal" href="#known-limitations">Known limitations</a><ul>
<li><a class="reference internal" href="#immortalization">Immortalization</a></li>
<li><a class="reference internal" href="#frame-objects">Frame objects</a></li>
<li><a class="reference internal" href="#iterators">Iterators</a></li>
<li><a class="reference internal" href="#single-threaded-performance">Single-threaded performance</a></li>
<li><a class="reference internal" href="#behavioral-changes">Behavioral changes</a><ul>
<li><a class="reference internal" href="#context-variables">Context variables</a></li>
<li><a class="reference internal" href="#warning-filters">Warning filters</a></li>
<li><a class="reference internal" href="#increased-memory-usage">Increased memory usage</a><ul>
<li><a class="reference internal" href="#all-interned-strings-are-immortal">All interned strings are immortal</a></li>
<li><a class="reference internal" href="#non-gc-objects-have-a-larger-object-header">Non-GC objects have a larger object header</a></li>
<li><a class="reference internal" href="#qsbr-can-delay-freeing-of-memory">QSBR can delay freeing of memory</a></li>
<li><a class="reference internal" href="#mimalloc-allocator-vs-pymalloc">mimalloc allocator vs pymalloc</a></li>
<li><a class="reference internal" href="#free-threaded-reference-counting-can-cause-objects-to-live-longer">Free-threaded reference counting can cause objects to live longer</a></li>
<li><a class="reference internal" href="#per-thread-reference-counting-can-delay-freeing-objects">Per-thread reference counting can delay freeing objects</a></li>
    <h4>موضوع قبلی</h4>
    <p class="topless"><a href="mro.html"
                          title="فصل قبلی">The Python 2.3 Method Resolution Order</a></p>
    <h4>موضوع  بعدی</h4>
    <p class="topless"><a href="free-threading-extensions.html"
                          title="فصل بعدی">C API Extension Support for Free Threading</a></p>
    document.addEventListener('DOMContentLoaded', () => {
        const title = document.querySelector('meta[property="og:title"]').content;
        const elements = document.querySelectorAll('.improvepage');
        const pageurl = window.location.href.split('?')[0];
        elements.forEach(element => {
            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
            url.searchParams.set('pagetitle', title);
            url.searchParams.set('pageurl', pageurl);
            url.searchParams.set('pagesource', "howto/free-threading-python.rst");
            element.href = url.toString();
        });
  </script>
  <div role="note" aria-label="source link">
    <h3>این صفحه</h3>
    <ul class="this-page-menu">
      <li><a href="../bugs.html">گزارش یک اشکال</a></li>
      <li><a class="improvepage" href="../improve-page-nojs.html">بهبود این صفحه</a></li>
        <a href="https://github.com/python/cpython/blob/main/Doc/howto/free-threading-python.rst?plain=1"
            rel="nofollow">نمایش منبع
        </a>
      </li>
        <a href="https://github.com/python/python-docs-fa/blob/3.14/howto/free-threading-python.po?plain=1"
           rel="nofollow">نمایش منبع ترجمه</a>
      </li>
        </nav>
    <div class="related" role="navigation" aria-label="Related">
      <h3>ناوبری</h3>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="فهرست کلی"
             accesskey="I">فهرست</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="نمایه ی ماژول های پایتون"
             >ماژول ها</a> |</li>
        <li class="right" >
          <a href="free-threading-extensions.html" title="C API Extension Support for Free Threading"
             accesskey="N">بعدی</a> |</li>
        <li class="right" >
          <a href="mro.html" title="The Python 2.3 Method Resolution Order"
             accesskey="P">قبلی</a> |</li>
          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
          <li><a href="https://www.python.org/">Python</a> &#187;</li>
          <li class="switchers">
            <div class="language_switcher_placeholder"></div>
            <div class="version_switcher_placeholder"></div>
          </li>
          <li>
          </li>
    <li id="cpython-language-and-version">
      <a href="../index.html">3.14.6 Documentation</a> &#187;
          <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python HOWTOs</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Python support for free threading</a></li>
                <li class="right">
    <div class="inline-search" role="search">
        <form class="inline-search" action="../search.html" method="get">
          <input placeholder="جستجو سریع" aria-label="جستجو سریع" type="search" name="q" id="search-box">
          <input type="submit" value="برو">
        </form>
                </li>
            <li class="right">
<label class="theme-selector-label">
    <select class="theme-selector" oninput="activateTheme(this.value)">
        <option value="auto" selected>Auto</option>
        <option value="light">Light</option>
        <option value="dark">Dark</option>
    </select>
</label> |</li>
      </ul>
    </div>    
    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
  <section id="python-support-for-free-threading">
<span id="freethreading-python-howto"></span><h1>Python support for free threading<a class="headerlink" href="#python-support-for-free-threading" title="Link to this heading">¶</a></h1>
<p>Starting with the 3.13 release, CPython has support for a build of
Python called <a class="reference internal" href="../glossary.html#term-free-threading"><span class="xref std std-term">free threading</span></a> where the <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">global interpreter lock</span></a>
(GIL) is disabled.  Free-threaded execution allows for full utilization of the
available processing power by running threads in parallel on available CPU cores.
While not all software will benefit from this automatically, programs
designed with threading in mind will run faster on multi-core hardware.</p>
<p>Some third-party packages, in particular ones
with an <a class="reference internal" href="../glossary.html#term-extension-module"><span class="xref std std-term">extension module</span></a>, may not be ready for use in a
free-threaded build, and will re-enable the <a class="reference internal" href="../glossary.html#term-GIL"><span class="xref std std-term">GIL</span></a>.</p>
<p>This document describes the implications of free threading
for Python code.  See <a class="reference internal" href="free-threading-extensions.html#freethreading-extensions-howto"><span class="std std-ref">C API Extension Support for Free Threading</span></a> for information on
how to write C extensions that support the free-threaded build.</p>
<div class="admonition seealso">
<p class="admonition-title">همچنین ملاحظه نمائید</p>
<p><span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0703/"><strong>PEP 703</strong></a> – Making the Global Interpreter Lock Optional in CPython for an
overall description of free-threaded Python.</p>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading">¶</a></h2>
<p>Starting with Python 3.13, the official macOS and Windows installers
optionally support installing free-threaded Python binaries.  The installers
are available at <a class="reference external" href="https://www.python.org/downloads/">https://www.python.org/downloads/</a>.</p>
<p>For information on other platforms, see the <a class="reference external" href="https://py-free-threading.github.io/installing-cpython/">Installing a Free-Threaded Python</a>, a
community-maintained installation guide for installing free-threaded Python.</p>
<p>When building CPython from source, the <a class="reference internal" href="../using/configure.html#cmdoption-disable-gil"><code class="xref std std-option docutils literal notranslate"><span class="pre">--disable-gil</span></code></a> configure option
should be used to build a free-threaded Python interpreter.</p>
<section id="identifying-free-threaded-python">
<h2>Identifying free-threaded Python<a class="headerlink" href="#identifying-free-threaded-python" title="Link to this heading">¶</a></h2>
<p>To check if the current interpreter supports free-threading, <a class="reference internal" href="../using/cmdline.html#cmdoption-V"><code class="xref std std-option docutils literal notranslate"><span class="pre">python</span> <span class="pre">-VV</span></code></a>
and <a class="reference internal" href="../library/sys.html#sys.version" title="sys.version"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.version</span></code></a> contain &quot;free-threading build&quot;.
The new <a class="reference internal" href="../library/sys.html#sys._is_gil_enabled" title="sys._is_gil_enabled"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys._is_gil_enabled()</span></code></a> function can be used to check whether
the GIL is actually disabled in the running process.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">sysconfig.get_config_var(&quot;Py_GIL_DISABLED&quot;)</span></code> configuration variable can
be used to determine whether the build supports free threading.  If the variable
is set to <code class="docutils literal notranslate"><span class="pre">1</span></code>, then the build supports free threading.  This is the recommended
mechanism for decisions related to the build configuration.</p>
<section id="the-global-interpreter-lock-in-free-threaded-python">
<h2>The global interpreter lock in free-threaded Python<a class="headerlink" href="#the-global-interpreter-lock-in-free-threaded-python" title="Link to this heading">¶</a></h2>
<p>Free-threaded builds of CPython support optionally running with the GIL enabled
at runtime using the environment variable <span class="target" id="index-1"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHON_GIL"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHON_GIL</span></code></a> or
the command-line option <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span> <span class="pre">gil</span></code></a>.</p>
<p>The GIL may also automatically be enabled when importing a C-API extension
module that is not explicitly marked as supporting free threading.  A warning
will be printed in this case.</p>
<p>In addition to individual package documentation, the following websites track
the status of popular packages support for free threading:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://py-free-threading.github.io/tracking/">https://py-free-threading.github.io/tracking/</a></p></li>
<li><p><a class="reference external" href="https://hugovk.github.io/free-threaded-wheels/">https://hugovk.github.io/free-threaded-wheels/</a></p></li>
<section id="thread-safety">
<h2>Thread safety<a class="headerlink" href="#thread-safety" title="Link to this heading">¶</a></h2>
<p>The free-threaded build of CPython aims to provide similar thread-safety
behavior at the Python level to the default GIL-enabled build.  Built-in
types like <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, and <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> use internal locks
to protect against concurrent modifications in ways that behave similarly to
the GIL.  However, Python has not historically guaranteed specific behavior for
concurrent modifications to these built-in types, so this should be treated
as a description of the current implementation, not a guarantee of current or
future behavior.</p>
<div class="admonition note">
<p class="admonition-title">توجه</p>
<p>It's recommended to use the <a class="reference internal" href="../library/threading.html#threading.Lock" title="threading.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Lock</span></code></a> or other synchronization
primitives instead of relying on the internal locks of built-in types, when
possible.</p>
<section id="known-limitations">
<h2>Known limitations<a class="headerlink" href="#known-limitations" title="Link to this heading">¶</a></h2>
<p>This section describes known limitations of the free-threaded CPython build.</p>
<section id="immortalization">
<h3>Immortalization<a class="headerlink" href="#immortalization" title="Link to this heading">¶</a></h3>
<p>In the free-threaded build, some objects are <a class="reference internal" href="../glossary.html#term-immortal"><span class="xref std std-term">immortal</span></a>.
Immortal objects are not deallocated and have reference counts that are
never modified.  This is done to avoid reference count contention that would
prevent efficient multi-threaded scaling.</p>
<p>As of the 3.14 release, immortalization is limited to:</p>
<ul class="simple">
<li><p>Code constants: numeric literals, string literals, and tuple literals
composed of other constants.</p></li>
<li><p>Strings interned by <a class="reference internal" href="../library/sys.html#sys.intern" title="sys.intern"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.intern()</span></code></a>.</p></li>
<section id="frame-objects">
<h3>Frame objects<a class="headerlink" href="#frame-objects" title="Link to this heading">¶</a></h3>
<p>It is not safe to access <a class="reference internal" href="../reference/datamodel.html#frame.f_locals" title="frame.f_locals"><code class="xref py py-attr docutils literal notranslate"><span class="pre">frame.f_locals</span></code></a> from a <a class="reference internal" href="../reference/datamodel.html#frame-objects"><span class="std std-ref">frame</span></a>
object if that frame is currently executing in another thread, and doing so may
crash the interpreter.</p>
<section id="iterators">
<h3>Iterators<a class="headerlink" href="#iterators" title="Link to this heading">¶</a></h3>
<p>It is generally not thread-safe to access the same iterator object from
multiple threads concurrently, and threads may see duplicate or missing
elements.</p>
<section id="single-threaded-performance">
<h3>Single-threaded performance<a class="headerlink" href="#single-threaded-performance" title="Link to this heading">¶</a></h3>
<p>The free-threaded build has additional overhead when executing Python code
compared to the default GIL-enabled build.  The amount of overhead depends
on the workload and hardware.  On the pyperformance benchmark suite, the
average overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linux
systems.</p>
<section id="behavioral-changes">
<h2>Behavioral changes<a class="headerlink" href="#behavioral-changes" title="Link to this heading">¶</a></h2>
<p>This section describes CPython behavioural changes with the free-threaded
<section id="context-variables">
<h3>Context variables<a class="headerlink" href="#context-variables" title="Link to this heading">¶</a></h3>
<p>In the free-threaded build, the flag <a class="reference internal" href="../library/sys.html#sys.flags.thread_inherit_context" title="sys.flags.thread_inherit_context"><code class="xref py py-data docutils literal notranslate"><span class="pre">thread_inherit_context</span></code></a>
is set to true by default which causes threads created with
<a class="reference internal" href="../library/threading.html#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Thread</span></code></a> to start with a copy of the
<a class="reference internal" href="../library/contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context()</span></code></a> of the caller of
<a class="reference internal" href="../library/threading.html#threading.Thread.start" title="threading.Thread.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a>.  In the default GIL-enabled build, the flag
defaults to false so threads start with an
empty <code class="xref py py-class docutils literal notranslate"><span class="pre">Context()</span></code>.</p>
<section id="warning-filters">
<h3>Warning filters<a class="headerlink" href="#warning-filters" title="Link to this heading">¶</a></h3>
<p>In the free-threaded build, the flag <a class="reference internal" href="../library/sys.html#sys.flags.context_aware_warnings" title="sys.flags.context_aware_warnings"><code class="xref py py-data docutils literal notranslate"><span class="pre">context_aware_warnings</span></code></a>
is set to true by default.  In the default GIL-enabled build, the flag defaults
to false.  If the flag is true then the <a class="reference internal" href="../library/warnings.html#warnings.catch_warnings" title="warnings.catch_warnings"><code class="xref py py-class docutils literal notranslate"><span class="pre">warnings.catch_warnings</span></code></a>
context manager uses a context variable for warning filters.  If the flag is
false then <code class="xref py py-class docutils literal notranslate"><span class="pre">catch_warnings</span></code> modifies the global filters list,
which is not thread-safe.  See the <a class="reference internal" href="../library/warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> module for more details.</p>
<section id="increased-memory-usage">
<h3>Increased memory usage<a class="headerlink" href="#increased-memory-usage" title="Link to this heading">¶</a></h3>
<p>The free-threaded build will typically use more memory compared to the default
build.  There are multiple reasons for this, mostly due to design decisions.</p>
<section id="all-interned-strings-are-immortal">
<h4>All interned strings are immortal<a class="headerlink" href="#all-interned-strings-are-immortal" title="Link to this heading">¶</a></h4>
<p>For modern Python versions (since version 2.3), interning a string (e.g. with
<a class="reference internal" href="../library/sys.html#sys.intern" title="sys.intern"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.intern()</span></code></a>) does not cause it to become immortal.  Instead, if the last
reference to that string disappears, it will be removed from the interned
string table.  This is not the case for the free-threaded build and any interned
string will become immortal, surviving until interpreter shutdown.</p>
<section id="non-gc-objects-have-a-larger-object-header">
<h4>Non-GC objects have a larger object header<a class="headerlink" href="#non-gc-objects-have-a-larger-object-header" title="Link to this heading">¶</a></h4>
<p>The free-threaded build uses a different <a class="reference internal" href="../c-api/structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> structure.  Instead
of having the GC related information allocated before the <code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code>
structure, like in the default build, the GC related info is part of the normal
object header.  For example, on the AMD64 platform, <code class="docutils literal notranslate"><span class="pre">None</span></code> uses 32 bytes on
the free-threaded build vs 16 bytes for the default build.  GC objects (such as
dicts and lists) are the same size for both builds since the free-threaded
build does not use additional space for the GC info.</p>
<section id="qsbr-can-delay-freeing-of-memory">
<h4>QSBR can delay freeing of memory<a class="headerlink" href="#qsbr-can-delay-freeing-of-memory" title="Link to this heading">¶</a></h4>
<p>In order to safely implement lock-free data structures, a safe memory
reclamation (SMR) scheme is used, known as quiescent state-based reclamation
(QSBR).  This means that the memory backing data structures allowing lock-free
access will use QSBR, which defers the free operation, rather than immediately
freeing the memory.  Two examples of these data structures are the list object
and the dictionary keys object.  See <code class="docutils literal notranslate"><span class="pre">InternalDocs/qsbr.md</span></code> in the CPython
source tree for more details on how QSBR is implemented.  Running
<a class="reference internal" href="../library/gc.html#gc.collect" title="gc.collect"><code class="xref py py-func docutils literal notranslate"><span class="pre">gc.collect()</span></code></a> should cause all memory being held by QSBR to be actually
freed.  Note that even when QSBR frees the memory, the underlying memory
allocator may not immediately return that memory to the OS and so the resident
set size (RSS) of the process might not decrease.</p>
<section id="mimalloc-allocator-vs-pymalloc">
<h4>mimalloc allocator vs pymalloc<a class="headerlink" href="#mimalloc-allocator-vs-pymalloc" title="Link to this heading">¶</a></h4>
<p>The default build will normally use the &quot;pymalloc&quot; memory allocator for small
allocations (512 bytes or smaller).  The free-threaded build does not use
pymalloc and allocates all Python objects using the &quot;mimalloc&quot; allocator.  The
pymalloc allocator has the following properties that help keep memory usage
low: small per-allocated-block overhead, effective memory fragmentation
prevention, and quick return of free memory to the operating system.  The
mimalloc allocator does quite well in these respects as well but can have some
more overhead.</p>
<p>In the free-threaded build, mimalloc manages memory in a number of separate
heaps (currently four).  For example, all GC supporting objects are allocated
from their own heap.  Using separate heaps means that free memory in one heap
cannot be used for an allocation that uses another heap.  Also, some heaps are
configured to use QSBR (quiescent-state based reclamation) when freeing the
memory that backs up the heap (known as &quot;pages&quot; in mimalloc terminology).  The
use of QSBR creates a delay between all memory blocks for a page being freed
and the memory page being released, either for new allocations or back to the
<p>The mimalloc allocator also defers returning freed memory back to the OS.  You
can reduce that delay by setting the environment variable
<code class="xref std std-envvar docutils literal notranslate"><span class="pre">MIMALLOC_PURGE_DELAY</span></code> to <code class="docutils literal notranslate"><span class="pre">0</span></code>.  Note that this will likely reduce
the performance of the allocator.</p>
<section id="free-threaded-reference-counting-can-cause-objects-to-live-longer">
<h4>Free-threaded reference counting can cause objects to live longer<a class="headerlink" href="#free-threaded-reference-counting-can-cause-objects-to-live-longer" title="Link to this heading">¶</a></h4>
<p>In the default build, when an object's reference count reaches zero, it is
normally deallocated.  The free-threaded build uses &quot;biased reference
counting&quot;, with a fast-path for objects &quot;owned&quot; by the current thread and a
slow path for other objects.  See <span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0703/"><strong>PEP 703</strong></a> for additional details.  Any time
an object's reference count ends up in a &quot;queued&quot; state, deallocation can be
deferred.  The queued state is cleared from the &quot;eval breaker&quot; section of the
bytecode evaluator.</p>
<p>The free-threaded build also allows a different mode of reference counting,
known as &quot;deferred reference counting&quot;.  This mode is enabled by setting a flag
on a per-object basis.  Deferred reference counting is enabled for the
following types:</p>
<ul class="simple">
<li><p>module objects</p></li>
<li><p>module top-level functions</p></li>
<li><p>class methods defined in the class scope</p></li>
<li><p>descriptor objects</p></li>
<li><p>thread-local objects, created by <a class="reference internal" href="../library/threading.html#threading.local" title="threading.local"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.local</span></code></a></p></li>
<p>When deferred reference counting is enabled, references from Python function
stacks are not added to the reference count.  This scheme reduces the overhead
of reference counting, especially for objects used from multiple threads.
Because the stack references are not counted, objects with deferred reference
counting are not immediately freed when their internal reference count goes to
zero.  Instead, they are examined by the next GC run and, if no stack
references to them are found, they are freed.  This means these objects are
freed by the GC and not when their reference count goes to zero, as is typical.</p>
<section id="per-thread-reference-counting-can-delay-freeing-objects">
<h4>Per-thread reference counting can delay freeing objects<a class="headerlink" href="#per-thread-reference-counting-can-delay-freeing-objects" title="Link to this heading">¶</a></h4>
<p>To avoid contention on the reference count fields of frequently shared
objects, the free-threaded build also uses &quot;per-thread reference counting&quot;
for a few selected object types.  Rather than updating a single shared
reference count, each thread maintains its own local reference count array,
indexed by a unique id assigned to the object.  The true reference count is
only computed by summing the per-thread counts when the object's local
count drops to zero.  Per-thread reference counting is currently used for:</p>
<ul class="simple">
<li><p>heap type objects (classes created in Python)</p></li>
<li><p>code objects</p></li>
<li><p>the <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> of module objects</p></li>
<p>Because the per-thread counts must be merged back to the object before it
can be deallocated, objects using per-thread reference counting are
typically freed later than they would be in the default build.  In
particular, such an object is usually not freed until the thread that
referenced it reaches a safe point (for example, in the &quot;eval breaker&quot;
section of the bytecode evaluator) or exits.  Running <a class="reference internal" href="../library/gc.html#gc.collect" title="gc.collect"><code class="xref py py-func docutils literal notranslate"><span class="pre">gc.collect()</span></code></a>
will merge the per-thread counts and allow these objects to be freed.</p>
            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper">
    <h3><a href="../contents.html">فهرست عناوین</a></h3>
<li><a class="reference internal" href="#">Python support for free threading</a><ul>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#identifying-free-threaded-python">Identifying free-threaded Python</a></li>
<li><a class="reference internal" href="#the-global-interpreter-lock-in-free-threaded-python">The global interpreter lock in free-threaded Python</a></li>
<li><a class="reference internal" href="#thread-safety">Thread safety</a></li>
<li><a class="reference internal" href="#known-limitations">Known limitations</a><ul>
<li><a class="reference internal" href="#immortalization">Immortalization</a></li>
<li><a class="reference internal" href="#frame-objects">Frame objects</a></li>
<li><a class="reference internal" href="#iterators">Iterators</a></li>
<li><a class="reference internal" href="#single-threaded-performance">Single-threaded performance</a></li>
<li><a class="reference internal" href="#behavioral-changes">Behavioral changes</a><ul>
<li><a class="reference internal" href="#context-variables">Context variables</a></li>
<li><a class="reference internal" href="#warning-filters">Warning filters</a></li>
<li><a class="reference internal" href="#increased-memory-usage">Increased memory usage</a><ul>
<li><a class="reference internal" href="#all-interned-strings-are-immortal">All interned strings are immortal</a></li>
<li><a class="reference internal" href="#non-gc-objects-have-a-larger-object-header">Non-GC objects have a larger object header</a></li>
<li><a class="reference internal" href="#qsbr-can-delay-freeing-of-memory">QSBR can delay freeing of memory</a></li>
<li><a class="reference internal" href="#mimalloc-allocator-vs-pymalloc">mimalloc allocator vs pymalloc</a></li>
<li><a class="reference internal" href="#free-threaded-reference-counting-can-cause-objects-to-live-longer">Free-threaded reference counting can cause objects to live longer</a></li>
<li><a class="reference internal" href="#per-thread-reference-counting-can-delay-freeing-objects">Per-thread reference counting can delay freeing objects</a></li>
    <h4>موضوع قبلی</h4>
    <p class="topless"><a href="mro.html"
                          title="فصل قبلی">The Python 2.3 Method Resolution Order</a></p>
    <h4>موضوع  بعدی</h4>
    <p class="topless"><a href="free-threading-extensions.html"
                          title="فصل بعدی">C API Extension Support for Free Threading</a></p>
    document.addEventListener('DOMContentLoaded', () => {
        const title = document.querySelector('meta[property="og:title"]').content;
        const elements = document.querySelectorAll('.improvepage');
        const pageurl = window.location.href.split('?')[0];
        elements.forEach(element => {
            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
            url.searchParams.set('pagetitle', title);
            url.searchParams.set('pageurl', pageurl);
            url.searchParams.set('pagesource', "howto/free-threading-python.rst");
            element.href = url.toString();
        });
  </script>
  <div role="note" aria-label="source link">
    <h3>این صفحه</h3>
    <ul class="this-page-menu">
      <li><a href="../bugs.html">گزارش یک اشکال</a></li>
      <li><a class="improvepage" href="../improve-page-nojs.html">بهبود این صفحه</a></li>
        <a href="https://github.com/python/cpython/blob/main/Doc/howto/free-threading-python.rst?plain=1"
            rel="nofollow">نمایش منبع
        </a>
      </li>
        <a href="https://github.com/python/python-docs-fa/blob/3.14/howto/free-threading-python.po?plain=1"
           rel="nofollow">نمایش منبع ترجمه</a>
      </li>
        </div>
<div id="sidebarbutton" title="تا کردن نوار کناره">
<span>«</span>
      </div>
      <div class="clearer"></div>
    </div>  
    <div class="related" role="navigation" aria-label="Related">
      <h3>ناوبری</h3>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="فهرست کلی"
             >فهرست</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="نمایه ی ماژول های پایتون"
             >ماژول ها</a> |</li>
        <li class="right" >
          <a href="free-threading-extensions.html" title="C API Extension Support for Free Threading"
             >بعدی</a> |</li>
        <li class="right" >
          <a href="mro.html" title="The Python 2.3 Method Resolution Order"
             >قبلی</a> |</li>
          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
          <li><a href="https://www.python.org/">Python</a> &#187;</li>
          <li class="switchers">
            <div class="language_switcher_placeholder"></div>
            <div class="version_switcher_placeholder"></div>
          </li>
          <li>
          </li>
    <li id="cpython-language-and-version">
      <a href="../index.html">3.14.6 Documentation</a> &#187;
          <li class="nav-item nav-item-1"><a href="index.html" >Python HOWTOs</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Python support for free threading</a></li>
                <li class="right">
    <div class="inline-search" role="search">
        <form class="inline-search" action="../search.html" method="get">
          <input placeholder="جستجو سریع" aria-label="جستجو سریع" type="search" name="q" id="search-box">
          <input type="submit" value="برو">
        </form>
                </li>
            <li class="right">
<label class="theme-selector-label">
    <select class="theme-selector" oninput="activateTheme(this.value)">
        <option value="auto" selected>Auto</option>
        <option value="light">Light</option>
        <option value="dark">Dark</option>
    </select>
</label> |</li>
      </ul>
    </div>  
    <div class="footer">
    &copy; <a href="../copyright.html">حق چاپ</a> 2001 Python Software Foundation.
    This page is licensed under the Python Software Foundation License Version 2.
    Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
      See <a href="/license.html">History and License</a> for more information.<br>
    The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
      آخرین بروز رسانی در اوت 18, 2026 (04:23 UTC) .
      <a href="/bugs.html">Found a bug</a>?
    ایجاد شده با<a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

free-threading-python.html

Latest commit

History

free-threading-python.html

File metadata and controls
