path: root/devdocs/python~3.12/library%2Fconcurrent.futures.html

 <span id="concurrent-futures-launching-parallel-tasks"></span><h1>concurrent.futures — Launching parallel tasks</h1> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> <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> 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>  <p>The <a class="reference internal" href="#module-concurrent.futures" title="concurrent.futures: Execute computations concurrently using threads or processes."><code>concurrent.futures</code></a> module provides a high-level interface for asynchronously executing callables.</p> <p>The asynchronous execution can be performed with threads, using <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code>ThreadPoolExecutor</code></a>, or separate processes, using <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code>ProcessPoolExecutor</code></a>. Both implement the same interface, which is defined by the abstract <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> class.</p> <div class="availability docutils container"> <p><a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#availability"><span class="std std-ref">Availability</span></a>: not Emscripten, not WASI.</p> <p>This module does not work or is not available on WebAssembly platforms <code>wasm32-emscripten</code> and <code>wasm32-wasi</code>. See <a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p> </div> <section id="executor-objects"> <h2>Executor Objects</h2> <dl class="py class"> <dt class="sig sig-object py" id="concurrent.futures.Executor">
<code>class concurrent.futures.Executor</code> </dt> <dd>
<p>An abstract class that provides methods to execute calls asynchronously. It should not be used directly, but through its concrete subclasses.</p> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Executor.submit">
<code>submit(fn, /, *args, **kwargs)</code> </dt> <dd>
<p>Schedules the callable, <em>fn</em>, to be executed as <code>fn(*args, **kwargs)</code> and returns a <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> object representing the execution of the callable.</p> <pre data-language="python">with ThreadPoolExecutor(max_workers=1) as executor:
    future = executor.submit(pow, 323, 1235)
    print(future.result())
</pre> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Executor.map">
<code>map(func, *iterables, timeout=None, chunksize=1)</code> </dt> <dd>
<p>Similar to <a class="reference internal" href="functions#map" title="map"><code>map(func, *iterables)</code></a> except:</p> <ul class="simple"> <li>the <em>iterables</em> are collected immediately rather than lazily;</li> <li>
<em>func</em> is executed asynchronously and several calls to <em>func</em> may be made concurrently.</li> </ul> <p>The returned iterator raises a <a class="reference internal" href="exceptions#TimeoutError" title="TimeoutError"><code>TimeoutError</code></a> if <a class="reference internal" href="stdtypes#iterator.__next__" title="iterator.__next__"><code>__next__()</code></a> is called and the result isn’t available 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>Executor.map()</code></a>. <em>timeout</em> can be an int or a float. If <em>timeout</em> is not specified or <code>None</code>, there is no limit to the wait time.</p> <p>If a <em>func</em> call raises an exception, then that exception will be raised when its value is retrieved from the iterator.</p> <p>When using <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code>ProcessPoolExecutor</code></a>, this method chops <em>iterables</em> into a number of chunks which it submits to the pool as separate tasks. The (approximate) size of these chunks can be specified by setting <em>chunksize</em> to a positive integer. For very long iterables, using a large value for <em>chunksize</em> can significantly improve performance compared to the default size of 1. With <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code>ThreadPoolExecutor</code></a>, <em>chunksize</em> has no effect.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>Added the <em>chunksize</em> argument.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Executor.shutdown">
<code>shutdown(wait=True, *, cancel_futures=False)</code> </dt> <dd>
<p>Signal the executor that it should free any resources that it is using when the currently pending futures are done executing. Calls to <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code>Executor.submit()</code></a> and <a class="reference internal" href="#concurrent.futures.Executor.map" title="concurrent.futures.Executor.map"><code>Executor.map()</code></a> made after shutdown will raise <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a>.</p> <p>If <em>wait</em> is <code>True</code> then this method will not return until all the pending futures are done executing and the resources associated with the executor have been freed. If <em>wait</em> is <code>False</code> then this method will return immediately and the resources associated with the executor will be freed when all pending futures are done executing. Regardless of the value of <em>wait</em>, the entire Python program will not exit until all pending futures are done executing.</p> <p>If <em>cancel_futures</em> is <code>True</code>, this method will cancel all pending futures that the executor has not started running. Any futures that are completed or running won’t be cancelled, regardless of the value of <em>cancel_futures</em>.</p> <p>If both <em>cancel_futures</em> and <em>wait</em> are <code>True</code>, all futures that the executor has started running will be completed prior to this method returning. The remaining futures are cancelled.</p> <p>You can avoid having to call this method explicitly if you use the <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement, which will shutdown the <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> (waiting as if <a class="reference internal" href="#concurrent.futures.Executor.shutdown" title="concurrent.futures.Executor.shutdown"><code>Executor.shutdown()</code></a> were called with <em>wait</em> set to <code>True</code>):</p> <pre data-language="python">import shutil
with ThreadPoolExecutor(max_workers=4) as e:
    e.submit(shutil.copy, 'src1.txt', 'dest1.txt')
    e.submit(shutil.copy, 'src2.txt', 'dest2.txt')
    e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
    e.submit(shutil.copy, 'src4.txt', 'dest4.txt')
