tornado.ioloop — Main event loop

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

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

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

IOLoop objects

class tornado.ioloop.IOLoop

A level-triggered I/O loop.

We use epoll (Linux) or kqueue (BSD and Mac OS X) 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 kqueue.

Example usage for a simple TCP server:

import errno
import functools
import tornado.ioloop
import socket

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

if __name__ == '__main__':
    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 = tornado.ioloop.IOLoop.current()
    callback = functools.partial(connection_ready, sock)
    io_loop.add_handler(sock.fileno(), callback, io_loop.READ)
    io_loop.start()

By default, a newly-constructed becomes the thread’s current , unless there already is a current . This behavior can be controlled with the make_current argument to the constructor: if make_current=True, the new will always try to become current and it raises an error if there is already a current instance. If make_current=False, the new will not try to become current.

在 4.2 版更改: Added the make_current keyword argument to the constructor.

Running an IOLoop

static IOLoop.current(instance=True)

Returns the current thread’s .

If an is currently running or has been marked as current by , returns that instance. If there is no current , returns (i.e. the main thread’s , creating one if necessary) if instance is true.

In general you should use as the default when constructing an asynchronous object, and use when you mean to communicate to the main thread from a different one.

在 4.1 版更改: Added instance argument to control the fallback to .

IOLoop.make_current()

Makes this the for the current thread.

An automatically becomes current for its thread when it is started, but it is sometimes useful to call explicitly before starting the , so that code run at startup time can find the right instance.

在 4.1 版更改: An created while there is no current will automatically become current.

static IOLoop.instance()

Returns a global instance.

Most applications have a single, global running on the main thread. Use this method to get this instance from another thread. In most other cases, it is better to use to get the current thread’s .

static IOLoop.initialized()

Returns true if the singleton instance has been created.

IOLoop.install()

Installs this object as the singleton instance.

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

When using an subclass, must be called prior to creating any objects that implicitly create their own (e.g., ).

static IOLoop.clear_instance()

Clear the global instance.

4.0 新版功能.

IOLoop.start()

Starts the I/O loop.

The loop will run until one of the callbacks calls , which will make the loop stop after the current event iteration completes.

IOLoop.stop()

Stop the I/O loop.

If the event loop is not currently running, the next call to 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.

Note that even after has been called, the is not completely stopped until has also returned. Some work that was scheduled before the call to may still be run before the shuts down.

IOLoop.run_sync(func, timeout=None)

Starts the , runs the given function, and stops the loop.

The function must return either a yieldable object or None. If the function returns a yieldable object, the will run until the yieldable is resolved (and will return the yieldable’s result). If it raises an exception, the will stop and the exception will be re-raised to the caller.

The keyword-only argument timeout may be used to set a maximum duration for the function. If the timeout expires, a is raised.

This method is useful in conjunction with to allow asynchronous calls in a main() function:

@gen.coroutine
def main():
    # do stuff...

if __name__ == '__main__':
    IOLoop.current().run_sync(main)

在 4.3 版更改: Returning a non-None, non-yieldable value is now an error.

IOLoop.close(all_fds=False)

Closes the , 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 itself).

Many applications will only use a single that runs for the entire lifetime of the process. In that case closing the is not necessary since everything will be cleaned up when the process exits. is provided mainly for scenarios such as unit tests, which create and destroy a large number of IOLoops.

An must be completely stopped before it can be closed. This means that must be called and must be allowed to return before attempting to call . Therefore the call to will usually appear just after the call to rather than near the call to .

在 3.1 版更改: If the implementation supports non-integer objects for “file descriptors”, those objects will have their close method when all_fds is true.

I/O events

IOLoop.add_handler(fd, handler, events)

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

The fd argument may either be an integer file descriptor or a file-like object with a fileno() method (and optionally a close() method, which may be called when the is shut down).

The events argument is a bitwise or of the constants IOLoop.READ, IOLoop.WRITE, and IOLoop.ERROR.

When an event occurs, handler(fd, events) will be run.

在 4.0 版更改: Added the ability to pass file-like objects in addition to raw file descriptors.

IOLoop.update_handler(fd, events)

Changes the events we listen for fd.

在 4.0 版更改: Added the ability to pass file-like objects in addition to raw file descriptors.

IOLoop.remove_handler(fd)

