Tornado 3.2.1

libs/tornado/concurrent.py

@@ -40,52 +40,132 @@ class ReturnValueIgnoredError(Exception):
     pass
 
 
-class _DummyFuture(object):
+class Future(object):
+    """Placeholder for an asynchronous result.
+
+    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`.
+
+    `tornado.concurrent.Future` is similar to
+    `concurrent.futures.Future`, but not thread-safe (and therefore
+    faster for use with single-threaded event loops).
+
+    In addition to ``exception`` and ``set_exception``, methods ``exc_info``
+    and ``set_exc_info`` are supported to capture tracebacks in Python 2.
+    The traceback is automatically available in Python 3, but in the
+    Python 2 futures backport this information is discarded.
+    This functionality was previously available in a separate class
+    ``TracebackFuture``, which is now a deprecated alias for this class.
+
+    .. versionchanged:: 3.3
+       `tornado.concurrent.Future` is always a thread-unsafe ``Future``
+       with support for the ``exc_info`` methods.  Previously it would
+       be an alias for the thread-safe `concurrent.futures.Future`
+       if that package was available and fall back to the thread-unsafe
+       implementation if it was not.
+
+    """
     def __init__(self):
         self._done = False
         self._result = None
         self._exception = None
+        self._exc_info = None
         self._callbacks = []
 
     def cancel(self):
+        """Cancel the operation, if possible.
+
+        Tornado ``Futures`` do not support cancellation, so this method always
+        returns False.
+        """
         return False
 
     def cancelled(self):
+        """Returns True if the operation has been cancelled.
+
+        Tornado ``Futures`` do not support cancellation, so this method
+        always returns False.
+        """
         return False
 
     def running(self):
+        """Returns True if this operation is currently running."""
         return not self._done
 
     def done(self):
+        """Returns True if the future has finished running."""
         return self._done
 
     def result(self, timeout=None):
-        self._check_done()
-        if self._exception:
+        """If the operation succeeded, return its result.  If it failed,
+        re-raise its exception.
+        """
+        if self._result is not None:
+            return self._result
+        if self._exc_info is not None:
+            raise_exc_info(self._exc_info)
+        elif self._exception is not None:
             raise self._exception
+        self._check_done()
         return self._result
 
     def exception(self, timeout=None):
-        self._check_done()
-        if self._exception:
+        """If the operation raised an exception, return the `Exception`
+        object.  Otherwise returns None.
+        """
+        if self._exception is not None:
             return self._exception
         else:
+            self._check_done()
             return None
 
     def add_done_callback(self, fn):
+        """Attaches the given callback to the `Future`.
+
+        It will be invoked with the `Future` as its argument when the Future
+        has finished running and its result is available.  In Tornado
+        consider using `.IOLoop.add_future` instead of calling
+        `add_done_callback` directly.
+        """
         if self._done:
             fn(self)
         else:
             self._callbacks.append(fn)
 
     def set_result(self, result):
+        """Sets the result of a ``Future``.
+
+        It is undefined to call any of the ``set`` methods more than once
+        on the same object.
+        """
         self._result = result
         self._set_done()
 
     def set_exception(self, exception):
+        """Sets the exception of a ``Future.``"""
         self._exception = exception
         self._set_done()
 
+    def exc_info(self):
+        """Returns a tuple in the same format as `sys.exc_info` or None.
+
+        .. versionadded:: 3.3
+        """
+        return self._exc_info
+
+    def set_exc_info(self, exc_info):
+        """Sets the exception information of a ``Future.``
+
+        Preserves tracebacks on Python 2.
+
+        .. versionadded:: 3.3
+        """
+        self._exc_info = exc_info
+        self.set_exception(exc_info[1])
+
     def _check_done(self):
         if not self._done:
             raise Exception("DummyFuture does not support blocking for results")
@@ -97,38 +177,16 @@ class _DummyFuture(object):
             cb(self)
         self._callbacks = None
 
+TracebackFuture = Future
+
 if futures is None:
-    Future = _DummyFuture
+    FUTURES = Future
 else:
-    Future = futures.Future
+    FUTURES = (futures.Future, Future)
 
 
-class TracebackFuture(Future):
-    """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 __init__(self):
-        super(TracebackFuture, self).__init__()
-        self.__exc_info = None
-
-    def exc_info(self):
-        return self.__exc_info
-
-    def set_exc_info(self, exc_info):
-        """Traceback-aware replacement for
-        `~concurrent.futures.Future.set_exception`.
-        """
-        self.__exc_info = exc_info
-        self.set_exception(exc_info[1])
-
-    def result(self, timeout=None):
-        if self.__exc_info is not None:
-            raise_exc_info(self.__exc_info)
-        else:
-            return super(TracebackFuture, self).result(timeout=timeout)
+def is_future(x):
+    return isinstance(x, FUTURES)
 
 
 class DummyExecutor(object):
@@ -254,10 +312,13 @@ def return_future(f):
 def chain_future(a, b):
     """Chain two futures together so that when one completes, so does the other.
 
-    The result (success or failure) of ``a`` will be copied to ``b``.
+    The result (success or failure) of ``a`` will be copied to ``b``, unless
+    ``b`` has already been completed or cancelled by the time ``a`` finishes.
     """
     def copy(future):
         assert future is a
+        if b.done():
+            return
         if (isinstance(a, TracebackFuture) and isinstance(b, TracebackFuture)
                 and a.exc_info() is not None):
             b.set_exc_info(a.exc_info())