Futures

A Python 2 backport of the concurrent.futures standard library module from Python 3. This package enables asynchronous execution of callables using threads or processes, providing modern concurrent programming patterns through ThreadPoolExecutor and ProcessPoolExecutor classes.

Package Information

• Package Name: futures
• Language: Python
• Installation: pip install futures (Python 2.6 and 2.7 only)
• License: Python Software Foundation License (PSF)

Core Imports

from concurrent import futures
# or
import concurrent.futures

Common imports for executors and utilities:

from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor
from concurrent.futures import Future, wait, as_completed
from concurrent.futures import FIRST_COMPLETED, FIRST_EXCEPTION, ALL_COMPLETED
from concurrent.futures import CancelledError, TimeoutError

Basic Usage

from concurrent.futures import ThreadPoolExecutor, as_completed
import time

def task(n):
    time.sleep(1)
    return n * n

# Using ThreadPoolExecutor with context manager
with ThreadPoolExecutor(max_workers=4) as executor:
    # Submit multiple tasks
    futures_list = [executor.submit(task, i) for i in range(5)]
    
    # Get results as they complete
    for future in as_completed(futures_list):
        result = future.result()
        print("Result:", result)

# Using executor.map for parallel mapping
with ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(task, range(5)))
    print("All results:", results)

Architecture

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

• Executor: Abstract base class for executing callables asynchronously
• ThreadPoolExecutor: Executor using a pool of threads for I/O-bound tasks
• ProcessPoolExecutor: Executor using a pool of processes for CPU-bound tasks
• Future: Represents the result of an asynchronous computation
• Utility Functions: wait() and as_completed() for managing multiple futures

Capabilities

Thread Pool Execution

Thread-based parallel execution optimized for I/O-bound and high-level structured network code. ThreadPoolExecutor provides thread pool management with configurable worker threads, thread naming, and initialization functions.

class ThreadPoolExecutor:
    def __init__(self, max_workers=None, thread_name_prefix='', initializer=None, initargs=()): ...
    def submit(self, fn, *args, **kwargs): ...
    def map(self, fn, *iterables, **kwargs): ...
    def shutdown(self, wait=True): ...

Thread and Process Executors

Process Pool Execution

Process-based parallel execution for CPU-bound tasks that can benefit from true parallelism. ProcessPoolExecutor manages worker processes and inter-process communication, though it has known limitations on Python 2.

class ProcessPoolExecutor:
    def __init__(self, max_workers=None): ...
    def submit(self, fn, *args, **kwargs): ...
    def map(self, fn, *iterables, **kwargs): ...
    def shutdown(self, wait=True): ...

Thread and Process Executors

Future Management

Future objects represent the result of asynchronous computations, providing methods to check status, retrieve results, handle exceptions, and attach completion callbacks.

class Future:
    def result(self, timeout=None): ...
    def exception(self, timeout=None): ...
    def cancel(self): ...
    def cancelled(self): ...
    def running(self): ...
    def done(self): ...
    def add_done_callback(self, fn): ...

Future Objects

Synchronization Utilities

Utility functions for coordinating multiple futures, including waiting for completion conditions and iterating over futures as they complete.

def wait(fs, timeout=None, return_when=ALL_COMPLETED): ...
def as_completed(fs, timeout=None): ...

Utility Functions

Important Notes

• Python 2 Only: This package does not work on Python 3 and is not needed since concurrent.futures is in the standard library
• ProcessPoolExecutor Limitations: Has known unfixable problems on Python 2 and should not be relied upon for mission-critical work
• Thread Safety: All classes and functions are thread-safe and designed for concurrent use
• Context Manager Support: Both executor classes support the with statement for automatic resource cleanup

Constants

# Wait condition constants
FIRST_COMPLETED = 'FIRST_COMPLETED'
FIRST_EXCEPTION = 'FIRST_EXCEPTION' 
ALL_COMPLETED = 'ALL_COMPLETED'

Exceptions

class CancelledError(Exception):
    """The Future was cancelled."""

class TimeoutError(Exception):
    """The operation exceeded the given deadline."""