tornado.ioloop — Main event loop

An I/O event loop for non-blocking sockets.

Typical applications will use a single IOLoop object, in the IOLoop.instance singleton. The IOLoop.start method should usually be called at the end of the main() function. Atypical applications may use more than one IOLoop, such as one IOLoop per thread, or per unittest case.

In addition to I/O events, the IOLoop can also schedule time-based events. IOLoop.add_timeout is a non-blocking alternative to time.sleep.

IOLoop objects

class tornado.ioloop.IOLoop(impl=None)

A level-triggered I/O loop.

We use epoll (Linux) or kqueue (BSD and Mac OS X; requires python 2.6+) if they are available, or else we fall back on select(). If you are implementing a system that needs to handle thousands of simultaneous connections, you should use a system that supports either epoll or queue.

Example usage for a simple TCP server:

import errno
import functools
import ioloop
import socket

def connection_ready(sock, fd, events):
    while True:
        try:
            connection, address = sock.accept()
        except socket.error, e:
            if e.args[0] not in (errno.EWOULDBLOCK, errno.EAGAIN):
                raise
            return
        connection.setblocking(0)
        handle_connection(connection, address)

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
sock.setblocking(0)
sock.bind(("", port))
sock.listen(128)

io_loop = ioloop.IOLoop.instance()
callback = functools.partial(connection_ready, sock)
io_loop.add_handler(sock.fileno(), callback, io_loop.READ)
io_loop.start()

Running an IOLoop

static IOLoop.instance()

Returns a global IOLoop instance.

Most single-threaded applications have a single, global IOLoop. Use this method instead of passing around IOLoop instances throughout your code.

A common pattern for classes that depend on IOLoops is to use a default argument to enable programs with multiple IOLoops but not require the argument for simpler applications:

class MyClass(object):
    def __init__(self, io_loop=None):
        self.io_loop = io_loop or IOLoop.instance()

static IOLoop.initialized()

Returns true if the singleton instance has been created.

IOLoop.install()

Installs this IOloop object as the singleton instance.

This is normally not necessary as instance() will create an IOLoop on demand, but you may want to call install to use a custom subclass of IOLoop.

IOLoop.start()

Starts the I/O loop.

The loop will run until one of the I/O handlers calls stop(), which will make the loop stop after the current event iteration completes.

IOLoop.running()

Returns true if this IOLoop is currently running.

IOLoop.stop()

Stop the loop after the current event loop iteration is complete. If the event loop is not currently running, the next call to start() will return immediately.

To use asynchronous methods from otherwise-synchronous code (such as unit tests), you can start and stop the event loop like this:

ioloop = IOLoop()
async_method(ioloop=ioloop, callback=ioloop.stop)
ioloop.start()

ioloop.start() will return after async_method has run its callback, whether that callback was invoked before or after ioloop.start.

IOLoop.close(all_fds=False)

Closes the IOLoop, freeing any resources used.

If all_fds is true, all file descriptors registered on the IOLoop will be closed (not just the ones created by the IOLoop itself.

I/O events

IOLoop.add_handler(fd, handler, events)

Registers the given handler to receive the given events for fd.

IOLoop.update_handler(fd, events)

Changes the events we listen for fd.

IOLoop.remove_handler(fd)

Stop listening for events on fd.

Timeouts

IOLoop.add_callback(callback)

Calls the given callback on the next I/O loop iteration.

It is safe to call this method from any thread at any time. Note that this is the only method in IOLoop that makes this guarantee; all other interaction with the IOLoop must be done from that IOLoop’s thread. add_callback() may be used to transfer control from other threads to the IOLoop’s thread.

IOLoop.add_timeout(deadline, callback)

Calls the given callback at the time deadline from the I/O loop.

Returns a handle that may be passed to remove_timeout to cancel.

deadline may be a number denoting a unix timestamp (as returned by time.time() or a datetime.timedelta object for a deadline relative to the current time.

Note that it is not safe to call add_timeout from other threads. Instead, you must use add_callback to transfer control to the IOLoop’s thread, and then call add_timeout from there.

IOLoop.remove_timeout(timeout)

Cancels a pending timeout.

The argument is a handle as returned by add_timeout.

class tornado.ioloop.PeriodicCallback(callback, callback_time, io_loop=None)

Schedules the given callback to be called periodically.

The callback is called every callback_time milliseconds.

start must be called after the PeriodicCallback is created.

start()

Starts the timer.

stop()

Stops the timer.

Debugging and error handling

IOLoop.handle_callback_exception(callback)

This method is called whenever a callback run by the IOLoop throws an exception.

By default simply logs the exception as an error. Subclasses may override this method to customize reporting of exceptions.

The exception itself is not passed explicitly, but is available in sys.exc_info.

IOLoop.set_blocking_signal_threshold(seconds, action)

Sends a signal if the ioloop is blocked for more than s seconds.

Pass seconds=None to disable. Requires python 2.6 on a unixy platform.

The action parameter is a python signal handler. Read the documentation for the python ‘signal’ module for more information. If action is None, the process will be killed if it is blocked for too long.

IOLoop.set_blocking_log_threshold(seconds)

Logs a stack trace if the ioloop is blocked for more than s seconds. Equivalent to set_blocking_signal_threshold(seconds, self.log_stack)

IOLoop.log_stack(signal, frame)

Signal handler to log the stack trace of the current thread.

For use with set_blocking_signal_threshold.