tornado.iostream — Convenient wrappers for non-blocking sockets¶

tornado.iostream — Convenient wrappers for non-blocking sockets¶

Utility classes to write to and read from non-blocking files and sockets.

Contents:

BaseIOStream: Generic interface for reading and writing.
IOStream: Implementation of BaseIOStream using non-blocking sockets.
SSLIOStream: SSL-aware version of IOStream.
PipeIOStream: Pipe-based IOStream implementation.

Base class¶

class tornado.iostream.BaseIOStream(io_loop=None, max_buffer_size=None, read_chunk_size=None, max_write_buffer_size=None)[源代码]¶: 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 aFuture only if no callback is given. When the operation completes,the callback will be run or the Future will resolve with the dataread (or None for write()). All outstanding Futures willresolve with a StreamClosedError when the stream is closed; usersof the callback interface will be notified viaBaseIOStream.set_close_callback instead.

When a stream is closed due to an error, the IOStream’s errorattribute contains the exception object.

Subclasses must implement fileno, close_fd, write_to_fd,read_from_fd, and optionally get_fd_error.

BaseIOStream constructor.

|参数:
|——-
|
- io_loop – The IOLoop to use; defaults to IOLoop.current.Deprecated since Tornado 4.1.
- max_buffer_size – Maximum amount of incoming data to buffer;defaults to 100MB.
- read_chunk_size – Amount of data to read at one time from theunderlying transport; defaults to 64KB.
- *max_write_buffer_size – Amount of outgoing data to buffer;defaults to unlimited.

在 4.0 版更改: Add the max_write_buffer_size parameter. Changed defaultread_chunk_size to 64KB.

Main interface¶

BaseIOStream.write(data, callback=None)[源代码]¶: Asynchronously write the given data to this stream.

If callback is given, we call it when all of the buffered writedata has been successfully written to the stream. If there waspreviously buffered write data and an old write callback, thatcallback is simply overwritten with this new callback.

If no callback is given, this method returns a Future thatresolves (with a result of None) when the write has beencompleted. If write is called again before that Future hasresolved, the previous future will be orphaned and will never resolve.

在 4.0 版更改: Now returns a Future if no callback is given.

BaseIOStream.readbytes(_num_bytes, callback=None, streaming_callback=None, partial=False)[源代码]¶: Asynchronously read a number of bytes.

If a streamingcallback is given, it will be called with chunksof 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 haveany bytes to return (but never more than num_bytes)

在 4.0 版更改: Added the partial argument. The callback argument is nowoptional and a Future will be returned if it is omitted.

