Futures?

Future 對象用來鏈接 底層回調式代碼 和高層異步/等待式代碼。

Future 函數?

asyncio.isfuture(obj)?

如果 obj 為下面任意對象，返回 True：

  • 一個 asyncio.Future 類的實例，

  • 一個 asyncio.Task 類的實例，

  • 帶有 _asyncio_future_blocking 屬性的類似 Future 的對象。

3.5 新版功能.

asyncio.ensure_future(obj, *, loop=None)?

返回：

  • obj 參數會是保持原樣，如果 obj 是 Future、 Task 或 類似 Future 的對象( isfuture() 用于測試。)

  • 封裝了 obj 的 Task 對象，如果 obj 是一個協程 (使用 iscoroutine() 進行檢測)；在此情況下該協程將通過 ensure_future() 加入執行計劃。

  • 等待 obj 的 Task 對象，如果 obj 是一個可等待對象( inspect.isawaitable() 用于測試)

如果 obj 不是上述對象會引發一個 TypeError 異常。

重要

查看 create_task() 函數，它是創建新任務的首選途徑。

在 3.5.1 版更改: 這個函數接受任意 awaitable 對象。

asyncio.wrap_future(future, *, loop=None)?

將一個 concurrent.futures.Future 對象封裝到 asyncio.Future 對象中。

Future 對象?

class asyncio.Future(*, loop=None)?

一個 Future 代表一個異步運算的最終結果。線程不安全。

Future 是一個 awaitable 對象。協程可以等待 Future 對象直到它們有結果或異常集合或被取消。

通常 Future 用于支持底層回調式代碼(例如在協議實現中使用asyncio transports) 與高層異步/等待式代碼交互。

經驗告訴我們永遠不要面向用戶的接口暴露 Future 對象，同時建議使用 loop.create_future() 來創建 Future 對象。這種方法可以讓 Future 對象使用其它的事件循環實現，它可以注入自己的優化實現。

在 3.7 版更改: 加入對 contextvars 模塊的支持。

result()?

返回 Future 的結果。

如果 Future 狀態為 完成 ，并由 set_result() 方法設置一個結果，則返回這個結果。

如果 Future 狀態為 完成 ，并由 set_exception() 方法設置一個異常，那么這個方法會引發異常。

如果 Future 已 取消，方法會引發一個 CancelledError 異常。

如果 Future 的結果還不可用，此方法會引發一個 InvalidStateError 異常。

set_result(result)?

將 Future 標記為 完成 并設置結果。

如果 Future 已經 完成 則拋出一個 InvalidStateError 錯誤。

set_exception(exception)?

將 Future 標記為 完成 并設置一個異常。

如果 Future 已經 完成 則拋出一個 InvalidStateError 錯誤。

done()?

如果 Future 為已 完成 則返回 True 。

如果 Future 為 取消 或調用 set_result() 設置了結果或調用 set_exception() 設置了異常，那么它就是 完成 。

cancelled()?

如果 Future 已 取消 則返回 True

這個方法通常在設置結果或異常前用來檢查 Future 是否已 取消 。

if not fut.cancelled():
    fut.set_result(42)
add_done_callback(callback, *, context=None)?

添加一個在 Future 完成 時運行的回調函數。

調用 callback 時，Future 對象是它的唯一參數。

如果調用這個方法時 Future 已經 完成，回調函數會被 loop.call_soon() 調度。

可選鍵值類的參數 context 允許 callback 運行在一個指定的自定義 contextvars.Context 對象中。如果沒有提供 context ，則使用當前上下文。

可以用 functools.partial() 給回調函數傳遞參數，例如:

# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
    functools.partial(print, "Future:"))

在 3.7 版更改: 加入鍵值類形參 context。請參閱 PEP 567 查看更多細節。

remove_done_callback(callback)?

從回調列表中移除 callback 。

返回被移除的回調函數的數量，通常為1，除非一個回調函數被添加多次。

cancel()?

取消 Future 并調度回調函數。

如果 Future 已經 完成 或 取消 ，返回 False 。否則將 Future 狀態改為 取消 并在調度回調函數后返回 True 。

exception()?

返回 Future 已設置的異常。

只有 Future 在 完成 時才返回異常（或者 None ，如果沒有設置異常）。

如果 Future 已 取消，方法會引發一個 CancelledError 異常。

如果 Future 還沒 完成 ，這個方法會引發一個 InvalidStateError 異常。

get_loop()?

返回 Future 對象已綁定的事件循環。

3.7 新版功能.

這個例子創建一個 Future 對象，創建和調度一個異步任務去設置 Future 結果，然后等待其結果:

async def set_after(fut, delay, value):
    # Sleep for *delay* seconds.
    await asyncio.sleep(delay)

    # Set *value* as a result of *fut* Future.
    fut.set_result(value)

async def main():
    # Get the current event loop.
    loop = asyncio.get_running_loop()

    # Create a new Future object.
    fut = loop.create_future()

    # Run "set_after()" coroutine in a parallel Task.
    # We are using the low-level "loop.create_task()" API here because
    # we already have a reference to the event loop at hand.
    # Otherwise we could have just used "asyncio.create_task()".
    loop.create_task(
        set_after(fut, 1, '... world'))

    print('hello ...')

    # Wait until *fut* has a result (1 second) and print it.
    print(await fut)

asyncio.run(main())

重要

該 Future 對象是為了模仿 concurrent.futures.Future 類。主要差異包含：