From: Ben Darnell Date: Sun, 17 Mar 2013 17:42:12 +0000 (-0400) Subject: Document tornado.concurrent.Future. X-Git-Tag: v3.0.0~12 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b5a27a3a2c68c895997814c9fc58b83cc3265380;p=thirdparty%2Ftornado.git Document tornado.concurrent.Future. All internal links now point there instead of to concurrent.future.Futures. --- diff --git a/docs/concurrent.rst b/docs/concurrent.rst index c41a3dc01..378adc9a4 100644 --- a/docs/concurrent.rst +++ b/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. diff --git a/docs/gen.rst b/docs/gen.rst index 673c252b7..28879c009 100644 --- a/docs/gen.rst +++ b/docs/gen.rst @@ -14,11 +14,11 @@ ------------ Instances of the following classes may be used in yield expressions - in the generator. `Futures ` 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 diff --git a/docs/releases/next.rst b/docs/releases/next.rst index 1874a91db..6ee05d855 100644 --- a/docs/releases/next.rst +++ b/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. diff --git a/tornado/auth.py b/tornado/auth.py index aa62540d4..1b354cd22 100644 --- a/tornado/auth.py +++ b/tornado/auth.py @@ -445,10 +445,10 @@ class OAuthMixin(object): """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`. diff --git a/tornado/concurrent.py b/tornado/concurrent.py index e5a6ade79..15a039ca1 100644 --- a/tornado/concurrent.py +++ b/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 @@ else: 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 @@ _NO_RESULT = object() 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() ` 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 diff --git a/tornado/gen.py b/tornado/gen.py index 12b258d58..23b3c81c3 100644 --- a/tornado/gen.py +++ b/tornado/gen.py @@ -27,8 +27,8 @@ could be written with ``gen`` as:: 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``. diff --git a/tornado/httpclient.py b/tornado/httpclient.py index cbdbef8be..2a6f4467b 100644 --- a/tornado/httpclient.py +++ b/tornado/httpclient.py @@ -158,9 +158,9 @@ class AsyncHTTPClient(Configurable): 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. diff --git a/tornado/ioloop.py b/tornado/ioloop.py index 724eece07..efe90d406 100644 --- a/tornado/ioloop.py +++ b/tornado/ioloop.py @@ -320,10 +320,10 @@ class IOLoop(Configurable): 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 @@ class IOLoop(Configurable): 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) diff --git a/tornado/netutil.py b/tornado/netutil.py index 112dcd068..5c2a7cf49 100644 --- a/tornado/netutil.py +++ b/tornado/netutil.py @@ -191,12 +191,12 @@ class Resolver(Configurable): 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 ` (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 ` (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()