tornado.concurrent — Work with Future objects

使用Future对象的实用程序.

Tornado以前提供了自己的Future类,但现在使用asyncio.Future . 此模块包含用于与asyncio.Future配合使用的实用工具功能,该功能与Tornado的旧Future实现向后兼容.

尽管此模块是Tornado内部实现的重要组成部分,但应用程序很少需要直接与其交互.

class tornado.concurrent.Future

tornado.concurrent.Future是一个别名asyncio.Future .

在Tornado中,应用程序与Future对象进行交互的主要方式是通过在协程中awaitingyielding它们,而不是在Future对象本身上调用方法. 有关可用方法的更多信息,请参见asyncio.Future文档.

版本5.0中的更改:如果可用,Tornado的Future的实现已被asyncio的版本替换.

  • Future objects can only be created while there is a current IOLoop

  • 通过Future.add_done_callback安排的回调的时间已更改.

  • 现在部分支持取消(仅适用于Python 3)

  • 在Python 3上不再可以使用exc_infoset_exc_info方法.

class tornado.concurrent.Future

该类几乎与parallel.futures.Future兼容.

Differences:

  • result()和exception()不会接受超时参数,并且在未来还没有完成时会引发异常.

  • 始终通过事件循环的call_soon_threadsafe()调用在add_done_callback()中注册的回调.

  • 此类与parallel.futures包中的wait()和as_completed()方法不兼容.

add_done_callback()

添加一个将来完成时要运行的回调.

使用单个参数-将来对象调用回调. 如果在调用此命令时已经完成了将来,则使用call_soon安排回调.

cancel()

取消将来并安排回调.

如果将来已经完成或取消,则返回False. 否则,将future的状态更改为cancelled,安排回调并返回True.

cancelled()

如果取消了将来,则返回True.

done()

如果将来完成,则返回True.

"完成"表示结果/异常可用,或者取消了将来.

exception()

返回在此将来设置的异常.

仅在将来完成时才返回异常(如果未设置任何异常,则返回None). 如果将来已取消,则引发CancelledError. 如果将来还没有完成,则引发InvalidStateError.

get_loop()

返回Future绑定到的事件循环.

remove_done_callback()

从"完成时调用"列表中删除回调的所有实例.

返回删除的回调数.

result()

返回这个未来代表的结果.

如果将来已取消,则引发CancelledError. 如果将来的结果尚不可用,则引发InvalidStateError. 如果将来完成并设置了例外,则会引发此例外.

set_exception()

标记未来已完成并设置例外.

If the future is already done when this method is called, raises InvalidStateError.

set_result()

标记未来并设定结果.

如果调用此方法时已经完成,则会引发InvalidStateError.

tornado.concurrent.run_on_executor(*args, **kwargs) → Callable[source]

装饰器,以在执行程序上异步运行同步方法.

装饰的方法可以使用callback关键字参数调用,并返回Future.

要使用的executorselfexecutor属性确定. 要使用其他属性名称,请将关键字参数传递给装饰器:

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

不应将此装饰器与类似名称的IOLoop.run_in_executor . 通常, 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[source]

将两个期货链接在一起,以便当一个期货完成时,另一个期货也完成.

结果(成功或失败) a将被复制到b ,除非b已经完成,或由时间取消a结束.

改变在5.0版本:现在接受龙卷风/ ASYNCIO Future对象和concurrent.futures.Future .

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

如果未取消,则将给定value设置为Future的结果.

避免asyncio.InvalidStateError时调用set_result()在取消asyncio.Future .

5.0版中的新功能.

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

将给定的exc设置为Future的例外.

如果Future已被取消,则记录异常. 如果不需要此日志记录,则调用方应显式检查Future的状态,并调用Future.set_exception而不是此包装器.

避免asyncio.InvalidStateError时调用set_exception()在取消asyncio.Future .

6.0版中的新功能.

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

将给定的exc_info设置为Future的异常.

理解asyncio.Future和旧版Tornado中的扩展,以在Python 2上实现更好的追溯.

5.0版中的新功能.

在版本6.0中更改:如果将来已经取消,则此功能为无操作状态. (以前会引发asyncio.InvalidStateError

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

安排在future完成时调用callback .

callback调用一个说法, future .

如果future已经完成,则立即调用callback . 这可能与Future.add_done_callback的行为不同,后者没有做出这样的保证.

5.0版中的新功能.