Stop listening for events on fd.

在 4.0 版更改: Added the ability to pass file-like objects in addition to raw file descriptors.

Callbacks and timeouts

IOLoop.add_callback(callback, *args, **kwargs)

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

It is safe to call this method from any thread at any time, except from a signal handler. Note that this is the only method in that makes this thread-safety guarantee; all other interaction with the must be done from that ‘s thread. may be used to transfer control from other threads to the ‘s thread.

To add a callback from a signal handler, see .

IOLoop.add_callback_from_signal(callback, *args, **kwargs)

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

Safe for use from a Python signal handler; should not be used otherwise.

Callbacks added with this method will be run without any , to avoid picking up the context of the function that was interrupted by the signal.

IOLoop.add_future(future, callback)

Schedules a callback on the IOLoop when the given is finished.

The callback is invoked with one argument, the .

IOLoop.add_timeout(deadline, callback, *args, **kwargs)

Runs the callback at the time deadline from the I/O loop.

Returns an opaque handle that may be passed to to cancel.

deadline may be a number denoting a time (on the same scale as , normally ), or a object for a deadline relative to the current time. Since Tornado 4.0, is a more convenient alternative for the relative case since it does not require a timedelta object.

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

Subclasses of IOLoop must implement either or ; the default implementations of each will call the other. is usually easier to implement, but subclasses that wish to maintain compatibility with Tornado versions prior to 4.0 must use instead.

在 4.0 版更改: Now passes through *args and **kwargs to the callback.

IOLoop.call_at(when, callback, *args, **kwargs)

Runs the callback at the absolute time designated by when.

when must be a number using the same reference point as .

Returns an opaque handle that may be passed to to cancel. Note that unlike the method of the same name, the returned object does not have a cancel() method.

See for comments on thread-safety and subclassing.

4.0 新版功能.

IOLoop.call_later(delay, callback, *args, **kwargs)

Runs the callback after delay seconds have passed.

Returns an opaque handle that may be passed to to cancel. Note that unlike the method of the same name, the returned object does not have a cancel() method.

See for comments on thread-safety and subclassing.

4.0 新版功能.

IOLoop.remove_timeout(timeout)

Cancels a pending timeout.

The argument is a handle as returned by . It is safe to call even if the callback has already been run.

IOLoop.spawn_callback(callback, *args, **kwargs)

Calls the given callback on the next IOLoop iteration.

Unlike all other callback-related methods on IOLoop, spawn_callback does not associate the callback with its caller’s stack_context, so it is suitable for fire-and-forget callbacks that should not interfere with the caller.

4.0 新版功能.

IOLoop.time()

Returns the current time according to the ‘s clock.

The return value is a floating-point number relative to an unspecified time in the past.

By default, the ‘s time function is . However, it may be configured to use e.g. instead. Calls to that pass a number instead of a should use this function to compute the appropriate time, so they can work no matter what time function is chosen.

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. Note that the timeout is given in milliseconds, while most other time-related functions in Tornado use seconds.

If the callback runs for longer than callback_time milliseconds, subsequent invocations will be skipped to get back on schedule.

must be called after the is created.

在 4.1 版更改: The io_loop argument is deprecated.

start()

Starts the timer.

stop()

Stops the timer.

is_running()

Return True if this has been started.

4.1 新版功能.

Debugging and error handling

IOLoop.handle_callback_exception(callback)

This method is called whenever a callback run by the 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 .

IOLoop.set_blocking_signal_threshold(seconds, action)

Sends a signal if the 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 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 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 .

Methods for subclasses

IOLoop.initialize(make_current=None)

IOLoop.close_fd(fd)

Utility method to close an fd.

If fd is a file-like object, we close it directly; otherwise we use .

This method is provided for use by subclasses (in implementations of IOLoop.close(all_fds=True) and should not generally be used by application code.

4.0 新版功能.

IOLoop.split_fd(fd)

Returns an (fd, obj) pair from an fd parameter.

We accept both raw file descriptors and file-like objects as input to and related methods. When a file-like object is passed, we must retain the object itself so we can close it correctly when the shuts down, but the poller interfaces favor file descriptors (they will accept file-like objects and call fileno() for you, but they always return the descriptor itself).

This method is provided for use by subclasses and should not generally be used by application code.

4.0 新版功能.