Detailed Description
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 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. Subclasses must implement `fileno`, `close_fd`, `write_to_fd`, `read_from_fd`, and optionally `get_fd_error`.
Definition at line 102 of file iostream.py.
Constructor & Destructor Documentation
| def tornado.iostream.BaseIOStream.__init__ | ( | self, | |
io_loop = None, |
|||
max_buffer_size = None, |
|||
read_chunk_size = None, |
|||
max_write_buffer_size = None |
|||
| ) |
`BaseIOStream` constructor.
:arg io_loop: The `.IOLoop` to use; defaults to `.IOLoop.current`.
:arg max_buffer_size: Maximum amount of incoming data to buffer;
defaults to 100MB.
:arg read_chunk_size: Amount of data to read at one time from the
underlying transport; defaults to 64KB.
:arg max_write_buffer_size: Amount of outgoing data to buffer;
defaults to unlimited.
.. versionchanged:: 4.0
Add the ``max_write_buffer_size`` parameter. Changed default
``read_chunk_size`` to 64KB.
Definition at line 120 of file iostream.py.
Member Function Documentation
| def tornado.iostream.BaseIOStream._add_io_state | ( | self, | |
| state | |||
| ) | [private] |
Adds `state` (IOLoop.{READ,WRITE} flags) to our event handler.
Implementation notes: Reads and writes have a fast path and a
slow path. The fast path reads synchronously from socket
buffers, while the slow path uses `_add_io_state` to schedule
an IOLoop callback. Note that in both cases, the callback is
run asynchronously with `_run_callback`.
To detect closed connections, we must have called
`_add_io_state` at some point, but we want to delay this as
much as possible so we don't have to set an `IOLoop.ERROR`
listener that will be overwritten by the next slow-path
operation. As long as there are callbacks scheduled for
fast-path ops, those callbacks may do more reads.
If a sequence of fast-path ops do not end in a slow-path op,
(e.g. for an @asynchronous long-poll request), we must add
the error handler. This is done in `_run_callback` and `write`
(since the write callback is optional so we can have a
fast-path write with no `_run_callback`)
Definition at line 853 of file iostream.py.
| def tornado.iostream.BaseIOStream._check_closed | ( | self | ) | [private] |
Definition at line 833 of file iostream.py.
| def tornado.iostream.BaseIOStream._check_max_bytes | ( | self, | |
| delimiter, | |||
| size | |||
| ) | [private] |
Definition at line 770 of file iostream.py.
| def tornado.iostream.BaseIOStream._consume | ( | self, | |
| loc | |||
| ) | [private] |
Definition at line 826 of file iostream.py.
| def tornado.iostream.BaseIOStream._find_read_pos | ( | self | ) | [private] |
Attempts to find a position in the read buffer that satisfies the currently-pending read. Returns a position in the buffer if the current read can be satisfied, or None if it cannot.
Definition at line 722 of file iostream.py.
| def tornado.iostream.BaseIOStream._handle_events | ( | self, | |
| fd, | |||
| events | |||
| ) | [private] |
Definition at line 451 of file iostream.py.
| def tornado.iostream.BaseIOStream._handle_read | ( | self | ) | [private] |
Reimplemented in tornado.iostream.SSLIOStream.
Definition at line 599 of file iostream.py.
| def tornado.iostream.BaseIOStream._handle_write | ( | self | ) | [private] |
Reimplemented in tornado.iostream.SSLIOStream.
Definition at line 777 of file iostream.py.
| def tornado.iostream.BaseIOStream._maybe_add_error_listener | ( | self | ) | [private] |
Definition at line 837 of file iostream.py.
| def tornado.iostream.BaseIOStream._maybe_run_close_callback | ( | self | ) | [private] |
Definition at line 390 of file iostream.py.
| def tornado.iostream.BaseIOStream._read_from_buffer | ( | self, | |
| pos | |||
| ) | [private] |
Attempts to complete the currently-pending read from the buffer. The argument is either a position in the read buffer or None, as returned by _find_read_pos.
Definition at line 712 of file iostream.py.
| def tornado.iostream.BaseIOStream._read_to_buffer | ( | self | ) | [private] |
Reads from the socket and appends the result to the read buffer. Returns the number of bytes read. Returns 0 if there is nothing to read (i.e. the read returns EWOULDBLOCK or equivalent). On error closes the socket and raises an exception.
Definition at line 675 of file iostream.py.
| def tornado.iostream.BaseIOStream._read_to_buffer_loop | ( | self | ) | [private] |
Definition at line 539 of file iostream.py.
| def tornado.iostream.BaseIOStream._run_callback | ( | self, | |
| callback, | |||
| args | |||
| ) | [private] |
Definition at line 504 of file iostream.py.
| def tornado.iostream.BaseIOStream._run_read_callback | ( | self, | |
| size, | |||
| streaming | |||
| ) | [private] |
Definition at line 623 of file iostream.py.
| def tornado.iostream.BaseIOStream._run_streaming_callback | ( | self | ) | [private] |
Definition at line 704 of file iostream.py.
| def tornado.iostream.BaseIOStream._set_read_callback | ( | self, | |
| callback | |||
| ) | [private] |
Definition at line 614 of file iostream.py.
| def tornado.iostream.BaseIOStream._try_inline_read | ( | self | ) | [private] |
Attempt to complete the current read operation from buffered data. If the read can be completed without blocking, schedules the read callback on the next IOLoop iteration; otherwise starts listening for reads on the socket.
Definition at line 642 of file iostream.py.
| def tornado.iostream.BaseIOStream.close | ( | self, | |
exc_info = False |
|||
| ) |
Close this stream. If ``exc_info`` is true, set the ``error`` attribute to the current exception from `sys.exc_info` (or if ``exc_info`` is a tuple, use that instead of `sys.exc_info`).
Definition at line 364 of file iostream.py.
| def tornado.iostream.BaseIOStream.close_fd | ( | self | ) |
Closes the file underlying this stream. ``close_fd`` is called by `BaseIOStream` and should not be called elsewhere; other users should call `close` instead.
Reimplemented in tornado.iostream.PipeIOStream, and tornado.iostream.IOStream.
Definition at line 172 of file iostream.py.
| def tornado.iostream.BaseIOStream.closed | ( | self | ) |
Returns true if the stream has been closed.
Definition at line 432 of file iostream.py.
| def tornado.iostream.BaseIOStream.fileno | ( | self | ) |
Returns the file descriptor for this stream.
Reimplemented in tornado.iostream.PipeIOStream, and tornado.iostream.IOStream.
Definition at line 168 of file iostream.py.
| def tornado.iostream.BaseIOStream.get_fd_error | ( | self | ) |
Returns information about any error on the underlying file. This method is called after the `.IOLoop` has signaled an error on the file descriptor, and should return an Exception (such as `socket.error` with additional information, or None if no such information is available.
Reimplemented in tornado.iostream.IOStream.
Definition at line 197 of file iostream.py.
| def tornado.iostream.BaseIOStream.read_bytes | ( | self, | |
| num_bytes, | |||
callback = None, |
|||
streaming_callback = None, |
|||
partial = False |
|||
| ) |
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 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`.
If ``partial`` is true, the callback is run as soon as we have
any bytes to return (but never more than ``num_bytes``)
.. versionchanged:: 4.0
Added the ``partial`` argument. The callback argument is now
optional and a `.Future` will be returned if it is omitted.
Definition at line 262 of file iostream.py.
| def tornado.iostream.BaseIOStream.read_from_fd | ( | self | ) |
Attempts to read from the underlying file. Returns ``None`` if there was nothing to read (the socket returned `~errno.EWOULDBLOCK` or equivalent), otherwise returns the data. When possible, should return no more than ``self.read_chunk_size`` bytes at a time.
Reimplemented in tornado.iostream.PipeIOStream, tornado.iostream.SSLIOStream, and tornado.iostream.IOStream.
Definition at line 187 of file iostream.py.
| def tornado.iostream.BaseIOStream.read_until | ( | self, | |
| delimiter, | |||
callback = None, |
|||
max_bytes = None |
|||
| ) |
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`.
If ``max_bytes`` is not None, the connection will be closed
if more than ``max_bytes`` bytes have been read and the delimiter
is not found.
.. versionchanged:: 4.0
Added the ``max_bytes`` argument. The ``callback`` argument is
now optional and a `.Future` will be returned if it is omitted.
Definition at line 235 of file iostream.py.
| def tornado.iostream.BaseIOStream.read_until_close | ( | self, | |
callback = None, |
|||
streaming_callback = None |
|||
| ) |
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 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:: 4.0
The callback argument is now optional and a `.Future` will
be returned if it is omitted.
Definition at line 287 of file iostream.py.
| def tornado.iostream.BaseIOStream.read_until_regex | ( | self, | |
| regex, | |||
callback = None, |
|||
max_bytes = None |
|||
| ) |
Asynchronously read until we have matched the given regex.
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`.
If ``max_bytes`` is not None, the connection will be closed
if more than ``max_bytes`` bytes have been read and the regex is
not satisfied.
.. versionchanged:: 4.0
Added the ``max_bytes`` argument. The ``callback`` argument is
now optional and a `.Future` will be returned if it is omitted.
Definition at line 207 of file iostream.py.
| def tornado.iostream.BaseIOStream.reading | ( | self | ) |
Returns true if we are currently reading from the stream.
Reimplemented in tornado.iostream.SSLIOStream.
Definition at line 424 of file iostream.py.
| def tornado.iostream.BaseIOStream.set_close_callback | ( | self, | |
| callback | |||
| ) |
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.
Definition at line 354 of file iostream.py.
| def tornado.iostream.BaseIOStream.set_nodelay | ( | self, | |
| value | |||
| ) |
Sets the no-delay flag for this stream. By default, data written to TCP streams may be held for a time to make the most efficient use of bandwidth (according to Nagle's algorithm). The no-delay flag requests that data be written as soon as possible, even if doing so would consume additional bandwidth. This flag is currently defined only for TCP-based ``IOStreams``. .. versionadded:: 3.1
Reimplemented in tornado.iostream.IOStream.
Definition at line 436 of file iostream.py.
| def tornado.iostream.BaseIOStream.write | ( | self, | |
| data, | |||
callback = None |
|||
| ) |
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:: 4.0
Now returns a `.Future` if no callback is given.
Definition at line 311 of file iostream.py.
| def tornado.iostream.BaseIOStream.write_to_fd | ( | self, | |
| data | |||
| ) |
Attempts to write ``data`` to the underlying file. Returns the number of bytes written.
Reimplemented in tornado.iostream.PipeIOStream, and tornado.iostream.IOStream.
Definition at line 180 of file iostream.py.
| def tornado.iostream.BaseIOStream.writing | ( | self | ) |
Returns true if we are currently writing to the stream.
Reimplemented in tornado.iostream.SSLIOStream.
Definition at line 428 of file iostream.py.
Member Data Documentation
Reimplemented in tornado.iostream.IOStream.
Definition at line 133 of file iostream.py.
tornado::iostream.BaseIOStream::_closed [private] |
Definition at line 133 of file iostream.py.
Reimplemented in tornado.iostream.IOStream.
Definition at line 133 of file iostream.py.
Reimplemented in tornado.iostream.IOStream.
Definition at line 133 of file iostream.py.
Reimplemented in tornado.iostream.IOStream.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
tornado::iostream.BaseIOStream::_state [private] |
Reimplemented in tornado.iostream.SSLIOStream.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Reimplemented in tornado.iostream.IOStream.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
Definition at line 133 of file iostream.py.
The documentation for this class was generated from the following file: