0
# Futures
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: futures
7
- **Language**: Python
8
- **Installation**: `pip install futures` (Python 2.6 and 2.7 only)
9
- **License**: Python Software Foundation License (PSF)
10

11
## Core Imports
12

13
```python
14
from concurrent import futures
15
# or
16
import concurrent.futures
17
```
18

19
Common imports for executors and utilities:
20

21
```python
22
from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor
23
from concurrent.futures import Future, wait, as_completed
24
from concurrent.futures import FIRST_COMPLETED, FIRST_EXCEPTION, ALL_COMPLETED
25
from concurrent.futures import CancelledError, TimeoutError
26
```
27

28
## Basic Usage
29

30
```python
31
from concurrent.futures import ThreadPoolExecutor, as_completed
32
import time
33

34
def task(n):
35
    time.sleep(1)
36
    return n * n
37

38
# Using ThreadPoolExecutor with context manager
39
with ThreadPoolExecutor(max_workers=4) as executor:
40
    # Submit multiple tasks
41
    futures_list = [executor.submit(task, i) for i in range(5)]
42
    
43
    # Get results as they complete
44
    for future in as_completed(futures_list):
45
        result = future.result()
46
        print("Result:", result)
47

48
# Using executor.map for parallel mapping
49
with ThreadPoolExecutor(max_workers=4) as executor:
50
    results = list(executor.map(task, range(5)))
51
    print("All results:", results)
52
```
53

54
## Architecture
55

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

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

64
## Capabilities
65

66
### Thread Pool Execution
67

68
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.
69

70
```python { .api }
71
class ThreadPoolExecutor:
72
    def __init__(self, max_workers=None, thread_name_prefix='', initializer=None, initargs=()): ...
73
    def submit(self, fn, *args, **kwargs): ...
74
    def map(self, fn, *iterables, **kwargs): ...
75
    def shutdown(self, wait=True): ...
76
```
77

78
[Thread and Process Executors](./executors.md)
79

80
### Process Pool Execution
81

82
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.
83

84
```python { .api }
85
class ProcessPoolExecutor:
86
    def __init__(self, max_workers=None): ...
87
    def submit(self, fn, *args, **kwargs): ...
88
    def map(self, fn, *iterables, **kwargs): ...
89
    def shutdown(self, wait=True): ...
90
```
91

92
[Thread and Process Executors](./executors.md)
93

94
### Future Management
95

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

98
```python { .api }
99
class Future:
100
    def result(self, timeout=None): ...
101
    def exception(self, timeout=None): ...
102
    def cancel(self): ...
103
    def cancelled(self): ...
104
    def running(self): ...
105
    def done(self): ...
106
    def add_done_callback(self, fn): ...
107
```
108

109
[Future Objects](./futures.md)
110

111
### Synchronization Utilities
112

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

115
```python { .api }
116
def wait(fs, timeout=None, return_when=ALL_COMPLETED): ...
117
def as_completed(fs, timeout=None): ...
118
```
119

120
[Utility Functions](./utilities.md)
121

122
## Important Notes
123

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

129
## Constants
130

131
```python { .api }
132
# Wait condition constants
133
FIRST_COMPLETED = 'FIRST_COMPLETED'
134
FIRST_EXCEPTION = 'FIRST_EXCEPTION' 
135
ALL_COMPLETED = 'ALL_COMPLETED'
136
```
137

138
## Exceptions
139

140
```python { .api }
141
class CancelledError(Exception):
142
    """The Future was cancelled."""
143

144
class TimeoutError(Exception):
145
    """The operation exceeded the given deadline."""
146
```