Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
multiprocessing.html3992 linesDownload Raw Back to docs
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="multiprocessing — Process-based parallelism" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/multiprocessing.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/multiprocessing/ Availability: not Android, not iOS, not WASI. This module is not supported on mobile platforms or WebAssembly platforms. Introduction: multiprocessing is a package..." />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_multiprocessing_5090001b.png" />15<meta property="og:image:alt" content="Source code: Lib/multiprocessing/ Availability: not Android, not iOS, not WASI. This module is not supported on mobile platforms or WebAssembly platforms. Introduction: multiprocessing is a package..." />16<meta name="description" content="Source code: Lib/multiprocessing/ Availability: not Android, not iOS, not WASI. This module is not supported on mobile platforms or WebAssembly platforms. Introduction: multiprocessing is a package..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>multiprocessing — Process-based parallelism &#8212; 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.shared_memory — Shared memory for direct access across processes" href="multiprocessing.shared_memory.html" />43    <link rel="prev" title="threading — Thread-based parallelism" href="threading.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/multiprocessing.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">multiprocessing</span></code> — Process-based parallelism</a><ul>108<li><a class="reference internal" href="#introduction">Introduction</a><ul>109<li><a class="reference internal" href="#the-process-class">The <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code> class</a></li>110<li><a class="reference internal" href="#contexts-and-start-methods">Contexts and start methods</a></li>111<li><a class="reference internal" href="#exchanging-objects-between-processes">Exchanging objects between processes</a></li>112<li><a class="reference internal" href="#synchronization-between-processes">Synchronization between processes</a></li>113<li><a class="reference internal" href="#sharing-state-between-processes">Sharing state between processes</a></li>114<li><a class="reference internal" href="#using-a-pool-of-workers">Using a pool of workers</a></li>115</ul>116</li>117<li><a class="reference internal" href="#reference">Reference</a><ul>118<li><a class="reference internal" href="#global-start-method">Global start method</a></li>119<li><a class="reference internal" href="#process-and-exceptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code> and exceptions</a></li>120<li><a class="reference internal" href="#pipes-and-queues">Pipes and Queues</a></li>121<li><a class="reference internal" href="#miscellaneous">Miscellaneous</a></li>122<li><a class="reference internal" href="#connection-objects">Connection Objects</a></li>123<li><a class="reference internal" href="#synchronization-primitives">Synchronization primitives</a></li>124<li><a class="reference internal" href="#shared-ctypes-objects">Shared <code class="xref py py-mod docutils literal notranslate"><span class="pre">ctypes</span></code> Objects</a><ul>125<li><a class="reference internal" href="#module-multiprocessing.sharedctypes">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing.sharedctypes</span></code> module</a></li>126</ul>127</li>128<li><a class="reference internal" href="#managers">Managers</a><ul>129<li><a class="reference internal" href="#customized-managers">Customized managers</a></li>130<li><a class="reference internal" href="#using-a-remote-manager">Using a remote manager</a></li>131</ul>132</li>133<li><a class="reference internal" href="#proxy-objects">Proxy Objects</a><ul>134<li><a class="reference internal" href="#cleanup">Cleanup</a></li>135</ul>136</li>137<li><a class="reference internal" href="#module-multiprocessing.pool">Process Pools</a></li>138<li><a class="reference internal" href="#module-multiprocessing.connection">Listeners and Clients</a><ul>139<li><a class="reference internal" href="#address-formats">Address Formats</a></li>140</ul>141</li>142<li><a class="reference internal" href="#authentication-keys">Authentication keys</a></li>143<li><a class="reference internal" href="#logging">Logging</a></li>144<li><a class="reference internal" href="#module-multiprocessing.dummy">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing.dummy</span></code> module</a></li>145</ul>146</li>147<li><a class="reference internal" href="#programming-guidelines">Programming guidelines</a><ul>148<li><a class="reference internal" href="#all-start-methods">All start methods</a></li>149<li><a class="reference internal" href="#the-spawn-and-forkserver-start-methods">The <em>spawn</em> and <em>forkserver</em> start methods</a></li>150</ul>151</li>152<li><a class="reference internal" href="#examples">Examples</a></li>153</ul>154</li>155</ul>156 157  </div>158  <div>159    <h4>Previous topic</h4>160    <p class="topless"><a href="threading.html"161                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code> — Thread-based parallelism</a></p>162  </div>163  <div>164    <h4>Next topic</h4>165    <p class="topless"><a href="multiprocessing.shared_memory.html"166                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing.shared_memory</span></code> — Shared memory for direct access across processes</a></p>167  </div>168  <script>169    document.addEventListener('DOMContentLoaded', () => {170        const title = document.querySelector('meta[property="og:title"]').content;171        const elements = document.querySelectorAll('.improvepage');172        const pageurl = window.location.href.split('?')[0];173        elements.forEach(element => {174            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));175            url.searchParams.set('pagetitle', title);176            url.searchParams.set('pageurl', pageurl);177            url.searchParams.set('pagesource', "library/multiprocessing.rst");178            element.href = url.toString();179        });180    });181  </script>182  <div role="note" aria-label="source link">183    <h3>This page</h3>184    <ul class="this-page-menu">185      <li><a href="../bugs.html">Report a bug</a></li>186      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>187      <li>188        <a href="https://github.com/python/cpython/blob/main/Doc/library/multiprocessing.rst?plain=1"189            rel="nofollow">Show source190        </a>191      </li>192      193    </ul>194  </div>195        </nav>196    </div>197</div>198 199  200    <div class="related" role="navigation" aria-label="Related">201      <h3>Navigation</h3>202      <ul>203        <li class="right" style="margin-right: 10px">204          <a href="../genindex.html" title="General Index"205             accesskey="I">index</a></li>206        <li class="right" >207          <a href="../py-modindex.html" title="Python Module Index"208             >modules</a> |</li>209        <li class="right" >210          <a href="multiprocessing.shared_memory.html" title="multiprocessing.shared_memory — Shared memory for direct access across processes"211             accesskey="N">next</a> |</li>212        <li class="right" >213          <a href="threading.html" title="threading — Thread-based parallelism"214             accesskey="P">previous</a> |</li>215 216          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>217          <li><a href="https://www.python.org/">Python</a> &#187;</li>218          <li class="switchers">219            <div class="language_switcher_placeholder"></div>220            <div class="version_switcher_placeholder"></div>221          </li>222          <li>223              224          </li>225    <li id="cpython-language-and-version">226      <a href="../index.html">3.15.0a6 Documentation</a> &#187;227    </li>228 229          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>230          <li class="nav-item nav-item-2"><a href="concurrency.html" accesskey="U">Concurrent Execution</a> &#187;</li>231        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> — Process-based parallelism</a></li>232                <li class="right">233                    234 235    <div class="inline-search" role="search">236        <form class="inline-search" action="../search.html" method="get">237          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">238          <input type="submit" value="Go">239        </form>240    </div>241                     |242                </li>243            <li class="right">244<label class="theme-selector-label">245    Theme246    <select class="theme-selector" oninput="activateTheme(this.value)">247        <option value="auto" selected>Auto</option>248        <option value="light">Light</option>249        <option value="dark">Dark</option>250    </select>251</label> |</li>252            253      </ul>254    </div>    255 256    <div class="document">257      <div class="documentwrapper">258        <div class="bodywrapper">259          <div class="body" role="main">260            261  <section id="module-multiprocessing">262<span id="multiprocessing-process-based-parallelism"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> — Process-based parallelism<a class="headerlink" href="#module-multiprocessing" title="Link to this heading">¶</a></h1>263<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/multiprocessing/">Lib/multiprocessing/</a></p>264<hr class="docutils" />265<div class="availability docutils container">266<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: not Android, not iOS, not WASI.</p>267<p>This module is not supported on <a class="reference internal" href="intro.html#mobile-availability"><span class="std std-ref">mobile platforms</span></a>268or <a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a>.</p>269</div>270<section id="introduction">271<h2>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>272<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> is a package that supports spawning processes using an273API similar to the <a class="reference internal" href="threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module.  The <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> package274offers both local and remote concurrency, effectively side-stepping the275<a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">Global Interpreter Lock</span></a> by using276subprocesses instead of threads.  Due277to this, the <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> module allows the programmer to fully278leverage multiple processors on a given machine.  It runs on both POSIX and279Windows.</p>280<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> module also introduces the281<a class="reference internal" href="#multiprocessing.pool.Pool" title="multiprocessing.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a> object which offers a convenient means of282parallelizing the execution of a function across multiple input values,283distributing the input data across processes (data parallelism).  The following284example demonstrates the common practice of defining such functions in a module285so that child processes can successfully import that module.  This basic example286of data parallelism using <code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code>,</p>287<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Pool</span>288 289<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>290    <span class="k">return</span> <span class="n">x</span><span class="o">*</span><span class="n">x</span>291 292<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>293    <span class="k">with</span> <span class="n">Pool</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span> <span class="k">as</span> <span class="n">p</span><span class="p">:</span>294        <span class="nb">print</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">map</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]))</span>295</pre></div>296</div>297<p>will print to standard output</p>298<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">9</span><span class="p">]</span>299</pre></div>300</div>301<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> module also introduces APIs which do not have302analogs in the <a class="reference internal" href="threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module, like the ability to <a class="reference internal" href="#multiprocessing.Process.terminate" title="multiprocessing.Process.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate</span></code></a>, <a class="reference internal" href="#multiprocessing.Process.interrupt" title="multiprocessing.Process.interrupt"><code class="xref py py-meth docutils literal notranslate"><span class="pre">interrupt</span></code></a> or <a class="reference internal" href="#multiprocessing.Process.kill" title="multiprocessing.Process.kill"><code class="xref py py-meth docutils literal notranslate"><span class="pre">kill</span></code></a> a running process.</p>303<div class="admonition seealso">304<p class="admonition-title">See also</p>305<p><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> offers a higher level interface306to push tasks to a background process without blocking execution of the307calling process. Compared to using the <a class="reference internal" href="#multiprocessing.pool.Pool" title="multiprocessing.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a>308interface directly, the <a class="reference internal" href="concurrent.futures.html#module-concurrent.futures" title="concurrent.futures: Execute computations concurrently using threads or processes."><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code></a> API more readily allows309the submission of work to the underlying process pool to be separated from310waiting for the results.</p>311</div>312<section id="the-process-class">313<h3>The <a class="reference internal" href="#multiprocessing.Process" title="multiprocessing.Process"><code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code></a> class<a class="headerlink" href="#the-process-class" title="Link to this heading">¶</a></h3>314<p>In <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code>, processes are spawned by creating a <a class="reference internal" href="#multiprocessing.Process" title="multiprocessing.Process"><code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code></a>315object and then calling its <a class="reference internal" href="#multiprocessing.Process.start" title="multiprocessing.Process.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a> method.  <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code>316follows the API of <a class="reference internal" href="threading.html#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Thread</span></code></a>.  A trivial example of a317multiprocess program is</p>318<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Process</span>319 320<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>321    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>322 323<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>324    <span class="n">p</span> <span class="o">=</span> <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;bob&#39;</span><span class="p">,))</span>325    <span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>326    <span class="n">p</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>327</pre></div>328</div>329<p>To show the individual process IDs involved, here is an expanded example:</p>330<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Process</span>331<span class="kn">import</span><span class="w"> </span><span class="nn">os</span>332 333<span class="k">def</span><span class="w"> </span><span class="nf">info</span><span class="p">(</span><span class="n">title</span><span class="p">):</span>334    <span class="nb">print</span><span class="p">(</span><span class="n">title</span><span class="p">)</span>335    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;module name:&#39;</span><span class="p">,</span> <span class="vm">__name__</span><span class="p">)</span>336    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;parent process:&#39;</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">getppid</span><span class="p">())</span>337    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;process id:&#39;</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">getpid</span><span class="p">())</span>338 339<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>340    <span class="n">info</span><span class="p">(</span><span class="s1">&#39;function f&#39;</span><span class="p">)</span>341    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>342 343<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>344    <span class="n">info</span><span class="p">(</span><span class="s1">&#39;main line&#39;</span><span class="p">)</span>345    <span class="n">p</span> <span class="o">=</span> <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;bob&#39;</span><span class="p">,))</span>346    <span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>347    <span class="n">p</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>348</pre></div>349</div>350<p>For an explanation of why the <code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">__name__</span> <span class="pre">==</span> <span class="pre">'__main__'</span></code> part is351necessary, see <a class="reference internal" href="#multiprocessing-programming"><span class="std std-ref">Programming guidelines</span></a>.</p>352<p>The arguments to <a class="reference internal" href="#multiprocessing.Process" title="multiprocessing.Process"><code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code></a> usually need to be unpickleable from within353the child process. If you tried typing the above example directly into a REPL it354could lead to an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> in the child process trying to locate the355<em>f</em> function in the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module.</p>356</section>357<section id="contexts-and-start-methods">358<span id="multiprocessing-start-methods"></span><h3>Contexts and start methods<a class="headerlink" href="#contexts-and-start-methods" title="Link to this heading">¶</a></h3>359<p>Depending on the platform, <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> supports three ways360to start a process.  These <em>start methods</em> are</p>361<blockquote>362<div><dl id="multiprocessing-start-method-spawn">363<dt><em>spawn</em></dt><dd><p>The parent process starts a fresh Python interpreter process.  The364child process will only inherit those resources necessary to run365the process object’s <a class="reference internal" href="#multiprocessing.Process.run" title="multiprocessing.Process.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method.  In particular,366unnecessary file descriptors and handles from the parent process367will not be inherited.  Starting a process using this method is368rather slow compared to using <em>fork</em> or <em>forkserver</em>.</p>369<p>Available on POSIX and Windows platforms.  The default on Windows and macOS.</p>370</dd>371</dl>372<dl id="multiprocessing-start-method-fork">373<dt><em>fork</em></dt><dd><p>The parent process uses <a class="reference internal" href="os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fork()</span></code></a> to fork the Python374interpreter.  The child process, when it begins, is effectively375identical to the parent process.  All resources of the parent are376inherited by the child process.  Note that safely forking a377multithreaded process is problematic.</p>378<p>Available on POSIX systems.</p>379<div class="versionchanged">380<p><span class="versionmodified changed">Changed in version 3.14: </span>This is no longer the default start method on any platform.381Code that requires <em>fork</em> must explicitly specify that via382<a class="reference internal" href="#multiprocessing.get_context" title="multiprocessing.get_context"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_context()</span></code></a> or <a class="reference internal" href="#multiprocessing.set_start_method" title="multiprocessing.set_start_method"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_start_method()</span></code></a>.</p>383</div>384<div class="versionchanged">385<p><span class="versionmodified changed">Changed in version 3.12: </span>If Python is able to detect that your process has multiple threads, the386<a class="reference internal" href="os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fork()</span></code></a> function that this start method calls internally will387raise a <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a>. Use a different start method.388See the <code class="xref py py-func docutils literal notranslate"><span class="pre">os.fork()</span></code> documentation for further explanation.</p>389</div>390</dd>391</dl>392<dl id="multiprocessing-start-method-forkserver">393<dt><em>forkserver</em></dt><dd><p>When the program starts and selects the <em>forkserver</em> start method,394a server process is spawned.  From then on, whenever a new process395is needed, the parent process connects to the server and requests396that it fork a new process.  The fork server process is single threaded397unless system libraries or preloaded imports spawn threads as a398side-effect so it is generally safe for it to use <a class="reference internal" href="os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fork()</span></code></a>.399No unnecessary resources are inherited.</p>400<p>Available on POSIX platforms which support passing file descriptors over401Unix pipes such as Linux.  The default on those.</p>402<div class="versionchanged">403<p><span class="versionmodified changed">Changed in version 3.14: </span>This became the default start method on POSIX platforms.</p>404</div>405</dd>406</dl>407</div></blockquote>408<div class="versionchanged">409<p><span class="versionmodified changed">Changed in version 3.4: </span><em>spawn</em> added on all POSIX platforms, and <em>forkserver</em> added for410some POSIX platforms.411Child processes no longer inherit all of the parents inheritable412handles on Windows.</p>413</div>414<div class="versionchanged">415<p><span class="versionmodified changed">Changed in version 3.8: </span>On macOS, the <em>spawn</em> start method is now the default.  The <em>fork</em> start416method should be considered unsafe as it can lead to crashes of the417subprocess as macOS system libraries may start threads. See <a class="reference external" href="https://bugs.python.org/issue?&#64;action=redirect&amp;bpo=33725">bpo-33725</a>.</p>418</div>419<div class="versionchanged">420<p><span class="versionmodified changed">Changed in version 3.14: </span>On POSIX platforms the default start method was changed from <em>fork</em> to421<em>forkserver</em> to retain the performance but avoid common multithreaded422process incompatibilities. See <a class="reference external" href="https://github.com/python/cpython/issues/84559">gh-84559</a>.</p>423</div>424<p>On POSIX using the <em>spawn</em> or <em>forkserver</em> start methods will also425start a <em>resource tracker</em> process which tracks the unlinked named426system resources (such as named semaphores or427<a class="reference internal" href="multiprocessing.shared_memory.html#multiprocessing.shared_memory.SharedMemory" title="multiprocessing.shared_memory.SharedMemory"><code class="xref py py-class docutils literal notranslate"><span class="pre">SharedMemory</span></code></a> objects) created428by processes of the program.  When all processes429have exited the resource tracker unlinks any remaining tracked object.430Usually there should be none, but if a process was killed by a signal431there may be some “leaked” resources.  (Neither leaked semaphores nor shared432memory segments will be automatically unlinked until the next reboot. This is433problematic for both objects because the system allows only a limited number of434named semaphores, and shared memory segments occupy some space in the main435memory.)</p>436<p>To select a start method you use the <a class="reference internal" href="#multiprocessing.set_start_method" title="multiprocessing.set_start_method"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_start_method()</span></code></a> in437the <code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">__name__</span> <span class="pre">==</span> <span class="pre">'__main__'</span></code> clause of the main module.  For438example:</p>439<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">mp</span>440 441<span class="k">def</span><span class="w"> </span><span class="nf">foo</span><span class="p">(</span><span class="n">q</span><span class="p">):</span>442    <span class="n">q</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">)</span>443 444<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>445    <span class="n">mp</span><span class="o">.</span><span class="n">set_start_method</span><span class="p">(</span><span class="s1">&#39;spawn&#39;</span><span class="p">)</span>446    <span class="n">q</span> <span class="o">=</span> <span class="n">mp</span><span class="o">.</span><span class="n">Queue</span><span class="p">()</span>447    <span class="n">p</span> <span class="o">=</span> <span class="n">mp</span><span class="o">.</span><span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">foo</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">q</span><span class="p">,))</span>448    <span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>449    <span class="nb">print</span><span class="p">(</span><span class="n">q</span><span class="o">.</span><span class="n">get</span><span class="p">())</span>450    <span class="n">p</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>451</pre></div>452</div>453<p><a class="reference internal" href="#multiprocessing.set_start_method" title="multiprocessing.set_start_method"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_start_method()</span></code></a> should not be used more than once in the454program.</p>455<p>Alternatively, you can use <a class="reference internal" href="#multiprocessing.get_context" title="multiprocessing.get_context"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_context()</span></code></a> to obtain a context456object.  Context objects have the same API as the multiprocessing457module, and allow one to use multiple start methods in the same458program.</p>459<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">mp</span>460 461<span class="k">def</span><span class="w"> </span><span class="nf">foo</span><span class="p">(</span><span class="n">q</span><span class="p">):</span>462    <span class="n">q</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">)</span>463 464<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>465    <span class="n">ctx</span> <span class="o">=</span> <span class="n">mp</span><span class="o">.</span><span class="n">get_context</span><span class="p">(</span><span class="s1">&#39;spawn&#39;</span><span class="p">)</span>466    <span class="n">q</span> <span class="o">=</span> <span class="n">ctx</span><span class="o">.</span><span class="n">Queue</span><span class="p">()</span>467    <span class="n">p</span> <span class="o">=</span> <span class="n">ctx</span><span class="o">.</span><span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">foo</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">q</span><span class="p">,))</span>468    <span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>469    <span class="nb">print</span><span class="p">(</span><span class="n">q</span><span class="o">.</span><span class="n">get</span><span class="p">())</span>470    <span class="n">p</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>471</pre></div>472</div>473<p>Note that objects related to one context may not be compatible with474processes for a different context.  In particular, locks created using475the <em>fork</em> context cannot be passed to processes started using the476<em>spawn</em> or <em>forkserver</em> start methods.</p>477<p>Libraries using <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> or478<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">ProcessPoolExecutor</span></code></a> should be designed to allow479their users to provide their own multiprocessing context.  Using a specific480context of your own within a library can lead to incompatibilities with the481rest of the library user’s application.  Always document if your library482requires a specific start method.</p>483<div class="admonition warning">484<p class="admonition-title">Warning</p>485<p>The <code class="docutils literal notranslate"><span class="pre">'spawn'</span></code> and <code class="docutils literal notranslate"><span class="pre">'forkserver'</span></code> start methods generally cannot486be used with “frozen” executables (i.e., binaries produced by487packages like <strong>PyInstaller</strong> and <strong>cx_Freeze</strong>) on POSIX systems.488The <code class="docutils literal notranslate"><span class="pre">'fork'</span></code> start method may work if code does not use threads.</p>489</div>490</section>491<section id="exchanging-objects-between-processes">492<h3>Exchanging objects between processes<a class="headerlink" href="#exchanging-objects-between-processes" title="Link to this heading">¶</a></h3>493<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> supports two types of communication channel between494processes:</p>495<p><strong>Queues</strong></p>496<blockquote>497<div><p>The <a class="reference internal" href="#multiprocessing.Queue" title="multiprocessing.Queue"><code class="xref py py-class docutils literal notranslate"><span class="pre">Queue</span></code></a> class is a near clone of <a class="reference internal" href="queue.html#queue.Queue" title="queue.Queue"><code class="xref py py-class docutils literal notranslate"><span class="pre">queue.Queue</span></code></a>.  For498example:</p>499<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Process</span><span class="p">,</span> <span class="n">Queue</span>500 501<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">q</span><span class="p">):</span>502    <span class="n">q</span><span class="o">.</span><span class="n">put</span><span class="p">([</span><span class="mi">42</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="s1">&#39;hello&#39;</span><span class="p">])</span>503 504<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>505    <span class="n">q</span> <span class="o">=</span> <span class="n">Queue</span><span class="p">()</span>506    <span class="n">p</span> <span class="o">=</span> <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">q</span><span class="p">,))</span>507    <span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>508    <span class="nb">print</span><span class="p">(</span><span class="n">q</span><span class="o">.</span><span class="n">get</span><span class="p">())</span>    <span class="c1"># prints &quot;[42, None, &#39;hello&#39;]&quot;</span>509    <span class="n">p</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>510</pre></div>511</div>512<p>Queues are thread and process safe.513Any object put into a <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> queue will be serialized.</p>514</div></blockquote>515<p><strong>Pipes</strong></p>516<blockquote>517<div><p>The <a class="reference internal" href="#multiprocessing.Pipe" title="multiprocessing.Pipe"><code class="xref py py-func docutils literal notranslate"><span class="pre">Pipe()</span></code></a> function returns a pair of connection objects connected by a518pipe which by default is duplex (two-way).  For example:</p>519<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Process</span><span class="p">,</span> <span class="n">Pipe</span>520 521<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">conn</span><span class="p">):</span>522    <span class="n">conn</span><span class="o">.</span><span class="n">send</span><span class="p">([</span><span class="mi">42</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="s1">&#39;hello&#39;</span><span class="p">])</span>523    <span class="n">conn</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>524 525<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>526    <span class="n">parent_conn</span><span class="p">,</span> <span class="n">child_conn</span> <span class="o">=</span> <span class="n">Pipe</span><span class="p">()</span>527    <span class="n">p</span> <span class="o">=</span> <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">child_conn</span><span class="p">,))</span>528    <span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>529    <span class="nb">print</span><span class="p">(</span><span class="n">parent_conn</span><span class="o">.</span><span class="n">recv</span><span class="p">())</span>   <span class="c1"># prints &quot;[42, None, &#39;hello&#39;]&quot;</span>530    <span class="n">p</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>531</pre></div>532</div>533<p>The two connection objects returned by <a class="reference internal" href="#multiprocessing.Pipe" title="multiprocessing.Pipe"><code class="xref py py-func docutils literal notranslate"><span class="pre">Pipe()</span></code></a> represent the two ends of534the pipe.  Each connection object has <code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code> and535<code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code> methods (among others).  Note that data in a pipe536may become corrupted if two processes (or threads) try to read from or write537to the <em>same</em> end of the pipe at the same time.  Of course there is no risk538of corruption from processes using different ends of the pipe at the same539time.</p>540<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code> method serializes the object and541<code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code> re-creates the object.</p>542</div></blockquote>543</section>544<section id="synchronization-between-processes">545<h3>Synchronization between processes<a class="headerlink" href="#synchronization-between-processes" title="Link to this heading">¶</a></h3>546<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> contains equivalents of all the synchronization547primitives from <a class="reference internal" href="threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a>.  For instance one can use a lock to ensure548that only one process prints to standard output at a time:</p>549<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Process</span><span class="p">,</span> <span class="n">Lock</span>550 551<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">l</span><span class="p">,</span> <span class="n">i</span><span class="p">):</span>552    <span class="n">l</span><span class="o">.</span><span class="n">acquire</span><span class="p">()</span>553    <span class="k">try</span><span class="p">:</span>554        <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;hello world&#39;</span><span class="p">,</span> <span class="n">i</span><span class="p">)</span>555    <span class="k">finally</span><span class="p">:</span>556        <span class="n">l</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>557 558<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>559    <span class="n">lock</span> <span class="o">=</span> <span class="n">Lock</span><span class="p">()</span>560 561    <span class="k">for</span> <span class="n">num</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>562        <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">lock</span><span class="p">,</span> <span class="n">num</span><span class="p">))</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>563</pre></div>564</div>565<p>Without using the lock output from the different processes is liable to get all566mixed up.</p>567</section>568<section id="sharing-state-between-processes">569<h3>Sharing state between processes<a class="headerlink" href="#sharing-state-between-processes" title="Link to this heading">¶</a></h3>570<p>As mentioned above, when doing concurrent programming it is usually best to571avoid using shared state as far as possible.  This is particularly true when572using multiple processes.</p>573<p>However, if you really do need to use some shared data then574<code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> provides a couple of ways of doing so.</p>575<p><strong>Shared memory</strong></p>576<blockquote>577<div><p>Data can be stored in a shared memory map using <a class="reference internal" href="#multiprocessing.Value" title="multiprocessing.Value"><code class="xref py py-class docutils literal notranslate"><span class="pre">Value</span></code></a> or578<a class="reference internal" href="#multiprocessing.Array" title="multiprocessing.Array"><code class="xref py py-class docutils literal notranslate"><span class="pre">Array</span></code></a>.  For example, the following code</p>579<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Process</span><span class="p">,</span> <span class="n">Value</span><span class="p">,</span> <span class="n">Array</span>580 581<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">a</span><span class="p">):</span>582    <span class="n">n</span><span class="o">.</span><span class="n">value</span> <span class="o">=</span> <span class="mf">3.1415927</span>583    <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">a</span><span class="p">)):</span>584        <span class="n">a</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="o">-</span><span class="n">a</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>585 586<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>587    <span class="n">num</span> <span class="o">=</span> <span class="n">Value</span><span class="p">(</span><span class="s1">&#39;d&#39;</span><span class="p">,</span> <span class="mf">0.0</span><span class="p">)</span>588    <span class="n">arr</span> <span class="o">=</span> <span class="n">Array</span><span class="p">(</span><span class="s1">&#39;i&#39;</span><span class="p">,</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span>589 590    <span class="n">p</span> <span class="o">=</span> <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">num</span><span class="p">,</span> <span class="n">arr</span><span class="p">))</span>591    <span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>592    <span class="n">p</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>593 594    <span class="nb">print</span><span class="p">(</span><span class="n">num</span><span class="o">.</span><span class="n">value</span><span class="p">)</span>595    <span class="nb">print</span><span class="p">(</span><span class="n">arr</span><span class="p">[:])</span>596</pre></div>597</div>598<p>will print</p>599<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="mf">3.1415927</span>600<span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="o">-</span><span class="mi">2</span><span class="p">,</span> <span class="o">-</span><span class="mi">3</span><span class="p">,</span> <span class="o">-</span><span class="mi">4</span><span class="p">,</span> <span class="o">-</span><span class="mi">5</span><span class="p">,</span> <span class="o">-</span><span class="mi">6</span><span class="p">,</span> <span class="o">-</span><span class="mi">7</span><span class="p">,</span> <span class="o">-</span><span class="mi">8</span><span class="p">,</span> <span class="o">-</span><span class="mi">9</span><span class="p">]</span>601</pre></div>602</div>603<p>The <code class="docutils literal notranslate"><span class="pre">'d'</span></code> and <code class="docutils literal notranslate"><span class="pre">'i'</span></code> arguments used when creating <code class="docutils literal notranslate"><span class="pre">num</span></code> and <code class="docutils literal notranslate"><span class="pre">arr</span></code> are604typecodes of the kind used by the <a class="reference internal" href="array.html#module-array" title="array: Space efficient arrays of uniformly typed numeric values."><code class="xref py py-mod docutils literal notranslate"><span class="pre">array</span></code></a> module: <code class="docutils literal notranslate"><span class="pre">'d'</span></code> indicates a605double precision float and <code class="docutils literal notranslate"><span class="pre">'i'</span></code> indicates a signed integer.  These shared606objects will be process and thread-safe.</p>607<p>For more flexibility in using shared memory one can use the608<a class="reference internal" href="#module-multiprocessing.sharedctypes" title="multiprocessing.sharedctypes: Allocate ctypes objects from shared memory."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing.sharedctypes</span></code></a> module which supports the creation of609arbitrary ctypes objects allocated from shared memory.</p>610</div></blockquote>611<p><strong>Server process</strong></p>612<blockquote>613<div><p>A manager object returned by <a class="reference internal" href="#multiprocessing.Manager" title="multiprocessing.Manager"><code class="xref py py-func docutils literal notranslate"><span class="pre">Manager()</span></code></a> controls a server process which614holds Python objects and allows other processes to manipulate them using615proxies.</p>616<p>A manager returned by <a class="reference internal" href="#multiprocessing.Manager" title="multiprocessing.Manager"><code class="xref py py-func docutils literal notranslate"><span class="pre">Manager()</span></code></a> will support types617<a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>, <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>, <a class="reference internal" href="#multiprocessing.managers.Namespace" title="multiprocessing.managers.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a>, <a class="reference internal" href="#multiprocessing.Lock" title="multiprocessing.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Lock</span></code></a>,618<a class="reference internal" href="#multiprocessing.RLock" title="multiprocessing.RLock"><code class="xref py py-class docutils literal notranslate"><span class="pre">RLock</span></code></a>, <a class="reference internal" href="#multiprocessing.Semaphore" title="multiprocessing.Semaphore"><code class="xref py py-class docutils literal notranslate"><span class="pre">Semaphore</span></code></a>, <a class="reference internal" href="#multiprocessing.BoundedSemaphore" title="multiprocessing.BoundedSemaphore"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundedSemaphore</span></code></a>,619<a class="reference internal" href="#multiprocessing.Condition" title="multiprocessing.Condition"><code class="xref py py-class docutils literal notranslate"><span class="pre">Condition</span></code></a>, <a class="reference internal" href="#multiprocessing.Event" title="multiprocessing.Event"><code class="xref py py-class docutils literal notranslate"><span class="pre">Event</span></code></a>, <a class="reference internal" href="#multiprocessing.Barrier" title="multiprocessing.Barrier"><code class="xref py py-class docutils literal notranslate"><span class="pre">Barrier</span></code></a>,620<a class="reference internal" href="#multiprocessing.Queue" title="multiprocessing.Queue"><code class="xref py py-class docutils literal notranslate"><span class="pre">Queue</span></code></a>, <a class="reference internal" href="#multiprocessing.Value" title="multiprocessing.Value"><code class="xref py py-class docutils literal notranslate"><span class="pre">Value</span></code></a> and <a class="reference internal" href="#multiprocessing.Array" title="multiprocessing.Array"><code class="xref py py-class docutils literal notranslate"><span class="pre">Array</span></code></a>.  For example,</p>621<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Process</span><span class="p">,</span> <span class="n">Manager</span>622 623<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="n">l</span><span class="p">,</span> <span class="n">s</span><span class="p">):</span>624    <span class="n">d</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;1&#39;</span>625    <span class="n">d</span><span class="p">[</span><span class="s1">&#39;2&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">2</span>626    <span class="n">d</span><span class="p">[</span><span class="mf">0.25</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>627    <span class="n">l</span><span class="o">.</span><span class="n">reverse</span><span class="p">()</span>628    <span class="n">s</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s1">&#39;a&#39;</span><span class="p">)</span>629    <span class="n">s</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s1">&#39;b&#39;</span><span class="p">)</span>630 631<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>632    <span class="k">with</span> <span class="n">Manager</span><span class="p">()</span> <span class="k">as</span> <span class="n">manager</span><span class="p">:</span>633        <span class="n">d</span> <span class="o">=</span> <span class="n">manager</span><span class="o">.</span><span class="n">dict</span><span class="p">()</span>634        <span class="n">l</span> <span class="o">=</span> <span class="n">manager</span><span class="o">.</span><span class="n">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span>635        <span class="n">s</span> <span class="o">=</span> <span class="n">manager</span><span class="o">.</span><span class="n">set</span><span class="p">()</span>636 637        <span class="n">p</span> <span class="o">=</span> <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">f</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="n">l</span><span class="p">,</span> <span class="n">s</span><span class="p">))</span>638        <span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>639        <span class="n">p</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>640 641        <span class="nb">print</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>642        <span class="nb">print</span><span class="p">(</span><span class="n">l</span><span class="p">)</span>643        <span class="nb">print</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>644</pre></div>645</div>646<p>will print</p>647<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="mf">0.25</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span> <span class="s1">&#39;1&#39;</span><span class="p">,</span> <span class="s1">&#39;2&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">}</span>648<span class="p">[</span><span class="mi">9</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span>649<span class="p">{</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">}</span>650</pre></div>651</div>652<p>Server process managers are more flexible than using shared memory objects653because they can be made to support arbitrary object types.  Also, a single654manager can be shared by processes on different computers over a network.655They are, however, slower than using shared memory.</p>656</div></blockquote>657</section>658<section id="using-a-pool-of-workers">659<h3>Using a pool of workers<a class="headerlink" href="#using-a-pool-of-workers" title="Link to this heading">¶</a></h3>660<p>The <a class="reference internal" href="#multiprocessing.pool.Pool" title="multiprocessing.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a> class represents a pool of worker661processes.  It has methods which allows tasks to be offloaded to the worker662processes in a few different ways.</p>663<p>For example:</p>664<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Pool</span><span class="p">,</span> <span class="ne">TimeoutError</span>665<span class="kn">import</span><span class="w"> </span><span class="nn">time</span>666<span class="kn">import</span><span class="w"> </span><span class="nn">os</span>667 668<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>669    <span class="k">return</span> <span class="n">x</span><span class="o">*</span><span class="n">x</span>670 671<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>672    <span class="c1"># start 4 worker processes</span>673    <span class="k">with</span> <span class="n">Pool</span><span class="p">(</span><span class="n">processes</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span> <span class="k">as</span> <span class="n">pool</span><span class="p">:</span>674 675        <span class="c1"># print &quot;[0, 1, 4,..., 81]&quot;</span>676        <span class="nb">print</span><span class="p">(</span><span class="n">pool</span><span class="o">.</span><span class="n">map</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">)))</span>677 678        <span class="c1"># print same numbers in arbitrary order</span>679        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">pool</span><span class="o">.</span><span class="n">imap_unordered</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">)):</span>680            <span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>681 682        <span class="c1"># evaluate &quot;f(20)&quot; asynchronously</span>683        <span class="n">res</span> <span class="o">=</span> <span class="n">pool</span><span class="o">.</span><span class="n">apply_async</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="p">(</span><span class="mi">20</span><span class="p">,))</span>      <span class="c1"># runs in *only* one process</span>684        <span class="nb">print</span><span class="p">(</span><span class="n">res</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">1</span><span class="p">))</span>             <span class="c1"># prints &quot;400&quot;</span>685 686        <span class="c1"># evaluate &quot;os.getpid()&quot; asynchronously</span>687        <span class="n">res</span> <span class="o">=</span> <span class="n">pool</span><span class="o">.</span><span class="n">apply_async</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">getpid</span><span class="p">,</span> <span class="p">())</span> <span class="c1"># runs in *only* one process</span>688        <span class="nb">print</span><span class="p">(</span><span class="n">res</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">1</span><span class="p">))</span>             <span class="c1"># prints the PID of that process</span>689 690        <span class="c1"># launching multiple evaluations asynchronously *may* use more processes</span>691        <span class="n">multiple_results</span> <span class="o">=</span> <span class="p">[</span><span class="n">pool</span><span class="o">.</span><span class="n">apply_async</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">getpid</span><span class="p">,</span> <span class="p">())</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">4</span><span class="p">)]</span>692        <span class="nb">print</span><span class="p">([</span><span class="n">res</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> <span class="k">for</span> <span class="n">res</span> <span class="ow">in</span> <span class="n">multiple_results</span><span class="p">])</span>693 694        <span class="c1"># make a single worker sleep for 10 seconds</span>695        <span class="n">res</span> <span class="o">=</span> <span class="n">pool</span><span class="o">.</span><span class="n">apply_async</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">,</span> <span class="p">(</span><span class="mi">10</span><span class="p">,))</span>696        <span class="k">try</span><span class="p">:</span>697            <span class="nb">print</span><span class="p">(</span><span class="n">res</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">1</span><span class="p">))</span>698        <span class="k">except</span> <span class="ne">TimeoutError</span><span class="p">:</span>699            <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;We lacked patience and got a multiprocessing.TimeoutError&quot;</span><span class="p">)</span>700 701        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;For the moment, the pool remains available for more work&quot;</span><span class="p">)</span>702 703    <span class="c1"># exiting the &#39;with&#39;-block has stopped the pool</span>704    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Now the pool is closed and no longer available&quot;</span><span class="p">)</span>705</pre></div>706</div>707<p>Note that the methods of a pool should only ever be used by the708process which created it.</p>709<div class="admonition note">710<p class="admonition-title">Note</p>711<p>Functionality within this package requires that the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module be712importable by the children. This is covered in <a class="reference internal" href="#multiprocessing-programming"><span class="std std-ref">Programming guidelines</span></a>713however it is worth pointing out here. This means that some examples, such714as the <a class="reference internal" href="#multiprocessing.pool.Pool" title="multiprocessing.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">multiprocessing.pool.Pool</span></code></a> examples will not work in the715interactive interpreter. For example:</p>716<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Pool</span>717<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Pool</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>718<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>719<span class="gp">... </span>    <span class="k">return</span> <span class="n">x</span><span class="o">*</span><span class="n">x</span>720<span class="gp">...</span>721<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">p</span><span class="p">:</span>722<span class="gp">... </span>    <span class="n">p</span><span class="o">.</span><span class="n">map</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>723<span class="go">Process PoolWorker-1:</span>724<span class="go">Process PoolWorker-2:</span>725<span class="go">Process PoolWorker-3:</span>726<span class="gt">Traceback (most recent call last):</span>727<span class="gt">Traceback (most recent call last):</span>728<span class="gt">Traceback (most recent call last):</span>729<span class="gr">AttributeError</span>: <span class="n">Can&#39;t get attribute &#39;f&#39; on &lt;module &#39;__main__&#39; (&lt;class &#39;_frozen_importlib.BuiltinImporter&#39;&gt;)&gt;</span>730<span class="x">AttributeError: Can&#39;t get attribute &#39;f&#39; on &lt;module &#39;__main__&#39; (&lt;class &#39;_frozen_importlib.BuiltinImporter&#39;&gt;)&gt;</span>731<span class="x">AttributeError: Can&#39;t get attribute &#39;f&#39; on &lt;module &#39;__main__&#39; (&lt;class &#39;_frozen_importlib.BuiltinImporter&#39;&gt;)&gt;</span>732</pre></div>733</div>734<p>(If you try this it will actually output three full tracebacks735interleaved in a semi-random fashion, and then you may have to736stop the parent process somehow.)</p>737</div>738</section>739</section>740<section id="reference">741<h2>Reference<a class="headerlink" href="#reference" title="Link to this heading">¶</a></h2>742<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> package mostly replicates the API of the743<a class="reference internal" href="threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module.</p>744<section id="global-start-method">745<span id="id1"></span><h3>Global start method<a class="headerlink" href="#global-start-method" title="Link to this heading">¶</a></h3>746<p>Python supports several ways to create and initialize a process.747The global start method sets the default mechanism for creating a process.</p>748<p>Several multiprocessing functions and methods that may also instantiate749certain objects will implicitly set the global start method to the system’s default,750if it hasn’t been set already. The global start method can only be set once.751If you need to change the start method from the system default, you must752proactively set the global start method before calling functions or methods,753or creating these objects.</p>754</section>755<section id="process-and-exceptions">756<h3><a class="reference internal" href="#multiprocessing.Process" title="multiprocessing.Process"><code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code></a> and exceptions<a class="headerlink" href="#process-and-exceptions" title="Link to this heading">¶</a></h3>757<dl class="py class">758<dt class="sig sig-object py" id="multiprocessing.Process">759<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">multiprocessing.</span></span><span class="sig-name descname"><span class="pre">Process</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><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Process" title="Link to this definition">¶</a></dt>760<dd><p>Process objects represent activity that is run in a separate process. The761<code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code> class has equivalents of all the methods of762<a class="reference internal" href="threading.html#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Thread</span></code></a>.</p>763<p>The constructor should always be called with keyword arguments. <em>group</em>764should always be <code class="docutils literal notranslate"><span class="pre">None</span></code>; it exists solely for compatibility with765<a class="reference internal" href="threading.html#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Thread</span></code></a>.  <em>target</em> is the callable object to be invoked by766the <a class="reference internal" href="#multiprocessing.Process.run" title="multiprocessing.Process.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method.  It defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>, meaning nothing is767called. <em>name</em> is the process name (see <a class="reference internal" href="#multiprocessing.Process.name" title="multiprocessing.Process.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> for more details).768<em>args</em> is the argument tuple for the target invocation.  <em>kwargs</em> is a769dictionary of keyword arguments for the target invocation.  If provided,770the keyword-only <em>daemon</em> argument sets the process <a class="reference internal" href="#multiprocessing.Process.daemon" title="multiprocessing.Process.daemon"><code class="xref py py-attr docutils literal notranslate"><span class="pre">daemon</span></code></a> flag771to <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code>.  If <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), this flag will be772inherited from the creating process.</p>773<p>By default, no arguments are passed to <em>target</em>. The <em>args</em> argument,774which defaults to <code class="docutils literal notranslate"><span class="pre">()</span></code>, can be used to specify a list or tuple of the arguments775to pass to <em>target</em>.</p>776<p>If a subclass overrides the constructor, it must make sure it invokes the777base class constructor (<code class="docutils literal notranslate"><span class="pre">super().__init__()</span></code>) before doing anything else778to the process.</p>779<div class="admonition note">780<p class="admonition-title">Note</p>781<p>In general, all arguments to <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code> must be picklable.  This is782frequently observed when trying to create a <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code> or use a783<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> from a REPL with a784locally defined <em>target</em> function.</p>785<p>Passing a callable object defined in the current REPL session causes the786child process to die via an uncaught <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> exception when787starting as <em>target</em> must have been defined within an importable module788in order to be loaded during unpickling.</p>789<p>Example of this uncatchable error from the child:</p>790<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">mp</span>791<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span><span class="w"> </span><span class="nf">knigit</span><span class="p">():</span>792<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Ni!&quot;</span><span class="p">)</span>793<span class="gp">...</span>794<span class="gp">&gt;&gt;&gt; </span><span class="n">process</span> <span class="o">=</span> <span class="n">mp</span><span class="o">.</span><span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">knigit</span><span class="p">)</span>795<span class="gp">&gt;&gt;&gt; </span><span class="n">process</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>796<span class="gp">&gt;&gt;&gt; </span><span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>797<span class="go">  File &quot;.../multiprocessing/spawn.py&quot;, line ..., in spawn_main</span>798<span class="go">  File &quot;.../multiprocessing/spawn.py&quot;, line ..., in _main</span>799<span class="go">AttributeError: module &#39;__main__&#39; has no attribute &#39;knigit&#39;</span>800<span class="gp">&gt;&gt;&gt; </span><span class="n">process</span>801<span class="go">&lt;SpawnProcess name=&#39;SpawnProcess-1&#39; pid=379473 parent=378707 stopped exitcode=1&gt;</span>802</pre></div>803</div>804<p>See <a class="reference internal" href="#multiprocessing-programming-spawn"><span class="std std-ref">The spawn and forkserver start methods</span></a>.  While this restriction is805not true if using the <code class="docutils literal notranslate"><span class="pre">&quot;fork&quot;</span></code> start method, as of Python <code class="docutils literal notranslate"><span class="pre">3.14</span></code> that806is no longer the default on any platform.  See807<a class="reference internal" href="#multiprocessing-start-methods"><span class="std std-ref">Contexts and start methods</span></a>.808See also <a class="reference external" href="https://github.com/python/cpython/issues/132898">gh-132898</a>.</p>809</div>810<div class="versionchanged">811<p><span class="versionmodified changed">Changed in version 3.3: </span>Added the <em>daemon</em> parameter.</p>812</div>813<dl class="py method">814<dt class="sig sig-object py" id="multiprocessing.Process.run">815<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="#multiprocessing.Process.run" title="Link to this definition">¶</a></dt>816<dd><p>Method representing the process’s activity.</p>817<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>818method invokes the callable object passed to the object’s constructor as819the target argument, if any, with sequential and keyword arguments taken820from the <em>args</em> and <em>kwargs</em> arguments, respectively.</p>821<p>Using a list or tuple as the <em>args</em> argument passed to <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code>822achieves the same effect.</p>823<p>Example:</p>824<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Process</span>825<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Process</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>826<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>827<span class="go">1</span>828<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Process</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>829<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>830<span class="go">1</span>831</pre></div>832</div>833</dd></dl>834 835<dl class="py method">836<dt class="sig sig-object py" id="multiprocessing.Process.start">837<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="#multiprocessing.Process.start" title="Link to this definition">¶</a></dt>838<dd><p>Start the process’s activity.</p>839<p>This must be called at most once per process object.  It arranges for the840object’s <a class="reference internal" href="#multiprocessing.Process.run" title="multiprocessing.Process.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method to be invoked in a separate process.</p>841</dd></dl>842 843<dl class="py method">844<dt class="sig sig-object py" id="multiprocessing.Process.join">845<span class="sig-name descname"><span class="pre">join</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">timeout</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Process.join" title="Link to this definition">¶</a></dt>846<dd><p>If the optional argument <em>timeout</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), the method847blocks until the process whose <code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code> method is called terminates.848If <em>timeout</em> is a positive number, it blocks at most <em>timeout</em> seconds.849Note that the method returns <code class="docutils literal notranslate"><span class="pre">None</span></code> if its process terminates or if the850method times out.  Check the process’s <a class="reference internal" href="#multiprocessing.Process.exitcode" title="multiprocessing.Process.exitcode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">exitcode</span></code></a> to determine if851it terminated.</p>852<p>A process can be joined many times.</p>853<p>A process cannot join itself because this would cause a deadlock.  It is854an error to attempt to join a process before it has been started.</p>855</dd></dl>856 857<dl class="py attribute">858<dt class="sig sig-object py" id="multiprocessing.Process.name">859<span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#multiprocessing.Process.name" title="Link to this definition">¶</a></dt>860<dd><p>The process’s name.  The name is a string used for identification purposes861only.  It has no semantics.  Multiple processes may be given the same862name.</p>863<p>The initial name is set by the constructor.  If no explicit name is864provided to the constructor, a name of the form865‘Process-N<sub>1</sub>:N<sub>2</sub>:…:N<sub>k</sub>’ is constructed, where866each N<sub>k</sub> is the N-th child of its parent.</p>867</dd></dl>868 869<dl class="py method">870<dt class="sig sig-object py" id="multiprocessing.Process.is_alive">871<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="#multiprocessing.Process.is_alive" title="Link to this definition">¶</a></dt>872<dd><p>Return whether the process is alive.</p>873<p>Roughly, a process object is alive from the moment the <a class="reference internal" href="#multiprocessing.Process.start" title="multiprocessing.Process.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a>874method returns until the child process terminates.</p>875</dd></dl>876 877<dl class="py attribute">878<dt class="sig sig-object py" id="multiprocessing.Process.daemon">879<span class="sig-name descname"><span class="pre">daemon</span></span><a class="headerlink" href="#multiprocessing.Process.daemon" title="Link to this definition">¶</a></dt>880<dd><p>The process’s daemon flag, a Boolean value.  This must be set before881<a class="reference internal" href="#multiprocessing.Process.start" title="multiprocessing.Process.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a> is called.</p>882<p>The initial value is inherited from the creating process.</p>883<p>When a process exits, it attempts to terminate all of its daemonic child884processes.</p>885<p>Note that a daemonic process is not allowed to create child processes.886Otherwise a daemonic process would leave its children orphaned if it gets887terminated when its parent process exits. Additionally, these are <strong>not</strong>888Unix daemons or services, they are normal processes that will be889terminated (and not joined) if non-daemonic processes have exited.</p>890</dd></dl>891 892<p>In addition to the  <a class="reference internal" href="threading.html#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.Thread</span></code></a> API, <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code> objects893also support the following attributes and methods:</p>894<dl class="py attribute">895<dt class="sig sig-object py" id="multiprocessing.Process.pid">896<span class="sig-name descname"><span class="pre">pid</span></span><a class="headerlink" href="#multiprocessing.Process.pid" title="Link to this definition">¶</a></dt>897<dd><p>Return the process ID.  Before the process is spawned, this will be898<code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>899</dd></dl>900 901<dl class="py attribute">902<dt class="sig sig-object py" id="multiprocessing.Process.exitcode">903<span class="sig-name descname"><span class="pre">exitcode</span></span><a class="headerlink" href="#multiprocessing.Process.exitcode" title="Link to this definition">¶</a></dt>904<dd><p>The child’s exit code.  This will be <code class="docutils literal notranslate"><span class="pre">None</span></code> if the process has not yet905terminated.</p>906<p>If the child’s <a class="reference internal" href="#multiprocessing.Process.run" title="multiprocessing.Process.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method returned normally, the exit code907will be 0.  If it terminated via <a class="reference internal" href="sys.html#sys.exit" title="sys.exit"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exit()</span></code></a> with an integer908argument <em>N</em>, the exit code will be <em>N</em>.</p>909<p>If the child terminated due to an exception not caught within910<a class="reference internal" href="#multiprocessing.Process.run" title="multiprocessing.Process.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a>, the exit code will be 1.  If it was terminated by911signal <em>N</em>, the exit code will be the negative value <em>-N</em>.</p>912</dd></dl>913 914<dl class="py attribute">915<dt class="sig sig-object py" id="multiprocessing.Process.authkey">916<span class="sig-name descname"><span class="pre">authkey</span></span><a class="headerlink" href="#multiprocessing.Process.authkey" title="Link to this definition">¶</a></dt>917<dd><p>The process’s authentication key (a byte string).</p>918<p>When <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> is initialized the main process is assigned a919random string using <a class="reference internal" href="os.html#os.urandom" title="os.urandom"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.urandom()</span></code></a>.</p>920<p>When a <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code> object is created, it will inherit the921authentication key of its parent process, although this may be changed by922setting <a class="reference internal" href="#multiprocessing.Process.authkey" title="multiprocessing.Process.authkey"><code class="xref py py-attr docutils literal notranslate"><span class="pre">authkey</span></code></a> to another byte string.</p>923<p>See <a class="reference internal" href="#multiprocessing-auth-keys"><span class="std std-ref">Authentication keys</span></a>.</p>924</dd></dl>925 926<dl class="py attribute">927<dt class="sig sig-object py" id="multiprocessing.Process.sentinel">928<span class="sig-name descname"><span class="pre">sentinel</span></span><a class="headerlink" href="#multiprocessing.Process.sentinel" title="Link to this definition">¶</a></dt>929<dd><p>A numeric handle of a system object which will become “ready” when930the process ends.</p>931<p>You can use this value if you want to wait on several events at932once using <a class="reference internal" href="#multiprocessing.connection.wait" title="multiprocessing.connection.wait"><code class="xref py py-func docutils literal notranslate"><span class="pre">multiprocessing.connection.wait()</span></code></a>.  Otherwise933calling <a class="reference internal" href="#multiprocessing.Process.join" title="multiprocessing.Process.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> is simpler.</p>934<p>On Windows, this is an OS handle usable with the <code class="docutils literal notranslate"><span class="pre">WaitForSingleObject</span></code>935and <code class="docutils literal notranslate"><span class="pre">WaitForMultipleObjects</span></code> family of API calls.  On POSIX, this is936a file descriptor usable with primitives from the <a class="reference internal" href="select.html#module-select" title="select: Wait for I/O completion on multiple streams."><code class="xref py py-mod docutils literal notranslate"><span class="pre">select</span></code></a> module.</p>937<div class="versionadded">938<p><span class="versionmodified added">Added in version 3.3.</span></p>939</div>940</dd></dl>941 942<dl class="py method">943<dt class="sig sig-object py" id="multiprocessing.Process.interrupt">944<span class="sig-name descname"><span class="pre">interrupt</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Process.interrupt" title="Link to this definition">¶</a></dt>945<dd><p>Terminate the process. Works on POSIX using the <a class="reference internal" href="signal.html#signal.SIGINT" title="signal.SIGINT"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGINT</span></code></a> signal.946Behavior on Windows is undefined.</p>947<p>By default, this terminates the child process by raising <a class="reference internal" href="exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a>.948This behavior can be altered by setting the respective signal handler in the child949process <a class="reference internal" href="signal.html#signal.signal" title="signal.signal"><code class="xref py py-func docutils literal notranslate"><span class="pre">signal.signal()</span></code></a> for <a class="reference internal" href="signal.html#signal.SIGINT" title="signal.SIGINT"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGINT</span></code></a>.</p>950<p>Note: if the child process catches and discards <a class="reference internal" href="exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a>, the951process will not be terminated.</p>952<p>Note: the default behavior will also set <a class="reference internal" href="#multiprocessing.Process.exitcode" title="multiprocessing.Process.exitcode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">exitcode</span></code></a> to <code class="docutils literal notranslate"><span class="pre">1</span></code> as if an953uncaught exception was raised in the child process. To have a different954<code class="xref py py-attr docutils literal notranslate"><span class="pre">exitcode</span></code> you may simply catch <a class="reference internal" href="exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a> and call955<code class="docutils literal notranslate"><span class="pre">exit(your_code)</span></code>.</p>956<div class="versionadded">957<p><span class="versionmodified added">Added in version 3.14.</span></p>958</div>959</dd></dl>960 961<dl class="py method">962<dt class="sig sig-object py" id="multiprocessing.Process.terminate">963<span class="sig-name descname"><span class="pre">terminate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Process.terminate" title="Link to this definition">¶</a></dt>964<dd><p>Terminate the process.  On POSIX this is done using the <a class="reference internal" href="signal.html#signal.SIGTERM" title="signal.SIGTERM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGTERM</span></code></a> signal;965on Windows <code class="xref c c-func docutils literal notranslate"><span class="pre">TerminateProcess()</span></code> is used.  Note that exit handlers and966finally clauses, etc., will not be executed.</p>967<p>Note that descendant processes of the process will <em>not</em> be terminated –968they will simply become orphaned.</p>969<div class="admonition warning">970<p class="admonition-title">Warning</p>971<p>If this method is used when the associated process is using a pipe or972queue then the pipe or queue is liable to become corrupted and may973become unusable by other process.  Similarly, if the process has974acquired a lock or semaphore etc. then terminating it is liable to975cause other processes to deadlock.</p>976</div>977</dd></dl>978 979<dl class="py method">980<dt class="sig sig-object py" id="multiprocessing.Process.kill">981<span class="sig-name descname"><span class="pre">kill</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Process.kill" title="Link to this definition">¶</a></dt>982<dd><p>Same as <a class="reference internal" href="#multiprocessing.Process.terminate" title="multiprocessing.Process.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate()</span></code></a> but using the <code class="docutils literal notranslate"><span class="pre">SIGKILL</span></code> signal on POSIX.</p>983<div class="versionadded">984<p><span class="versionmodified added">Added in version 3.7.</span></p>985</div>986</dd></dl>987 988<dl class="py method">989<dt class="sig sig-object py" id="multiprocessing.Process.close">990<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Process.close" title="Link to this definition">¶</a></dt>991<dd><p>Close the <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code> object, releasing all resources associated992with it.  <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 if the underlying process993is still running.  Once <code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code> returns successfully, most994other methods and attributes of the <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code> object will995raise <code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code>.</p>996<div class="versionadded">997<p><span class="versionmodified added">Added in version 3.7.</span></p>998</div>999</dd></dl>1000 1001<p>Note that the <a class="reference internal" href="#multiprocessing.Process.start" title="multiprocessing.Process.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a>, <a class="reference internal" href="#multiprocessing.Process.join" title="multiprocessing.Process.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>, <a class="reference internal" href="#multiprocessing.Process.is_alive" title="multiprocessing.Process.is_alive"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_alive()</span></code></a>,1002<a class="reference internal" href="#multiprocessing.Process.terminate" title="multiprocessing.Process.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate()</span></code></a> and <a class="reference internal" href="#multiprocessing.Process.exitcode" title="multiprocessing.Process.exitcode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">exitcode</span></code></a> methods should only be called by1003the process that created the process object.</p>1004<p>Example usage of some of the methods of <code class="xref py py-class docutils literal notranslate"><span class="pre">Process</span></code>:</p>1005<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">multiprocessing</span><span class="o">,</span><span class="w"> </span><span class="nn">time</span><span class="o">,</span><span class="w"> </span><span class="nn">signal</span>1006<span class="gp">&gt;&gt;&gt; </span><span class="n">mp_context</span> <span class="o">=</span> <span class="n">multiprocessing</span><span class="o">.</span><span class="n">get_context</span><span class="p">(</span><span class="s1">&#39;spawn&#39;</span><span class="p">)</span>1007<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">mp_context</span><span class="o">.</span><span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="mi">1000</span><span class="p">,))</span>1008<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">is_alive</span><span class="p">())</span>1009<span class="go">&lt;...Process ... initial&gt; False</span>1010<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>1011<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">is_alive</span><span class="p">())</span>1012<span class="go">&lt;...Process ... started&gt; True</span>1013<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">terminate</span><span class="p">()</span>1014<span class="gp">&gt;&gt;&gt; </span><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>1015<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">is_alive</span><span class="p">())</span>1016<span class="go">&lt;...Process ... stopped exitcode=-SIGTERM&gt; False</span>1017<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">exitcode</span> <span class="o">==</span> <span class="o">-</span><span class="n">signal</span><span class="o">.</span><span class="n">SIGTERM</span>1018<span class="go">True</span>1019</pre></div>1020</div>1021</dd></dl>1022 1023<dl class="py exception">1024<dt class="sig sig-object py" id="multiprocessing.ProcessError">1025<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">multiprocessing.</span></span><span class="sig-name descname"><span class="pre">ProcessError</span></span><a class="headerlink" href="#multiprocessing.ProcessError" title="Link to this definition">¶</a></dt>1026<dd><p>The base class of all <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> exceptions.</p>1027</dd></dl>1028 1029<dl class="py exception">1030<dt class="sig sig-object py" id="multiprocessing.BufferTooShort">1031<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">multiprocessing.</span></span><span class="sig-name descname"><span class="pre">BufferTooShort</span></span><a class="headerlink" href="#multiprocessing.BufferTooShort" title="Link to this definition">¶</a></dt>1032<dd><p>Exception raised by <code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.recv_bytes_into()</span></code> when the supplied1033buffer object is too small for the message read.</p>1034<p>If <code class="docutils literal notranslate"><span class="pre">e</span></code> is an instance of <code class="xref py py-exc docutils literal notranslate"><span class="pre">BufferTooShort</span></code> then <code class="docutils literal notranslate"><span class="pre">e.args[0]</span></code> will give1035the message as a byte string.</p>1036</dd></dl>1037 1038<dl class="py exception">1039<dt class="sig sig-object py" id="multiprocessing.AuthenticationError">1040<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">multiprocessing.</span></span><span class="sig-name descname"><span class="pre">AuthenticationError</span></span><a class="headerlink" href="#multiprocessing.AuthenticationError" title="Link to this definition">¶</a></dt>1041<dd><p>Raised when there is an authentication error.</p>1042</dd></dl>1043 1044<dl class="py exception">1045<dt class="sig sig-object py" id="multiprocessing.TimeoutError">1046<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">multiprocessing.</span></span><span class="sig-name descname"><span class="pre">TimeoutError</span></span><a class="headerlink" href="#multiprocessing.TimeoutError" title="Link to this definition">¶</a></dt>1047<dd><p>Raised by methods with a timeout when the timeout expires.</p>1048</dd></dl>1049 1050</section>1051<section id="pipes-and-queues">1052<h3>Pipes and Queues<a class="headerlink" href="#pipes-and-queues" title="Link to this heading">¶</a></h3>1053<p>When using multiple processes, one generally uses message passing for1054communication between processes and avoids having to use any synchronization1055primitives like locks.</p>1056<p>For passing messages one can use <a class="reference internal" href="#multiprocessing.Pipe" title="multiprocessing.Pipe"><code class="xref py py-func docutils literal notranslate"><span class="pre">Pipe()</span></code></a> (for a connection between two1057processes) or a queue (which allows multiple producers and consumers).</p>1058<p>The <a class="reference internal" href="#multiprocessing.Queue" title="multiprocessing.Queue"><code class="xref py py-class docutils literal notranslate"><span class="pre">Queue</span></code></a>, <a class="reference internal" href="#multiprocessing.SimpleQueue" title="multiprocessing.SimpleQueue"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleQueue</span></code></a> and <a class="reference internal" href="#multiprocessing.JoinableQueue" title="multiprocessing.JoinableQueue"><code class="xref py py-class docutils literal notranslate"><span class="pre">JoinableQueue</span></code></a> types1059are multi-producer, multi-consumer <abbr title="first-in, first-out">FIFO</abbr>1060queues modelled on the <a class="reference internal" href="queue.html#queue.Queue" title="queue.Queue"><code class="xref py py-class docutils literal notranslate"><span class="pre">queue.Queue</span></code></a> class in the1061standard library.  They differ in that <code class="xref py py-class docutils literal notranslate"><span class="pre">Queue</span></code> lacks the1062<a class="reference internal" href="queue.html#queue.Queue.task_done" title="queue.Queue.task_done"><code class="xref py py-meth docutils literal notranslate"><span class="pre">task_done()</span></code></a> and <a class="reference internal" href="queue.html#queue.Queue.join" title="queue.Queue.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> methods introduced1063into Python 2.5’s <code class="xref py py-class docutils literal notranslate"><span class="pre">queue.Queue</span></code> class.</p>1064<p>If you use <a class="reference internal" href="#multiprocessing.JoinableQueue" title="multiprocessing.JoinableQueue"><code class="xref py py-class docutils literal notranslate"><span class="pre">JoinableQueue</span></code></a> then you <strong>must</strong> call1065<a class="reference internal" href="#multiprocessing.JoinableQueue.task_done" title="multiprocessing.JoinableQueue.task_done"><code class="xref py py-meth docutils literal notranslate"><span class="pre">JoinableQueue.task_done()</span></code></a> for each task removed from the queue or else the1066semaphore used to count the number of unfinished tasks may eventually overflow,1067raising an exception.</p>1068<p>One difference from other Python queue implementations, is that <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code>1069queues serializes all objects that are put into them using <a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pickle</span></code></a>.1070The object returned by the get method is a re-created object that does not share1071memory with the original object.</p>1072<p>Note that one can also create a shared queue by using a manager object – see1073<a class="reference internal" href="#multiprocessing-managers"><span class="std std-ref">Managers</span></a>.</p>1074<div class="admonition note">1075<p class="admonition-title">Note</p>1076<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> uses the usual <a class="reference internal" href="queue.html#queue.Empty" title="queue.Empty"><code class="xref py py-exc docutils literal notranslate"><span class="pre">queue.Empty</span></code></a> and1077<a class="reference internal" href="queue.html#queue.Full" title="queue.Full"><code class="xref py py-exc docutils literal notranslate"><span class="pre">queue.Full</span></code></a> exceptions to signal a timeout.  They are not available in1078the <code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code> namespace so you need to import them from1079<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>.</p>1080</div>1081<div class="admonition note">1082<p class="admonition-title">Note</p>1083<p>When an object is put on a queue, the object is pickled and a1084background thread later flushes the pickled data to an underlying1085pipe.  This has some consequences which are a little surprising,1086but should not cause any practical difficulties – if they really1087bother you then you can instead use a queue created with a1088<a class="reference internal" href="#multiprocessing-managers"><span class="std std-ref">manager</span></a>.</p>1089<ol class="arabic simple">1090<li><p>After putting an object on an empty queue there may be an1091infinitesimal delay before the queue’s <a class="reference internal" href="#multiprocessing.Queue.empty" title="multiprocessing.Queue.empty"><code class="xref py py-meth docutils literal notranslate"><span class="pre">empty()</span></code></a>1092method returns <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> and <a class="reference internal" href="#multiprocessing.Queue.get_nowait" title="multiprocessing.Queue.get_nowait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_nowait()</span></code></a> can1093return without raising <a class="reference internal" href="queue.html#queue.Empty" title="queue.Empty"><code class="xref py py-exc docutils literal notranslate"><span class="pre">queue.Empty</span></code></a>.</p></li>1094<li><p>If multiple processes are enqueuing objects, it is possible for1095the objects to be received at the other end out-of-order.1096However, objects enqueued by the same process will always be in1097the expected order with respect to each other.</p></li>1098</ol>1099</div>1100<div class="admonition warning">1101<p class="admonition-title">Warning</p>1102<p>If a process is killed using <a class="reference internal" href="#multiprocessing.Process.terminate" title="multiprocessing.Process.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Process.terminate()</span></code></a> or <a class="reference internal" href="os.html#os.kill" title="os.kill"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.kill()</span></code></a>1103while it is trying to use a <a class="reference internal" href="#multiprocessing.Queue" title="multiprocessing.Queue"><code class="xref py py-class docutils literal notranslate"><span class="pre">Queue</span></code></a>, then the data in the queue is1104likely to become corrupted.  This may cause any other process to get an1105exception when it tries to use the queue later on.</p>1106</div>1107<div class="admonition warning">1108<p class="admonition-title">Warning</p>1109<p>As mentioned above, if a child process has put items on a queue (and it has1110not used <a class="reference internal" href="#multiprocessing.Queue.cancel_join_thread" title="multiprocessing.Queue.cancel_join_thread"><code class="xref py py-meth docutils literal notranslate"><span class="pre">JoinableQueue.cancel_join_thread</span></code></a>), then that process will1111not terminate until all buffered items have been flushed to the pipe.</p>1112<p>This means that if you try joining that process you may get a deadlock unless1113you are sure that all items which have been put on the queue have been1114consumed.  Similarly, if the child process is non-daemonic then the parent1115process may hang on exit when it tries to join all its non-daemonic children.</p>1116<p>Note that a queue created using a manager does not have this issue.  See1117<a class="reference internal" href="#multiprocessing-programming"><span class="std std-ref">Programming guidelines</span></a>.</p>1118</div>1119<p>For an example of the usage of queues for interprocess communication see1120<a class="reference internal" href="#multiprocessing-examples"><span class="std std-ref">Examples</span></a>.</p>1121<dl class="py function">1122<dt class="sig sig-object py" id="multiprocessing.Pipe">1123<span class="sig-prename descclassname"><span class="pre">multiprocessing.</span></span><span class="sig-name descname"><span class="pre">Pipe</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">duplex</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Pipe" title="Link to this definition">¶</a></dt>1124<dd><p>Returns a pair <code class="docutils literal notranslate"><span class="pre">(conn1,</span> <span class="pre">conn2)</span></code> of1125<a class="reference internal" href="#multiprocessing.connection.Connection" title="multiprocessing.connection.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> objects representing the1126ends of a pipe.</p>1127<p>If <em>duplex</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default) then the pipe is bidirectional.  If1128<em>duplex</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> then the pipe is unidirectional: <code class="docutils literal notranslate"><span class="pre">conn1</span></code> can only be1129used for receiving messages and <code class="docutils literal notranslate"><span class="pre">conn2</span></code> can only be used for sending1130messages.</p>1131<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code> method serializes the object using1132<a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pickle</span></code></a> and the <code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code> re-creates the object.</p>1133</dd></dl>1134 1135<dl class="py class">1136<dt class="sig sig-object py" id="multiprocessing.Queue">1137<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">multiprocessing.</span></span><span class="sig-name descname"><span class="pre">Queue</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">maxsize</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Queue" title="Link to this definition">¶</a></dt>1138<dd><p>Returns a process shared queue implemented using a pipe and a few1139locks/semaphores.  When a process first puts an item on the queue a feeder1140thread is started which transfers objects from a buffer into the pipe.</p>1141<p>Instantiating this class may set the global start method. See1142<a class="reference internal" href="#global-start-method"><span class="std std-ref">Global start method</span></a> for more details.</p>1143<p>The usual <a class="reference internal" href="queue.html#queue.Empty" title="queue.Empty"><code class="xref py py-exc docutils literal notranslate"><span class="pre">queue.Empty</span></code></a> and <a class="reference internal" href="queue.html#queue.Full" title="queue.Full"><code class="xref py py-exc docutils literal notranslate"><span class="pre">queue.Full</span></code></a> exceptions from the1144standard library’s <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> module are raised to signal timeouts.</p>1145<p><code class="xref py py-class docutils literal notranslate"><span class="pre">Queue</span></code> implements all the methods of <a class="reference internal" href="queue.html#queue.Queue" title="queue.Queue"><code class="xref py py-class docutils literal notranslate"><span class="pre">queue.Queue</span></code></a> except for1146<a class="reference internal" href="queue.html#queue.Queue.task_done" title="queue.Queue.task_done"><code class="xref py py-meth docutils literal notranslate"><span class="pre">task_done()</span></code></a> and <a class="reference internal" href="queue.html#queue.Queue.join" title="queue.Queue.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>.</p>1147<dl class="py method">1148<dt class="sig sig-object py" id="multiprocessing.Queue.qsize">1149<span class="sig-name descname"><span class="pre">qsize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Queue.qsize" title="Link to this definition">¶</a></dt>1150<dd><p>Return the approximate size of the queue.  Because of1151multithreading/multiprocessing semantics, this number is not reliable.</p>1152<p>Note that this may raise <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a> on platforms like1153macOS where <code class="docutils literal notranslate"><span class="pre">sem_getvalue()</span></code> is not implemented.</p>1154</dd></dl>1155 1156<dl class="py method">1157<dt class="sig sig-object py" id="multiprocessing.Queue.empty">1158<span class="sig-name descname"><span class="pre">empty</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Queue.empty" title="Link to this definition">¶</a></dt>1159<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the queue is empty, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.  Because of1160multithreading/multiprocessing semantics, this is not reliable.</p>1161<p>May raise an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> on closed queues. (not guaranteed)</p>1162</dd></dl>1163 1164<dl class="py method">1165<dt class="sig sig-object py" id="multiprocessing.Queue.full">1166<span class="sig-name descname"><span class="pre">full</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Queue.full" title="Link to this definition">¶</a></dt>1167<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the queue is full, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.  Because of1168multithreading/multiprocessing semantics, this is not reliable.</p>1169</dd></dl>1170 1171<dl class="py method">1172<dt class="sig sig-object py" id="multiprocessing.Queue.put">1173<span class="sig-name descname"><span class="pre">put</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">block</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span></em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Queue.put" title="Link to this definition">¶</a></dt>1174<dd><p>Put obj into the queue.  If the optional argument <em>block</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>1175(the default) and <em>timeout</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), block if necessary until1176a free slot is available.  If <em>timeout</em> is a positive number, it blocks at1177most <em>timeout</em> seconds and raises the <a class="reference internal" href="queue.html#queue.Full" title="queue.Full"><code class="xref py py-exc docutils literal notranslate"><span class="pre">queue.Full</span></code></a> exception if no1178free slot was available within that time.  Otherwise (<em>block</em> is1179<code class="docutils literal notranslate"><span class="pre">False</span></code>), put an item on the queue if a free slot is immediately1180available, else raise the <code class="xref py py-exc docutils literal notranslate"><span class="pre">queue.Full</span></code> exception (<em>timeout</em> is1181ignored in that case).</p>1182<div class="versionchanged">1183<p><span class="versionmodified changed">Changed in version 3.8: </span>If the queue is closed, <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 instead of1184<a class="reference internal" href="exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AssertionError</span></code></a>.</p>1185</div>1186</dd></dl>1187 1188<dl class="py method">1189<dt class="sig sig-object py" id="multiprocessing.Queue.put_nowait">1190<span class="sig-name descname"><span class="pre">put_nowait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Queue.put_nowait" title="Link to this definition">¶</a></dt>1191<dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">put(obj,</span> <span class="pre">False)</span></code>.</p>1192</dd></dl>1193 1194<dl class="py method">1195<dt class="sig sig-object py" id="multiprocessing.Queue.get">1196<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">block</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span></em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#multiprocessing.Queue.get" title="Link to this definition">¶</a></dt>1197<dd><p>Remove and return an item from the queue.  If optional args <em>block</em> is1198<code class="docutils literal notranslate"><span class="pre">True</span></code> (the default) and <em>timeout</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), block if1199necessary until an item is available.  If <em>timeout</em> is a positive number,1200it blocks at most <em>timeout</em> seconds and raises the <a class="reference internal" href="queue.html#queue.Empty" title="queue.Empty"><code class="xref py py-exc docutils literal notranslate"><span class="pre">queue.Empty</span></code></a>

Showing the first 1,200 of 3992 lines. Download the file for the rest.