python-clinic / Doc / library / concurrent.futures.rst

Full commit

:mod:`concurrent.futures` --- Launching parallel tasks

Source code: :source:`Lib/concurrent/futures/` and :source:`Lib/concurrent/futures/`

The :mod:`concurrent.futures` module provides a high-level interface for asynchronously executing callables.

The asynchronous execution can be performed with threads, using :class:`ThreadPoolExecutor`, or separate processes, using :class:`ProcessPoolExecutor`. Both implement the same interface, which is defined by the abstract :class:`Executor` class.

Executor Objects

An abstract class that provides methods to execute calls asynchronously. It should not be used directly, but through its concrete subclasses.


:class:`ThreadPoolExecutor` is a :class:`Executor` subclass that uses a pool of threads to execute calls asynchronously.

Deadlocks can occur when the callable associated with a :class:`Future` waits on the results of another :class:`Future`. For example:

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

def wait_on_a():
    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)


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.

executor = ThreadPoolExecutor(max_workers=1)

An :class:`Executor` subclass that uses a pool of at most max_workers threads to execute calls asynchronously.

ThreadPoolExecutor Example

import concurrent.futures
import urllib.request

URLS = ['',

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

# 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]
            data = future.result()
        except Exception as exc:
            print('%r generated an exception: %s' % (url, exc))
            print('%r page is %d bytes' % (url, len(data)))


The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that uses a pool of processes to execute calls asynchronously. :class:`ProcessPoolExecutor` uses the :mod:`multiprocessing` module, which allows it to side-step the :term:`Global Interpreter Lock` but also means that only picklable objects can be executed and returned.

Calling :class:`Executor` or :class:`Future` methods from a callable submitted to a :class:`ProcessPoolExecutor` will result in deadlock.

An :class:`Executor` subclass that executes calls asynchronously using a pool of at most max_workers processes. If max_workers is None or not given, it will default to the number of processors on the machine.

ProcessPoolExecutor Example

import concurrent.futures
import math


def is_prime(n):
    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,, PRIMES)):
            print('%d is prime: %s' % (number, prime))

if __name__ == '__main__':

Future Objects

The :class:`Future` class encapsulates the asynchronous execution of a callable. :class:`Future` instances are created by :meth:`Executor.submit`.

Encapsulates the asynchronous execution of a callable. :class:`Future` instances are created by :meth:`Executor.submit` and should not be created directly except for testing.

The following :class:`Future` methods are meant for use in unit tests and :class:`Executor` implementations.

Module Functions

Exception classes