diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Fconcurrent.futures.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Fconcurrent.futures.html | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Fconcurrent.futures.html b/devdocs/python~3.12/library%2Fconcurrent.futures.html new file mode 100644 index 00000000..92f20a7f --- /dev/null +++ b/devdocs/python~3.12/library%2Fconcurrent.futures.html @@ -0,0 +1,179 @@ + <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 < 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"> + © 2001–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> |