tornado.iostream — Convenient wrappers for non-blocking sockets

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

class tornado.iostream.IOStream(socket, io_loop=None, max_buffer_size=104857600, read_chunk_size=4096)[source]

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

We support three methods: write(), read_until(), and read_bytes(). All of the methods take callbacks (since writing and reading are non-blocking and asynchronous). read_until() reads the socket until a given delimiter, and read_bytes() reads until a specified number of bytes have been read from the socket.

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

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

from tornado import ioloop
from tornado import iostream
import socket

def send_request():
    stream.write("GET / HTTP/1.0\r\nHost:\r\n\r\n")
    stream.read_until("\r\n\r\n", on_headers)

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

def on_body(data):
    print data

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
stream = iostream.IOStream(s)
stream.connect(("", 80), send_request)
connect(address, callback=None)[source]

Connects the socket to a remote address without blocking.

May only be called if the socket passed to the constructor was not previously connected. The address parameter is in the same format as for socket.connect, i.e. a (host, port) tuple. If callback is specified, it will be called when the connection is completed.

Note that it is safe to call IOStream.write while the connection is pending, 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.

read_until(delimiter, callback)[source]

Call callback when we read the given delimiter.

read_bytes(num_bytes, callback)[source]

Call callback when we read the given number of bytes.

write(data, callback=None)[source]

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.


Call the given callback when the stream is closed.


Close this stream.


Returns true if we are currently reading from the stream.


Returns true if we are currently writing to the stream.


Returns true if the stream has been closed.

class tornado.iostream.SSLIOStream(*args, **kwargs)[source]

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.wrap_socket(sock, do_handshake_on_connect=False, **kwargs)

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

Creates an SSLIOStream.

If a dictionary is provided as keyword argument ssl_options, it will be used as additional keyword arguments to ssl.wrap_socket.

Previous topic

tornado.ioloop — Main event loop

Next topic

tornado.httpclient — Non-blocking HTTP client

This Page