</pre> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>Added <em>cancel_futures</em>.</p> </div> </dd>
</dl> </dd>
</dl> </section> <section id="threadpoolexecutor"> <h2>ThreadPoolExecutor</h2> <p><a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code>ThreadPoolExecutor</code></a> is an <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> subclass that uses a pool of threads to execute calls asynchronously.</p> <p>Deadlocks can occur when the callable associated with a <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> waits on the results of another <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a>. For example:</p> <pre data-language="python">import time
def wait_on_b():
    time.sleep(5)
    print(b.result())  # b will never complete because it is waiting on a.
    return 5

def wait_on_a():
    time.sleep(5)
    print(a.result())  # a will never complete because it is waiting on b.
    return 6


executor = ThreadPoolExecutor(max_workers=2)
a = executor.submit(wait_on_b)
b = executor.submit(wait_on_a)
</pre> <p>And:</p> <pre data-language="python">def wait_on_future():
    f = executor.submit(pow, 5, 2)
    # This will never complete because there is only one worker thread and
    # it is executing this function.
    print(f.result())

executor = ThreadPoolExecutor(max_workers=1)
executor.submit(wait_on_future)
</pre> <dl class="py class"> <dt class="sig sig-object py" id="concurrent.futures.ThreadPoolExecutor">
<code>class concurrent.futures.ThreadPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())</code> </dt> <dd>
<p>An <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> subclass that uses a pool of at most <em>max_workers</em> threads to execute calls asynchronously.</p> <p>All threads enqueued to <code>ThreadPoolExecutor</code> will be joined before the interpreter can exit. Note that the exit handler which does this is executed <em>before</em> any exit handlers added using <code>atexit</code>. This means exceptions in the main thread must be caught and handled in order to signal threads to exit gracefully. For this reason, it is recommended that <code>ThreadPoolExecutor</code> not be used for long-running tasks.</p> <p><em>initializer</em> is an optional callable that is called at the start of each worker thread; <em>initargs</em> is a tuple of arguments passed to the initializer. Should <em>initializer</em> raise an exception, all currently pending jobs will raise a <a class="reference internal" href="#concurrent.futures.thread.BrokenThreadPool" title="concurrent.futures.thread.BrokenThreadPool"><code>BrokenThreadPool</code></a>, as well as any attempt to submit more jobs to the pool.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>If <em>max_workers</em> is <code>None</code> or not given, it will default to the number of processors on the machine, multiplied by <code>5</code>, assuming that <a class="reference internal" href="#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code>ThreadPoolExecutor</code></a> is often used to overlap I/O instead of CPU work and the number of workers should be higher than the number of workers for <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code>ProcessPoolExecutor</code></a>.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6: </span>The <em>thread_name_prefix</em> argument was added to allow users to control the <a class="reference internal" href="threading#threading.Thread" title="threading.Thread"><code>threading.Thread</code></a> names for worker threads created by the pool for easier debugging.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>initializer</em> and <em>initargs</em> arguments.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Default value of <em>max_workers</em> is changed to <code>min(32, os.cpu_count() + 4)</code>. This default value preserves at least 5 workers for I/O bound tasks. It utilizes at most 32 CPU cores for CPU bound tasks which release the GIL. And it avoids using very large resources implicitly on many-core machines.</p> <p>ThreadPoolExecutor now reuses idle worker threads before starting <em>max_workers</em> worker threads too.</p> </div> </dd>
</dl> <section id="threadpoolexecutor-example"> <span id="id1"></span><h3>ThreadPoolExecutor Example</h3> <pre data-language="python">import concurrent.futures
import urllib.request

URLS = ['http://www.foxnews.com/',
        'http://www.cnn.com/',
        'http://europe.wsj.com/',
        'http://www.bbc.co.uk/',
        'http://nonexistant-subdomain.python.org/']

