Inside Tornado’s IOLoop: Callbacks, Futures & Coroutines Explained

IOLoop Core Overview

The IOLoop class is the core scheduler of Tornado, responsible for managing callbacks, timeouts and I/O events within a while True loop.

Callback Mechanism

Callbacks are stored in self._callbacks and executed each iteration. Methods such as add_callback and add_future schedule functions to run later, wrapping them with stack_context.wrap when needed.

Timer Management

Timeouts are kept in self._timeouts. The loop calculates the nearest timeout and uses it as the poll timeout for the underlying poller, ensuring timely execution of scheduled callbacks.

I/O Event Loop

File descriptors are registered with add_handler(fd, handler, events). The poller monitors these descriptors and invokes the associated handler when events occur.

Future Object

Tornado’s Future (or TracebackFuture) represents a value that will become available later. It provides add_done_callback to register callbacks and set_result or set_exc_info to complete the future.

gen.coroutine Implementation

The @gen.coroutine decorator wraps a generator function, creates a Future, runs the generator, and drives it forward by sending results back whenever a yielded Future is resolved. The internal _make_coroutine_wrapper and Runner classes handle this orchestration.

Practical Code Examples

Examples demonstrate adding a future, using add_timeout to simulate I/O delay, and writing a coroutine that yields futures to compute a sum asynchronously.

Overall, the IOLoop combines callbacks, timers, and I/O events to provide a non‑blocking execution model that underpins Tornado’s higher‑level features such as gen.coroutine, AsyncHTTPClient, and IOStream.