tornado.concurrent — 處理 Future 物件

用於處理 Future 物件的工具。

Tornado 之前提供自己的 Future 類別，但現在使用 asyncio.Future。這個模組包含用於處理 asyncio.Future 的工具函式，且這些函式與 Tornado 舊有的 Future 實作向後相容。

雖然這個模組是 Tornado 內部實作的重要一部分，但應用程式很少需要直接與其互動。

class tornado.concurrent.Future

tornado.concurrent.Future 是 asyncio.Future 的別名。

在 Tornado 中，應用程式與 Future 物件互動的主要方式是在協程中 awaiting 或 yielding 它們，而不是直接呼叫 Future 物件上的方法。如需可用方法的更多資訊，請參閱 asyncio.Future 文件。

變更於版本 5.0: Tornado 的 Future 實作已由 asyncio 中的版本取代 (如果可用的話)。

• Future 物件只能在目前有 IOLoop 時建立

• 使用 Future.add_done_callback 排程的回呼時機已變更。

• 現在部分支援取消 (僅限 Python 3)

• exc_info 和 set_exc_info 方法在 Python 3 上不再可用。

tornado.concurrent.run_on_executor(*args: Any, **kwargs: Any) → Callable

裝飾器，用於在執行器上非同步執行同步方法。

會傳回 Future。

要使用的執行器由 self 的 executor 屬性決定。若要使用不同的屬性名稱，請將關鍵字引數傳遞至裝飾器

@run_on_executor(executor='_thread_pool')
def foo(self):
    pass

這個裝飾器不應與名稱相似的 IOLoop.run_in_executor 混淆。一般來說，當呼叫阻塞方法時，建議使用 run_in_executor，而不是在定義方法時使用這個裝飾器。如果需要與舊版 Tornado 相容，請考慮定義一個執行器，並在呼叫點使用 executor.submit()。

變更於版本 4.2: 新增了使用替代屬性的關鍵字引數。

變更於版本 5.0: 一律使用目前的 IOLoop，而不是 self.io_loop。

變更於版本 5.1: 傳回與 await 相容的 Future，而不是 concurrent.futures.Future。

自版本 5.1 起已棄用: callback 引數已棄用，並將在 6.0 中移除。不建議在新程式碼中使用裝飾器本身，但不會在 6.0 中移除。

變更於版本 6.0: 已移除 callback 引數。

tornado.concurrent.chain_future(a: Future[_T], b: Future[_T]) → None

將兩個 Future 鏈結在一起，使一個完成時，另一個也會完成。

除非 b 在 a 完成時已經完成或取消，否則 a 的結果 (成功或失敗) 將複製到 b。

變更於版本 5.0: 現在接受 Tornado/asyncio Future 物件和 concurrent.futures.Future。

tornado.concurrent.future_set_result_unless_cancelled(future: Union[futures.Future[_T], Future[_T]], value: _T) → None

如果未取消，則將給定的 value 設定為 Future 的結果。

避免在已取消的 asyncio.Future 上呼叫 set_result() 時發生 asyncio.InvalidStateError。

新增於版本 5.0。

tornado.concurrent.future_set_exception_unless_cancelled(future: Union[futures.Future[_T], Future[_T]], exc: BaseException) → None

將給定的 exc 設定為 Future 的例外。

如果 Future 已經被取消，則會記錄異常。如果不需要此記錄，呼叫者應明確檢查 Future 的狀態，並呼叫 Future.set_exception，而不是使用此包裝函式。

避免在已取消的 asyncio.Future 上呼叫 set_exception() 時發生 asyncio.InvalidStateError。

6.0 版本新增。

tornado.concurrent.future_set_exc_info(future: Union[futures.Future[_T], Future[_T]], exc_info: Tuple[Optional[type], Optional[BaseException], Optional[TracebackType]]) → None

將給定的 exc_info 設定為 Future 的例外。

了解 asyncio.Future 和 Tornado 較舊版本中的擴充功能，以便在 Python 2 上啟用更好的追溯。

新增於版本 5.0。

在 6.0 版本中變更：如果 future 已經被取消，此函式將不會執行任何操作。（先前會引發 asyncio.InvalidStateError）

tornado.concurrent.future_add_done_callback(future: futures.Future[_T], callback: Callable[[futures.Future[_T]], None]) → None

tornado.concurrent.future_add_done_callback(future: Future[_T], callback: Callable[[Future[_T]], None]) → None

安排在 future 完成時呼叫 callback。

callback 會使用一個引數呼叫，即 future。

如果 future 已經完成，則會立即呼叫 callback。這可能與 Future.add_done_callback 的行為不同，後者不做此保證。

新增於版本 5.0。