Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Прати 1
Волим 0
Вики 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Грана: master
Гране Ознаке
${ item.name }
Create branch ${ searchTerm }
from 'master'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/concurrent.futures.html

954 lines
87KB
Датотека Пермалинк Blame Историја 

  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="concurrent.futures — Launching parallel tasks" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/library/concurrent.futures.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="Source code: Lib/concurrent/futures/thread.py and Lib/concurrent/futures/process.py The concurrent.futures module provides a high-level interface for asynchronously executing callables. The asynchr..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="Source code: Lib/concurrent/futures/thread.py and Lib/concurrent/futures/process.py The concurrent.futures module provides a high-level interface for asynchronously executing callables. The asynchr..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>concurrent.futures — Launching parallel tasks &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="subprocess — Subprocess management" href="subprocess.html" />

  39.     <link rel="prev" title="The concurrent package" href="concurrent.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/concurrent.futures.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <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>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> — Launching parallel tasks</a><ul>

  99. <li><a class="reference internal" href="#executor-objects">Executor Objects</a></li>

  100. <li><a class="reference internal" href="#threadpoolexecutor">ThreadPoolExecutor</a><ul>

  101. <li><a class="reference internal" href="#threadpoolexecutor-example">ThreadPoolExecutor Example</a></li>

  102. </ul>

  103. </li>

  104. <li><a class="reference internal" href="#processpoolexecutor">ProcessPoolExecutor</a><ul>

  105. <li><a class="reference internal" href="#processpoolexecutor-example">ProcessPoolExecutor Example</a></li>

  106. </ul>

  107. </li>

  108. <li><a class="reference internal" href="#future-objects">Future Objects</a></li>

  109. <li><a class="reference internal" href="#module-functions">Module Functions</a></li>

  110. <li><a class="reference internal" href="#exception-classes">Exception classes</a></li>

  111. </ul>

  112. </li>

  113. </ul>

  114. 

  115.   </div>

  116.   <div>

  117.     <h4>Previous topic</h4>

  118.     <p class="topless"><a href="concurrent.html"

  119.                           title="previous chapter">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent</span></code> package</a></p>

  120.   </div>

  121.   <div>

  122.     <h4>Next topic</h4>

  123.     <p class="topless"><a href="subprocess.html"

  124.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> — Subprocess management</a></p>

  125.   </div>

  126.   <div role="note" aria-label="source link">

  127.     <h3>This Page</h3>

  128.     <ul class="this-page-menu">

  129.       <li><a href="../bugs.html">Report a Bug</a></li>

  130.       <li>

  131.         <a href="https://github.com/python/cpython/blob/main/Doc/library/concurrent.futures.rst"

  132.             rel="nofollow">Show Source

  133.         </a>

  134.       </li>

  135.     </ul>

  136.   </div>

  137.         </nav>

  138.     </div>

  139. </div>

  140. 

  141.   

  142.     <div class="related" role="navigation" aria-label="related navigation">

  143.       <h3>Navigation</h3>

  144.       <ul>

  145.         <li class="right" style="margin-right: 10px">

  146.           <a href="../genindex.html" title="General Index"

  147.              accesskey="I">index</a></li>

  148.         <li class="right" >

  149.           <a href="../py-modindex.html" title="Python Module Index"

  150.              >modules</a> |</li>

  151.         <li class="right" >

  152.           <a href="subprocess.html" title="subprocess — Subprocess management"

  153.              accesskey="N">next</a> |</li>

  154.         <li class="right" >

  155.           <a href="concurrent.html" title="The concurrent package"

  156.              accesskey="P">previous</a> |</li>

  157. 

  158.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  159.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  160.           <li class="switchers">

  161.             <div class="language_switcher_placeholder"></div>

  162.             <div class="version_switcher_placeholder"></div>

  163.           </li>

  164.           <li>

  165.               

  166.           </li>

  167.     <li id="cpython-language-and-version">

  168.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  169.     </li>

  170. 

  171.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  172.           <li class="nav-item nav-item-2"><a href="concurrency.html" accesskey="U">Concurrent Execution</a> &#187;</li>

  173.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> — Launching parallel tasks</a></li>

  174.                 <li class="right">

  175.                     

  176. 

  177.     <div class="inline-search" role="search">

  178.         <form class="inline-search" action="../search.html" method="get">

  179.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  180.           <input type="submit" value="Go" />

  181.         </form>

  182.     </div>

  183.                      |

  184.                 </li>

  185.             <li class="right">

  186. <label class="theme-selector-label">

  187.     Theme

  188.     <select class="theme-selector" oninput="activateTheme(this.value)">

  189.         <option value="auto" selected>Auto</option>

  190.         <option value="light">Light</option>

  191.         <option value="dark">Dark</option>

  192.     </select>

  193. </label> |</li>

  194.             

  195.       </ul>

  196.     </div>    

  197. 

  198.     <div class="document">

  199.       <div class="documentwrapper">

  200.         <div class="bodywrapper">

  201.           <div class="body" role="main">

  202.             

  203.   <section id="module-concurrent.futures">

  204. <span id="concurrent-futures-launching-parallel-tasks"></span><h1><a class="reference internal" href="#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> — Launching parallel tasks<a class="headerlink" href="#module-concurrent.futures" title="Link to this heading">¶</a></h1>

  205. <div class="versionadded">

  206. <p><span class="versionmodified added">New in version 3.2.</span></p>

  207. </div>

  208. <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/concurrent/futures/thread.py">Lib/concurrent/futures/thread.py</a>

  209. and <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/concurrent/futures/process.py">Lib/concurrent/futures/process.py</a></p>

  210. <hr class="docutils" />

  211. <p>The <a class="reference internal" href="#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> module provides a high-level interface for

  212. asynchronously executing callables.</p>

  213. <p>The asynchronous execution can be performed with threads, using

  214. <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a>, or separate processes, using

  215. <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a>.  Both implement the same interface, which is

  216. defined by the abstract <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> class.</p>

  217. <div class="availability docutils container">

  218. <p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: not Emscripten, not WASI.</p>

  219. <p>This module does not work or is not available on WebAssembly platforms

  220. <code class="docutils literal notranslate"><span class="pre">wasm32-emscripten</span></code> and <code class="docutils literal notranslate"><span class="pre">wasm32-wasi</span></code>. See

  221. <a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p>

  222. </div>

  223. <section id="executor-objects">

  224. <h2>Executor Objects<a class="headerlink" href="#executor-objects" title="Link to this heading">¶</a></h2>

  225. <dl class="py class">

  226. <dt class="sig sig-object py" id="concurrent.futures.Executor">

  227. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">Executor</span></span><a class="headerlink" href="#concurrent.futures.Executor" title="Link to this definition">¶</a></dt>

  228. <dd><p>An abstract class that provides methods to execute calls asynchronously.  It

  229. should not be used directly, but through its concrete subclasses.</p>

  230. <dl class="py method">

  231. <dt class="sig sig-object py" id="concurrent.futures.Executor.submit">

  232. <span class="sig-name descname"><span class="pre">submit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fn</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">/</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Executor.submit" title="Link to this definition">¶</a></dt>

  233. <dd><p>Schedules the callable, <em>fn</em>, to be executed as <code class="docutils literal notranslate"><span class="pre">fn(*args,</span> <span class="pre">**kwargs)</span></code>

  234. and returns a <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> object representing the execution of the

  235. callable.</p>

  236. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> <span class="k">as</span> <span class="n">executor</span><span class="p">:</span>

  237.     <span class="n">future</span> <span class="o">=</span> <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="nb">pow</span><span class="p">,</span> <span class="mi">323</span><span class="p">,</span> <span class="mi">1235</span><span class="p">)</span>

  238.     <span class="nb">print</span><span class="p">(</span><span class="n">future</span><span class="o">.</span><span class="n">result</span><span class="p">())</span>

  239. </pre></div>

  240. </div>

  241. </dd></dl>

  242. 

  243. <dl class="py method">

  244. <dt class="sig sig-object py" id="concurrent.futures.Executor.map">

  245. <span class="sig-name descname"><span class="pre">map</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fn</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">iterables</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">chunksize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Executor.map" title="Link to this definition">¶</a></dt>

  246. <dd><p>Similar to <a class="reference internal" href="functions.html#map" title="map"><code class="xref py py-func docutils literal notranslate"><span class="pre">map(fn,</span> <span class="pre">*iterables)</span></code></a> except:</p>

  247. <ul class="simple">

  248. <li><p>the <em>iterables</em> are collected immediately rather than lazily;</p></li>

  249. <li><p><em>fn</em> is executed asynchronously and several calls to

  250. <em>fn</em> may be made concurrently.</p></li>

  251. </ul>

  252. <p>The returned iterator raises a <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>

  253. if <a class="reference internal" href="stdtypes.html#iterator.__next__" title="iterator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a> is called and the result isn’t available

  254. after <em>timeout</em> seconds from the original call to <a class="reference internal" href="#concurrent.futures.Executor.map" title="concurrent.futures.Executor.map"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.map()</span></code></a>.

  255. <em>timeout</em> can be an int or a float.  If <em>timeout</em> is not specified or

  256. <code class="docutils literal notranslate"><span class="pre">None</span></code>, there is no limit to the wait time.</p>

  257. <p>If a <em>fn</em> call raises an exception, then that exception will be

  258. raised when its value is retrieved from the iterator.</p>

  259. <p>When using <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a>, this method chops <em>iterables</em>

  260. into a number of chunks which it submits to the pool as separate

  261. tasks.  The (approximate) size of these chunks can be specified by

  262. setting <em>chunksize</em> to a positive integer.  For very long iterables,

  263. using a large value for <em>chunksize</em> can significantly improve

  264. performance compared to the default size of 1.  With

  265. <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a>, <em>chunksize</em> has no effect.</p>

  266. <div class="versionchanged">

  267. <p><span class="versionmodified changed">Changed in version 3.5: </span>Added the <em>chunksize</em> argument.</p>

  268. </div>

  269. </dd></dl>

  270. 

  271. <dl class="py method">

  272. <dt class="sig sig-object py" id="concurrent.futures.Executor.shutdown">

  273. <span class="sig-name descname"><span class="pre">shutdown</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">wait</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cancel_futures</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Executor.shutdown" title="Link to this definition">¶</a></dt>

  274. <dd><p>Signal the executor that it should free any resources that it is using

  275. when the currently pending futures are done executing.  Calls to

  276. <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.submit()</span></code></a> and <a class="reference internal" href="#concurrent.futures.Executor.map" title="concurrent.futures.Executor.map"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.map()</span></code></a> made after shutdown will

  277. raise <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a>.</p>

  278. <p>If <em>wait</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> then this method will not return until all the

  279. pending futures are done executing and the resources associated with the

  280. executor have been freed.  If <em>wait</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> then this method will

  281. return immediately and the resources associated with the executor will be

  282. freed when all pending futures are done executing.  Regardless of the

  283. value of <em>wait</em>, the entire Python program will not exit until all

  284. pending futures are done executing.</p>

  285. <p>If <em>cancel_futures</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, this method will cancel all pending

  286. futures that the executor has not started running. Any futures that

  287. are completed or running won’t be cancelled, regardless of the value

  288. of <em>cancel_futures</em>.</p>

  289. <p>If both <em>cancel_futures</em> and <em>wait</em> are <code class="docutils literal notranslate"><span class="pre">True</span></code>, all futures that the

  290. executor has started running will be completed prior to this method

  291. returning. The remaining futures are cancelled.</p>

  292. <p>You can avoid having to call this method explicitly if you use the

  293. <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement, which will shutdown the <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a>

  294. (waiting as if <a class="reference internal" href="#concurrent.futures.Executor.shutdown" title="concurrent.futures.Executor.shutdown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.shutdown()</span></code></a> were called with <em>wait</em> set to

  295. <code class="docutils literal notranslate"><span class="pre">True</span></code>):</p>

  296. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">shutil</span>

  297. <span class="k">with</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>

  298.     <span class="n">e</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">shutil</span><span class="o">.</span><span class="n">copy</span><span class="p">,</span> <span class="s1">&#39;src1.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;dest1.txt&#39;</span><span class="p">)</span>

  299.     <span class="n">e</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">shutil</span><span class="o">.</span><span class="n">copy</span><span class="p">,</span> <span class="s1">&#39;src2.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;dest2.txt&#39;</span><span class="p">)</span>

  300.     <span class="n">e</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">shutil</span><span class="o">.</span><span class="n">copy</span><span class="p">,</span> <span class="s1">&#39;src3.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;dest3.txt&#39;</span><span class="p">)</span>

  301.     <span class="n">e</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">shutil</span><span class="o">.</span><span class="n">copy</span><span class="p">,</span> <span class="s1">&#39;src4.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;dest4.txt&#39;</span><span class="p">)</span>

  302. </pre></div>

  303. </div>

  304. <div class="versionchanged">

  305. <p><span class="versionmodified changed">Changed in version 3.9: </span>Added <em>cancel_futures</em>.</p>

  306. </div>

  307. </dd></dl>

  308. 

  309. </dd></dl>

  310. 

  311. </section>

  312. <section id="threadpoolexecutor">

  313. <h2>ThreadPoolExecutor<a class="headerlink" href="#threadpoolexecutor" title="Link to this heading">¶</a></h2>

  314. <p><a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a> is an <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> subclass that uses a pool of

  315. threads to execute calls asynchronously.</p>

  316. <p>Deadlocks can occur when the callable associated with a <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> waits on

  317. the results of another <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a>.  For example:</p>

  318. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">time</span>

  319. <span class="k">def</span> <span class="nf">wait_on_b</span><span class="p">():</span>

  320.     <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>

  321.     <span class="nb">print</span><span class="p">(</span><span class="n">b</span><span class="o">.</span><span class="n">result</span><span class="p">())</span>  <span class="c1"># b will never complete because it is waiting on a.</span>

  322.     <span class="k">return</span> <span class="mi">5</span>

  323. 

  324. <span class="k">def</span> <span class="nf">wait_on_a</span><span class="p">():</span>

  325.     <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>

  326.     <span class="nb">print</span><span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">result</span><span class="p">())</span>  <span class="c1"># a will never complete because it is waiting on b.</span>

  327.     <span class="k">return</span> <span class="mi">6</span>

  328. 

  329. 

  330. <span class="n">executor</span> <span class="o">=</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>

  331. <span class="n">a</span> <span class="o">=</span> <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">wait_on_b</span><span class="p">)</span>

  332. <span class="n">b</span> <span class="o">=</span> <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">wait_on_a</span><span class="p">)</span>

  333. </pre></div>

  334. </div>

  335. <p>And:</p>

  336. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">wait_on_future</span><span class="p">():</span>

  337.     <span class="n">f</span> <span class="o">=</span> <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="nb">pow</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>

  338.     <span class="c1"># This will never complete because there is only one worker thread and</span>

  339.     <span class="c1"># it is executing this function.</span>

  340.     <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">result</span><span class="p">())</span>

  341. 

  342. <span class="n">executor</span> <span class="o">=</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>

  343. <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">wait_on_future</span><span class="p">)</span>

  344. </pre></div>

  345. </div>

  346. <dl class="py class">

  347. <dt class="sig sig-object py" id="concurrent.futures.ThreadPoolExecutor">

  348. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">ThreadPoolExecutor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">max_workers</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">thread_name_prefix</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">initializer</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">initargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.ThreadPoolExecutor" title="Link to this definition">¶</a></dt>

  349. <dd><p>An <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> subclass that uses a pool of at most <em>max_workers</em>

  350. threads to execute calls asynchronously.</p>

  351. <p>All threads enqueued to <code class="docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code> will be joined before the

  352. interpreter can exit. Note that the exit handler which does this is

  353. executed <em>before</em> any exit handlers added using <code class="docutils literal notranslate"><span class="pre">atexit</span></code>. This means

  354. exceptions in the main thread must be caught and handled in order to

  355. signal threads to exit gracefully. For this reason, it is recommended

  356. that <code class="docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code> not be used for long-running tasks.</p>

  357. <p><em>initializer</em> is an optional callable that is called at the start of

  358. each worker thread; <em>initargs</em> is a tuple of arguments passed to the

  359. initializer.  Should <em>initializer</em> raise an exception, all currently

  360. pending jobs will raise a <a class="reference internal" href="#concurrent.futures.thread.BrokenThreadPool" title="concurrent.futures.thread.BrokenThreadPool"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenThreadPool</span></code></a>,

  361. as well as any attempt to submit more jobs to the pool.</p>

  362. <div class="versionchanged">

  363. <p><span class="versionmodified changed">Changed in version 3.5: </span>If <em>max_workers</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> or

  364. not given, it will default to the number of processors on the machine,

  365. multiplied by <code class="docutils literal notranslate"><span class="pre">5</span></code>, assuming that <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a> is often

  366. used to overlap I/O instead of CPU work and the number of workers

  367. should be higher than the number of workers

  368. for <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a>.</p>

  369. </div>

  370. <div class="versionchanged">

  371. <p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <em>thread_name_prefix</em> parameter to allow users to

  372. control 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> names for worker threads created by

  373. the pool for easier debugging.</p>

  374. </div>

  375. <div class="versionchanged">

  376. <p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>initializer</em> and <em>initargs</em> arguments.</p>

  377. </div>

  378. <div class="versionchanged">

  379. <p><span class="versionmodified changed">Changed in version 3.8: </span>Default value of <em>max_workers</em> is changed to <code class="docutils literal notranslate"><span class="pre">min(32,</span> <span class="pre">os.cpu_count()</span> <span class="pre">+</span> <span class="pre">4)</span></code>.

  380. This default value preserves at least 5 workers for I/O bound tasks.

  381. It utilizes at most 32 CPU cores for CPU bound tasks which release the GIL.

  382. And it avoids using very large resources implicitly on many-core machines.</p>

  383. <p>ThreadPoolExecutor now reuses idle worker threads before starting

  384. <em>max_workers</em> worker threads too.</p>

  385. </div>

  386. </dd></dl>

  387. 

  388. <section id="threadpoolexecutor-example">

  389. <span id="id1"></span><h3>ThreadPoolExecutor Example<a class="headerlink" href="#threadpoolexecutor-example" title="Link to this heading">¶</a></h3>

  390. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">concurrent.futures</span>

  391. <span class="kn">import</span> <span class="nn">urllib.request</span>

  392. 

  393. <span class="n">URLS</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;http://www.foxnews.com/&#39;</span><span class="p">,</span>

  394.         <span class="s1">&#39;http://www.cnn.com/&#39;</span><span class="p">,</span>

  395.         <span class="s1">&#39;http://europe.wsj.com/&#39;</span><span class="p">,</span>

  396.         <span class="s1">&#39;http://www.bbc.co.uk/&#39;</span><span class="p">,</span>

  397.         <span class="s1">&#39;http://nonexistant-subdomain.python.org/&#39;</span><span class="p">]</span>

  398. 

  399. <span class="c1"># Retrieve a single page and report the URL and contents</span>

  400. <span class="k">def</span> <span class="nf">load_url</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">timeout</span><span class="p">):</span>

  401.     <span class="k">with</span> <span class="n">urllib</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">urlopen</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="n">timeout</span><span class="p">)</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>

  402.         <span class="k">return</span> <span class="n">conn</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>

  403. 

  404. <span class="c1"># We can use a with statement to ensure threads are cleaned up promptly</span>

  405. <span class="k">with</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span> <span class="k">as</span> <span class="n">executor</span><span class="p">:</span>

  406.     <span class="c1"># Start the load operations and mark each future with its URL</span>

  407.     <span class="n">future_to_url</span> <span class="o">=</span> <span class="p">{</span><span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">load_url</span><span class="p">,</span> <span class="n">url</span><span class="p">,</span> <span class="mi">60</span><span class="p">):</span> <span class="n">url</span> <span class="k">for</span> <span class="n">url</span> <span class="ow">in</span> <span class="n">URLS</span><span class="p">}</span>

  408.     <span class="k">for</span> <span class="n">future</span> <span class="ow">in</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">as_completed</span><span class="p">(</span><span class="n">future_to_url</span><span class="p">):</span>

  409.         <span class="n">url</span> <span class="o">=</span> <span class="n">future_to_url</span><span class="p">[</span><span class="n">future</span><span class="p">]</span>

  410.         <span class="k">try</span><span class="p">:</span>

  411.             <span class="n">data</span> <span class="o">=</span> <span class="n">future</span><span class="o">.</span><span class="n">result</span><span class="p">()</span>

  412.         <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>

  413.             <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%r</span><span class="s1"> generated an exception: </span><span class="si">%s</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">exc</span><span class="p">))</span>

  414.         <span class="k">else</span><span class="p">:</span>

  415.             <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%r</span><span class="s1"> page is </span><span class="si">%d</span><span class="s1"> bytes&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">data</span><span class="p">)))</span>

  416. </pre></div>

  417. </div>

  418. </section>

  419. </section>

  420. <section id="processpoolexecutor">

  421. <h2>ProcessPoolExecutor<a class="headerlink" href="#processpoolexecutor" title="Link to this heading">¶</a></h2>

  422. <p>The <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> class is an <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> subclass that

  423. uses a pool of processes to execute calls asynchronously.

  424. <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> uses the <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> module, which

  425. allows it to side-step the <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">Global Interpreter Lock</span></a> but also means that

  426. only picklable objects can be executed and returned.</p>

  427. <p>The <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module must be importable by worker subprocesses. This means

  428. that <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> will not work in the interactive interpreter.</p>

  429. <p>Calling <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> or <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> methods from a callable submitted

  430. to a <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> will result in deadlock.</p>

  431. <dl class="py class">

  432. <dt class="sig sig-object py" id="concurrent.futures.ProcessPoolExecutor">

  433. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">ProcessPoolExecutor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">max_workers</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">mp_context</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">initializer</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">initargs</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">max_tasks_per_child</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="#concurrent.futures.ProcessPoolExecutor" title="Link to this definition">¶</a></dt>

  434. <dd><p>An <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> subclass that executes calls asynchronously using a pool

  435. of at most <em>max_workers</em> processes.  If <em>max_workers</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> or not

  436. given, it will default to the number of processors on the machine.

  437. If <em>max_workers</em> is less than or equal to <code class="docutils literal notranslate"><span class="pre">0</span></code>, then a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>

  438. will be raised.

  439. On Windows, <em>max_workers</em> must be less than or equal to <code class="docutils literal notranslate"><span class="pre">61</span></code>. If it is not

  440. then <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> will be raised. If <em>max_workers</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, then

  441. the default chosen will be at most <code class="docutils literal notranslate"><span class="pre">61</span></code>, even if more processors are

  442. available.

  443. <em>mp_context</em> can be a <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> context or <code class="docutils literal notranslate"><span class="pre">None</span></code>. It will be

  444. used to launch the workers. If <em>mp_context</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> or not given, the

  445. default <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> context is used.

  446. See <a class="reference internal" href="multiprocessing.html#multiprocessing-start-methods"><span class="std std-ref">Contexts and start methods</span></a>.</p>

  447. <p><em>initializer</em> is an optional callable that is called at the start of

  448. each worker process; <em>initargs</em> is a tuple of arguments passed to the

  449. initializer.  Should <em>initializer</em> raise an exception, all currently

  450. pending jobs will raise a <a class="reference internal" href="#concurrent.futures.process.BrokenProcessPool" title="concurrent.futures.process.BrokenProcessPool"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenProcessPool</span></code></a>,

  451. as well as any attempt to submit more jobs to the pool.</p>

  452. <p><em>max_tasks_per_child</em> is an optional argument that specifies the maximum

  453. number of tasks a single process can execute before it will exit and be

  454. replaced with a fresh worker process. By default <em>max_tasks_per_child</em> is

  455. <code class="docutils literal notranslate"><span class="pre">None</span></code> which means worker processes will live as long as the pool. When

  456. a max is specified, the “spawn” multiprocessing start method will be used by

  457. default in absence of a <em>mp_context</em> parameter. This feature is incompatible

  458. with the “fork” start method.</p>

  459. <div class="versionchanged">

  460. <p><span class="versionmodified changed">Changed in version 3.3: </span>When one of the worker processes terminates abruptly, a

  461. <a class="reference internal" href="#concurrent.futures.process.BrokenProcessPool" title="concurrent.futures.process.BrokenProcessPool"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenProcessPool</span></code></a> error is now raised.

  462. Previously, behaviour

  463. was undefined but operations on the executor or its futures would often

  464. freeze or deadlock.</p>

  465. </div>

  466. <div class="versionchanged">

  467. <p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>mp_context</em> argument was added to allow users to control the

  468. start_method for worker processes created by the pool.</p>

  469. <p>Added the <em>initializer</em> and <em>initargs</em> arguments.</p>

  470. <div class="admonition note">

  471. <p class="admonition-title">Note</p>

  472. <p>The default <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> start method

  473. (see <a class="reference internal" href="multiprocessing.html#multiprocessing-start-methods"><span class="std std-ref">Contexts and start methods</span></a>) will change away from

  474. <em>fork</em> in Python 3.14.  Code that requires <em>fork</em> be used for their

  475. <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a> should explicitly specify that by

  476. passing a <code class="docutils literal notranslate"><span class="pre">mp_context=multiprocessing.get_context(&quot;fork&quot;)</span></code>

  477. parameter.</p>

  478. </div>

  479. </div>

  480. <div class="versionchanged">

  481. <p><span class="versionmodified changed">Changed in version 3.11: </span>The <em>max_tasks_per_child</em> argument was added to allow users to

  482. control the lifetime of workers in the pool.</p>

  483. </div>

  484. <div class="versionchanged">

  485. <p><span class="versionmodified changed">Changed in version 3.12: </span>On POSIX systems, if your application has multiple threads and the

  486. <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> context uses the <code class="docutils literal notranslate"><span class="pre">&quot;fork&quot;</span></code> start method:

  487. The <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 called internally to spawn workers may raise a

  488. <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>. Pass a <em>mp_context</em> configured to use a

  489. different start method. See the <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> documentation for

  490. further explanation.</p>

  491. </div>

  492. </dd></dl>

  493. 

  494. <section id="processpoolexecutor-example">

  495. <span id="id2"></span><h3>ProcessPoolExecutor Example<a class="headerlink" href="#processpoolexecutor-example" title="Link to this heading">¶</a></h3>

  496. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">concurrent.futures</span>

  497. <span class="kn">import</span> <span class="nn">math</span>

  498. 

  499. <span class="n">PRIMES</span> <span class="o">=</span> <span class="p">[</span>

  500.     <span class="mi">112272535095293</span><span class="p">,</span>

  501.     <span class="mi">112582705942171</span><span class="p">,</span>

  502.     <span class="mi">112272535095293</span><span class="p">,</span>

  503.     <span class="mi">115280095190773</span><span class="p">,</span>

  504.     <span class="mi">115797848077099</span><span class="p">,</span>

  505.     <span class="mi">1099726899285419</span><span class="p">]</span>

  506. 

  507. <span class="k">def</span> <span class="nf">is_prime</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>

  508.     <span class="k">if</span> <span class="n">n</span> <span class="o">&lt;</span> <span class="mi">2</span><span class="p">:</span>

  509.         <span class="k">return</span> <span class="kc">False</span>

  510.     <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">2</span><span class="p">:</span>

  511.         <span class="k">return</span> <span class="kc">True</span>

  512.     <span class="k">if</span> <span class="n">n</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>

  513.         <span class="k">return</span> <span class="kc">False</span>

  514. 

  515.     <span class="n">sqrt_n</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">floor</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">sqrt</span><span class="p">(</span><span class="n">n</span><span class="p">)))</span>

  516.     <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">3</span><span class="p">,</span> <span class="n">sqrt_n</span> <span class="o">+</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">):</span>

  517.         <span class="k">if</span> <span class="n">n</span> <span class="o">%</span> <span class="n">i</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>

  518.             <span class="k">return</span> <span class="kc">False</span>

  519.     <span class="k">return</span> <span class="kc">True</span>

  520. 

  521. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  522.     <span class="k">with</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">ProcessPoolExecutor</span><span class="p">()</span> <span class="k">as</span> <span class="n">executor</span><span class="p">:</span>

  523.         <span class="k">for</span> <span class="n">number</span><span class="p">,</span> <span class="n">prime</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">PRIMES</span><span class="p">,</span> <span class="n">executor</span><span class="o">.</span><span class="n">map</span><span class="p">(</span><span class="n">is_prime</span><span class="p">,</span> <span class="n">PRIMES</span><span class="p">)):</span>

  524.             <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%d</span><span class="s1"> is prime: </span><span class="si">%s</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">number</span><span class="p">,</span> <span class="n">prime</span><span class="p">))</span>

  525. 

  526. <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>

  527.     <span class="n">main</span><span class="p">()</span>

  528. </pre></div>

  529. </div>

  530. </section>

  531. </section>

  532. <section id="future-objects">

  533. <h2>Future Objects<a class="headerlink" href="#future-objects" title="Link to this heading">¶</a></h2>

  534. <p>The <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> class encapsulates the asynchronous execution of a callable.

  535. <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> instances are created by <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.submit()</span></code></a>.</p>

  536. <dl class="py class">

  537. <dt class="sig sig-object py" id="concurrent.futures.Future">

  538. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">Future</span></span><a class="headerlink" href="#concurrent.futures.Future" title="Link to this definition">¶</a></dt>

  539. <dd><p>Encapsulates the asynchronous execution of a callable.  <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a>

  540. instances are created by <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executor.submit()</span></code></a> and should not be created

  541. directly except for testing.</p>

  542. <dl class="py method">

  543. <dt class="sig sig-object py" id="concurrent.futures.Future.cancel">

  544. <span class="sig-name descname"><span class="pre">cancel</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.cancel" title="Link to this definition">¶</a></dt>

  545. <dd><p>Attempt to cancel the call.  If the call is currently being executed or

  546. finished running and cannot be cancelled then the method will return

  547. <code class="docutils literal notranslate"><span class="pre">False</span></code>, otherwise the call will be cancelled and the method will

  548. return <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>

  549. </dd></dl>

  550. 

  551. <dl class="py method">

  552. <dt class="sig sig-object py" id="concurrent.futures.Future.cancelled">

  553. <span class="sig-name descname"><span class="pre">cancelled</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.cancelled" title="Link to this definition">¶</a></dt>

  554. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the call was successfully cancelled.</p>

  555. </dd></dl>

  556. 

  557. <dl class="py method">

  558. <dt class="sig sig-object py" id="concurrent.futures.Future.running">

  559. <span class="sig-name descname"><span class="pre">running</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.running" title="Link to this definition">¶</a></dt>

  560. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the call is currently being executed and cannot be

  561. cancelled.</p>

  562. </dd></dl>

  563. 

  564. <dl class="py method">

  565. <dt class="sig sig-object py" id="concurrent.futures.Future.done">

  566. <span class="sig-name descname"><span class="pre">done</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.done" title="Link to this definition">¶</a></dt>

  567. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the call was successfully cancelled or finished

  568. running.</p>

  569. </dd></dl>

  570. 

  571. <dl class="py method">

  572. <dt class="sig sig-object py" id="concurrent.futures.Future.result">

  573. <span class="sig-name descname"><span class="pre">result</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.result" title="Link to this definition">¶</a></dt>

  574. <dd><p>Return the value returned by the call. If the call hasn’t yet completed

  575. then this method will wait up to <em>timeout</em> seconds.  If the call hasn’t

  576. completed in <em>timeout</em> seconds, then a

  577. <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a> will be raised. <em>timeout</em> can be

  578. an int or float.  If <em>timeout</em> is not specified or <code class="docutils literal notranslate"><span class="pre">None</span></code>, there is no

  579. limit to the wait time.</p>

  580. <p>If the future is cancelled before completing then <a class="reference internal" href="#concurrent.futures.CancelledError" title="concurrent.futures.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CancelledError</span></code></a>

  581. will be raised.</p>

  582. <p>If the call raised an exception, this method will raise the same exception.</p>

  583. </dd></dl>

  584. 

  585. <dl class="py method">

  586. <dt class="sig sig-object py" id="concurrent.futures.Future.exception">

  587. <span class="sig-name descname"><span class="pre">exception</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.exception" title="Link to this definition">¶</a></dt>

  588. <dd><p>Return the exception raised by the call.  If the call hasn’t yet

  589. completed then this method will wait up to <em>timeout</em> seconds.  If the

  590. call hasn’t completed in <em>timeout</em> seconds, then a

  591. <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a> will be raised.  <em>timeout</em> can be

  592. an int or float.  If <em>timeout</em> is not specified or <code class="docutils literal notranslate"><span class="pre">None</span></code>, there is no

  593. limit to the wait time.</p>

  594. <p>If the future is cancelled before completing then <a class="reference internal" href="#concurrent.futures.CancelledError" title="concurrent.futures.CancelledError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CancelledError</span></code></a>

  595. will be raised.</p>

  596. <p>If the call completed without raising, <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>

  597. </dd></dl>

  598. 

  599. <dl class="py method">

  600. <dt class="sig sig-object py" id="concurrent.futures.Future.add_done_callback">

  601. <span class="sig-name descname"><span class="pre">add_done_callback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fn</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.add_done_callback" title="Link to this definition">¶</a></dt>

  602. <dd><p>Attaches the callable <em>fn</em> to the future.  <em>fn</em> will be called, with the

  603. future as its only argument, when the future is cancelled or finishes

  604. running.</p>

  605. <p>Added callables are called in the order that they were added and are

  606. always called in a thread belonging to the process that added them.  If

  607. the callable raises an <a class="reference internal" href="exceptions.html#Exception" title="Exception"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Exception</span></code></a> subclass, it will be logged and

  608. ignored.  If the callable raises a <a class="reference internal" href="exceptions.html#BaseException" title="BaseException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BaseException</span></code></a> subclass, the

  609. behavior is undefined.</p>

  610. <p>If the future has already completed or been cancelled, <em>fn</em> will be

  611. called immediately.</p>

  612. </dd></dl>

  613. 

  614. <p>The following <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> methods are meant for use in unit tests and

  615. <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> implementations.</p>

  616. <dl class="py method">

  617. <dt class="sig sig-object py" id="concurrent.futures.Future.set_running_or_notify_cancel">

  618. <span class="sig-name descname"><span class="pre">set_running_or_notify_cancel</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.set_running_or_notify_cancel" title="Link to this definition">¶</a></dt>

  619. <dd><p>This method should only be called by <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> implementations

  620. before executing the work associated with the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> and by unit

  621. tests.</p>

  622. <p>If the method returns <code class="docutils literal notranslate"><span class="pre">False</span></code> then the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> was cancelled,

  623. i.e. <a class="reference internal" href="#concurrent.futures.Future.cancel" title="concurrent.futures.Future.cancel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Future.cancel()</span></code></a> was called and returned <code class="docutils literal notranslate"><span class="pre">True</span></code>.  Any threads

  624. waiting on the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> completing (i.e. through

  625. <a class="reference internal" href="#concurrent.futures.as_completed" title="concurrent.futures.as_completed"><code class="xref py py-func docutils literal notranslate"><span class="pre">as_completed()</span></code></a> or <a class="reference internal" href="#concurrent.futures.wait" title="concurrent.futures.wait"><code class="xref py py-func docutils literal notranslate"><span class="pre">wait()</span></code></a>) will be woken up.</p>

  626. <p>If the method returns <code class="docutils literal notranslate"><span class="pre">True</span></code> then the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> was not cancelled

  627. and has been put in the running state, i.e. calls to

  628. <a class="reference internal" href="#concurrent.futures.Future.running" title="concurrent.futures.Future.running"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Future.running()</span></code></a> will return <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>

  629. <p>This method can only be called once and cannot be called after

  630. <a class="reference internal" href="#concurrent.futures.Future.set_result" title="concurrent.futures.Future.set_result"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Future.set_result()</span></code></a> or <a class="reference internal" href="#concurrent.futures.Future.set_exception" title="concurrent.futures.Future.set_exception"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Future.set_exception()</span></code></a> have been

  631. called.</p>

  632. </dd></dl>

  633. 

  634. <dl class="py method">

  635. <dt class="sig sig-object py" id="concurrent.futures.Future.set_result">

  636. <span class="sig-name descname"><span class="pre">set_result</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">result</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.set_result" title="Link to this definition">¶</a></dt>

  637. <dd><p>Sets the result of the work associated with the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> to

  638. <em>result</em>.</p>

  639. <p>This method should only be used by <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> implementations and

  640. unit tests.</p>

  641. <div class="versionchanged">

  642. <p><span class="versionmodified changed">Changed in version 3.8: </span>This method raises

  643. <a class="reference internal" href="#concurrent.futures.InvalidStateError" title="concurrent.futures.InvalidStateError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">concurrent.futures.InvalidStateError</span></code></a> if the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> is

  644. already done.</p>

  645. </div>

  646. </dd></dl>

  647. 

  648. <dl class="py method">

  649. <dt class="sig sig-object py" id="concurrent.futures.Future.set_exception">

  650. <span class="sig-name descname"><span class="pre">set_exception</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">exception</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.Future.set_exception" title="Link to this definition">¶</a></dt>

  651. <dd><p>Sets the result of the work associated with the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> to the

  652. <a class="reference internal" href="exceptions.html#Exception" title="Exception"><code class="xref py py-class docutils literal notranslate"><span class="pre">Exception</span></code></a> <em>exception</em>.</p>

  653. <p>This method should only be used by <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> implementations and

  654. unit tests.</p>

  655. <div class="versionchanged">

  656. <p><span class="versionmodified changed">Changed in version 3.8: </span>This method raises

  657. <a class="reference internal" href="#concurrent.futures.InvalidStateError" title="concurrent.futures.InvalidStateError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">concurrent.futures.InvalidStateError</span></code></a> if the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> is

  658. already done.</p>

  659. </div>

  660. </dd></dl>

  661. 

  662. </dd></dl>

  663. 

  664. </section>

  665. <section id="module-functions">

  666. <h2>Module Functions<a class="headerlink" href="#module-functions" title="Link to this heading">¶</a></h2>

  667. <dl class="py function">

  668. <dt class="sig sig-object py" id="concurrent.futures.wait">

  669. <span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">wait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_when</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">ALL_COMPLETED</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.wait" title="Link to this definition">¶</a></dt>

  670. <dd><p>Wait for the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> instances (possibly created by different

  671. <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> instances) given by <em>fs</em> to complete. Duplicate futures

  672. given to <em>fs</em> are removed and will be returned only once. Returns a named

  673. 2-tuple of sets.  The first set, named <code class="docutils literal notranslate"><span class="pre">done</span></code>, contains the futures that

  674. completed (finished or cancelled futures) before the wait completed.  The

  675. second set, named <code class="docutils literal notranslate"><span class="pre">not_done</span></code>, contains the futures that did not complete

  676. (pending or running futures).</p>

  677. <p><em>timeout</em> can be used to control the maximum number of seconds to wait before

  678. returning.  <em>timeout</em> can be an int or float.  If <em>timeout</em> is not specified

  679. or <code class="docutils literal notranslate"><span class="pre">None</span></code>, there is no limit to the wait time.</p>

  680. <p><em>return_when</em> indicates when this function should return.  It must be one of

  681. the following constants:</p>

  682. <table class="docutils align-default">

  683. <thead>

  684. <tr class="row-odd"><th class="head"><p>Constant</p></th>

  685. <th class="head"><p>Description</p></th>

  686. </tr>

  687. </thead>

  688. <tbody>

  689. <tr class="row-even"><td><dl class="py data">

  690. <dt class="sig sig-object py" id="concurrent.futures.FIRST_COMPLETED">

  691. <span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">FIRST_COMPLETED</span></span><a class="headerlink" href="#concurrent.futures.FIRST_COMPLETED" title="Link to this definition">¶</a></dt>

  692. <dd></dd></dl>

  693. 

  694. </td>

  695. <td><p>The function will return when any future finishes or is cancelled.</p></td>

  696. </tr>

  697. <tr class="row-odd"><td><dl class="py data">

  698. <dt class="sig sig-object py" id="concurrent.futures.FIRST_EXCEPTION">

  699. <span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">FIRST_EXCEPTION</span></span><a class="headerlink" href="#concurrent.futures.FIRST_EXCEPTION" title="Link to this definition">¶</a></dt>

  700. <dd></dd></dl>

  701. 

  702. </td>

  703. <td><p>The function will return when any future finishes by raising an

  704. exception. If no future raises an exception

  705. then it is equivalent to <a class="reference internal" href="#concurrent.futures.ALL_COMPLETED" title="concurrent.futures.ALL_COMPLETED"><code class="xref py py-const docutils literal notranslate"><span class="pre">ALL_COMPLETED</span></code></a>.</p></td>

  706. </tr>

  707. <tr class="row-even"><td><dl class="py data">

  708. <dt class="sig sig-object py" id="concurrent.futures.ALL_COMPLETED">

  709. <span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">ALL_COMPLETED</span></span><a class="headerlink" href="#concurrent.futures.ALL_COMPLETED" title="Link to this definition">¶</a></dt>

  710. <dd></dd></dl>

  711. 

  712. </td>

  713. <td><p>The function will return when all futures finish or are cancelled.</p></td>

  714. </tr>

  715. </tbody>

  716. </table>

  717. </dd></dl>

  718. 

  719. <dl class="py function">

  720. <dt class="sig sig-object py" id="concurrent.futures.as_completed">

  721. <span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">as_completed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#concurrent.futures.as_completed" title="Link to this definition">¶</a></dt>

  722. <dd><p>Returns an iterator over the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> instances (possibly created by

  723. different <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Executor</span></code></a> instances) given by <em>fs</em> that yields futures as

  724. they complete (finished or cancelled futures). Any futures given by <em>fs</em> that

  725. are duplicated will be returned once. Any futures that completed before

  726. <a class="reference internal" href="#concurrent.futures.as_completed" title="concurrent.futures.as_completed"><code class="xref py py-func docutils literal notranslate"><span class="pre">as_completed()</span></code></a> is called will be yielded first.  The returned iterator

  727. raises a <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a> if <a class="reference internal" href="stdtypes.html#iterator.__next__" title="iterator.__next__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code></a>

  728. is called and the result isn’t available after <em>timeout</em> seconds from the

  729. original call to <a class="reference internal" href="#concurrent.futures.as_completed" title="concurrent.futures.as_completed"><code class="xref py py-func docutils literal notranslate"><span class="pre">as_completed()</span></code></a>.  <em>timeout</em> can be an int or float. If

  730. <em>timeout</em> is not specified or <code class="docutils literal notranslate"><span class="pre">None</span></code>, there is no limit to the wait time.</p>

  731. </dd></dl>

  732. 

  733. <div class="admonition seealso">

  734. <p class="admonition-title">See also</p>

  735. <dl class="simple">

  736. <dt><span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-3148/"><strong>PEP 3148</strong></a> – futures - execute computations asynchronously</dt><dd><p>The proposal which described this feature for inclusion in the Python

  737. standard library.</p>

  738. </dd>

  739. </dl>

  740. </div>

  741. </section>

  742. <section id="exception-classes">

  743. <h2>Exception classes<a class="headerlink" href="#exception-classes" title="Link to this heading">¶</a></h2>

  744. <dl class="py exception">

  745. <dt class="sig sig-object py" id="concurrent.futures.CancelledError">

  746. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">CancelledError</span></span><a class="headerlink" href="#concurrent.futures.CancelledError" title="Link to this definition">¶</a></dt>

  747. <dd><p>Raised when a future is cancelled.</p>

  748. </dd></dl>

  749. 

  750. <dl class="py exception">

  751. <dt class="sig sig-object py" id="concurrent.futures.TimeoutError">

  752. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">TimeoutError</span></span><a class="headerlink" href="#concurrent.futures.TimeoutError" title="Link to this definition">¶</a></dt>

  753. <dd><p>A deprecated alias of <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>,

  754. raised when a future operation exceeds the given timeout.</p>

  755. <div class="versionchanged">

  756. <p><span class="versionmodified changed">Changed in version 3.11: </span>This class was made an alias of <a class="reference internal" href="exceptions.html#TimeoutError" title="TimeoutError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutError</span></code></a>.</p>

  757. </div>

  758. </dd></dl>

  759. 

  760. <dl class="py exception">

  761. <dt class="sig sig-object py" id="concurrent.futures.BrokenExecutor">

  762. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">BrokenExecutor</span></span><a class="headerlink" href="#concurrent.futures.BrokenExecutor" title="Link to this definition">¶</a></dt>

  763. <dd><p>Derived from <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a>, this exception class is raised

  764. when an executor is broken for some reason, and cannot be used

  765. to submit or execute new tasks.</p>

  766. <div class="versionadded">

  767. <p><span class="versionmodified added">New in version 3.7.</span></p>

  768. </div>

  769. </dd></dl>

  770. 

  771. <dl class="py exception">

  772. <dt class="sig sig-object py" id="concurrent.futures.InvalidStateError">

  773. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.</span></span><span class="sig-name descname"><span class="pre">InvalidStateError</span></span><a class="headerlink" href="#concurrent.futures.InvalidStateError" title="Link to this definition">¶</a></dt>

  774. <dd><p>Raised when an operation is performed on a future that is not allowed

  775. in the current state.</p>

  776. <div class="versionadded">

  777. <p><span class="versionmodified added">New in version 3.8.</span></p>

  778. </div>

  779. </dd></dl>

  780. 

  781. <dl class="py exception">

  782. <dt class="sig sig-object py" id="concurrent.futures.thread.BrokenThreadPool">

  783. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.thread.</span></span><span class="sig-name descname"><span class="pre">BrokenThreadPool</span></span><a class="headerlink" href="#concurrent.futures.thread.BrokenThreadPool" title="Link to this definition">¶</a></dt>

  784. <dd><p>Derived from <a class="reference internal" href="#concurrent.futures.BrokenExecutor" title="concurrent.futures.BrokenExecutor"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenExecutor</span></code></a>, this exception

  785. class is raised when one of the workers

  786. of a <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadPoolExecutor</span></code></a>

  787. has failed initializing.</p>

  788. <div class="versionadded">

  789. <p><span class="versionmodified added">New in version 3.7.</span></p>

  790. </div>

  791. </dd></dl>

  792. 

  793. <dl class="py exception">

  794. <dt class="sig sig-object py" id="concurrent.futures.process.BrokenProcessPool">

  795. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">concurrent.futures.process.</span></span><span class="sig-name descname"><span class="pre">BrokenProcessPool</span></span><a class="headerlink" href="#concurrent.futures.process.BrokenProcessPool" title="Link to this definition">¶</a></dt>

  796. <dd><p>Derived from <a class="reference internal" href="#concurrent.futures.BrokenExecutor" title="concurrent.futures.BrokenExecutor"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BrokenExecutor</span></code></a> (formerly

  797. <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a>), this exception class is raised when one of the

  798. workers of a <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProcessPoolExecutor</span></code></a>

  799. has terminated in a non-clean

  800. fashion (for example, if it was killed from the outside).</p>

  801. <div class="versionadded">

  802. <p><span class="versionmodified added">New in version 3.3.</span></p>

  803. </div>

  804. </dd></dl>

  805. 

  806. </section>

  807. </section>

  808. 

  809. 

  810.             <div class="clearer"></div>

  811.           </div>

  812.         </div>

  813.       </div>

  814.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  815.         <div class="sphinxsidebarwrapper">

  816.   <div>

  817.     <h3><a href="../contents.html">Table of Contents</a></h3>

  818.     <ul>

  819. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> — Launching parallel tasks</a><ul>

  820. <li><a class="reference internal" href="#executor-objects">Executor Objects</a></li>

  821. <li><a class="reference internal" href="#threadpoolexecutor">ThreadPoolExecutor</a><ul>

  822. <li><a class="reference internal" href="#threadpoolexecutor-example">ThreadPoolExecutor Example</a></li>

  823. </ul>

  824. </li>

  825. <li><a class="reference internal" href="#processpoolexecutor">ProcessPoolExecutor</a><ul>

  826. <li><a class="reference internal" href="#processpoolexecutor-example">ProcessPoolExecutor Example</a></li>

  827. </ul>

  828. </li>

  829. <li><a class="reference internal" href="#future-objects">Future Objects</a></li>

  830. <li><a class="reference internal" href="#module-functions">Module Functions</a></li>

  831. <li><a class="reference internal" href="#exception-classes">Exception classes</a></li>

  832. </ul>

  833. </li>

  834. </ul>

  835. 

  836.   </div>

  837.   <div>

  838.     <h4>Previous topic</h4>

  839.     <p class="topless"><a href="concurrent.html"

  840.                           title="previous chapter">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent</span></code> package</a></p>

  841.   </div>

  842.   <div>

  843.     <h4>Next topic</h4>

  844.     <p class="topless"><a href="subprocess.html"

  845.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> — Subprocess management</a></p>

  846.   </div>

  847.   <div role="note" aria-label="source link">

  848.     <h3>This Page</h3>

  849.     <ul class="this-page-menu">

  850.       <li><a href="../bugs.html">Report a Bug</a></li>

  851.       <li>

  852.         <a href="https://github.com/python/cpython/blob/main/Doc/library/concurrent.futures.rst"

  853.             rel="nofollow">Show Source

  854.         </a>

  855.       </li>

  856.     </ul>

  857.   </div>

  858.         </div>

  859. <div id="sidebarbutton" title="Collapse sidebar">

  860. <span>«</span>

  861. </div>

  862. 

  863.       </div>

  864.       <div class="clearer"></div>

  865.     </div>  

  866.     <div class="related" role="navigation" aria-label="related navigation">

  867.       <h3>Navigation</h3>

  868.       <ul>

  869.         <li class="right" style="margin-right: 10px">

  870.           <a href="../genindex.html" title="General Index"

  871.              >index</a></li>

  872.         <li class="right" >

  873.           <a href="../py-modindex.html" title="Python Module Index"

  874.              >modules</a> |</li>

  875.         <li class="right" >

  876.           <a href="subprocess.html" title="subprocess — Subprocess management"

  877.              >next</a> |</li>

  878.         <li class="right" >

  879.           <a href="concurrent.html" title="The concurrent package"

  880.              >previous</a> |</li>

  881. 

  882.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  883.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  884.           <li class="switchers">

  885.             <div class="language_switcher_placeholder"></div>

  886.             <div class="version_switcher_placeholder"></div>

  887.           </li>

  888.           <li>

  889.               

  890.           </li>

  891.     <li id="cpython-language-and-version">

  892.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  893.     </li>

  894. 

  895.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  896.           <li class="nav-item nav-item-2"><a href="concurrency.html" >Concurrent Execution</a> &#187;</li>

  897.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code> — Launching parallel tasks</a></li>

  898.                 <li class="right">

  899.                     

  900. 

  901.     <div class="inline-search" role="search">

  902.         <form class="inline-search" action="../search.html" method="get">

  903.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  904.           <input type="submit" value="Go" />

  905.         </form>

  906.     </div>

  907.                      |

  908.                 </li>

  909.             <li class="right">

  910. <label class="theme-selector-label">

  911.     Theme

  912.     <select class="theme-selector" oninput="activateTheme(this.value)">

  913.         <option value="auto" selected>Auto</option>

  914.         <option value="light">Light</option>

  915.         <option value="dark">Dark</option>

  916.     </select>

  917. </label> |</li>

  918.             

  919.       </ul>

  920.     </div>  

  921.     <div class="footer">

  922.     &copy; 

  923.       <a href="../copyright.html">

  924.     

  925.     Copyright

  926.     

  927.       </a>

  928.      2001-2024, Python Software Foundation.

  929.     <br />

  930.     This page is licensed under the Python Software Foundation License Version 2.

  931.     <br />

  932.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  933.     <br />

  934.     

  935.       See <a href="/license.html">History and License</a> for more information.<br />

  936.     

  937.     

  938.     <br />

  939. 

  940.     The Python Software Foundation is a non-profit corporation.

  941. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  942. <br />

  943.     <br />

  944.       Last updated on Apr 09, 2024 (13:47 UTC).

  945.     

  946.       <a href="/bugs.html">Found a bug</a>?

  947.     

  948.     <br />

  949. 

  950.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  951.     </div>

  952. 

  953.   </body>

  954. </html>
上海开阖软件有限公司 沪ICP备12045867号-1