tornado.concurrent — 使用 Future 对象

用于使用 Future 对象的实用工具。

Tornado 以前提供自己的 Future 类，但现在使用 asyncio.Future。此模块包含用于以向后兼容 Tornado 旧的 Future 实现的方式使用 asyncio.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 链在一起，以便当一个完成时，另一个也完成。

a 的结果（成功或失败）将被复制到 b，除非 b 在 a 完成之前已经完成或取消。

版本 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 中新增。