.. autofunction:: engine
- Yield points
- ------------
+ Utility functions
+ -----------------
- Instances of the following classes may be used in yield expressions
- 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. Yielding dicts with these objects in values will
- return dict with results at the same keys.
-
- .. autofunction:: Task
-
- .. autoclass:: Callback
-
- .. autoclass:: Wait
-
- .. autoclass:: WaitAll
-
- .. autoclass:: YieldPoint
- :members:
+ .. autoexception:: Return
.. autofunction:: with_timeout
.. autoexception:: TimeoutError
.. autodata:: moment
:annotation:
- Other classes
- -------------
-
- .. autoexception:: Return
+ .. autofunction:: Task
.. class:: Arguments
- The result of a yield expression whose callback had more than one
+ The result of a `Task` or `Wait` whose callback had more than one
argument (or keyword arguments).
The `Arguments` object is a `collections.namedtuple` and can be
used either as a tuple ``(args, kwargs)`` or an object with attributes
``args`` and ``kwargs``.
+
+ Legacy interface
+ ----------------
+
+ Before support for `Futures <.Future>` was introduced in Tornado 3.0,
+ coroutines used subclasses of `YieldPoint` in their ``yield`` expressions.
+ These classes are still supported but should generally not be used
+ except for compatibility with older interfaces.
+
+ .. autoclass:: YieldPoint
+ :members:
+
+ .. autoclass:: Callback
+
+ .. autoclass:: Wait
+
+ .. autoclass:: WaitAll
`WebSockets <http://en.wikipedia.org/wiki/WebSocket>`_, and other
applications that require a long-lived connection to each user.
-Tornado can be roughly divided into three major components:
+Tornado can be roughly divided into four major components:
* A web framework (including `.RequestHandler` which is subclassed to
create web applications, and various supporting classes).
* An asynchronous networking library (`.IOLoop` and `.IOStream`),
which serve as the building blocks for the HTTP components and can
also be used to implement other protocols.
+* A coroutine library (`tornado.gen`) which allows asynchronous
+ code to be written in a more straightforward way than chaining
+ callbacks.
The Tornado web framework and HTTP server together offer a full-stack
alternative to `WSGI <http://www.python.org/dev/peps/pep-3333/>`_.
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
-can be used in either style, although the ``Future`` style is preferred
-since it is both shorter and provides better exception handling)::
-
- @gen.coroutine
- def get(self):
- yield gen.Task(AsyncHTTPClient().fetch, "http://example.com")
-
-You can also yield a list or dict of ``Futures`` and/or ``Tasks``, which will be
+You can also yield a list or dict of ``Futures``, which will be
started at the same time and run in parallel; a list or dict of results will
be returned when they are all finished::
.. versionchanged:: 3.2
Dict support added.
-
-For more complicated interfaces, `Task` can be split into two parts:
-`Callback` and `Wait`::
-
- class GenAsyncHandler2(RequestHandler):
- @gen.coroutine
- def get(self):
- http_client = AsyncHTTPClient()
- http_client.fetch("http://example.com",
- callback=(yield gen.Callback("key")))
- response = yield gen.Wait("key")
- do_something_with_response(response)
- self.render("template.html")
-
-The ``key`` argument to `Callback` and `Wait` allows for multiple
-asynchronous operations to be started at different times and proceed
-in parallel: yield several callbacks with different keys, then wait
-for them once all the async operations have started.
-
-The result of a `Wait` or `Task` yield expression depends on how the callback
-was run. If it was called with no arguments, the result is ``None``. If
-it was called with one argument, the result is that argument. If it was
-called with more than one argument or any keyword arguments, the result
-is an `Arguments` object, which is a named tuple ``(args, kwargs)``.
"""
from __future__ import absolute_import, division, print_function, with_statement
class YieldPoint(object):
"""Base class for objects that may be yielded from the generator.
- Applications do not normally need to use this class, but it may be
- subclassed to provide additional yielding behavior.
+ .. deprecated:: 4.0
+ Use `Futures <.Future>` instead.
"""
def start(self, runner):
"""Called by the runner after the generator has yielded.
The callback may be called with zero or one arguments; if an argument
is given it will be returned by `Wait`.
+
+ .. deprecated:: 4.0
+ Use `Futures <.Future>` instead.
"""
def __init__(self, key):
self.key = key
class Wait(YieldPoint):
- """Returns the argument passed to the result of a previous `Callback`."""
+ """Returns the argument passed to the result of a previous `Callback`.
+
+ .. deprecated:: 4.0
+ Use `Futures <.Future>` instead.
+ """
def __init__(self, key):
self.key = key
a list of results in the same order.
`WaitAll` is equivalent to yielding a list of `Wait` objects.
+
+ .. deprecated:: 4.0
+ Use `Futures <.Future>` instead.
"""
def __init__(self, keys):
self.keys = keys
def Task(func, *args, **kwargs):
- """Runs a single asynchronous operation.
+ """Adapts a callback-based asynchronous function for use in coroutines.
Takes a function (and optional additional arguments) and runs it with
those arguments plus a ``callback`` keyword argument. The argument passed
to the callback is returned as the result of the yield expression.
- A `Task` is equivalent to a `Callback`/`Wait` pair (with a unique
- key generated automatically)::
-
- result = yield gen.Task(func, args)
-
- func(args, callback=(yield gen.Callback(key)))
- result = yield gen.Wait(key)
-
.. versionchanged:: 4.0
``gen.Task`` is now a function that returns a `.Future`, instead of
a subclass of `YieldPoint`. It still behaves the same way when
projects / thirdparty / tornado.git / commitdiff