BaseIOStream.read_until(_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 maxbytes is not None, the connection will be closedif more than max_bytes bytes have been read and the delimiteris not found.

在 4.0 版更改: Added the max_bytes argument. The callback argument isnow optional and a Future will be returned if it is omitted.

BaseIOStream.read_until_regex(_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 anythingthat came before it. If a callback is given, it will be runwith the data as an argument; if not, this method returns aFuture.

If maxbytes is not None, the connection will be closedif more than max_bytes bytes have been read and the regex isnot satisfied.

在 4.0 版更改: Added the max_bytes argument. The callback argument isnow optional and a Future will be returned if it is omitted.

BaseIOStream.read_until_close(_callback=None, streaming_callback=None)[源代码]¶: Asynchronously reads all data from the socket until it is closed.

If a streamingcallback is given, it will be called with chunksof 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.

Note that if a streaming_callback is used, data will beread from the socket as quickly as it becomes available; thereis no way to apply backpressure or cancel the reads. If flowcontrol or cancellation are desired, use a loop withread_bytes(partial=True) instead.

在 4.0 版更改: The callback argument is now optional and a Future willbe returned if it is omitted.

BaseIOStream.close(_exc_info=False)[源代码]¶: Close this stream.

If excinfo is true, set the error attribute to the currentexception from sys.exc_info (or if exc_info is a tuple,use that instead of sys.exc_info).

BaseIOStream.set_close_callback(_callback)[源代码]¶: Call the given callback when the stream is closed.

This is not necessary for applications that use the Futureinterface; all outstanding Futures will resolve with aStreamClosedError when the stream is closed.

BaseIOStream.closed()[源代码]¶: Returns true if the stream has been closed.

BaseIOStream.reading()[源代码]¶: Returns true if we are currently reading from the stream.

BaseIOStream.writing()[源代码]¶: Returns true if we are currently writing to the stream.

BaseIOStream.setnodelay(_value)[源代码]¶: Sets the no-delay flag for this stream.

By default, data written to TCP streams may be held for a timeto make the most efficient use of bandwidth (according toNagle’s algorithm). The no-delay flag requests that data bewritten as soon as possible, even if doing so would consumeadditional bandwidth.

This flag is currently defined only for TCP-based IOStreams.

3.1 新版功能.

Methods for subclasses¶

BaseIOStream.fileno()[源代码]¶: Returns the file descriptor for this stream.

BaseIOStream.closefd()[源代码]¶: Closes the file underlying this stream.

close_fd is called by BaseIOStream and should not be calledelsewhere; other users should call close instead.

BaseIOStream.write_to_fd(_data)[源代码]¶: Attempts to write data to the underlying file.

Returns the number of bytes written.

BaseIOStream.read_from_fd()[源代码]¶: Attempts to read from the underlying file.

Returns None if there was nothing to read (the socketreturned EWOULDBLOCK or equivalent), otherwisereturns the data. When possible, should return no more thanself.read_chunk_size bytes at a time.

BaseIOStream.get_fd_error()[源代码]¶: Returns information about any error on the underlying file.

This method is called after the IOLoop has signaled an error on thefile descriptor, and should return an Exception (such as socket.errorwith additional information, or None if no such information isavailable.

Implementations¶

class tornado.iostream.IOStream(socket, *args, **kwargs)[源代码]¶

Socket-based IOStream implementation.

This class supports the read and write methods from BaseIOStreamplus a connect method.

The socket parameter may either be connected or unconnected.For server operations the socket is the result of callingsocket.accept. For client operations thesocket is created with socket.socket, and may either beconnected before passing it to the IOStream or connected withIOStream.connect.

A very simple (and broken) HTTP client using this class:

import tornado.ioloop
import tornado.iostream
import socket

def sendrequest():
    stream.write(b"GET / HTTP/1.0\r\nHost: friendfeed.com\r\n\r\n")
    stream.readuntil(b"\r\n\r\n", onheaders)

def onheaders(data):
    headers = {}
    for line in data.split(b"\r\n"):
       parts = line.split(b":")
       if len(parts) == 2:
           headers[parts[0].strip()] = parts[1].strip()
    stream.readbytes(int(headers[b"Content-Length"]), on_body)

def on_body(data):
    print(data)
    stream.close()
    tornado.ioloop.IOLoop.current().stop()

if __name == '__main':
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
    stream = tornado.iostream.IOStream(s)
    stream.connect(("friendfeed.com", 80), send_request)
    tornado.ioloop.IOLoop.current().start()

connect(_address, callback=None, server_hostname=None)[源代码]¶: Connects the socket to a remote address without blocking.

May only be called if the socket passed to the constructor wasnot previously connected. The address parameter is in thesame format as for socket.connect forthe type of socket passed to the IOStream constructor,e.g. an (ip, port) tuple. Hostnames are accepted here,but will be resolved synchronously and block the IOLoop.If you have a hostname instead of an IP address, the TCPClientclass is recommended instead of calling this method directly.TCPClient will do asynchronous DNS resolution and handleboth IPv4 and IPv6.

If callback is specified, it will be called with noarguments when the connection is completed; if not this methodreturns a Future (whose result after a successfulconnection will be the stream itself).

In SSL mode, the serverhostname parameter will be usedfor certificate validation (unless disabled in thessl_options) and SNI (if supported; requires Python2.7.9+).

Note that it is safe to call IOStream.write while the connection is pending, inwhich case the data will be written as soon as the connectionis ready. Calling IOStream read methods before the socket isconnected works on some platforms but is non-portable.

在 4.0 版更改: If no callback is given, returns a Future.

在 4.2 版更改: SSL certificates are validated by default; passssl_options=dict(cert_reqs=ssl.CERT_NONE) or asuitably-configured ssl.SSLContext to theSSLIOStream constructor to disable.

start_tls(_server_side, ssl_options=None, server_hostname=None)[源代码]¶: Convert this IOStream to an SSLIOStream.

This enables protocols that begin in clear-text mode andswitch to SSL after some initial negotiation (such as theSTARTTLS extension to SMTP and IMAP).

This method cannot be used if there are outstanding readsor writes on the stream, or if there is any data in theIOStream’s buffer (data in the operating system’s socketbuffer is allowed). This means it must generally be usedimmediately after reading or writing the last clear-textdata. It can also be used immediately after connecting,before any reads or writes.

The ssloptions argument may be either an ssl.SSLContextobject or a dictionary of keyword arguments for thessl.wrap_socket function. The server_hostname argumentwill be used for certificate validation unless disabledin the ssl_options.

This method returns a Future whose result is the newSSLIOStream. After this method has been called,any other operation on the original stream is undefined.

If a close callback is defined on this stream, it will betransferred to the new stream.

4.0 新版功能.

在 4.2 版更改: SSL certificates are validated by default; passssl_options=dict(cert_reqs=ssl.CERT_NONE) or asuitably-configured ssl.SSLContext to disable.

_class tornado.iostream.SSLIOStream(*args, **kwargs)[源代码]¶

A utility class to write to and read from a non-blocking SSL socket.

If the socket passed to the constructor is already connected,it should be wrapped with:

ssl.wrapsocket(sock, do_handshake_on_connect=False, **kwargs)

before constructing the SSLIOStream. Unconnected sockets will bewrapped when IOStream.connect is finished.

The ssl_options keyword argument may either be anssl.SSLContext object or a dictionary of keywords argumentsfor ssl.wrap_socket

wait_for_handshake(_callback=None)[源代码]¶: Wait for the initial SSL handshake to complete.

If a callback is given, it will be called with noarguments once the handshake is complete; otherwise thismethod returns a Future which will resolve to thestream itself after the handshake is complete.

Once the handshake is complete, information such asthe peer’s certificate and NPN/ALPN selections may beaccessed on self.socket.

This method is intended for use on server-side streamsor after using IOStream.start_tls; it should not be usedwith IOStream.connect (which already waits for thehandshake to complete). It may only be called once per stream.

4.2 新版功能.

class tornado.iostream.PipeIOStream(fd, *args, **kwargs)[源代码]¶: Pipe-based IOStream implementation.

The constructor takes an integer file descriptor (such as one returnedby os.pipe) rather than an open file object. Pipes are generallyone-way, so a PipeIOStream can be used for reading or writing but notboth.

Exceptions¶

exception tornado.iostream.StreamBufferFullError[源代码]¶: Exception raised by IOStream methods when the buffer is full.

exception tornado.iostream.StreamClosedError(real_error=None)[源代码]¶: Exception raised by IOStream methods when the stream is closed.

Note that the close callback is scheduled to run after othercallbacks on the stream (to allow for buffered data to be processed),so you may see this error before you see the close callback.

The realerror attribute contains the underlying error that causedthe stream to close (if any).

在 4.3 版更改: Added the real_error attribute.

_exception tornado.iostream.UnsatisfiableReadError[源代码]¶: Exception raised when a read cannot be satisfied.

Raised by read_until and read_until_regex with a max_bytesargument.

原文:

https://tornado-zh-cn.readthedocs.io/zh_CN/latest/iostream.html