# `tornado.concurrent` — Work with `Future` objects

> Utilities for working with `Future` objects.

> Tornado previously provided its own `Future` class, but now uses `asyncio.Future`. This module contains utility functions for working with `asyncio.Future` in a way that is backwards-compatible with Tornado’s old `Future` 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 for `asyncio.Future`.

  In Tornado, the main way in which applications interact with `Future` objects is by `awaiting` or `yielding` them in coroutines, instead of calling methods on the `Future` objects themselves. For more information on the available methods, see the `asyncio.Future` docs.

  Changed in version 5.0: Tornado’s implementation of `Future` has been replaced by the version from `asyncio` when available.

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

  - The timing of callbacks scheduled with `Future.add_done_callback` has changed.

  - Cancellation is now partially supported (only on Python 3)

  - The `exc_info` and `set_exc_info` methods are no longer available on Python 3.

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

  Decorator to run a synchronous method asynchronously on an executor.

  Returns a future.

  The executor to be used is determined by the `executor` attributes of `self`. 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, using `run_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 using `executor.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 with `await` instead of a `concurrent.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

  Chain two futures together so that when one completes, so does the other.

  The result (success or failure) of `a` will be copied to `b`, unless `b` has already been completed or cancelled by the time `a` finishes.

  Changed in version 5.0: Now accepts both Tornado/asyncio `Future` objects and `concurrent.futures.Future`.

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

  Set the given `value` as the `Future`’s result, if not cancelled.

  Avoids `asyncio.InvalidStateError` when calling `set_result()` on a cancelled `asyncio.Future`.

  New in version 5.0.

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

  Set the given `exc` as the `Future`’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 calling `set_exception()` on a cancelled `asyncio.Future`.

  New in version 6.0.

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

  Set the given `exc_info` as the `Future`’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: Future[_T], callback: Callable[[Future[_T]], None]) → None
tornado.concurrent.future_add_done_callback(future: Future[_T], callback: Callable[[Future[_T]], None]) → None

  Arrange to call `callback` when `future` is complete.

  `callback` is invoked with one argument, the `future`.

  If `future` is already done, `callback` is invoked immediately. This may differ from the behavior of `Future.add_done_callback`, which makes no such guarantee.

  New in version 5.0.