tornado.concurrent — Work with Future objects

Utilities for working with threads and Futures.

Futures are a pattern for concurrent programming introduced in Python 3.2 in the concurrent.futures package. This package defines a mostly-compatible Future class designed for use from coroutines, as well as some utility functions for interacting with the concurrent.futures package.

class tornado.concurrent.Future[source]

tornado.concurrent.Future is an alias for asyncio.Future on Python 3. On Python 2, it provides an equivalent implementation.

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, **kwargs)[source]

Decorator to run a synchronous method asynchronously on an executor.

The decorated method may be called with a callback keyword argument and 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.

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.

tornado.concurrent.return_future(f)[source]

Decorator to make a function that returns via callback return a Future.

The wrapped function should take a callback keyword argument and invoke it with one argument when it has finished. To signal failure, the function can simply raise an exception (which will be captured by the StackContext and passed along to the Future).

From the caller’s perspective, the callback argument is optional. If one is given, it will be invoked when the function is complete with Future.result() as an argument. If the function fails, the callback will not be run and an exception will be raised into the surrounding StackContext.

If no callback is given, the caller should use the Future to wait for the function to complete (perhaps by yielding it in a gen.engine function, or passing it to IOLoop.add_future).

Usage:

@return_future
def future_func(arg1, arg2, callback):
    # Do stuff (possibly asynchronous)
    callback(result)

@gen.engine
def caller(callback):
    yield future_func(arg1, arg2)
    callback()

Note that @return_future and @gen.engine can be applied to the same function, provided @return_future appears first. However, consider using @gen.coroutine instead of this combination.

tornado.concurrent.chain_future(a, b)[source]

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, value)[source]

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_exc_info(future, exc_info)[source]

Set the given exc_info as the Future’s exception.

Understands both asyncio.Future and Tornado’s extensions to enable better tracebacks on Python 2.

New in version 5.0.

tornado.concurrent.future_add_done_callback(future, callback)[source]

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.