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
```