Document tornado.concurrent.Future.

All internal links now point there instead of to concurrent.future.Futures.

docs/concurrent.rst

@@ -3,3 +3,43 @@
 
 .. 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.

docs/gen.rst

@@ -14,11 +14,11 @@
    ------------
 
    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
 

docs/releases/next.rst

@@ -8,9 +8,9 @@ Highlights
 ^^^^^^^^^^
 
 * 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.
@@ -90,10 +90,9 @@ Multiple modules
 * 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`)
@@ -131,10 +130,10 @@ Multiple modules
 
 * 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.
@@ -146,7 +145,7 @@ Multiple modules
 `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
@@ -190,7 +189,7 @@ Multiple modules
   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.

tornado/auth.py

@@ -445,10 +445,10 @@ def _oauth_get_user_future(self, access_token, callback):
         """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`.

tornado/concurrent.py

@@ -13,11 +13,14 @@
 # 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
 
@@ -101,8 +104,8 @@ def _set_done(self):
 
 
 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.
@@ -162,7 +165,7 @@ def wrapper(self, *args, **kwargs):
 
 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,
@@ -171,9 +174,9 @@ def return_future(f):
 
     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

tornado/gen.py

@@ -27,8 +27,8 @@ def get(self):
             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
@@ -115,8 +115,8 @@ def engine(func):
     `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
@@ -180,14 +180,13 @@ def coroutine(func):
     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``.

tornado/httpclient.py

@@ -158,9 +158,9 @@ def fetch(self, request, callback=None, **kwargs):
         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.

tornado/ioloop.py

@@ -320,10 +320,10 @@ def stop(self):
     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,
@@ -434,10 +434,10 @@ def add_callback_from_signal(self, callback, *args, **kwargs):
 
     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)

tornado/netutil.py

@@ -191,12 +191,12 @@ def resolve(self, host, port, family=socket.AF_UNSPEC, callback=None):
         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()