---
title: futures
sidebarTitle: futures
---

# `prefect.futures`

## Functions

### `as_completed` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L506" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
as_completed(futures: list[PrefectFuture[R]], timeout: float | None = None) -> Generator[PrefectFuture[R], None]
```

### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L557" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(futures: list[PrefectFuture[R]], timeout: float | None = None) -> DoneAndNotDoneFutures[R]
```


Wait for the futures in the given sequence to complete.

**Args:**
- `futures`: The sequence of Futures to wait upon.
- `timeout`: The maximum number of seconds to wait. If None, then there
is no limit on the wait time.

**Returns:**
- A named 2-tuple of sets. The first set, named 'done', contains the
- futures that completed (is finished or cancelled) before the wait
- completed. The second set, named 'not_done', contains uncompleted
- futures. Duplicate futures given to *futures* are removed and will be
- returned only once.

**Examples:**

```python
@task
def sleep_task(seconds):
    sleep(seconds)
    return 42

@flow
def flow():
    futures = random_task.map(range(10))
    done, not_done = wait(futures, timeout=5)
    print(f"Done: {len(done)}")
    print(f"Not Done: {len(not_done)}")
```


### `resolve_futures_to_states` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L641" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_futures_to_states(expr: PrefectFuture[R] | Any) -> PrefectFuture[R] | Any
```


Given a Python built-in collection, recursively find `PrefectFutures` and build a
new collection with the same structure with futures resolved to their final states.
Resolving futures to their final states may wait for execution to complete.

Unsupported object types will be returned without modification.


### `resolve_futures_to_results` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L662" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
resolve_futures_to_results(expr: PrefectFuture[R] | Any) -> Any
```


Given a Python built-in collection, recursively find `PrefectFutures` and build a
new collection with the same structure with futures resolved to their final results.
Resolving futures to their final result may wait for execution to complete.

Unsupported object types will be returned without modification.


## Classes

### `PrefectFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Abstract base class for Prefect futures. A Prefect future is a handle to the
asynchronous execution of a run. It provides methods to wait for the
to complete and to retrieve the result of the run.


**Methods:**

#### `add_done_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_done_callback(self, fn: Callable[['PrefectFuture[R]'], None]) -> None
```

Add a callback to be run when the future completes or is cancelled.

**Args:**
- `fn`: A callable that will be called with this future as its only argument when the future completes or is cancelled.


#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> State
```

The current state of the task run associated with this future


#### `task_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_id(self) -> uuid.UUID
```

The ID of the task run associated with this future


#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

### `PrefectTaskRunFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A Prefect future that represents the eventual execution of a task run.


**Methods:**

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> State
```

The current state of the task run associated with this future


#### `task_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_run_id(self) -> uuid.UUID
```

The ID of the task run associated with this future


### `PrefectWrappedFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A Prefect future that wraps another future object.


**Methods:**

#### `add_done_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_done_callback(self, fn: Callable[[PrefectFuture[R]], None]) -> None
```

Add a callback to be executed when the future completes.


#### `wrapped_future` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wrapped_future(self) -> F
```

The underlying future object wrapped by this Prefect future


### `PrefectConcurrentFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A Prefect future that wraps a concurrent.futures.Future. This future is used
when the task run is submitted to a ThreadPoolExecutor.


**Methods:**

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L203" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

### `PrefectDistributedFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Represents the result of a computation happening anywhere.

This class is typically used to interact with the result of a task run
scheduled to run in a Prefect task worker but can be used to interact with
any task run scheduled in Prefect's API.


**Methods:**

#### `add_done_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_done_callback(self, fn: Callable[[PrefectFuture[R]], None]) -> None
```

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L288" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `result_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result_async(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

#### `wait_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_async(self, timeout: float | None = None) -> None
```

### `PrefectFlowRunFuture` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L340" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A Prefect future that represents the eventual execution of a flow run.


**Methods:**

#### `add_done_callback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
add_done_callback(self, fn: Callable[[PrefectFuture[R]], None]) -> None
```

#### `aresult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aresult(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `flow_run_id` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
flow_run_id(self) -> uuid.UUID
```

The ID of the flow run associated with this future


#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R
```

#### `state` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
state(self) -> State
```

The current state of the flow run associated with this future


#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

#### `wait_async` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L373" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait_async(self, timeout: float | None = None) -> None
```

### `PrefectFutureList` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L455" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A list of Prefect futures.

This class provides methods to wait for all futures
in the list to complete and to retrieve the results of all task runs.


**Methods:**

#### `result` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L473" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
result(self: Self, timeout: float | None = None, raise_on_failure: bool = True) -> list[R]
```

Get the results of all task runs associated with the futures in the list.

**Args:**
- `timeout`: The maximum number of seconds to wait for all futures to
complete.
- `raise_on_failure`: If `True`, an exception will be raised if any task run fails.

**Returns:**
- A list of results of the task runs.

**Raises:**
- `TimeoutError`: If the timeout is reached before all futures complete.


#### `wait` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L463" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
wait(self, timeout: float | None = None) -> None
```

Wait for all futures in the list to complete.

**Args:**
- `timeout`: The maximum number of seconds to wait for all futures to
complete. This method will not raise if the timeout is reached.


### `DoneAndNotDoneFutures` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L547" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A named 2-tuple of sets.

multiple inheritance supported in 3.11+, use typing_extensions.NamedTuple

