Document convert_yielded.

diff --git a/docs/asyncio.rst b/docs/asyncio.rst
index e7c2c8fd9f29d5ec0b4ffb2c18c03aa658ad48e1..b9e7459cbf1a3f56c3ac870c2514ff18408ffb03 100644 (file)
--- a/docs/asyncio.rst
+++ b/docs/asyncio.rst
@@ -45,3 +45,15 @@ loops.
 
     Each ``AsyncIOLoop`` creates a new ``asyncio.EventLoop``; this object
     can be accessed with the ``asyncio_loop`` attribute.
+
+.. py:function:: to_tornado_future
+
+   Convert an ``asyncio.Future`` to a `tornado.concurrent.Future`.
+
+   .. versionadded:: 4.1
+
+.. py:function:: to_asyncio_future
+
+   Convert a `tornado.concurrent.Future` to an ``asyncio.Future``.
+
+   .. versionadded:: 4.1

diff --git a/docs/gen.rst b/docs/gen.rst
index c010ed4186a875dc9ef881de584e0d38e4e60c88..e9a7e5c53841813bb8ebcfa6f5f27effd67206be 100644 (file)
--- a/docs/gen.rst
+++ b/docs/gen.rst
@@ -34,6 +34,8 @@
       used either as a tuple ``(args, kwargs)`` or an object with attributes
       ``args`` and ``kwargs``.
 
+   .. autofunction:: convert_yielded
+
    Legacy interface
    ----------------
 

diff --git a/tornado/gen.py b/tornado/gen.py
index f41cbafd984eedbb7510f0b13a46dd03cbf378a3..c9c6f5c1dce755bd7986e92b6baaff37e66117af 100644 (file)
--- a/tornado/gen.py
+++ b/tornado/gen.py
@@ -43,8 +43,21 @@ be returned when they are all finished::
         response3 = response_dict['response3']
         response4 = response_dict['response4']
 
+If the `~functools.singledispatch` library is available (standard in
+Python 3.4, available via the `singledispatch
+<https://pypi.python.org/pypi/singledispatch>`_ package on older
+versions), additional types of objects may be yielded. Tornado includes
+support for ``asyncio.Future`` and Twisted's ``Deferred`` class when
+``tornado.platform.asyncio`` and ``tornado.platform.twisted`` are imported.
+See the `convert_yielded` function to extend this mechanism.
+
 .. versionchanged:: 3.2
    Dict support added.
+
+.. versionchanged:: 4.1
+   Support added for yielding ``asyncio`` Futures and Twisted Deferreds
+   via ``singledispatch``.
+
 """
 from __future__ import absolute_import, division, print_function, with_statement
 
@@ -900,6 +913,19 @@ def _argument_adapter(callback):
 
 
 def convert_yielded(yielded):
+    """Convert a yielded object into a `.Future`.
+
+    The default implementation accepts lists, dictionaries, and Futures.
+
+    If the `~functools.singledispatch` library is available, this function
+    may be extended to support additional types. For example::
+
+        @convert_yielded.register(asyncio.Future)
+        def _(asyncio_future):
+            return tornado.platform.asyncio.to_tornado_future(asyncio_future)
+
+    .. versionadded:: 4.1
+    """
     # Lists and dicts containing YieldPoints were handled separately
     # via Multi().
     if isinstance(yielded, (list, dict)):