tornado.concurrent
— Work with Future
objects¶
Utilities for working with
Future
objects.Tornado previously provided its own
Future
class, but now usesasyncio.Future
. This module contains utility functions for working withasyncio.Future
in a way that is backwards-compatible with Tornado’s oldFuture
implementation.While this module is an important part of Tornado’s internal implementation, applications rarely need to interact with it directly.
- class tornado.concurrent.Future¶
tornado.concurrent.Future
is an alias forasyncio.Future
.In Tornado, the main way in which applications interact with
Future
objects is byawaiting
oryielding
them in coroutines, instead of calling methods on theFuture
objects themselves. For more information on the available methods, see theasyncio.Future
docs.Changed in version 5.0: Tornado’s implementation of
Future
has been replaced by the version fromasyncio
when available.Future
objects can only be created while there is a currentIOLoop
The timing of callbacks scheduled with
Future.add_done_callback
has changed.Cancellation is now partially supported (only on Python 3)
The
exc_info
andset_exc_info
methods are no longer available on Python 3.
- tornado.concurrent.run_on_executor(*args: Any, **kwargs: Any) Callable [source]¶
Decorator to run a synchronous method asynchronously on an executor.
Returns a future.
The executor to be used is determined by the
executor
attributes ofself
. To use a different attribute name, pass a keyword argument to the decorator:@run_on_executor(executor='_thread_pool') def foo(self): pass
This decorator should not be confused with the similarly-named
IOLoop.run_in_executor
. In general, usingrun_in_executor
when calling a blocking method is recommended instead of using this decorator when defining a method. If compatibility with older versions of Tornado is required, consider defining an executor and usingexecutor.submit()
at the call site.Changed in version 4.2: Added keyword arguments to use alternative attributes.
Changed in version 5.0: Always uses the current IOLoop instead of
self.io_loop
.Changed in version 5.1: Returns a
Future
compatible withawait
instead of aconcurrent.futures.Future
.Deprecated since version 5.1: The
callback
argument is deprecated and will be removed in 6.0. The decorator itself is discouraged in new code but will not be removed in 6.0.Changed in version 6.0: The
callback
argument was removed.
- tornado.concurrent.chain_future(a: Future[_T], b: Future[_T]) None [source]¶
Chain two futures together so that when one completes, so does the other.
The result (success or failure) of
a
will be copied tob
, unlessb
has already been completed or cancelled by the timea
finishes.Changed in version 5.0: Now accepts both Tornado/asyncio
Future
objects andconcurrent.futures.Future
.
- tornado.concurrent.future_set_result_unless_cancelled(future: Union[futures.Future[_T], Future[_T]], value: _T) None [source]¶
Set the given
value
as theFuture
’s result, if not cancelled.Avoids
asyncio.InvalidStateError
when callingset_result()
on a cancelledasyncio.Future
.New in version 5.0.
- tornado.concurrent.future_set_exception_unless_cancelled(future: Union[futures.Future[_T], Future[_T]], exc: BaseException) None [source]¶
Set the given
exc
as theFuture
’s exception.If the Future is already canceled, logs the exception instead. If this logging is not desired, the caller should explicitly check the state of the Future and call
Future.set_exception
instead of this wrapper.Avoids
asyncio.InvalidStateError
when callingset_exception()
on a cancelledasyncio.Future
.New in version 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 [source]¶
Set the given
exc_info
as theFuture
’s exception.Understands both
asyncio.Future
and the extensions in older versions of Tornado to enable better tracebacks on Python 2.New in version 5.0.
Changed in version 6.0: If the future is already cancelled, this function is a no-op. (previously
asyncio.InvalidStateError
would be raised)
- tornado.concurrent.future_add_done_callback(future: futures.Future[_T], callback: Callable[[futures.Future[_T]], None]) None [source]¶
- tornado.concurrent.future_add_done_callback(future: Future[_T], callback: Callable[[Future[_T]], None]) None
Arrange to call
callback
whenfuture
is complete.callback
is invoked with one argument, thefuture
.If
future
is already done,callback
is invoked immediately. This may differ from the behavior ofFuture.add_done_callback
, which makes no such guarantee.New in version 5.0.