Classes | |
| class | BadYieldError |
| class | Callback |
| class | KeyReuseError |
| class | LeakedCallbackError |
| class | Multi |
| class | Return |
| class | ReturnValueIgnoredError |
| class | Runner |
| class | TimeoutError |
| class | UnknownKeyError |
| class | Wait |
| class | WaitAll |
| class | YieldFuture |
| class | YieldPoint |
Functions | |
| def | _argument_adapter |
| def | _make_coroutine_wrapper |
| def | coroutine |
| def | engine |
| def | maybe_future |
| def | multi_future |
| def | Task |
| def | with_timeout |
Variables | |
| tuple | _null_future = Future() |
| tuple | Arguments = collections.namedtuple('Arguments', ['args', 'kwargs']) |
| tuple | moment = Future() |
``tornado.gen`` is a generator-based interface to make it easier to
work in an asynchronous environment. Code using the ``gen`` module
is technically asynchronous, but it is written as a single generator
instead of a collection of separate functions.
For example, the following asynchronous handler::
class AsyncHandler(RequestHandler):
@asynchronous
def get(self):
http_client = AsyncHTTPClient()
http_client.fetch("http://example.com",
callback=self.on_fetch)
def on_fetch(self, response):
do_something_with_response(response)
self.render("template.html")
could be written with ``gen`` as::
class GenAsyncHandler(RequestHandler):
@gen.coroutine
def get(self):
http_client = AsyncHTTPClient()
response = yield http_client.fetch("http://example.com")
do_something_with_response(response)
self.render("template.html")
Most asynchronous functions in Tornado return a `.Future`;
yielding this object returns its `~.Future.result`.
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::
@gen.coroutine
def get(self):
http_client = AsyncHTTPClient()
response1, response2 = yield [http_client.fetch(url1),
http_client.fetch(url2)]
response_dict = yield dict(response3=http_client.fetch(url3),
response4=http_client.fetch(url4))
response3 = response_dict['response3']
response4 = response_dict['response4']
.. versionchanged:: 3.2
Dict support added.
| def tornado.gen._argument_adapter | ( | callback | ) | [private] |
Returns a function that when invoked runs ``callback`` with one arg. If the function returned by this function is called with exactly one argument, that argument is passed to ``callback``. Otherwise the args tuple and kwargs dict are wrapped in an `Arguments` object.
| def tornado.gen._make_coroutine_wrapper | ( | func, | |
| replace_callback | |||
| ) | [private] |
| def tornado.gen.coroutine | ( | func, | |
replace_callback = True |
|||
| ) |
Decorator for asynchronous generators. Any generator that yields objects from this module must be wrapped in either this decorator or `engine`. Coroutines may "return" by raising the special exception `Return(value) <Return>`. In Python 3.3+, it is also possible for the function to simply use the ``return value`` statement (prior to Python 3.3 generators were not allowed to also return values). 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 `.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``.
| def tornado.gen.engine | ( | func | ) |
Callback-oriented decorator for asynchronous generators. This is an older interface; for new code that does not need to be compatible with versions of Tornado older than 3.0 the `coroutine` decorator is recommended instead. This decorator is similar to `coroutine`, except it does not 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 they are finished. One notable exception is the `~tornado.web.RequestHandler` :ref:`HTTP verb methods <verbs>`, which use ``self.finish()`` in place of a callback argument.
| def tornado.gen.maybe_future | ( | x | ) |
Converts ``x`` into a `.Future`. If ``x`` is already a `.Future`, it is simply returned; otherwise it is wrapped in a new `.Future`. This is suitable for use as ``result = yield gen.maybe_future(f())`` when you don't know whether ``f()`` returns a `.Future` or not.
| def tornado.gen.multi_future | ( | children | ) |
Wait for multiple asynchronous futures in parallel. Takes a list of ``Futures`` (but *not* other ``YieldPoints``) and returns a new Future that resolves when all the other Futures are done. If all the ``Futures`` succeeded, the returned Future's result is a list of their results. If any failed, the returned Future raises the exception of the first one to fail. Instead of a list, the argument may also be a dictionary whose values are Futures, in which case a parallel dictionary is returned mapping the same keys to their results. It is not necessary to call `multi_future` explcitly, since the engine will do so automatically when the generator yields a list of `Futures`. This function is faster than the `Multi` `YieldPoint` because it does not require the creation of a stack context. .. versionadded:: 4.0
| def tornado.gen.Task | ( | func, | |
| args, | |||
| kwargs | |||
| ) |
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. .. 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 yielded.
| def tornado.gen.with_timeout | ( | timeout, | |
| future, | |||
io_loop = None |
|||
| ) |
Wraps a `.Future` in a timeout. Raises `TimeoutError` if the input future does not complete before ``timeout``, which may be specified in any form allowed by `.IOLoop.add_timeout` (i.e. a `datetime.timedelta` or an absolute time relative to `.IOLoop.time`) Currently only supports Futures, not other `YieldPoint` classes. .. versionadded:: 4.0
| tuple tornado::gen::_null_future = Future() |
| tuple tornado::gen::Arguments = collections.namedtuple('Arguments', ['args', 'kwargs']) |
| tuple tornado::gen::moment = Future() |