# Retrieve a single page and report the URL and contents
def load_url(url, timeout):
    with urllib.request.urlopen(url, timeout=timeout) as conn:
        return conn.read()

# We can use a with statement to ensure threads are cleaned up promptly
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
    # Start the load operations and mark each future with its URL
    future_to_url = {executor.submit(load_url, url, 60): url for url in URLS}
    for future in concurrent.futures.as_completed(future_to_url):
        url = future_to_url[future]
        try:
            data = future.result()
        except Exception as exc:
            print('%r generated an exception: %s' % (url, exc))
        else:
            print('%r page is %d bytes' % (url, len(data)))
</pre> </section> </section> <section id="processpoolexecutor"> <h2>ProcessPoolExecutor</h2> <p>The <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code>ProcessPoolExecutor</code></a> class is an <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> subclass that uses a pool of processes to execute calls asynchronously. <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code>ProcessPoolExecutor</code></a> uses the <a class="reference internal" href="multiprocessing#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code>multiprocessing</code></a> module, which allows it to side-step the <a class="reference internal" href="../glossary#term-global-interpreter-lock"><span class="xref std std-term">Global Interpreter Lock</span></a> but also means that only picklable objects can be executed and returned.</p> <p>The <code>__main__</code> module must be importable by worker subprocesses. This means that <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code>ProcessPoolExecutor</code></a> will not work in the interactive interpreter.</p> <p>Calling <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> or <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> methods from a callable submitted to a <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code>ProcessPoolExecutor</code></a> will result in deadlock.</p> <dl class="py class"> <dt class="sig sig-object py" id="concurrent.futures.ProcessPoolExecutor">
<code>class concurrent.futures.ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)</code> </dt> <dd>
<p>An <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> subclass that executes calls asynchronously using a pool of at most <em>max_workers</em> processes. If <em>max_workers</em> is <code>None</code> or not given, it will default to the number of processors on the machine. If <em>max_workers</em> is less than or equal to <code>0</code>, then a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> will be raised. On Windows, <em>max_workers</em> must be less than or equal to <code>61</code>. If it is not then <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> will be raised. If <em>max_workers</em> is <code>None</code>, then the default chosen will be at most <code>61</code>, even if more processors are available. <em>mp_context</em> can be a <a class="reference internal" href="multiprocessing#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code>multiprocessing</code></a> context or <code>None</code>. It will be used to launch the workers. If <em>mp_context</em> is <code>None</code> or not given, the default <a class="reference internal" href="multiprocessing#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code>multiprocessing</code></a> context is used. See <a class="reference internal" href="multiprocessing#multiprocessing-start-methods"><span class="std std-ref">Contexts and start methods</span></a>.</p> <p><em>initializer</em> is an optional callable that is called at the start of each worker process; <em>initargs</em> is a tuple of arguments passed to the initializer. Should <em>initializer</em> raise an exception, all currently pending jobs will raise a <a class="reference internal" href="#concurrent.futures.process.BrokenProcessPool" title="concurrent.futures.process.BrokenProcessPool"><code>BrokenProcessPool</code></a>, as well as any attempt to submit more jobs to the pool.</p> <p><em>max_tasks_per_child</em> is an optional argument that specifies the maximum number of tasks a single process can execute before it will exit and be replaced with a fresh worker process. By default <em>max_tasks_per_child</em> is <code>None</code> which means worker processes will live as long as the pool. When a max is specified, the “spawn” multiprocessing start method will be used by default in absence of a <em>mp_context</em> parameter. This feature is incompatible with the “fork” start method.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span>When one of the worker processes terminates abruptly, a <code>BrokenProcessPool</code> error is now raised. Previously, behaviour was undefined but operations on the executor or its futures would often freeze or deadlock.</p> </div> <div class="versionchanged"> <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 start_method for worker processes created by the pool.</p> <p>Added the <em>initializer</em> and <em>initargs</em> arguments.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The default <a class="reference internal" href="multiprocessing#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code>multiprocessing</code></a> start method (see <a class="reference internal" href="multiprocessing#multiprocessing-start-methods"><span class="std std-ref">Contexts and start methods</span></a>) will change away from <em>fork</em> in Python 3.14. Code that requires <em>fork</em> be used for their <a class="reference internal" href="#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code>ProcessPoolExecutor</code></a> should explicitly specify that by passing a <code>mp_context=multiprocessing.get_context("fork")</code> parameter.</p> </div> </div> <div class="versionchanged"> <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 control the lifetime of workers in the pool.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>On POSIX systems, if your application has multiple threads and the <a class="reference internal" href="multiprocessing#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code>multiprocessing</code></a> context uses the <code>"fork"</code> start method: The <a class="reference internal" href="os#os.fork" title="os.fork"><code>os.fork()</code></a> function called internally to spawn workers may raise a <a class="reference internal" href="exceptions#DeprecationWarning" title="DeprecationWarning"><code>DeprecationWarning</code></a>. Pass a <em>mp_context</em> configured to use a different start method. See the <a class="reference internal" href="os#os.fork" title="os.fork"><code>os.fork()</code></a> documentation for further explanation.</p> </div> </dd>
</dl> <section id="processpoolexecutor-example"> <span id="id2"></span><h3>ProcessPoolExecutor Example</h3> <pre data-language="python">import concurrent.futures
import math

