parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="threading — Thread-based parallelism" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/threading.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/threading.py This module constructs higher-level threading interfaces on top of the lower level_thread module. Availability: not WASI. This module does not work or is not available..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_threading_d91eaec3.png" />15<meta property="og:image:alt" content="Source code: Lib/threading.py This module constructs higher-level threading interfaces on top of the lower level_thread module. Availability: not WASI. This module does not work or is not available..." />16<meta name="description" content="Source code: Lib/threading.py This module constructs higher-level threading interfaces on top of the lower level_thread module. Availability: not WASI. This module does not work or is not available..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>threading — Thread-based parallelism — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="multiprocessing — Process-based parallelism" href="multiprocessing.html" />43 <link rel="prev" title="Concurrent Execution" href="concurrency.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/threading.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <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>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> — Thread-based parallelism</a><ul>108<li><a class="reference internal" href="#introduction">Introduction</a></li>109<li><a class="reference internal" href="#gil-and-performance-considerations">GIL and performance considerations</a></li>110<li><a class="reference internal" href="#reference">Reference</a><ul>111<li><a class="reference internal" href="#thread-local-data">Thread-local data</a></li>112<li><a class="reference internal" href="#thread-objects">Thread objects</a></li>113<li><a class="reference internal" href="#lock-objects">Lock objects</a></li>114<li><a class="reference internal" href="#rlock-objects">RLock objects</a></li>115<li><a class="reference internal" href="#condition-objects">Condition objects</a></li>116<li><a class="reference internal" href="#semaphore-objects">Semaphore objects</a></li>117<li><a class="reference internal" href="#semaphore-example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Semaphore</span></code> example</a></li>118<li><a class="reference internal" href="#event-objects">Event objects</a></li>119<li><a class="reference internal" href="#timer-objects">Timer objects</a></li>120<li><a class="reference internal" href="#barrier-objects">Barrier objects</a></li>121</ul>122</li>123<li><a class="reference internal" href="#using-locks-conditions-and-semaphores-in-the-with-statement">Using locks, conditions, and semaphores in the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code> statement</a></li>124</ul>125</li>126</ul>127 128 </div>129 <div>130 <h4>Previous topic</h4>131 <p class="topless"><a href="concurrency.html"132 title="previous chapter">Concurrent Execution</a></p>133 </div>134 <div>135 <h4>Next topic</h4>136 <p class="topless"><a href="multiprocessing.html"137 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> — Process-based parallelism</a></p>138 </div>139 <script>140 document.addEventListener('DOMContentLoaded', () => {141 const title = document.querySelector('meta[property="og:title"]').content;142 const elements = document.querySelectorAll('.improvepage');143 const pageurl = window.location.href.split('?')[0];144 elements.forEach(element => {145 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));146 url.searchParams.set('pagetitle', title);147 url.searchParams.set('pageurl', pageurl);148 url.searchParams.set('pagesource', "library/threading.rst");149 element.href = url.toString();150 });151 });152 </script>153 <div role="note" aria-label="source link">154 <h3>This page</h3>155 <ul class="this-page-menu">156 <li><a href="../bugs.html">Report a bug</a></li>157 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>158 <li>159 <a href="https://github.com/python/cpython/blob/main/Doc/library/threading.rst?plain=1"160 rel="nofollow">Show source161 </a>162 </li>163 164 </ul>165 </div>166 </nav>167 </div>168</div>169 170 171 <div class="related" role="navigation" aria-label="Related">172 <h3>Navigation</h3>173 <ul>174 <li class="right" style="margin-right: 10px">175 <a href="../genindex.html" title="General Index"176 accesskey="I">index</a></li>177 <li class="right" >178 <a href="../py-modindex.html" title="Python Module Index"179 >modules</a> |</li>180 <li class="right" >181 <a href="multiprocessing.html" title="multiprocessing — Process-based parallelism"182 accesskey="N">next</a> |</li>183 <li class="right" >184 <a href="concurrency.html" title="Concurrent Execution"185 accesskey="P">previous</a> |</li>186 187 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>188 <li><a href="https://www.python.org/">Python</a> »</li>189 <li class="switchers">190 <div class="language_switcher_placeholder"></div>191 <div class="version_switcher_placeholder"></div>192 </li>193 <li>194 195 </li>196 <li id="cpython-language-and-version">197 <a href="../index.html">3.15.0a6 Documentation</a> »198 </li>199 200 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>201 <li class="nav-item nav-item-2"><a href="concurrency.html" accesskey="U">Concurrent Execution</a> »</li>202 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> — Thread-based parallelism</a></li>203 <li class="right">204 205 206 <div class="inline-search" role="search">207 <form class="inline-search" action="../search.html" method="get">208 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">209 <input type="submit" value="Go">210 </form>211 </div>212 |213 </li>214 <li class="right">215<label class="theme-selector-label">216 Theme217 <select class="theme-selector" oninput="activateTheme(this.value)">218 <option value="auto" selected>Auto</option>219 <option value="light">Light</option>220 <option value="dark">Dark</option>221 </select>222</label> |</li>223 224 </ul>225 </div> 226 227 <div class="document">228 <div class="documentwrapper">229 <div class="bodywrapper">230 <div class="body" role="main">231 232 <section id="module-threading">233<span id="threading-thread-based-parallelism"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> — Thread-based parallelism<a class="headerlink" href="#module-threading" title="Link to this heading">¶</a></h1>234<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/threading.py">Lib/threading.py</a></p>235<hr class="docutils" />236<p>This module constructs higher-level threading interfaces on top of the lower237level <a class="reference internal" href="_thread.html#module-_thread" title="_thread: Low-level threading API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">_thread</span></code></a> module.</p>238<div class="availability docutils container">239<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: not WASI.</p>240<p>This module does not work or is not available on WebAssembly. See241<a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p>242</div>243<section id="introduction">244<h2>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>245<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> module provides a way to run multiple <a class="reference external" href="https://en.wikipedia.org/wiki/Thread_(computing)">threads</a> (smaller246units of a process) concurrently within a single process. It allows for the247creation and management of threads, making it possible to execute tasks in248parallel, sharing memory space. Threads are particularly useful when tasks are249I/O bound, such as file operations or making network requests,250where much of the time is spent waiting for external resources.</p>251<p>A typical use case for <code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> includes managing a pool of worker252threads that can process multiple tasks concurrently. Here’s a basic example of253creating and starting threads using <a class="reference internal" href="#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">Thread</span></code></a>:</p>254<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">threading</span>255<span class="kn">import</span><span class="w"> </span><span class="nn">time</span>256 257<span class="k">def</span><span class="w"> </span><span class="nf">crawl</span><span class="p">(</span><span class="n">link</span><span class="p">,</span> <span class="n">delay</span><span class="o">=</span><span class="mi">3</span><span class="p">):</span>258 <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"crawl started for </span><span class="si">{</span><span class="n">link</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>259 <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="n">delay</span><span class="p">)</span> <span class="c1"># Blocking I/O (simulating a network request)</span>260 <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"crawl ended for </span><span class="si">{</span><span class="n">link</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>261 262<span class="n">links</span> <span class="o">=</span> <span class="p">[</span>263 <span class="s2">"https://python.org"</span><span class="p">,</span>264 <span class="s2">"https://docs.python.org"</span><span class="p">,</span>265 <span class="s2">"https://peps.python.org"</span><span class="p">,</span>266<span class="p">]</span>267 268<span class="c1"># Start threads for each link</span>269<span class="n">threads</span> <span class="o">=</span> <span class="p">[]</span>270<span class="k">for</span> <span class="n">link</span> <span class="ow">in</span> <span class="n">links</span><span class="p">:</span>271 <span class="c1"># Using `args` to pass positional arguments and `kwargs` for keyword arguments</span>272 <span class="n">t</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">crawl</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">link</span><span class="p">,),</span> <span class="n">kwargs</span><span class="o">=</span><span class="p">{</span><span class="s2">"delay"</span><span class="p">:</span> <span class="mi">2</span><span class="p">})</span>273 <span class="n">threads</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">t</span><span class="p">)</span>274 275<span class="c1"># Start each thread</span>276<span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="n">threads</span><span class="p">:</span>277 <span class="n">t</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>278 279<span class="c1"># Wait for all threads to finish</span>280<span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="n">threads</span><span class="p">:</span>281 <span class="n">t</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>282</pre></div>283</div>284<div class="versionchanged">285<p><span class="versionmodified changed">Changed in version 3.7: </span>This module used to be optional, it is now always available.</p>286</div>287<div class="admonition seealso">288<p class="admonition-title">See also</p>289<p><a class="reference internal" href="concurrent.futures.html#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">concurrent.futures.ThreadPoolExecutor</span></code></a> offers a higher level interface290to push tasks to a background thread without blocking execution of the291calling thread, while still being able to retrieve their results when needed.</p>292<p><a class="reference internal" href="queue.html#module-queue" title="queue: A synchronized queue class."><code class="xref py py-mod docutils literal notranslate"><span class="pre">queue</span></code></a> provides a thread-safe interface for exchanging data between293running threads.</p>294<p><a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> offers an alternative approach to achieving task level295concurrency without requiring the use of multiple operating system threads.</p>296</div>297<div class="admonition note">298<p class="admonition-title">Note</p>299<p>In the Python 2.x series, this module contained <code class="docutils literal notranslate"><span class="pre">camelCase</span></code> names300for some methods and functions. These are deprecated as of Python 3.10,301but they are still supported for compatibility with Python 2.5 and lower.</p>302</div>303<div class="impl-detail compound">304<p><strong>CPython implementation detail:</strong> In CPython, due to the <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">Global Interpreter Lock</span></a>, only one thread305can execute Python code at once (even though certain performance-oriented306libraries might overcome this limitation).307If you want your application to make better use of the computational308resources of multi-core machines, you are advised to use309<a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> or <a class="reference internal" href="concurrent.futures.html#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">concurrent.futures.ProcessPoolExecutor</span></code></a>.310However, threading is still an appropriate model if you want to run311multiple I/O-bound tasks simultaneously.</p>312</div>313</section>314<section id="gil-and-performance-considerations">315<h2>GIL and performance considerations<a class="headerlink" href="#gil-and-performance-considerations" title="Link to this heading">¶</a></h2>316<p>Unlike the <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> module, which uses separate processes to317bypass the <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">global interpreter lock</span></a> (GIL), the threading module operates318within a single process, meaning that all threads share the same memory space.319However, the GIL limits the performance gains of threading when it comes to320CPU-bound tasks, as only one thread can execute Python bytecode at a time.321Despite this, threads remain a useful tool for achieving concurrency in many322scenarios.</p>323<p>As of Python 3.13, <a class="reference internal" href="../glossary.html#term-free-threading"><span class="xref std std-term">free-threaded</span></a> builds324can disable the GIL, enabling true parallel execution of threads, but this325feature is not available by default (see <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0703/"><strong>PEP 703</strong></a>).</p>326</section>327<section id="reference">328<h2>Reference<a class="headerlink" href="#reference" title="Link to this heading">¶</a></h2>329<p>This module defines the following functions:</p>330<dl class="py function">331<dt class="sig sig-object py" id="threading.active_count">332<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">active_count</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.active_count" title="Link to this definition">¶</a></dt>333<dd><p>Return the number of <a class="reference internal" href="#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">Thread</span></code></a> objects currently alive. The returned334count is equal to the length of the list returned by <a class="reference internal" href="#threading.enumerate" title="threading.enumerate"><code class="xref py py-func docutils literal notranslate"><span class="pre">enumerate()</span></code></a>.</p>335<p>The function <code class="docutils literal notranslate"><span class="pre">activeCount</span></code> is a deprecated alias for this function.</p>336</dd></dl>337 338<dl class="py function">339<dt class="sig sig-object py" id="threading.current_thread">340<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">current_thread</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.current_thread" title="Link to this definition">¶</a></dt>341<dd><p>Return the current <a class="reference internal" href="#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">Thread</span></code></a> object, corresponding to the caller’s thread342of control. If the caller’s thread of control was not created through the343<code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> module, a dummy thread object with limited functionality is344returned.</p>345<p>The function <code class="docutils literal notranslate"><span class="pre">currentThread</span></code> is a deprecated alias for this function.</p>346</dd></dl>347 348<dl class="py function">349<dt class="sig sig-object py" id="threading.excepthook">350<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">excepthook</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.excepthook" title="Link to this definition">¶</a></dt>351<dd><p>Handle uncaught exception raised by <a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">Thread.run()</span></code></a>.</p>352<p>The <em>args</em> argument has the following attributes:</p>353<ul class="simple">354<li><p><em>exc_type</em>: Exception type.</p></li>355<li><p><em>exc_value</em>: Exception value, can be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>356<li><p><em>exc_traceback</em>: Exception traceback, can be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>357<li><p><em>thread</em>: Thread which raised the exception, can be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>358</ul>359<p>If <em>exc_type</em> is <a class="reference internal" href="exceptions.html#SystemExit" title="SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a>, the exception is silently ignored.360Otherwise, the exception is printed out on <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a>.</p>361<p>If this function raises an exception, <a class="reference internal" href="sys.html#sys.excepthook" title="sys.excepthook"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.excepthook()</span></code></a> is called to362handle it.</p>363<p><a class="reference internal" href="#threading.excepthook" title="threading.excepthook"><code class="xref py py-func docutils literal notranslate"><span class="pre">threading.excepthook()</span></code></a> can be overridden to control how uncaught364exceptions raised by <a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">Thread.run()</span></code></a> are handled.</p>365<p>Storing <em>exc_value</em> using a custom hook can create a reference cycle. It366should be cleared explicitly to break the reference cycle when the367exception is no longer needed.</p>368<p>Storing <em>thread</em> using a custom hook can resurrect it if it is set to an369object which is being finalized. Avoid storing <em>thread</em> after the custom370hook completes to avoid resurrecting objects.</p>371<div class="admonition seealso">372<p class="admonition-title">See also</p>373<p><a class="reference internal" href="sys.html#sys.excepthook" title="sys.excepthook"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.excepthook()</span></code></a> handles uncaught exceptions.</p>374</div>375<div class="versionadded">376<p><span class="versionmodified added">Added in version 3.8.</span></p>377</div>378</dd></dl>379 380<dl class="py data">381<dt class="sig sig-object py" id="threading.__excepthook__">382<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">__excepthook__</span></span><a class="headerlink" href="#threading.__excepthook__" title="Link to this definition">¶</a></dt>383<dd><p>Holds the original value of <a class="reference internal" href="#threading.excepthook" title="threading.excepthook"><code class="xref py py-func docutils literal notranslate"><span class="pre">threading.excepthook()</span></code></a>. It is saved so that the384original value can be restored in case they happen to get replaced with385broken or alternative objects.</p>386<div class="versionadded">387<p><span class="versionmodified added">Added in version 3.10.</span></p>388</div>389</dd></dl>390 391<dl class="py function">392<dt class="sig sig-object py" id="threading.get_ident">393<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">get_ident</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.get_ident" title="Link to this definition">¶</a></dt>394<dd><p>Return the ‘thread identifier’ of the current thread. This is a nonzero395integer. Its value has no direct meaning; it is intended as a magic cookie396to be used e.g. to index a dictionary of thread-specific data. Thread397identifiers may be recycled when a thread exits and another thread is398created.</p>399<div class="versionadded">400<p><span class="versionmodified added">Added in version 3.3.</span></p>401</div>402</dd></dl>403 404<dl class="py function">405<dt class="sig sig-object py" id="threading.get_native_id">406<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">get_native_id</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.get_native_id" title="Link to this definition">¶</a></dt>407<dd><p>Return the native integral Thread ID of the current thread assigned by the kernel.408This is a non-negative integer.409Its value may be used to uniquely identify this particular thread system-wide410(until the thread terminates, after which the value may be recycled by the OS).</p>411<div class="availability docutils container">412<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD, Solaris.</p>413</div>414<div class="versionadded">415<p><span class="versionmodified added">Added in version 3.8.</span></p>416</div>417<div class="versionchanged">418<p><span class="versionmodified changed">Changed in version 3.13: </span>Added support for GNU/kFreeBSD.</p>419</div>420<div class="versionchanged">421<p><span class="versionmodified changed">Changed in version 3.15: </span>Added support for Solaris.</p>422</div>423</dd></dl>424 425<dl class="py function">426<dt class="sig sig-object py" id="threading.enumerate">427<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">enumerate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.enumerate" title="Link to this definition">¶</a></dt>428<dd><p>Return a list of all <a class="reference internal" href="#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">Thread</span></code></a> objects currently active. The list429includes daemonic threads and dummy thread objects created by430<a class="reference internal" href="#threading.current_thread" title="threading.current_thread"><code class="xref py py-func docutils literal notranslate"><span class="pre">current_thread()</span></code></a>. It excludes terminated threads and threads431that have not yet been started. However, the main thread is always part432of the result, even when terminated.</p>433</dd></dl>434 435<dl class="py function">436<dt class="sig sig-object py" id="threading.main_thread">437<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">main_thread</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.main_thread" title="Link to this definition">¶</a></dt>438<dd><p>Return the main <a class="reference internal" href="#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">Thread</span></code></a> object. In normal conditions, the439main thread is the thread from which the Python interpreter was440started.</p>441<div class="versionadded">442<p><span class="versionmodified added">Added in version 3.4.</span></p>443</div>444</dd></dl>445 446<dl class="py function">447<dt class="sig sig-object py" id="threading.settrace">448<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">settrace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.settrace" title="Link to this definition">¶</a></dt>449<dd><p id="index-1">Set a trace function for all threads started from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> module.450The <em>func</em> will be passed to <a class="reference internal" href="sys.html#sys.settrace" title="sys.settrace"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.settrace()</span></code></a> for each thread, before its451<a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method is called.</p>452</dd></dl>453 454<dl class="py function">455<dt class="sig sig-object py" id="threading.settrace_all_threads">456<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">settrace_all_threads</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.settrace_all_threads" title="Link to this definition">¶</a></dt>457<dd><p>Set a trace function for all threads started from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> module458and all Python threads that are currently executing.</p>459<p>The <em>func</em> will be passed to <a class="reference internal" href="sys.html#sys.settrace" title="sys.settrace"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.settrace()</span></code></a> for each thread, before its460<a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method is called.</p>461<div class="versionadded">462<p><span class="versionmodified added">Added in version 3.12.</span></p>463</div>464</dd></dl>465 466<dl class="py function">467<dt class="sig sig-object py" id="threading.gettrace">468<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">gettrace</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.gettrace" title="Link to this definition">¶</a></dt>469<dd><p id="index-2">Get the trace function as set by <a class="reference internal" href="#threading.settrace" title="threading.settrace"><code class="xref py py-func docutils literal notranslate"><span class="pre">settrace()</span></code></a>.</p>470<div class="versionadded">471<p><span class="versionmodified added">Added in version 3.10.</span></p>472</div>473</dd></dl>474 475<dl class="py function">476<dt class="sig sig-object py" id="threading.setprofile">477<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">setprofile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.setprofile" title="Link to this definition">¶</a></dt>478<dd><p id="index-3">Set a profile function for all threads started from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> module.479The <em>func</em> will be passed to <a class="reference internal" href="sys.html#sys.setprofile" title="sys.setprofile"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.setprofile()</span></code></a> for each thread, before its480<a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method is called.</p>481</dd></dl>482 483<dl class="py function">484<dt class="sig sig-object py" id="threading.setprofile_all_threads">485<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">setprofile_all_threads</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.setprofile_all_threads" title="Link to this definition">¶</a></dt>486<dd><p>Set a profile function for all threads started from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> module487and all Python threads that are currently executing.</p>488<p>The <em>func</em> will be passed to <a class="reference internal" href="sys.html#sys.setprofile" title="sys.setprofile"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.setprofile()</span></code></a> for each thread, before its489<a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method is called.</p>490<div class="versionadded">491<p><span class="versionmodified added">Added in version 3.12.</span></p>492</div>493</dd></dl>494 495<dl class="py function">496<dt class="sig sig-object py" id="threading.getprofile">497<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">getprofile</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.getprofile" title="Link to this definition">¶</a></dt>498<dd><p id="index-4">Get the profiler function as set by <a class="reference internal" href="#threading.setprofile" title="threading.setprofile"><code class="xref py py-func docutils literal notranslate"><span class="pre">setprofile()</span></code></a>.</p>499<div class="versionadded">500<p><span class="versionmodified added">Added in version 3.10.</span></p>501</div>502</dd></dl>503 504<dl class="py function">505<dt class="sig sig-object py" id="threading.stack_size">506<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">stack_size</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">size</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.stack_size" title="Link to this definition">¶</a></dt>507<dd><p>Return the thread stack size used when creating new threads. The optional508<em>size</em> argument specifies the stack size to be used for subsequently created509threads, and must be 0 (use platform or configured default) or a positive510integer value of at least 32,768 (32 KiB). If <em>size</em> is not specified,5110 is used. If changing the thread stack size is512unsupported, a <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> is raised. If the specified stack size is513invalid, a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised and the stack size is unmodified. 32 KiB514is currently the minimum supported stack size value to guarantee sufficient515stack space for the interpreter itself. Note that some platforms may have516particular restrictions on values for the stack size, such as requiring a517minimum stack size > 32 KiB or requiring allocation in multiples of the system518memory page size - platform documentation should be referred to for more519information (4 KiB pages are common; using multiples of 4096 for the stack size is520the suggested approach in the absence of more specific information).</p>521<div class="availability docutils container">522<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows, pthreads.</p>523<p>Unix platforms with POSIX threads support.</p>524</div>525</dd></dl>526 527<p>This module also defines the following constant:</p>528<dl class="py data">529<dt class="sig sig-object py" id="threading.TIMEOUT_MAX">530<span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">TIMEOUT_MAX</span></span><a class="headerlink" href="#threading.TIMEOUT_MAX" title="Link to this definition">¶</a></dt>531<dd><p>The maximum value allowed for the <em>timeout</em> parameter of blocking functions532(<a class="reference internal" href="#threading.Lock.acquire" title="threading.Lock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Lock.acquire()</span></code></a>, <a class="reference internal" href="#threading.RLock.acquire" title="threading.RLock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">RLock.acquire()</span></code></a>, <a class="reference internal" href="#threading.Condition.wait" title="threading.Condition.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Condition.wait()</span></code></a>, etc.).533Specifying a timeout greater than this value will raise an534<a class="reference internal" href="exceptions.html#OverflowError" title="OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a>.</p>535<div class="versionadded">536<p><span class="versionmodified added">Added in version 3.2.</span></p>537</div>538</dd></dl>539 540<p>This module defines a number of classes, which are detailed in the sections541below.</p>542<p>The design of this module is loosely based on Java’s threading model. However,543where Java makes locks and condition variables basic behavior of every object,544they are separate objects in Python. Python’s <a class="reference internal" href="#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">Thread</span></code></a> class supports a545subset of the behavior of Java’s Thread class; currently, there are no546priorities, no thread groups, and threads cannot be destroyed, stopped,547suspended, resumed, or interrupted. The static methods of Java’s Thread class,548when implemented, are mapped to module-level functions.</p>549<p>All of the methods described below are executed atomically.</p>550<section id="thread-local-data">551<h3>Thread-local data<a class="headerlink" href="#thread-local-data" title="Link to this heading">¶</a></h3>552<p>Thread-local data is data whose values are thread specific. If you553have data that you want to be local to a thread, create a554<a class="reference internal" href="#threading.local" title="threading.local"><code class="xref py py-class docutils literal notranslate"><span class="pre">local</span></code></a> object and use its attributes:</p>555<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span> <span class="o">=</span> <span class="n">local</span><span class="p">()</span>556<span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">number</span> <span class="o">=</span> <span class="mi">42</span>557<span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">number</span>558<span class="go">42</span>559</pre></div>560</div>561<p>You can also access the <a class="reference internal" href="#threading.local" title="threading.local"><code class="xref py py-class docutils literal notranslate"><span class="pre">local</span></code></a>-object’s dictionary:</p>562<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="vm">__dict__</span>563<span class="go">{'number': 42}</span>564<span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">setdefault</span><span class="p">(</span><span class="s1">'widgets'</span><span class="p">,</span> <span class="p">[])</span>565<span class="go">[]</span>566<span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">widgets</span>567<span class="go">[]</span>568</pre></div>569</div>570<p>If we access the data in a different thread:</p>571<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">log</span> <span class="o">=</span> <span class="p">[]</span>572<span class="gp">>>> </span><span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">():</span>573<span class="gp">... </span> <span class="n">items</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">mydata</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">items</span><span class="p">())</span>574<span class="gp">... </span> <span class="n">log</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">items</span><span class="p">)</span>575<span class="gp">... </span> <span class="n">mydata</span><span class="o">.</span><span class="n">number</span> <span class="o">=</span> <span class="mi">11</span>576<span class="gp">... </span> <span class="n">log</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">mydata</span><span class="o">.</span><span class="n">number</span><span class="p">)</span>577 578<span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">threading</span>579<span class="gp">>>> </span><span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">)</span>580<span class="gp">>>> </span><span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>581<span class="gp">>>> </span><span class="n">thread</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>582<span class="gp">>>> </span><span class="n">log</span>583<span class="go">[[], 11]</span>584</pre></div>585</div>586<p>we get different data. Furthermore, changes made in the other thread587don’t affect data seen in this thread:</p>588<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">number</span>589<span class="go">42</span>590</pre></div>591</div>592<p>Of course, values you get from a <a class="reference internal" href="#threading.local" title="threading.local"><code class="xref py py-class docutils literal notranslate"><span class="pre">local</span></code></a> object, including their593<a class="reference internal" href="../reference/datamodel.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> attribute, are for whatever thread was current594at the time the attribute was read. For that reason, you generally595don’t want to save these values across threads, as they apply only to596the thread they came from.</p>597<p>You can create custom <a class="reference internal" href="#threading.local" title="threading.local"><code class="xref py py-class docutils literal notranslate"><span class="pre">local</span></code></a> objects by subclassing the598<code class="xref py py-class docutils literal notranslate"><span class="pre">local</span></code> class:</p>599<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span><span class="w"> </span><span class="nc">MyLocal</span><span class="p">(</span><span class="n">local</span><span class="p">):</span>600<span class="gp">... </span> <span class="n">number</span> <span class="o">=</span> <span class="mi">2</span>601<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>602<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">kw</span><span class="p">)</span>603<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="nf">squared</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>604<span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">number</span> <span class="o">**</span> <span class="mi">2</span>605</pre></div>606</div>607<p>This can be useful to support default values, methods and608initialization. Note that if you define an <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>609method, it will be called each time the <a class="reference internal" href="#threading.local" title="threading.local"><code class="xref py py-class docutils literal notranslate"><span class="pre">local</span></code></a> object is used610in a separate thread. This is necessary to initialize each thread’s611dictionary.</p>612<p>Now if we create a <a class="reference internal" href="#threading.local" title="threading.local"><code class="xref py py-class docutils literal notranslate"><span class="pre">local</span></code></a> object:</p>613<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span> <span class="o">=</span> <span class="n">MyLocal</span><span class="p">(</span><span class="n">color</span><span class="o">=</span><span class="s1">'red'</span><span class="p">)</span>614</pre></div>615</div>616<p>we have a default number:</p>617<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">number</span>618<span class="go">2</span>619</pre></div>620</div>621<p>an initial color:</p>622<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">color</span>623<span class="go">'red'</span>624<span class="gp">>>> </span><span class="k">del</span> <span class="n">mydata</span><span class="o">.</span><span class="n">color</span>625</pre></div>626</div>627<p>And a method that operates on the data:</p>628<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">squared</span><span class="p">()</span>629<span class="go">4</span>630</pre></div>631</div>632<p>As before, we can access the data in a separate thread:</p>633<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">log</span> <span class="o">=</span> <span class="p">[]</span>634<span class="gp">>>> </span><span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">)</span>635<span class="gp">>>> </span><span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>636<span class="gp">>>> </span><span class="n">thread</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>637<span class="gp">>>> </span><span class="n">log</span>638<span class="go">[[('color', 'red')], 11]</span>639</pre></div>640</div>641<p>without affecting this thread’s data:</p>642<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">number</span>643<span class="go">2</span>644<span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">color</span>645<span class="gt">Traceback (most recent call last):</span>646<span class="c">...</span>647<span class="gr">AttributeError</span>: <span class="n">'MyLocal' object has no attribute 'color'</span>648</pre></div>649</div>650<p>Note that subclasses can define <a class="reference internal" href="../glossary.html#term-__slots__"><span class="xref std std-term">__slots__</span></a>, but they are not651thread local. They are shared across threads:</p>652<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span><span class="w"> </span><span class="nc">MyLocal</span><span class="p">(</span><span class="n">local</span><span class="p">):</span>653<span class="gp">... </span> <span class="vm">__slots__</span> <span class="o">=</span> <span class="s1">'number'</span>654 655<span class="gp">>>> </span><span class="n">mydata</span> <span class="o">=</span> <span class="n">MyLocal</span><span class="p">()</span>656<span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">number</span> <span class="o">=</span> <span class="mi">42</span>657<span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">color</span> <span class="o">=</span> <span class="s1">'red'</span>658</pre></div>659</div>660<p>So, the separate thread:</p>661<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">)</span>662<span class="gp">>>> </span><span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>663<span class="gp">>>> </span><span class="n">thread</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>664</pre></div>665</div>666<p>affects what we see:</p>667<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mydata</span><span class="o">.</span><span class="n">number</span>668<span class="go">11</span>669</pre></div>670</div>671<dl class="py class">672<dt class="sig sig-object py" id="threading.local">673<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">local</span></span><a class="headerlink" href="#threading.local" title="Link to this definition">¶</a></dt>674<dd><p>A class that represents thread-local data.</p>675</dd></dl>676 677</section>678<section id="thread-objects">679<span id="id1"></span><h3>Thread objects<a class="headerlink" href="#thread-objects" title="Link to this heading">¶</a></h3>680<p>The <a class="reference internal" href="#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">Thread</span></code></a> class represents an activity that is run in a separate681thread of control. There are two ways to specify the activity: by passing a682callable object to the constructor, or by overriding the <a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a>683method in a subclass. No other methods (except for the constructor) should be684overridden in a subclass. In other words, <em>only</em> override the685<code class="docutils literal notranslate"><span class="pre">__init__()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code> methods of this class.</p>686<p>Once a thread object is created, its activity must be started by calling the687thread’s <a class="reference internal" href="#threading.Thread.start" title="threading.Thread.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a> method. This invokes the <a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a>688method in a separate thread of control.</p>689<p>Once the thread’s activity is started, the thread is considered ‘alive’. It690stops being alive when its <a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method terminates – either691normally, or by raising an unhandled exception. The <a class="reference internal" href="#threading.Thread.is_alive" title="threading.Thread.is_alive"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_alive()</span></code></a>692method tests whether the thread is alive.</p>693<p>Other threads can call a thread’s <a class="reference internal" href="#threading.Thread.join" title="threading.Thread.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> method. This blocks694the calling thread until the thread whose <code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code> method is695called is terminated.</p>696<p>A thread has a name. The name can be passed to the constructor, and read or697changed through the <a class="reference internal" href="#threading.Thread.name" title="threading.Thread.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> attribute.</p>698<p>If the <a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method raises an exception,699<a class="reference internal" href="#threading.excepthook" title="threading.excepthook"><code class="xref py py-func docutils literal notranslate"><span class="pre">threading.excepthook()</span></code></a> is called to handle it. By default,700<code class="xref py py-func docutils literal notranslate"><span class="pre">threading.excepthook()</span></code> ignores silently <a class="reference internal" href="exceptions.html#SystemExit" title="SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a>.</p>701<p>A thread can be flagged as a “daemon thread”. The significance of this flag is702that the entire Python program exits when only daemon threads are left. The703initial value is inherited from the creating thread. The flag can be set704through the <a class="reference internal" href="#threading.Thread.daemon" title="threading.Thread.daemon"><code class="xref py py-attr docutils literal notranslate"><span class="pre">daemon</span></code></a> property or the <em>daemon</em> constructor705argument.</p>706<div class="admonition note">707<p class="admonition-title">Note</p>708<p>Daemon threads are abruptly stopped at shutdown. Their resources (such709as open files, database transactions, etc.) may not be released properly.710If you want your threads to stop gracefully, make them non-daemonic and711use a suitable signalling mechanism such as an <a class="reference internal" href="#threading.Event" title="threading.Event"><code class="xref py py-class docutils literal notranslate"><span class="pre">Event</span></code></a>.</p>712</div>713<p>There is a “main thread” object; this corresponds to the initial thread of714control in the Python program. It is not a daemon thread.</p>715<p>There is the possibility that “dummy thread objects” are created. These are716thread objects corresponding to “alien threads”, which are threads of control717started outside the threading module, such as directly from C code. Dummy718thread objects have limited functionality; they are always considered alive and719daemonic, and cannot be <a class="reference internal" href="#meth-thread-join"><span class="std std-ref">joined</span></a>. They are never deleted,720since it is impossible to detect the termination of alien threads.</p>721<dl class="py class">722<dt class="sig sig-object py" id="threading.Thread">723<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">Thread</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">group</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">target</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">kwargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">{}</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">daemon</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">context</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.Thread" title="Link to this definition">¶</a></dt>724<dd><p>This constructor should always be called with keyword arguments. Arguments725are:</p>726<p><em>group</em> should be <code class="docutils literal notranslate"><span class="pre">None</span></code>; reserved for future extension when a727<code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadGroup</span></code> class is implemented.</p>728<p><em>target</em> is the callable object to be invoked by the <a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method.729Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>, meaning nothing is called.</p>730<p><em>name</em> is the thread name. By default, a unique name is constructed731of the form “Thread-<em>N</em>” where <em>N</em> is a small decimal number,732or “Thread-<em>N</em> (target)” where “target” is <code class="docutils literal notranslate"><span class="pre">target.__name__</span></code> if the733<em>target</em> argument is specified.</p>734<p><em>args</em> is a list or tuple of arguments for the target invocation. Defaults to <code class="docutils literal notranslate"><span class="pre">()</span></code>.</p>735<p><em>kwargs</em> is a dictionary of keyword arguments for the target invocation.736Defaults to <code class="docutils literal notranslate"><span class="pre">{}</span></code>.</p>737<p>If not <code class="docutils literal notranslate"><span class="pre">None</span></code>, <em>daemon</em> explicitly sets whether the thread is daemonic.738If <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), the daemonic property is inherited from the739current thread.</p>740<p><em>context</em> is the <a class="reference internal" href="contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> value to use when starting741the thread. The default value is <code class="docutils literal notranslate"><span class="pre">None</span></code> which indicates that the742<a class="reference internal" href="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">sys.flags.thread_inherit_context</span></code></a> flag controls the behaviour. If743the flag is true, threads will start with a copy of the context of the744caller of <a class="reference internal" href="#threading.Thread.start" title="threading.Thread.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a>. If false, they will start with an empty745context. To explicitly start with an empty context, pass a new instance of746<a class="reference internal" href="contextvars.html#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context()</span></code></a>. To explicitly start with a copy of the747current context, pass the value from <a class="reference internal" href="contextvars.html#contextvars.copy_context" title="contextvars.copy_context"><code class="xref py py-func docutils literal notranslate"><span class="pre">copy_context()</span></code></a>. The748flag defaults true on free-threaded builds and false otherwise.</p>749<p>If the subclass overrides the constructor, it must make sure to invoke the750base class constructor (<code class="docutils literal notranslate"><span class="pre">Thread.__init__()</span></code>) before doing anything else to751the thread.</p>752<div class="versionchanged">753<p><span class="versionmodified changed">Changed in version 3.3: </span>Added the <em>daemon</em> parameter.</p>754</div>755<div class="versionchanged">756<p><span class="versionmodified changed">Changed in version 3.10: </span>Use the <em>target</em> name if <em>name</em> argument is omitted.</p>757</div>758<div class="versionchanged">759<p><span class="versionmodified changed">Changed in version 3.14: </span>Added the <em>context</em> parameter.</p>760</div>761<dl class="py method">762<dt class="sig sig-object py" id="threading.Thread.start">763<span class="sig-name descname"><span class="pre">start</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Thread.start" title="Link to this definition">¶</a></dt>764<dd><p>Start the thread’s activity.</p>765<p>It must be called at most once per thread object. It arranges for the766object’s <a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method to be invoked in a separate thread767of control.</p>768<p>This method will raise a <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> if called more than once769on the same thread object.</p>770<p>If supported, set the operating system thread name to771<a class="reference internal" href="#threading.Thread.name" title="threading.Thread.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">threading.Thread.name</span></code></a>. The name can be truncated depending on the772operating system thread name limits.</p>773<div class="versionchanged">774<p><span class="versionmodified changed">Changed in version 3.14: </span>Set the operating system thread name.</p>775</div>776</dd></dl>777 778<dl class="py method">779<dt class="sig sig-object py" id="threading.Thread.run">780<span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Thread.run" title="Link to this definition">¶</a></dt>781<dd><p>Method representing the thread’s activity.</p>782<p>You may override this method in a subclass. The standard <code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code>783method invokes the callable object passed to the object’s constructor as784the <em>target</em> argument, if any, with positional and keyword arguments taken785from the <em>args</em> and <em>kwargs</em> arguments, respectively.</p>786<p>Using list or tuple as the <em>args</em> argument which passed to the <code class="xref py py-class docutils literal notranslate"><span class="pre">Thread</span></code>787could achieve the same effect.</p>788<p>Example:</p>789<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">threading</span><span class="w"> </span><span class="kn">import</span> <span class="n">Thread</span>790<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="nb">print</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>791<span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>792<span class="go">1</span>793<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="nb">print</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="p">,))</span>794<span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>795<span class="go">1</span>796</pre></div>797</div>798</dd></dl>799 800<dl class="py method" id="meth-thread-join">801<dt class="sig sig-object py" id="threading.Thread.join">802<span class="sig-name descname"><span class="pre">join</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.Thread.join" title="Link to this definition">¶</a></dt>803<dd><p>Wait until the thread terminates. This blocks the calling thread until804the thread whose <code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code> method is called terminates – either805normally or through an unhandled exception – or until the optional806timeout occurs.</p>807<p>When the <em>timeout</em> argument is present and not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it should be a808real number specifying a timeout for the operation in seconds809(or fractions thereof). As <code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code> always returns <code class="docutils literal notranslate"><span class="pre">None</span></code>,810you must call <a class="reference internal" href="#threading.Thread.is_alive" title="threading.Thread.is_alive"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_alive()</span></code></a> after <code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code> to811decide whether a timeout happened – if the thread is still alive, the812<code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code> call timed out.</p>813<p>When the <em>timeout</em> argument is not present or <code class="docutils literal notranslate"><span class="pre">None</span></code>, the operation will814block until the thread terminates.</p>815<p>A thread can be joined many times.</p>816<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code> raises a <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> if an attempt is made817to join the current thread as that would cause a deadlock. It is also818an error to <code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code> a thread before it has been started819and attempts to do so raise the same exception.</p>820<p>If an attempt is made to join a running daemonic thread in late stages821of <a class="reference internal" href="../glossary.html#term-interpreter-shutdown"><span class="xref std std-term">Python finalization</span></a> <code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code>822raises a <a class="reference internal" href="exceptions.html#PythonFinalizationError" title="PythonFinalizationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PythonFinalizationError</span></code></a>.</p>823<div class="versionchanged">824<p><span class="versionmodified changed">Changed in version 3.14: </span>May raise <a class="reference internal" href="exceptions.html#PythonFinalizationError" title="PythonFinalizationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PythonFinalizationError</span></code></a>.</p>825</div>826<div class="versionchanged">827<p><span class="versionmodified changed">Changed in version 3.15: </span>Accepts any real number as <em>timeout</em>, not only integer or float.</p>828</div>829</dd></dl>830 831<dl class="py attribute">832<dt class="sig sig-object py" id="threading.Thread.name">833<span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#threading.Thread.name" title="Link to this definition">¶</a></dt>834<dd><p>A string used for identification purposes only. It has no semantics.835Multiple threads may be given the same name. The initial name is set by836the constructor.</p>837<p>On some platforms, the thread name is set at the operating system level838when the thread starts, so that it is visible in task managers.839This name may be truncated to fit in a system-specific limit (for example,84015 bytes on Linux or 63 bytes on macOS).</p>841<p>Changes to <em>name</em> are only reflected at the OS level when the currently842running thread is renamed. (Setting the <em>name</em> attribute of a843different thread only updates the Python Thread object.)</p>844</dd></dl>845 846<dl class="py method">847<dt class="sig sig-object py" id="threading.Thread.getName">848<span class="sig-name descname"><span class="pre">getName</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Thread.getName" title="Link to this definition">¶</a></dt>849<dt class="sig sig-object py" id="threading.Thread.setName">850<span class="sig-name descname"><span class="pre">setName</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Thread.setName" title="Link to this definition">¶</a></dt>851<dd><p>Deprecated getter/setter API for <a class="reference internal" href="#threading.Thread.name" title="threading.Thread.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a>; use it directly as a852property instead.</p>853<div class="deprecated">854<p><span class="versionmodified deprecated">Deprecated since version 3.10.</span></p>855</div>856</dd></dl>857 858<dl class="py attribute">859<dt class="sig sig-object py" id="threading.Thread.ident">860<span class="sig-name descname"><span class="pre">ident</span></span><a class="headerlink" href="#threading.Thread.ident" title="Link to this definition">¶</a></dt>861<dd><p>The ‘thread identifier’ of this thread or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the thread has not862been started. This is a nonzero integer. See the <a class="reference internal" href="#threading.get_ident" title="threading.get_ident"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_ident()</span></code></a>863function. Thread identifiers may be recycled when a thread exits and864another thread is created. The identifier is available even after the865thread has exited.</p>866</dd></dl>867 868<dl class="py attribute">869<dt class="sig sig-object py" id="threading.Thread.native_id">870<span class="sig-name descname"><span class="pre">native_id</span></span><a class="headerlink" href="#threading.Thread.native_id" title="Link to this definition">¶</a></dt>871<dd><p>The Thread ID (<code class="docutils literal notranslate"><span class="pre">TID</span></code>) of this thread, as assigned by the OS (kernel).872This is a non-negative integer, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the thread has not873been started. See the <a class="reference internal" href="#threading.get_native_id" title="threading.get_native_id"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_native_id()</span></code></a> function.874This value may be used to uniquely identify this particular thread875system-wide (until the thread terminates, after which the value876may be recycled by the OS).</p>877<div class="admonition note">878<p class="admonition-title">Note</p>879<p>Similar to Process IDs, Thread IDs are only valid (guaranteed unique880system-wide) from the time the thread is created until the thread881has been terminated.</p>882</div>883<div class="availability docutils container">884<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD.</p>885</div>886<div class="versionadded">887<p><span class="versionmodified added">Added in version 3.8.</span></p>888</div>889</dd></dl>890 891<dl class="py method">892<dt class="sig sig-object py" id="threading.Thread.is_alive">893<span class="sig-name descname"><span class="pre">is_alive</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Thread.is_alive" title="Link to this definition">¶</a></dt>894<dd><p>Return whether the thread is alive.</p>895<p>This method returns <code class="docutils literal notranslate"><span class="pre">True</span></code> just before the <a class="reference internal" href="#threading.Thread.run" title="threading.Thread.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method896starts until just after the <code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code> method terminates. The897module function <a class="reference internal" href="#threading.enumerate" title="threading.enumerate"><code class="xref py py-func docutils literal notranslate"><span class="pre">enumerate()</span></code></a> returns a list of all alive threads.</p>898</dd></dl>899 900<dl class="py attribute">901<dt class="sig sig-object py" id="threading.Thread.daemon">902<span class="sig-name descname"><span class="pre">daemon</span></span><a class="headerlink" href="#threading.Thread.daemon" title="Link to this definition">¶</a></dt>903<dd><p>A boolean value indicating whether this thread is a daemon thread (<code class="docutils literal notranslate"><span class="pre">True</span></code>)904or not (<code class="docutils literal notranslate"><span class="pre">False</span></code>). This must be set before <a class="reference internal" href="#threading.Thread.start" title="threading.Thread.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a> is called,905otherwise <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> is raised. Its initial value is inherited906from the creating thread; the main thread is not a daemon thread and907therefore all threads created in the main thread default to908<code class="xref py py-attr docutils literal notranslate"><span class="pre">daemon</span></code> = <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>909<p>The entire Python program exits when no alive non-daemon threads are left.</p>910</dd></dl>911 912<dl class="py method">913<dt class="sig sig-object py" id="threading.Thread.isDaemon">914<span class="sig-name descname"><span class="pre">isDaemon</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Thread.isDaemon" title="Link to this definition">¶</a></dt>915<dt class="sig sig-object py" id="threading.Thread.setDaemon">916<span class="sig-name descname"><span class="pre">setDaemon</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Thread.setDaemon" title="Link to this definition">¶</a></dt>917<dd><p>Deprecated getter/setter API for <a class="reference internal" href="#threading.Thread.daemon" title="threading.Thread.daemon"><code class="xref py py-attr docutils literal notranslate"><span class="pre">daemon</span></code></a>; use it directly as a918property instead.</p>919<div class="deprecated">920<p><span class="versionmodified deprecated">Deprecated since version 3.10.</span></p>921</div>922</dd></dl>923 924</dd></dl>925 926</section>927<section id="lock-objects">928<span id="id2"></span><h3>Lock objects<a class="headerlink" href="#lock-objects" title="Link to this heading">¶</a></h3>929<p>A primitive lock is a synchronization primitive that is not owned by a930particular thread when locked. In Python, it is currently the lowest level931synchronization primitive available, implemented directly by the <a class="reference internal" href="_thread.html#module-_thread" title="_thread: Low-level threading API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">_thread</span></code></a>932extension module.</p>933<p>A primitive lock is in one of two states, “locked” or “unlocked”. It is created934in the unlocked state. It has two basic methods, <a class="reference internal" href="#threading.Lock.acquire" title="threading.Lock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a> and935<a class="reference internal" href="#threading.Lock.release" title="threading.Lock.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a>. When the state is unlocked, <code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code>936changes the state to locked and returns immediately. When the state is locked,937<code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code> blocks until a call to <code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code> in another938thread changes it to unlocked, then the <code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code> call resets it939to locked and returns. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code> method should only be940called in the locked state; it changes the state to unlocked and returns941immediately. If an attempt is made to release an unlocked lock, a942<a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> will be raised.</p>943<p>Locks also support the <a class="reference internal" href="#with-locks"><span class="std std-ref">context management protocol</span></a>.</p>944<p>When more than one thread is blocked in <a class="reference internal" href="#threading.Lock.acquire" title="threading.Lock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a> waiting for the945state to turn to unlocked, only one thread proceeds when a <a class="reference internal" href="#threading.Lock.release" title="threading.Lock.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a>946call resets the state to unlocked; which one of the waiting threads proceeds947is not defined, and may vary across implementations.</p>948<p>All methods are executed atomically.</p>949<dl class="py class">950<dt class="sig sig-object py" id="threading.Lock">951<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">Lock</span></span><a class="headerlink" href="#threading.Lock" title="Link to this definition">¶</a></dt>952<dd><p>The class implementing primitive lock objects. Once a thread has acquired a953lock, subsequent attempts to acquire it block, until it is released; any954thread may release it.</p>955<div class="versionchanged">956<p><span class="versionmodified changed">Changed in version 3.13: </span><code class="docutils literal notranslate"><span class="pre">Lock</span></code> is now a class. In earlier Pythons, <code class="docutils literal notranslate"><span class="pre">Lock</span></code> was a factory957function which returned an instance of the underlying private lock958type.</p>959</div>960<dl class="py method">961<dt class="sig sig-object py" id="threading.Lock.acquire">962<span class="sig-name descname"><span class="pre">acquire</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">blocking</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.Lock.acquire" title="Link to this definition">¶</a></dt>963<dd><p>Acquire a lock, blocking or non-blocking.</p>964<p>When invoked with the <em>blocking</em> argument set to <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default),965block until the lock is unlocked, then set it to locked and return <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>966<p>When invoked with the <em>blocking</em> argument set to <code class="docutils literal notranslate"><span class="pre">False</span></code>, do not block.967If a call with <em>blocking</em> set to <code class="docutils literal notranslate"><span class="pre">True</span></code> would block, return <code class="docutils literal notranslate"><span class="pre">False</span></code>968immediately; otherwise, set the lock to locked and return <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>969<p>When invoked with the <em>timeout</em> argument set to a positive970value, block for at most the number of seconds specified by <em>timeout</em>971and as long as the lock cannot be acquired. A <em>timeout</em> argument of <code class="docutils literal notranslate"><span class="pre">-1</span></code>972specifies an unbounded wait. It is forbidden to specify a <em>timeout</em>973when <em>blocking</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>974<p>The return value is <code class="docutils literal notranslate"><span class="pre">True</span></code> if the lock is acquired successfully,975<code class="docutils literal notranslate"><span class="pre">False</span></code> if not (for example if the <em>timeout</em> expired).</p>976<div class="versionchanged">977<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>timeout</em> parameter is new.</p>978</div>979<div class="versionchanged">980<p><span class="versionmodified changed">Changed in version 3.2: </span>Lock acquisition can now be interrupted by signals on POSIX if the981underlying threading implementation supports it.</p>982</div>983<div class="versionchanged">984<p><span class="versionmodified changed">Changed in version 3.14: </span>Lock acquisition can now be interrupted by signals on Windows.</p>985</div>986<div class="versionchanged">987<p><span class="versionmodified changed">Changed in version 3.15: </span>Accepts any real number as <em>timeout</em>, not only integer or float.</p>988</div>989</dd></dl>990 991<dl class="py method">992<dt class="sig sig-object py" id="threading.Lock.release">993<span class="sig-name descname"><span class="pre">release</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Lock.release" title="Link to this definition">¶</a></dt>994<dd><p>Release a lock. This can be called from any thread, not only the thread995which has acquired the lock.</p>996<p>When the lock is locked, reset it to unlocked, and return. If any other threads997are blocked waiting for the lock to become unlocked, allow exactly one of them998to proceed.</p>999<p>When invoked on an unlocked lock, a <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> is raised.</p>1000<p>There is no return value.</p>1001</dd></dl>1002 1003<dl class="py method">1004<dt class="sig sig-object py" id="threading.Lock.locked">1005<span class="sig-name descname"><span class="pre">locked</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Lock.locked" title="Link to this definition">¶</a></dt>1006<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the lock is acquired.</p>1007</dd></dl>1008 1009</dd></dl>1010 1011</section>1012<section id="rlock-objects">1013<span id="id3"></span><h3>RLock objects<a class="headerlink" href="#rlock-objects" title="Link to this heading">¶</a></h3>1014<p>A reentrant lock is a synchronization primitive that may be acquired multiple1015times by the same thread. Internally, it uses the concepts of “owning thread”1016and “recursion level” in addition to the locked/unlocked state used by primitive1017locks. In the locked state, some thread owns the lock; in the unlocked state,1018no thread owns it.</p>1019<p>Threads call a lock’s <a class="reference internal" href="#threading.RLock.acquire" title="threading.RLock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a> method to lock it,1020and its <a class="reference internal" href="#threading.Lock.release" title="threading.Lock.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a> method to unlock it.</p>1021<div class="admonition note">1022<p class="admonition-title">Note</p>1023<p>Reentrant locks support the <a class="reference internal" href="#with-locks"><span class="std std-ref">context management protocol</span></a>,1024so it is recommended to use <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> instead of manually calling1025<a class="reference internal" href="#threading.RLock.acquire" title="threading.RLock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a> and <a class="reference internal" href="#threading.RLock.release" title="threading.RLock.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a>1026to handle acquiring and releasing the lock for a block of code.</p>1027</div>1028<p>RLock’s <a class="reference internal" href="#threading.RLock.acquire" title="threading.RLock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a>/<a class="reference internal" href="#threading.RLock.release" title="threading.RLock.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a> call pairs may be nested,1029unlike Lock’s <a class="reference internal" href="#threading.Lock.acquire" title="threading.Lock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a>/<a class="reference internal" href="#threading.Lock.release" title="threading.Lock.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a>. Only the final1030<code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code> (the <code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code> of the outermost pair) resets1031the lock to an unlocked state and allows another thread blocked in1032<code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code> to proceed.</p>1033<p><a class="reference internal" href="#threading.RLock.acquire" title="threading.RLock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a>/<a class="reference internal" href="#threading.RLock.release" title="threading.RLock.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a> must be used in pairs: each acquire1034must have a release in the thread that has acquired the lock. Failing to1035call release as many times the lock has been acquired can lead to deadlock.</p>1036<dl class="py class">1037<dt class="sig sig-object py" id="threading.RLock">1038<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">RLock</span></span><a class="headerlink" href="#threading.RLock" title="Link to this definition">¶</a></dt>1039<dd><p>This class implements reentrant lock objects. A reentrant lock must be1040released by the thread that acquired it. Once a thread has acquired a1041reentrant lock, the same thread may acquire it again without blocking; the1042thread must release it once for each time it has acquired it.</p>1043<p>Note that <code class="docutils literal notranslate"><span class="pre">RLock</span></code> is actually a factory function which returns an instance1044of the most efficient version of the concrete RLock class that is supported1045by the platform.</p>1046<dl class="py method">1047<dt class="sig sig-object py" id="threading.RLock.acquire">1048<span class="sig-name descname"><span class="pre">acquire</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">blocking</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.RLock.acquire" title="Link to this definition">¶</a></dt>1049<dd><p>Acquire a lock, blocking or non-blocking.</p>1050<div class="admonition seealso">1051<p class="admonition-title">See also</p>1052<dl class="simple">1053<dt><a class="reference internal" href="#with-locks"><span class="std std-ref">Using RLock as a context manager</span></a></dt><dd><p>Recommended over manual <code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code> and <a class="reference internal" href="#threading.RLock.release" title="threading.RLock.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a> calls1054whenever practical.</p>1055</dd>1056</dl>1057</div>1058<p>When invoked with the <em>blocking</em> argument set to <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default):</p>1059<blockquote>1060<div><ul class="simple">1061<li><p>If no thread owns the lock, acquire the lock and return immediately.</p></li>1062<li><p>If another thread owns the lock, block until we are able to acquire1063lock, or <em>timeout</em>, if set to a positive value.</p></li>1064<li><p>If the same thread owns the lock, acquire the lock again, and1065return immediately. This is the difference between <a class="reference internal" href="#threading.Lock" title="threading.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Lock</span></code></a> and1066<code class="xref py py-class docutils literal notranslate"><span class="pre">RLock</span></code>; <code class="xref py py-class docutils literal notranslate"><span class="pre">Lock</span></code> handles this case the same as the previous,1067blocking until the lock can be acquired.</p></li>1068</ul>1069</div></blockquote>1070<p>When invoked with the <em>blocking</em> argument set to <code class="docutils literal notranslate"><span class="pre">False</span></code>:</p>1071<blockquote>1072<div><ul class="simple">1073<li><p>If no thread owns the lock, acquire the lock and return immediately.</p></li>1074<li><p>If another thread owns the lock, return immediately.</p></li>1075<li><p>If the same thread owns the lock, acquire the lock again and return1076immediately.</p></li>1077</ul>1078</div></blockquote>1079<p>In all cases, if the thread was able to acquire the lock, return <code class="docutils literal notranslate"><span class="pre">True</span></code>.1080If the thread was unable to acquire the lock (i.e. if not blocking or1081the timeout was reached) return <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>1082<p>If called multiple times, failing to call <a class="reference internal" href="#threading.RLock.release" title="threading.RLock.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a> as many times1083may lead to deadlock. Consider using <code class="xref py py-class docutils literal notranslate"><span class="pre">RLock</span></code> as a context manager rather than1084calling acquire/release directly.</p>1085<div class="versionchanged">1086<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>timeout</em> parameter is new.</p>1087</div>1088<div class="versionchanged">1089<p><span class="versionmodified changed">Changed in version 3.15: </span>Accepts any real number as <em>timeout</em>, not only integer or float.</p>1090</div>1091</dd></dl>1092 1093<dl class="py method">1094<dt class="sig sig-object py" id="threading.RLock.release">1095<span class="sig-name descname"><span class="pre">release</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.RLock.release" title="Link to this definition">¶</a></dt>1096<dd><p>Release a lock, decrementing the recursion level. If after the decrement it is1097zero, reset the lock to unlocked (not owned by any thread), and if any other1098threads are blocked waiting for the lock to become unlocked, allow exactly one1099of them to proceed. If after the decrement the recursion level is still1100nonzero, the lock remains locked and owned by the calling thread.</p>1101<p>Only call this method when the calling thread owns the lock. A1102<a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> is raised if this method is called when the lock is1103not acquired.</p>1104<p>There is no return value.</p>1105</dd></dl>1106 1107<dl class="py method">1108<dt class="sig sig-object py" id="threading.RLock.locked">1109<span class="sig-name descname"><span class="pre">locked</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.RLock.locked" title="Link to this definition">¶</a></dt>1110<dd><p>Return a boolean indicating whether this object is locked right now.</p>1111<div class="versionadded">1112<p><span class="versionmodified added">Added in version 3.14.</span></p>1113</div>1114</dd></dl>1115 1116</dd></dl>1117 1118</section>1119<section id="condition-objects">1120<span id="id4"></span><h3>Condition objects<a class="headerlink" href="#condition-objects" title="Link to this heading">¶</a></h3>1121<p>A condition variable is always associated with some kind of lock; this can be1122passed in or one will be created by default. Passing one in is useful when1123several condition variables must share the same lock. The lock is part of1124the condition object: you don’t have to track it separately.</p>1125<p>A condition variable obeys the <a class="reference internal" href="#with-locks"><span class="std std-ref">context management protocol</span></a>:1126using the <code class="docutils literal notranslate"><span class="pre">with</span></code> statement acquires the associated lock for the duration of1127the enclosed block. The <a class="reference internal" href="#threading.Condition.acquire" title="threading.Condition.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a> and1128<a class="reference internal" href="#threading.Condition.release" title="threading.Condition.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a> methods also call the corresponding methods of1129the associated lock.</p>1130<p>Other methods must be called with the associated lock held. The1131<a class="reference internal" href="#threading.Condition.wait" title="threading.Condition.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a> method releases the lock, and then blocks until1132another thread awakens it by calling <a class="reference internal" href="#threading.Condition.notify" title="threading.Condition.notify"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify()</span></code></a> or1133<a class="reference internal" href="#threading.Condition.notify_all" title="threading.Condition.notify_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify_all()</span></code></a>. Once awakened, <code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code>1134re-acquires the lock and returns. It is also possible to specify a timeout.</p>1135<p>The <a class="reference internal" href="#threading.Condition.notify" title="threading.Condition.notify"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify()</span></code></a> method wakes up one of the threads waiting for1136the condition variable, if any are waiting. The <a class="reference internal" href="#threading.Condition.notify_all" title="threading.Condition.notify_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify_all()</span></code></a>1137method wakes up all threads waiting for the condition variable.</p>1138<p>Note: the <a class="reference internal" href="#threading.Condition.notify" title="threading.Condition.notify"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify()</span></code></a> and <a class="reference internal" href="#threading.Condition.notify_all" title="threading.Condition.notify_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify_all()</span></code></a> methods1139don’t release the lock; this means that the thread or threads awakened will1140not return from their <a class="reference internal" href="#threading.Condition.wait" title="threading.Condition.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a> call immediately, but only when1141the thread that called <code class="xref py py-meth docutils literal notranslate"><span class="pre">notify()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">notify_all()</span></code>1142finally relinquishes ownership of the lock.</p>1143<p>The typical programming style using condition variables uses the lock to1144synchronize access to some shared state; threads that are interested in a1145particular change of state call <a class="reference internal" href="#threading.Condition.wait" title="threading.Condition.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a> repeatedly until they1146see the desired state, while threads that modify the state call1147<a class="reference internal" href="#threading.Condition.notify" title="threading.Condition.notify"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify()</span></code></a> or <a class="reference internal" href="#threading.Condition.notify_all" title="threading.Condition.notify_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify_all()</span></code></a> when they change1148the state in such a way that it could possibly be a desired state for one1149of the waiters. For example, the following code is a generic1150producer-consumer situation with unlimited buffer capacity:</p>1151<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Consume one item</span>1152<span class="k">with</span> <span class="n">cv</span><span class="p">:</span>1153 <span class="k">while</span> <span class="ow">not</span> <span class="n">an_item_is_available</span><span class="p">():</span>1154 <span class="n">cv</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>1155 <span class="n">get_an_available_item</span><span class="p">()</span>1156 1157<span class="c1"># Produce one item</span>1158<span class="k">with</span> <span class="n">cv</span><span class="p">:</span>1159 <span class="n">make_an_item_available</span><span class="p">()</span>1160 <span class="n">cv</span><span class="o">.</span><span class="n">notify</span><span class="p">()</span>1161</pre></div>1162</div>1163<p>The <code class="docutils literal notranslate"><span class="pre">while</span></code> loop checking for the application’s condition is necessary1164because <a class="reference internal" href="#threading.Condition.wait" title="threading.Condition.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a> can return after an arbitrary long time,1165and the condition which prompted the <a class="reference internal" href="#threading.Condition.notify" title="threading.Condition.notify"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify()</span></code></a> call may1166no longer hold true. This is inherent to multi-threaded programming. The1167<a class="reference internal" href="#threading.Condition.wait_for" title="threading.Condition.wait_for"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait_for()</span></code></a> method can be used to automate the condition1168checking, and eases the computation of timeouts:</p>1169<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Consume an item</span>1170<span class="k">with</span> <span class="n">cv</span><span class="p">:</span>1171 <span class="n">cv</span><span class="o">.</span><span class="n">wait_for</span><span class="p">(</span><span class="n">an_item_is_available</span><span class="p">)</span>1172 <span class="n">get_an_available_item</span><span class="p">()</span>1173</pre></div>1174</div>1175<p>To choose between <a class="reference internal" href="#threading.Condition.notify" title="threading.Condition.notify"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify()</span></code></a> and <a class="reference internal" href="#threading.Condition.notify_all" title="threading.Condition.notify_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify_all()</span></code></a>,1176consider whether one state change can be interesting for only one or several1177waiting threads. E.g. in a typical producer-consumer situation, adding one1178item to the buffer only needs to wake up one consumer thread.</p>1179<dl class="py class">1180<dt class="sig sig-object py" id="threading.Condition">1181<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">threading.</span></span><span class="sig-name descname"><span class="pre">Condition</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lock</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.Condition" title="Link to this definition">¶</a></dt>1182<dd><p>This class implements condition variable objects. A condition variable1183allows one or more threads to wait until they are notified by another thread.</p>1184<p>If the <em>lock</em> argument is given and not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it must be a <a class="reference internal" href="#threading.Lock" title="threading.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Lock</span></code></a>1185or <a class="reference internal" href="#threading.RLock" title="threading.RLock"><code class="xref py py-class docutils literal notranslate"><span class="pre">RLock</span></code></a> object, and it is used as the underlying lock. Otherwise,1186a new <code class="xref py py-class docutils literal notranslate"><span class="pre">RLock</span></code> object is created and used as the underlying lock.</p>1187<div class="versionchanged">1188<p><span class="versionmodified changed">Changed in version 3.3: </span>changed from a factory function to a class.</p>1189</div>1190<dl class="py method">1191<dt class="sig sig-object py" id="threading.Condition.acquire">1192<span class="sig-name descname"><span class="pre">acquire</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#threading.Condition.acquire" title="Link to this definition">¶</a></dt>1193<dd><p>Acquire the underlying lock. This method calls the corresponding method on1194the underlying lock; the return value is whatever that method returns.</p>1195</dd></dl>1196 1197<dl class="py method">1198<dt class="sig sig-object py" id="threading.Condition.release">1199<span class="sig-name descname"><span class="pre">release</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#threading.Condition.release" title="Link to this definition">¶</a></dt>1200<dd><p>Release the underlying lock. This method calls the corresponding method on