torch.futures

此包提供了一个类型，该类型封装了 一个异步执行和一组用于简化操作的实用函数 在对象上。目前，该类型主要由分布式 RPC 框架使用。

类 torch.futures 中。未来（*， devices=无)

封装异步 执行一个可调用对象，例如 .它 还公开了一组 API，用于添加回调函数和设置结果。torch._C.Future

警告

GPU 支持是一项测试版功能，可能会发生更改。

add_done_callback（回调）

将给定的回调函数附加到 this ，该函数将运行 当完成时。可以添加多个回调 相同，但它们的执行顺序不能 得到保证。回调必须采用一个参数，即 引用此 .回调函数可以使用该方法获取值。请注意，如果这是 已经完成，给定的回调将内联运行。FutureFutureFutureFutureFuture

我们建议您使用该方法，因为它提供了一种方法 以在回调完成后进行同步。 如果您的回调不返回任何内容，则可能会更便宜。但两者 和 使用相同的回调 注册 API。add_done_callbackadd_done_callback

对于 GPU 张量，此方法的行为方式与 相同。

参数

callback （） – 一个接受一个参数， 这是对 this 的引用。FutureCallableFuture

注意

请注意，如果回调函数引发，则 通过原始 future 被完成但有一个例外，并且 调用 ，或通过回调中的其他代码 必须仔细处理错误。例如，如果 此回调稍后会完成其他 futures，这些 future 是 未标记为已完成，但出现错误，用户负责 独立处理这些 future 的完成 / 等待。fut.wait()

例：：

>>> def callback(fut):
...     print("This will run after the future has finished.")
...     print(fut.wait())
>>> fut = torch.futures.Future()
>>> fut.add_done_callback(callback)
>>> fut.set_result(5)
This will run after the future has finished.
5

done（

如果完成此操作，则返回。如果 A 完成，则 有 result 或 exception。TrueFutureFuture

如果该值包含驻留在 GPU 上的张量，则即使 填充这些张量尚未在设备上运行， 因为在这样的阶段，结果已经可用了，只要有一个 执行相应的同步（请参阅 ）。Future.done()True

返回类型

布尔

set_exception（结果）

为此设置一个例外，这会将其标记为 completed 但出现错误，并触发所有附加的回调。请注意， 当对 this 调用 wait（）/value（） 时，此处设置的异常 将内联引发。FutureFutureFuture

参数

result （BaseException） – 此 .Future

例：：

>>> fut = torch.futures.Future()
>>> fut.set_exception(ValueError("foo"))
>>> fut.wait()
Traceback (most recent call last):
...
ValueError: foo

set_result（结果）

为此设置结果，这会将其标记为 completed 并触发所有附加的回调。请注意，a 不能标记为已完成两次。FutureFutureFuture

如果结果包含驻留在 GPU 上的张量，则此方法可以是 调用，即使填充这些 张量尚未在设备上运行，前提是 这些内核入队的流将设置为当前 当调用此方法时。简单地说，调用此方法是安全的 在启动这些内核后立即启动，无需任何其他 同步，只要在两者之间不更改流即可。这 方法将记录所有相关当前流上的事件，并将 使用它们来确保为此的所有使用者进行适当的调度。Future

参数

result （object） - 此 .Future

例：：

>>> import threading
>>> import time
>>> 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()

then（回调）

将给定的回调函数附加到 this ，该函数将运行 当完成时。可以添加多个回调 相同，但它们的执行顺序不能 被保证（要执行特定顺序，请考虑链接：）。回调必须采用一个参数，该参数 是对此 的引用。回调函数可以使用该方法获取值。请注意，如果这是 已经完成，给定的回调将立即内联运行。FutureFutureFuturefut.then(cb1).then(cb2)FutureFuture

如果 的 值包含驻留在 GPU 上的张量，则 callback 可能会在填充的异步内核 这些张量尚未在设备上完成执行。但是， callback 将被调用，并将一些专用流设置为 current （从全局池中获取），该池将与这些 内核。因此，回调对这些张量执行的任何操作 将在内核完成后调度到设备上。在其他 words，只要 callback 不切换流，就可以安全地 操作结果，无需任何其他同步。这是 类似于 的非阻塞行为。Future

同样，如果回调返回的值包含的张量 驻留在 GPU 上，即使正在生成 这些张量仍在设备上运行，只要回调 在执行过程中未更改流。如果一个人想改变 streams 中，必须小心地将它们与原始 流，即调用回调时为当前流的流。

参数

callback （） – a 将其作为 唯一的参数。CallableCallableFuture

返回

一个保存 和 返回值的新对象将在给定完成时标记为已完成。Futurecallbackcallback

返回类型

未来]

注意

请注意，如果回调函数引发，则 通过原始 future 被完成但有一个例外，并且 调用 ，或者通过回调中的其他代码， future 将适当地标记为 遇到错误。但是，如果此回调稍后完成 Additional futures，则这些 future 不会标记为 completed 错误，并且用户负责处理完成/等待 在这些期货上独立。fut.wait()then

例：：

>>> 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)
RPC return value is 5.
Chained cb done. None

value（）

获取已完成的 future 的值。

此方法只能在调用 has 后调用 completed，或在传递给 .在 在其他情况下，这可能还不保存值，并且调用可能会失败。Futurevalue()

如果该值包含驻留在 GPU 上的张量，则此方法不会执行任何其他同步。这应该完成 在此之前，单独通过对 （除了在 callbacks 的调用，它已经由 ） 处理。

返回

此 .如果函数（callback 或 RPC） 创建 value 时抛出一个错误，此方法将 也会引发一个错误。Futurevalue()

返回类型

T

wait（

Block 直到 this 的值准备就绪。Future

如果该值包含驻留在 GPU 上的张量，则额外的 使用内核执行同步（在设备上执行） 这可能会异步填充这些张量。这种同步是 non-blocking，这意味着将插入必要的 说明，以确保进一步的操作 enqueued 将在异步 kernels 的 c3 中，但一旦完成，就会返回，即使那些 内核仍在运行。在以下情况下不需要进一步同步 访问和使用这些值，只要不更改 streams。wait()wait()

返回

此 .如果函数（callback 或 RPC） 创建 value 时抛出一个错误，此方法将 也会引发一个错误。Futurewait

返回类型

T

torch.futures 中。collect_all（期货）

将提供的对象收集到单个 组合在一起，当所有 子 futures 完成。

参数

futures （list） – 对象列表。

返回

将对象返回到传递的 在 Futures 中。

返回类型

Future[列表[Future]]

例：：

>>> 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()}")
fut0 result = 0
>>> print(f"fut1 result = {fut_list[1].wait()}")
fut1 result = 1

torch.futures 中。wait_all（期货）

等待所有提供的 futures 完成，并返回 已完成值的列表。如果任何 futures 遇到错误， 该方法会提前退出并报告错误 Not waiting for Other futures 来完成。

参数

futures （list） - 对象列表。

返回

已完成结果的列表。这 method 将抛出错误 if on any throws.wait

返回类型

列表