Utilities for working with Future objects.

Futures are a pattern for concurrent programming introduced in Python 3.2 in the concurrent.futures package, and also adopted (in a slightly different form) in Python 3.4’s asyncio package. This package defines a Future class that is an alias for asyncio.Future when available, and a compatible implementation for older versions of Python. It also includes some utility functions for interacting with Future objects.

While this package 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 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)

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. 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.

tornado.concurrent.return_future(f)

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

This decorator was provided to ease the transition from callback-oriented code to coroutines. It is not recommended for new code.

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)

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)

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)

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)

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.