Module: eventloop.ioloop

tornado IOLoop API with zmq compatibility

If you have tornado ≥ 3.0, this is a subclass of tornado’s IOLoop, otherwise we ship a minimal subset of tornado in zmq.eventloop.minitornado.

The minimal shipped version of tornado’s IOLoop does not include support for concurrent futures - this will only be available if you have tornado ≥ 3.0.



class zmq.eventloop.ioloop.DelayedCallback(callback, callback_time, io_loop=None)

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.


Return True if this .PeriodicCallback has been started.

New in version 4.1.


Starts the timer.


Stops the timer.


class zmq.eventloop.ioloop.ZMQIOLoop

ZMQ subclass of tornado’s IOLoop

Minor modifications, so that .current/.instance return self

ERROR = 24
NONE = 0
READ = 1
add_callback(callback, *args, **kwargs)
add_callback_from_signal(callback, *args, **kwargs)
add_future(future, callback)

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

The callback is invoked with one argument, the .Future.

add_handler(fd, handler, events)
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 remove_timeout to cancel.

deadline may be a number denoting a time (on the same scale as IOLoop.time, normally time.time), or a datetime.timedelta object for a deadline relative to the current time. Since Tornado 4.0, call_later 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 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.

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

Changed in version 4.0: Now passes through *args and **kwargs to the callback.

call_at(deadline, callback, *args, **kwargs)
call_later(delay, callback, *args, **kwargs)

Runs the callback after delay seconds have passed.

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

See add_timeout for comments on thread-safety and subclassing.

New in version 4.0.


Clear the global IOLoop instance.

New in version 4.0.


Utility method to close an fd.

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

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

New in version 4.0.

configure(impl, **kwargs)

Sets the class to use when the base class is instantiated.

Keyword arguments will be saved and added to the arguments passed to the constructor. This can be used to set global defaults for some parameters.


Returns the currently configured class.

classmethod current(*args, **kwargs)

Returns the current thread’s IOLoop.


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.

initialize(impl=None, **kwargs)

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.

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

classmethod instance(*args, **kwargs)

Returns a global IOLoop instance.

Most applications have a single, global IOLoop running on the main thread. Use this method to get this instance from another thread. To get the current thread’s IOLoop, use current().

log_stack(signal, frame)

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

For use with set_blocking_signal_threshold.


Makes this the IOLoop for the current thread.

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

Changed in version 4.1: An IOLoop created while there is no current IOLoop will automatically become current.

run_sync(func, timeout=None)

Starts the IOLoop, 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 IOLoop will run until the yieldable is resolved (and run_sync() will return the yieldable’s result). If it raises an exception, the IOLoop 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 TimeoutError is raised.

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

def main():
    # do stuff...

if __name__ == '__main__':

Changed in version 4.3: Returning a non-None, non-yieldable value is now an error.


Logs a stack trace if the IOLoop is blocked for more than s seconds.

Equivalent to set_blocking_signal_threshold(seconds, self.log_stack)

set_blocking_signal_threshold(seconds, action)
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.

New in version 4.0.


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

We accept both raw file descriptors and file-like objects as input to add_handler and related methods. When a file-like object is passed, we must retain the object itself so we can close it correctly when the IOLoop 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 IOLoop subclasses and should not generally be used by application code.

New in version 4.0.

update_handler(fd, events)


class zmq.eventloop.ioloop.ZMQPoller

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.

modify(fd, events)

poll in seconds rather than milliseconds.

Event masks will be IOLoop.READ/WRITE/ERROR

register(fd, events)



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.