The torch.futures package is experimental and subject to change.

This package provides a Future type that encapsulates an asynchronous execution and a set of utility functions to simplify operations on Future objects. Currently, the Future type is primarily used by the Distributed RPC Framework.

class torch.futures.Future[source]

Wrapper around a torch._C.Future which encapsulates an asynchronous execution of a callable, e.g. rpc_async(). It also exposes a set of APIs to add callback functions and set results.


Set the result for this Future, which will mark this Future as completed and trigger all attached callbacks. Note that a Future cannot be marked completed twice.


result (object) – the result object of this Future.

>>> import threading
>>> import time
>>> import torch
>>> def slow_set_future(fut, value):
>>>     time.sleep(0.5)
>>>     fut.set_result(value)
>>> fut = torch.futures.Future()
>>> t = threading.Thread(
>>>     target=slow_set_future,
>>>     args=(fut, torch.ones(2) * 3)
>>> )
>>> t.start()
>>> print(fut.wait())  # tensor([3., 3.])
>>> t.join()

Append the given callback function to this Future, which will be run when the Future is completed. Multiple callbacks can be added to the same Future, and will be invoked in the same order as they were added. The callback must take one argument, which is the reference to this Future. The callback function can use the Future.wait() API to get the value.


callback (Callable) – a Callable that takes this Future as the only argument.


A new Future object that holds the return value of the callback and will be marked as completed when the given callback finishes.

>>> import torch
>>> def callback(fut):
>>>     print(f"RPC return value is {fut.wait()}.")
>>> fut = torch.futures.Future()
>>> # The inserted callback will print the return value when
>>> # receiving the response from "worker1"
>>> cb_fut = fut.then(callback)
>>> chain_cb_fut = cb_fut.then(
>>>     lambda x : print(f"Chained cb done. {x.wait()}")
>>> )
>>> fut.set_result(5)
>>> # Outputs are:
>>> # RPC return value is 5.
>>> # Chained cb done. None

Block until the value of this Future is ready.


The value held by this Future. If the function (callback or RPC) creating the value has thrown an error, this wait method will also throw an error.


Collects the provided Future objects into a single combined Future that is completed when all of the sub-futures are completed.


futures (list) – a list of Future objects.


Returns a Future object to a list of the passed in Futures.

>>> import torch
>>> fut0 = torch.futures.Future()
>>> fut1 = torch.futures.Future()
>>> fut = torch.futures.collect_all([fut0, fut1])
>>> fut0.set_result(0)
>>> fut1.set_result(1)
>>> fut_list = fut.wait()
>>> print(f"fut0 result = {fut_list[0].wait()}")
>>> print(f"fut1 result = {fut_list[1].wait()}")
>>> # outputs:
>>> # fut0 result = 0
>>> # fut1 result = 1

Waits for all provided futures to be complete, and returns the list of completed values.


futures (list) – a list of Future object.


A list of the completed Future results. This method will throw an error if wait on any Future throws.


Access comprehensive developer documentation for PyTorch

View Docs


Get in-depth tutorials for beginners and advanced developers

View Tutorials


Find development resources and get your questions answered

View Resources