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.
Schedules the given callback to be called once.
The callback is called once, after callback_time milliseconds.
start must be called after the DelayedCallback is created.
The timeout is calculated from when start is called.
Starts the timer.
Stops the timer.
A level-triggered I/O loop.
We use the zmq Poller for polling events.
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 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()
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.
Registers the given handler to receive the given events for fd.
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.
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).
Many applications will only use a single IOLoop that runs for the entire lifetime of the process. In that case closing the IOLoop is not necessary since everything will be cleaned up when the process exits. IOLoop.close is provided mainly for scenarios such as unit tests, which create and destroy a large number of IOLoops.
An IOLoop must be completely stopped before it can be closed. This means that IOLoop.stop() must be called and IOLoop.start() must be allowed to return before attempting to call IOLoop.close(). Therefore the call to close will usually appear just after the call to start rather than near the call to stop.
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.
Returns true if the singleton instance has been created.
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.
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()
Signal handler to log the stack trace of the current thread.
For use with set_blocking_signal_threshold.
Stop listening for events on fd.
Cancels a pending timeout.
The argument is a handle as returned by add_timeout.
Returns true if this IOLoop is currently running.
Logs a stack trace if the ioloop is blocked for more than s seconds. Equivalent to set_blocking_signal_threshold(seconds, self.log_stack)
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.
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.
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.
Note that even after stop has been called, the IOLoop is not completely stopped until IOLoop.start has also returned.
This method will be added in tornado 3.0
When 3.0 is closer to done, we will do a real upstream sync, but this seems to be enough for now.
Changes the events we listen for fd.
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.
Starts the timer.
Stops the timer.
A poller that can be used in the tornado IOLoop.
This simply wraps a regular zmq.Poller, scaling the timeout by 1000, so that it is in seconds rather than milliseconds.
poll in seconds rather than milliseconds.
Event masks will be IOLoop.READ/WRITE/ERROR
set the tornado IOLoop instance with the pyzmq IOLoop.
After calling this function, tornado’s IOLoop.instance() and pyzmq’s IOLoop.instance() will return the same object.
An assertion error will be raised if tornado’s IOLoop has been initialized prior to calling this function.