.. automodule:: tornado.concurrent
:members:
+ :exclude-members: Future, TracebackFuture
- .. py:class:: Future
+ .. autoclass:: 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`.
+ Consumer methods
+ ^^^^^^^^^^^^^^^^
- 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:
+ .. automethod:: Future.result
+ .. automethod:: Future.exception
+ .. automethod:: Future.exc_info
+ .. automethod:: Future.add_done_callback
+ .. automethod:: Future.done
+ .. automethod:: Future.running
+ .. automethod:: Future.cancel
+ .. automethod:: Future.cancelled
- * It is an error to call `result` or `exception` before the
- ``Future`` has completed.
- * Cancellation is not supported.
+ Producer methods
+ ^^^^^^^^^^^^^^^^
- .. 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.
+ .. automethod:: Future.set_result
+ .. automethod:: Future.set_exception
+ .. automethod:: Future.set_exc_info
.. automethod:: IOLoop.instance
.. automethod:: IOLoop.initialized
.. automethod:: IOLoop.install
+ .. automethod:: IOLoop.clear_instance
.. automethod:: IOLoop.start
.. automethod:: IOLoop.stop
.. automethod:: IOLoop.run_sync
* Now works on Python 2.6.
-`tornado.simple_httpclient`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``tornado.simple_httpclient``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Improved default cipher suite selection (Python 2.7+).
-`tornado.speedups`
-~~~~~~~~~~~~~~~~~~
-
-* The C extension now builds on windows in both 32 and 64-bit modes.
-* The fallback mechanism for detecting a missing C compiler now
- works correctly on Mac OS X.
`tornado.stack_context`
~~~~~~~~~~~~~~~~~~~~~~~
values when the other side closes.
* The C speedup module now builds correctly with MSVC, and can support
messages larger than 2GB on 64-bit systems.
+* The fallback mechanism for detecting a missing C compiler now
+ works correctly on Mac OS X.
`tornado.concurrent`
~~~~~~~~~~~~~~~~~~~~
-* `.TracebackFuture` now accepts a ``timeout`` keyword argument (although
+* ``TracebackFuture`` now accepts a ``timeout`` keyword argument (although
it is still incorrect to use a non-zero timeout in non-blocking code).
``tornado.curl_httpclient``
class Future(object):
"""Placeholder for an asynchronous result.
- Similar to `concurrent.futures.Future`, but not thread-safe (and
- therefore faster for use with single-threaded event loops.
+ 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.
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._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):
+ """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:
return self._result
def exception(self, timeout=None):
+ """If the operation raised an exception, return the `Exception`
+ object. Otherwise returns None.
+ """
if self._exception is not None:
return self._exception
else:
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):
- """Traceback-aware replacement for
- `~concurrent.futures.Future.set_exception`.
+ """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])
"""A utility class to write to and read from a non-blocking file or socket.
We support a non-blocking ``write()`` and a family of ``read_*()`` methods.
- All of the methods take callbacks (since writing and reading are
- non-blocking and asynchronous).
+ All of the methods take an optional ``callback`` argument and return a
+ `.Future` only if no callback is given. When the operation completes,
+ the callback will be run or the `.Future` will resolve with the data
+ read (or ``None`` for ``write()``). All outstanding ``Futures`` will
+ resolve with a `StreamClosedError` when the stream is closed; users
+ of the callback interface will be notified via
+ `.BaseIOStream.set_close_callback` instead.
When a stream is closed due to an error, the IOStream's ``error``
attribute contains the exception object.
return None
def read_until_regex(self, regex, callback=None):
- """Run ``callback`` when we read the given regex pattern.
+ """Asynchronously read until we have matched the given regex.
- The callback will get the data read (including the data that
- matched the regex and anything that came before it) as an argument.
+ The result includes the data that matches the regex and anything
+ that came before it. If a callback is given, it will be run
+ with the data as an argument; if not, this method returns a
+ `.Future`.
+
+ .. versionchanged:: 3.3
+ The callback argument is now optional and a `.Future` will
+ be returned if it is omitted.
"""
future = self._set_read_callback(callback)
self._read_regex = re.compile(regex)
return future
def read_until(self, delimiter, callback=None):
- """Run ``callback`` when we read the given delimiter.
+ """Asynchronously read until we have found the given delimiter.
+
+ The result includes all the data read including the delimiter.
+ If a callback is given, it will be run with the data as an argument;
+ if not, this method returns a `.Future`.
- The callback will get the data read (including the delimiter)
- as an argument.
+ .. versionchanged:: 3.3
+ The callback argument is now optional and a `.Future` will
+ be returned if it is omitted.
"""
future = self._set_read_callback(callback)
self._read_delimiter = delimiter
return future
def read_bytes(self, num_bytes, callback=None, streaming_callback=None):
- """Run callback when we read the given number of bytes.
+ """Asynchronously read a number of bytes.
If a ``streaming_callback`` is given, it will be called with chunks
- of data as they become available, and the argument to the final
- ``callback`` will be empty. Otherwise, the ``callback`` gets
- the data as an argument.
+ of data as they become available, and the final result will be empty.
+ Otherwise, the result is all the data that was read.
+ If a callback is given, it will be run with the data as an argument;
+ if not, this method returns a `.Future`.
+
+ .. versionchanged:: 3.3
+ The callback argument is now optional and a `.Future` will
+ be returned if it is omitted.
"""
future = self._set_read_callback(callback)
assert isinstance(num_bytes, numbers.Integral)
return future
def read_until_close(self, callback=None, streaming_callback=None):
- """Reads all data from the socket until it is closed.
+ """Asynchronously reads all data from the socket until it is closed.
If a ``streaming_callback`` is given, it will be called with chunks
- of data as they become available, and the argument to the final
- ``callback`` will be empty. Otherwise, the ``callback`` gets the
- data as an argument.
-
- Subject to ``max_buffer_size`` limit from `IOStream` constructor if
- a ``streaming_callback`` is not used.
+ of data as they become available, and the final result will be empty.
+ Otherwise, the result is all the data that was read.
+ If a callback is given, it will be run with the data as an argument;
+ if not, this method returns a `.Future`.
+
+ .. versionchanged:: 3.3
+ The callback argument is now optional and a `.Future` will
+ be returned if it is omitted.
"""
future = self._set_read_callback(callback)
self._streaming_callback = stack_context.wrap(streaming_callback)
return future
def write(self, data, callback=None):
- """Write the given data to this stream.
+ """Asynchronously write the given data to this stream.
If ``callback`` is given, we call it when all of the buffered write
data has been successfully written to the stream. If there was
previously buffered write data and an old write callback, that
callback is simply overwritten with this new callback.
+
+ If no ``callback`` is given, this method returns a `.Future` that
+ resolves (with a result of ``None``) when the write has been
+ completed. If `write` is called again before that `.Future` has
+ resolved, the previous future will be orphaned and will never resolve.
+
+ .. versionchanged:: 3.3
+ Now returns a `.Future` if no callback is given.
"""
assert isinstance(data, bytes_type)
self._check_closed()
return future
def set_close_callback(self, callback):
- """Call the given callback when the stream is closed."""
+ """Call the given callback when the stream is closed.
+
+ This is not necessary for applications that use the `.Future`
+ interface; all outstanding ``Futures`` will resolve with a
+ `StreamClosedError` when the stream is closed.
+ """
self._close_callback = stack_context.wrap(callback)
def close(self, exc_info=False):
not previously connected. The address parameter is in the
same format as for `socket.connect <socket.socket.connect>`,
i.e. a ``(host, port)`` tuple. If ``callback`` is specified,
- it will be called when the connection is completed.
+ it will be called when the connection is completed; if not
+ this method returns a `.Future`.
If specified, the ``server_hostname`` parameter will be used
in SSL connections for certificate validation (if requested in
which case the data will be written as soon as the connection
is ready. Calling `IOStream` read methods before the socket is
connected works on some platforms but is non-portable.
+
+ .. versionchanged:: 3.3
+ If no callback is given, returns a `.Future`.
"""
self._connecting = True
try:
"""Applies the gzip content encoding to the response.
See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11
+
+ .. versionchanged:: 3.3
+ Now compresses all mime types beginning with ``text/``, instead
+ of just a whitelist. (the whitelist is still used for certain
+ non-text mime types).
"""
# Whitelist of compressible mime types (in addition to any types
# beginning with "text/").
projects / thirdparty / tornado.git / commitdiff
