All internal links now point there instead of to concurrent.future.Futures.
.. automodule:: tornado.concurrent
:members:
+
+ .. py:class:: Future
+
+ A ``Future`` encapsulates the result of an asynchronous
+ operation. In synchronous applications ``Futures`` are used
+ to wait for the result from a thread or process pool; in
+ Tornado they are normally used with `.IOLoop.add_future` or by
+ yielding them in a `.gen.coroutine`.
+
+ If the `concurrent.futures` package is available,
+ `tornado.concurrent.Future` is simply an alias for
+ `concurrent.futures.Future`. Otherwise, we support the same
+ interface with a few limitations:
+
+ * It is an error to call `result` or `exception` before the
+ ``Future`` has completed.
+ * Cancellation is not supported.
+
+ .. py:method:: result()
+
+ If the operation succeeded, return its result. If it failed,
+ re-raise its exception.
+
+ .. py:method:: exception()
+
+ If the operation raised an exception, return the `Exception`
+ object. Otherwise returns None.
+
+ .. py:method:: add_done_callback(fn)
+
+ Attaches the given callback to the `Future`. It will be invoked
+ with the `Future` as its argument when it has finished running
+ and its result is available. In Tornado consider using
+ `.IOLoop.add_future` instead of calling `add_done_callback`
+ directly.
+
+ .. py:method:: done()
+
+ Returns True if the future has finished running and its
+ `result` and `exception` methods are available.
------------
Instances of the following classes may be used in yield expressions
- in the generator. `Futures <concurrent.futures.Future>` may be yielded as
- well; their result method will be called automatically when they
- are ready. Additionally, lists of any combination of these objects
- may be yielded; the result is a list of the results of each yield
- point in the same order.
+ in the generator. `Futures <.Future>` may be yielded as well;
+ their result method will be called automatically when they are
+ ready. Additionally, lists of any combination of these objects may
+ be yielded; the result is a list of the results of each yield point
+ in the same order.
.. autoclass:: Task
^^^^^^^^^^
* The ``callback`` argument to many asynchronous methods is now
- optional, and these methods return a `~concurrent.futures.Future`.
- The `tornado.gen` module now understands ``Futures``, and these
- methods can be used directly without a `.gen.Task` wrapper.
+ optional, and these methods return a `.Future`. The `tornado.gen`
+ module now understands ``Futures``, and these methods can be used
+ directly without a `.gen.Task` wrapper.
* New function `.IOLoop.current` returns the `.IOLoop` that is running
on the current thread (as opposed to `.IOLoop.instance`, which
returns a specific thread's (usually the main thread's) IOLoop.
* On Python 3, the ``get_authenticated_user`` method family now returns
character strings instead of byte strings.
* Asynchronous methods defined in `tornado.auth` now return a
- `~concurrent.futures.Future`, and their ``callback`` argument is
- optional. The ``Future`` interface is preferred as it offers better
- error handling (the previous interface just logged a warning and
- returned None).
+ `.Future`, and their ``callback`` argument is optional. The
+ ``Future`` interface is preferred as it offers better error handling
+ (the previous interface just logged a warning and returned None).
* The `tornado.auth` mixin classes now define a method
``get_auth_http_client``, which can be overridden to use a non-default
`.AsyncHTTPClient` instance (e.g. to use a different `.IOLoop`)
* New decorator ``@gen.coroutine`` is available as an alternative to
``@gen.engine``. It automatically returns a
- `~concurrent.futures.Future`, and within the function instead of
+ `.Future`, and within the function instead of
calling a callback you return a value with ``raise
gen.Return(value)`` (or simply ``return value`` in Python 3.3).
-* Generators may now yield ``Future`` objects.
+* Generators may now yield `.Future` objects.
* Callbacks produced by `.gen.Callback` and `.gen.Task` are now automatically
stack-context-wrapped, to minimize the risk of context leaks when used
with asynchronous functions that don't do their own wrapping.
`tornado.httpclient`
~~~~~~~~~~~~~~~~~~~~
-* `.AsyncHTTPClient.fetch` now returns a ``Future`` and its callback argument
+* `.AsyncHTTPClient.fetch` now returns a `.Future` and its callback argument
is optional. When the future interface is used, any error will be raised
automatically, as if `.HTTPResponse.rethrow` was called.
* `.AsyncHTTPClient.configure` and all `.AsyncHTTPClient` constructors
on the current thread (as opposed to `.IOLoop.instance`, which returns a
specific thread's (usually the main thread's) IOLoop).
* New method `.IOLoop.add_future` to run a callback on the IOLoop when
- an asynchronous ``Future`` finishes.
+ an asynchronous `.Future` finishes.
* `.IOLoop` now has a static `configure <.Configurable.configure>`
method like the one on `.AsyncHTTPClient`, which can be used to
select an `.IOLoop` implementation other than the default.
"""Subclasses must override this to get basic information about the
user.
- Should return a `~concurrent.futures.Future` whose result is a
- dictionary containing information about the user, which may
- have been retrieved by using ``access_token`` to make a
- request to the service.
+ Should return a `.Future` whose result is a dictionary
+ containing information about the user, which may have been
+ retrieved by using ``access_token`` to make a request to the
+ service.
The access token will be added to the returned dictionary to make
the result of `get_authenticated_user`.
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
-"""Utilities for working with the `concurrent.futures` package.
-
-This module also contains compatibility shims including a dummy
-implementation of `concurrent.futures.Future` which can be used
-when `concurrent.futures` is not available.
+"""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 has also
+been backported to older versions of Python and can be installed with
+``pip install futures``). Tornado will use `concurrent.futures.Future` if
+it is available; otherwise it will use a compatible class defined in this
+module.
"""
from __future__ import absolute_import, division, print_function, with_statement
class TracebackFuture(Future):
- """Subclass of `~concurrent.futures.Future` which can store a traceback
- with exceptions.
+ """Subclass of `Future` which can store a traceback with
+ exceptions.
The traceback is automatically available in Python 3, but in the
Python 2 futures backport this information is discarded.
def return_future(f):
"""Decorator to make a function that returns via callback return a
- `~concurrent.futures.Future`.
+ `Future`.
The wrapped function should take a ``callback`` keyword argument
and invoke it with one argument when it has finished. To signal failure,
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() <concurrent.futures.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`.
+ 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
do_something_with_response(response)
self.render("template.html")
-Most asynchronous functions in Tornado return a `~concurrent.futures.Future`;
-yielding this object returns its `~concurrent.futures.Future.result`.
+Most asynchronous functions in Tornado return a `.Future`;
+yielding this object returns its `~.Future.result`.
For functions that do not return ``Futures``, `Task` works with any
function that takes a ``callback`` keyword argument (most Tornado functions
`coroutine` decorator is recommended instead.
This decorator is similar to `coroutine`, except it does not
- return a `~concurrent.futures.Future` and the ``callback``
- argument is not treated specially.
+ return a `.Future` and the ``callback`` argument is not treated
+ specially.
In most cases, functions decorated with `engine` should take
a ``callback`` argument and invoke it with their result when
In all versions of Python a coroutine that simply wishes to exit
early may use the ``return`` statement without a value.
- Functions with this decorator return a
- `~concurrent.futures.Future`. Additionally, they may be called
- with a ``callback`` keyword argument, which will be invoked with
- the future's result when it resolves. If the coroutine fails, the
- callback will not be run and an exception will be raised into the
- surrounding `.StackContext`. The ``callback`` argument is not
- visible inside the decorated function; it is handled by the
- decorator itself.
+ Functions with this decorator return a `.Future`. Additionally,
+ they may be called with a ``callback`` keyword argument, which
+ will be invoked with the future's result when it resolves. If the
+ coroutine fails, the callback will not be run and an exception
+ will be raised into the surrounding `.StackContext`. The
+ ``callback`` argument is not visible inside the decorated
+ function; it is handled by the decorator itself.
From the caller's perspective, ``@gen.coroutine`` is similar to
the combination of ``@return_future`` and ``@gen.engine``.
If it is a string, we construct an `HTTPRequest` using any additional
kwargs: ``HTTPRequest(request, **kwargs)``
- This method returns a `~concurrent.futures.Future` whose
- result is an `HTTPResponse`. The ``Future`` wil raise an
- `HTTPError` if the request returned a non-200 response code.
+ This method returns a `.Future` whose result is an
+ `HTTPResponse`. The ``Future`` wil raise an `HTTPError` if
+ the request returned a non-200 response code.
If a ``callback`` is given, it will be invoked with the `HTTPResponse`.
In the callback interface, `HTTPError` is not automatically raised.
def run_sync(self, func, timeout=None):
"""Starts the `IOLoop`, runs the given function, and stops the loop.
- If the function returns a `~concurrent.futures.Future`, the
- `IOLoop` will run until the future is resolved. If it raises
- an exception, the `IOLoop` will stop and the exception will be
- re-raised to the caller.
+ If the function returns a `.Future`, the `IOLoop` will run
+ until the future is resolved. If it raises an exception, the
+ `IOLoop` will stop and the exception will be re-raised to the
+ caller.
The keyword-only argument ``timeout`` may be used to set
a maximum duration for the function. If the timeout expires,
def add_future(self, future, callback):
"""Schedules a callback on the ``IOLoop`` when the given
- `~concurrent.futures.Future` is finished.
+ `.Future` is finished.
The callback is invoked with one argument, the
- `~concurrent.futures.Future`.
+ `.Future`.
"""
assert isinstance(future, Future)
callback = stack_context.wrap(callback)
The ``host`` argument is a string which may be a hostname or a
literal IP address.
- Returns a `~concurrent.futures.Future` whose result is a list
- of (family, address) pairs, where address is a tuple suitable
- to pass to `socket.connect <socket.socket.connect>` (i.e. a
- ``(host, port)`` pair for IPv4; additional fields may be
- present for IPv6). If a ``callback`` is passed, it will be run
- with the result as an argument when it is complete.
+ Returns a `.Future` whose result is a list of (family,
+ address) pairs, where address is a tuple suitable to pass to
+ `socket.connect <socket.socket.connect>` (i.e. a ``(host,
+ port)`` pair for IPv4; additional fields may be present for
+ IPv6). If a ``callback`` is passed, it will be run with the
+ result as an argument when it is complete.
"""
raise NotImplementedError()
projects / thirdparty / tornado.git / commitdiff