PRIMES = [
    112272535095293,
    112582705942171,
    112272535095293,
    115280095190773,
    115797848077099,
    1099726899285419]

def is_prime(n):
    if n &lt; 2:
        return False
    if n == 2:
        return True
    if n % 2 == 0:
        return False

    sqrt_n = int(math.floor(math.sqrt(n)))
    for i in range(3, sqrt_n + 1, 2):
        if n % i == 0:
            return False
    return True

def main():
    with concurrent.futures.ProcessPoolExecutor() as executor:
        for number, prime in zip(PRIMES, executor.map(is_prime, PRIMES)):
            print('%d is prime: %s' % (number, prime))

if __name__ == '__main__':
    main()
</pre> </section> </section> <section id="future-objects"> <h2>Future Objects</h2> <p>The <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> class encapsulates the asynchronous execution of a callable. <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> instances are created by <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code>Executor.submit()</code></a>.</p> <dl class="py class"> <dt class="sig sig-object py" id="concurrent.futures.Future">
<code>class concurrent.futures.Future</code> </dt> <dd>
<p>Encapsulates the asynchronous execution of a callable. <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> instances are created by <a class="reference internal" href="#concurrent.futures.Executor.submit" title="concurrent.futures.Executor.submit"><code>Executor.submit()</code></a> and should not be created directly except for testing.</p> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.cancel">
<code>cancel()</code> </dt> <dd>
<p>Attempt to cancel the call. If the call is currently being executed or finished running and cannot be cancelled then the method will return <code>False</code>, otherwise the call will be cancelled and the method will return <code>True</code>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.cancelled">
<code>cancelled()</code> </dt> <dd>
<p>Return <code>True</code> if the call was successfully cancelled.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.running">
<code>running()</code> </dt> <dd>
<p>Return <code>True</code> if the call is currently being executed and cannot be cancelled.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.done">
<code>done()</code> </dt> <dd>
<p>Return <code>True</code> if the call was successfully cancelled or finished running.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.result">
<code>result(timeout=None)</code> </dt> <dd>
<p>Return the value returned by the call. If the call hasn’t yet completed then this method will wait up to <em>timeout</em> seconds. If the call hasn’t completed in <em>timeout</em> seconds, then a <a class="reference internal" href="exceptions#TimeoutError" title="TimeoutError"><code>TimeoutError</code></a> will be raised. <em>timeout</em> can be an int or float. If <em>timeout</em> is not specified or <code>None</code>, there is no limit to the wait time.</p> <p>If the future is cancelled before completing then <a class="reference internal" href="#concurrent.futures.CancelledError" title="concurrent.futures.CancelledError"><code>CancelledError</code></a> will be raised.</p> <p>If the call raised an exception, this method will raise the same exception.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.exception">
<code>exception(timeout=None)</code> </dt> <dd>
<p>Return the exception raised by the call. If the call hasn’t yet completed then this method will wait up to <em>timeout</em> seconds. If the call hasn’t completed in <em>timeout</em> seconds, then a <a class="reference internal" href="exceptions#TimeoutError" title="TimeoutError"><code>TimeoutError</code></a> will be raised. <em>timeout</em> can be an int or float. If <em>timeout</em> is not specified or <code>None</code>, there is no limit to the wait time.</p> <p>If the future is cancelled before completing then <a class="reference internal" href="#concurrent.futures.CancelledError" title="concurrent.futures.CancelledError"><code>CancelledError</code></a> will be raised.</p> <p>If the call completed without raising, <code>None</code> is returned.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.add_done_callback">
<code>add_done_callback(fn)</code> </dt> <dd>
<p>Attaches the callable <em>fn</em> to the future. <em>fn</em> will be called, with the future as its only argument, when the future is cancelled or finishes running.</p> <p>Added callables are called in the order that they were added and are always called in a thread belonging to the process that added them. If the callable raises an <a class="reference internal" href="exceptions#Exception" title="Exception"><code>Exception</code></a> subclass, it will be logged and ignored. If the callable raises a <a class="reference internal" href="exceptions#BaseException" title="BaseException"><code>BaseException</code></a> subclass, the behavior is undefined.</p> <p>If the future has already completed or been cancelled, <em>fn</em> will be called immediately.</p> </dd>
</dl> <p>The following <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> methods are meant for use in unit tests and <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> implementations.</p> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.set_running_or_notify_cancel">
<code>set_running_or_notify_cancel()</code> </dt> <dd>
<p>This method should only be called by <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> implementations before executing the work associated with the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> and by unit tests.</p> <p>If the method returns <code>False</code> then the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> was cancelled, i.e. <a class="reference internal" href="#concurrent.futures.Future.cancel" title="concurrent.futures.Future.cancel"><code>Future.cancel()</code></a> was called and returned <code>True</code>. Any threads waiting on the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> completing (i.e. through <a class="reference internal" href="#concurrent.futures.as_completed" title="concurrent.futures.as_completed"><code>as_completed()</code></a> or <a class="reference internal" href="#concurrent.futures.wait" title="concurrent.futures.wait"><code>wait()</code></a>) will be woken up.</p> <p>If the method returns <code>True</code> then the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> was not cancelled and has been put in the running state, i.e. calls to <a class="reference internal" href="#concurrent.futures.Future.running" title="concurrent.futures.Future.running"><code>Future.running()</code></a> will return <code>True</code>.</p> <p>This method can only be called once and cannot be called after <a class="reference internal" href="#concurrent.futures.Future.set_result" title="concurrent.futures.Future.set_result"><code>Future.set_result()</code></a> or <a class="reference internal" href="#concurrent.futures.Future.set_exception" title="concurrent.futures.Future.set_exception"><code>Future.set_exception()</code></a> have been called.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.set_result">
<code>set_result(result)</code> </dt> <dd>
<p>Sets the result of the work associated with the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> to <em>result</em>.</p> <p>This method should only be used by <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> implementations and unit tests.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>This method raises <a class="reference internal" href="#concurrent.futures.InvalidStateError" title="concurrent.futures.InvalidStateError"><code>concurrent.futures.InvalidStateError</code></a> if the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> is already done.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="concurrent.futures.Future.set_exception">
<code>set_exception(exception)</code> </dt> <dd>
<p>Sets the result of the work associated with the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> to the <a class="reference internal" href="exceptions#Exception" title="Exception"><code>Exception</code></a> <em>exception</em>.</p> <p>This method should only be used by <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> implementations and unit tests.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>This method raises <a class="reference internal" href="#concurrent.futures.InvalidStateError" title="concurrent.futures.InvalidStateError"><code>concurrent.futures.InvalidStateError</code></a> if the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> is already done.</p> </div> </dd>
</dl> </dd>
</dl> </section> <section id="module-functions"> <h2>Module Functions</h2> <dl class="py function"> <dt class="sig sig-object py" id="concurrent.futures.wait">
<code>concurrent.futures.wait(fs, timeout=None, return_when=ALL_COMPLETED)</code> </dt> <dd>
<p>Wait for the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> instances (possibly created by different <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> instances) given by <em>fs</em> to complete. Duplicate futures given to <em>fs</em> are removed and will be returned only once. Returns a named 2-tuple of sets. The first set, named <code>done</code>, contains the futures that completed (finished or cancelled futures) before the wait completed. The second set, named <code>not_done</code>, contains the futures that did not complete (pending or running futures).</p> <p><em>timeout</em> can be used to control the maximum number of seconds to wait before returning. <em>timeout</em> can be an int or float. If <em>timeout</em> is not specified or <code>None</code>, there is no limit to the wait time.</p> <p><em>return_when</em> indicates when this function should return. It must be one of the following constants:</p> <table class="docutils align-default">  <thead> <tr>
<th class="head"><p>Constant</p></th> <th class="head"><p>Description</p></th> </tr> </thead>  <tr>
<td><p><code>FIRST_COMPLETED</code></p></td> <td><p>The function will return when any future finishes or is cancelled.</p></td> </tr> <tr>
<td><p><code>FIRST_EXCEPTION</code></p></td> <td><p>The function will return when any future finishes by raising an exception. If no future raises an exception then it is equivalent to <code>ALL_COMPLETED</code>.</p></td> </tr> <tr>
<td><p><code>ALL_COMPLETED</code></p></td> <td><p>The function will return when all futures finish or are cancelled.</p></td> </tr>  </table> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="concurrent.futures.as_completed">
<code>concurrent.futures.as_completed(fs, timeout=None)</code> </dt> <dd>
<p>Returns an iterator over the <a class="reference internal" href="#concurrent.futures.Future" title="concurrent.futures.Future"><code>Future</code></a> instances (possibly created by different <a class="reference internal" href="#concurrent.futures.Executor" title="concurrent.futures.Executor"><code>Executor</code></a> instances) given by <em>fs</em> that yields futures as they complete (finished or cancelled futures). Any futures given by <em>fs</em> that are duplicated will be returned once. Any futures that completed before <a class="reference internal" href="#concurrent.futures.as_completed" title="concurrent.futures.as_completed"><code>as_completed()</code></a> is called will be yielded first. The returned iterator raises a <a class="reference internal" href="exceptions#TimeoutError" title="TimeoutError"><code>TimeoutError</code></a> if <a class="reference internal" href="stdtypes#iterator.__next__" title="iterator.__next__"><code>__next__()</code></a> is called and the result isn’t available after <em>timeout</em> seconds from the original call to <a class="reference internal" href="#concurrent.futures.as_completed" title="concurrent.futures.as_completed"><code>as_completed()</code></a>. <em>timeout</em> can be an int or float. If <em>timeout</em> is not specified or <code>None</code>, there is no limit to the wait time.</p> </dd>
</dl> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <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 standard library.</p> </dd> </dl> </div> </section> <section id="exception-classes"> <h2>Exception classes</h2> <dl class="py exception"> <dt class="sig sig-object py" id="concurrent.futures.CancelledError">
<code>exception concurrent.futures.CancelledError</code> </dt> <dd>
<p>Raised when a future is cancelled.</p> </dd>
</dl> <dl class="py exception"> <dt class="sig sig-object py" id="concurrent.futures.TimeoutError">
<code>exception concurrent.futures.TimeoutError</code> </dt> <dd>
<p>A deprecated alias of <a class="reference internal" href="exceptions#TimeoutError" title="TimeoutError"><code>TimeoutError</code></a>, raised when a future operation exceeds the given timeout.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>This class was made an alias of <a class="reference internal" href="exceptions#TimeoutError" title="TimeoutError"><code>TimeoutError</code></a>.</p> </div> </dd>
</dl> <dl class="py exception"> <dt class="sig sig-object py" id="concurrent.futures.BrokenExecutor">
<code>exception concurrent.futures.BrokenExecutor</code> </dt> <dd>
<p>Derived from <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a>, this exception class is raised when an executor is broken for some reason, and cannot be used to submit or execute new tasks.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> </dd>
</dl> <dl class="py exception"> <dt class="sig sig-object py" id="concurrent.futures.InvalidStateError">
<code>exception concurrent.futures.InvalidStateError</code> </dt> <dd>
<p>Raised when an operation is performed on a future that is not allowed in the current state.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.8.</span></p> </div> </dd>
</dl> <dl class="py exception"> <dt class="sig sig-object py" id="concurrent.futures.thread.BrokenThreadPool">
<code>exception concurrent.futures.thread.BrokenThreadPool</code> </dt> <dd>
<p>Derived from <a class="reference internal" href="#concurrent.futures.BrokenExecutor" title="concurrent.futures.BrokenExecutor"><code>BrokenExecutor</code></a>, this exception class is raised when one of the workers of a <code>ThreadPoolExecutor</code> has failed initializing.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> </dd>
</dl> <dl class="py exception"> <dt class="sig sig-object py" id="concurrent.futures.process.BrokenProcessPool">
<code>exception concurrent.futures.process.BrokenProcessPool</code> </dt> <dd>
<p>Derived from <a class="reference internal" href="#concurrent.futures.BrokenExecutor" title="concurrent.futures.BrokenExecutor"><code>BrokenExecutor</code></a> (formerly <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a>), this exception class is raised when one of the workers of a <code>ProcessPoolExecutor</code> has terminated in a non-clean fashion (for example, if it was killed from the outside).</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> </dd>
</dl> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/concurrent.futures.html" class="_attribution-link">https://docs.python.org/3.12/library/concurrent.futures.html</a>
  </p>
</div>