Tornado 异步编程指南：深入理解非阻塞 I/O 与事件循环

本篇指南以 Tornado 官方文档 docs/guide/async.rst 为骨架，系统讲解 Tornado 中阻塞（Blocking）、异步（Asynchronous）与非阻塞（Non-Blocking）三大核心概念的区别与联系，并结合 tornado/ioloop.py、tornado/httpclient.py、tornado/gen.py 等源码剖析其底层实现。读完本文，你将掌握 Tornado 单线程事件循环的工作模型、Future 的异步约定，以及如何用原生协程、tornado.gen 装饰器或手动回调写出真正非阻塞的代码。

为什么 Tornado 需要异步：实时 Web 的长连接困境

实时 Web 功能（如消息推送、在线聊天、股票行情）要求每个用户保持一条长时间存活、但大多数时间处于空闲状态的连接。在传统的同步 Web 服务器中，每处理一个用户就需要独占一个线程：线程要一直挂起等待该用户的 I/O 事件。

这种"每用户一线程"模型的代价非常高昂：

• 每个线程都有独立的内核栈与用户态资源，内存开销巨大；
• 大量线程的创建、销毁与调度会带来严重的上下文切换开销；
• 当连接数上升到数万时，同步模型几乎不可用。

Tornado 正是为这一场景而生的。它在 FriendFeed 时期被开发出来，通过非阻塞网络 I/O 可以支撑数万条并发打开的连接，非常适合 长轮询、WebSocket 等需要与每个用户保持长连接的应用（见 docs/guide/intro.rst）。

Tornado 的应对方案：单线程事件循环

为了最小化并发连接的成本，Tornado 采用单线程事件循环（single-threaded event loop）。这意味着：

• 整个进程只有一个线程在驱动事件循环；
• 所有应用代码都应尽量写成异步、非阻塞的形式；
• 任意时刻只有一个操作处于活动状态——如果你写了一段阻塞代码，整个服务器都会卡住，所有用户的请求都会被拖慢。

这个事件循环的核心实现就是 tornado/ioloop.py 中的 IOLoop 类。它在 5.0 之后基于 asyncio 事件循环实现，对外提供 start()、stop()、add_callback()、run_sync() 等核心方法（见 tornado/ioloop.py#L434）。其工作机制是：事件循环不断询问操作系统"有哪些 I/O 就绪了"，然后依次调度对应的回调；当没有事件时，线程让出 CPU 进入等待，而不是忙轮询。

这里有一个容易被忽视的关键设计：IOLoop.add_callback() 是 IOLoop 中唯一保证线程安全的方法，它可以把控制权从其他线程安全地转移到 IOLoop 所在线程（见 tornado/ioloop.py#L640）。除此之外，对 IOLoop 的所有操作都必须在 IOLoop 自己的线程内完成。

概念辨析：阻塞、非阻塞与异步

"异步"（asynchronous）和"非阻塞"（non-blocking）这两个术语紧密相关、经常被混用，但它们并非完全相同。

阻塞（Blocking）

当一个函数在返回之前必须"等待某件事发生"，它就是阻塞的。阻塞的原因多种多样：网络 I/O、磁盘 I/O、互斥锁等待等。事实上，每一个函数在执行期间至少会轻微阻塞——只要它在运行并使用 CPU 就算。文档特别举了一个极端例子：像 bcrypt 这样的密码哈希函数，设计上就会消耗数百毫秒的 CPU 时间，远超一次典型的网络或磁盘访问，因此 CPU 型阻塞必须与 I/O 型阻塞同等重视。

一个函数可能在某些方面阻塞、在其他方面不阻塞。在 Tornado 的语境下，我们通常讨论的是网络 I/O 意义上的阻塞，但所有类型的阻塞都应尽量最小化。

异步（Asynchronous）

异步函数在完成之前就返回，通常会让某些工作在后台进行，稍后再触发应用中的某个动作。与之相对的是同步（synchronous）函数——它们会在返回前把该做的一切都做完。

异步接口有多种风格，文档列举了四种常见类型：

• 回调参数（Callback argument）
• 返回占位对象（.Future、Promise、Deferred）
• 投递到队列（Deliver to a queue）
• 回调注册表（Callback registry，例如 POSIX 信号）

无论使用哪种接口风格，异步函数按定义都与调用方的交互方式不同：不存在一种免费的方法，能把同步函数改造成对调用方完全透明的异步函数。文档特别指出，像 gevent 这样的系统用轻量级线程来获得与异步系统相当的性能，但它们实际上并没有把事情变成异步的——只是把阻塞分摊到了大量协程里。

Tornado 的异步约定：Future 优先

Tornado 中的异步操作通常返回占位对象（Future），唯一的例外是 IOLoop 等少数底层组件直接使用回调。Future 通常通过 await 或 yield 关键字转换成最终结果。

值得注意的是，从 Tornado 5.0 开始，Tornado 不再维护自己的 Future 实现，而是直接复用 asyncio.Future：tornado/concurrent.py#L47 中的 Future = asyncio.Future 一行，让 Tornado 与标准库 asyncio 在异步对象层面完全打通。

代码示例：从同步到异步的三种写法

文档给出了一个典型场景——用 HTTP 客户端抓取一个 URL 并返回响应体，分别演示同步、原生协程与旧式协程三种写法。

同步写法（会阻塞）

from tornado.httpclient import HTTPClient

def synchronous_fetch(url):
    http_client = HTTPClient()
    response = http_client.fetch(url)
    return response.body

这里的 HTTPClient 是阻塞式客户端。从源码看（tornado/httpclient.py#L59），它在构造函数里自己创建了一个独立的 IOLoop（见 tornado/httpclient.py#L98），然后在 fetch() 中通过 self._io_loop.run_sync(...) 驱动事件循环直到请求完成（见 tornado/httpclient.py#L134）。也就是说，HTTPClient 内部其实是"把一个异步客户端包进一个临时事件循环"，对外呈现出阻塞语义。它的文档明确警告：由于 asyncio 的限制，在 IOLoop 运行期间不能再使用同步的 HTTPClient（见 tornado/httpclient.py#L81），应用应改用 AsyncHTTPClient。

异步写法一：原生协程（推荐）

from tornado.httpclient import AsyncHTTPClient

async def asynchronous_fetch(url):
    http_client = AsyncHTTPClient()
    response = await http_client.fetch(url)
    return response.body

这是当前推荐的形式。AsyncHTTPClient 是非阻塞客户端（tornado/httpclient.py#L140），它的 fetch() 立即返回一个 Future，await 会挂起当前协程、把控制权交还事件循环，等网络响应就绪后再恢复执行。整个等待期间，事件循环可以继续处理其他用户的请求。

异步写法二：tornado.gen 装饰器（兼容旧版 Python）

from tornado.httpclient import AsyncHTTPClient
from tornado import gen

@gen.coroutine
def async_fetch_gen(url):
    http_client = AsyncHTTPClient()
    response = yield http_client.fetch(url)
    raise gen.Return(response.body)

这是为兼容旧版 Python（3.5 之前、尚无 async/await 关键字）而保留的"装饰器协程"写法。raise gen.Return(...) 是 Python 2 时代 yield 函数无法混用 return 值而引入的特殊机制，gen.Return 类定义在 tornado/gen.py#L271。在原生协程出现后，gen.Return 已基本不需要，但大量存量代码仍在使用这种形式。

协程的"魔法"：揭开 Future 与回调的真实面目

协程看起来有点"魔法"，但文档明确指出，协程内部做的事情其实就是这样一段手动代码：

from tornado.concurrent import Future

def async_fetch_manual(url):
    http_client = AsyncHTTPClient()
    my_future = Future()
    fetch_future = http_client.fetch(url)
    def on_fetch(f):
        my_future.set_result(f.result().body)
    fetch_future.add_done_callback(on_fetch)
    return my_future

注意这里的关键事实：协程在 fetch 完成之前就返回了它的 Future——这正是协程之所以"异步"的本质。

从源码看，装饰器协程的内部执行引擎是 tornado/gen.py#L723 的 Runner 类。文档给出了其内部循环的精简版本：

# Simplified inner loop of tornado.gen.Runner
def run(self):
    # send(x) makes the current yield return x.
    # It returns when the next yield is reached
    future = self.gen.send(self.next)
    def callback(f):
        self.next = f.result()
        self.run()
    future.add_done_callback(callback)

工作流程是：装饰器从生成器那里拿到一个 Future，然后不阻塞地等待这个 Future 完成，再把结果"解包"并通过 yield 表达式送回生成器。Runner.run() 的完整实现在 tornado/gen.py#L750 可以找到：它维护一个 self.future 状态，只有在 Future 完成（future.done()）时才继续推进生成器，否则立即返回把控制权交还事件循环——这就是协作式调度的具体落地。

原生协程在概念上与此类似，但由于与 Python 运行时深度集成而稍复杂。大多数应用代码永远不需要直接操作 Future 类，只需把异步函数返回的 Future 立刻交给 await/yield 表达式即可。

为什么协程优于回调：错误处理的革命

用协程能做的事，用回调对象绕来绕去也都能做；但协程带来一个重要的简化——你可以像写同步代码一样组织异步代码。这一点在错误处理上体现得尤为明显：

• 在协程中，try/except 块的行为与你预期完全一致，异常可以自然地沿调用栈传播；
• 在回调风格中，异常很难通过回调链正确传递，通常需要手写错误分支、层层嵌套，代码迅速变得难以维护。

同时，协程还显著减少了"上下文切换可能发生的位置"，让并发更容易推理——这是协程相对回调的另一个重要优势。

从源码看异步客户端的真实架构

为了深入理解上面的示例，值得看一下 HTTPClient 与 AsyncHTTPClient 的关系（均在 tornado/httpclient.py）：

• AsyncHTTPClient 是一个基于 Configurable 的可配置类，构造函数有"魔法"：它实际创建的是某个实现子类的实例，且实例按 IOLoop 以伪单例方式复用；可用 force_instance=True 关闭复用，用静态方法 configure() 指定实现子类与构造参数（见 tornado/httpclient.py#L154）。它还支持 defaults 关键字参数，为 HTTPRequest 属性设置默认值。
• HTTPClient 是阻塞客户端，包装了一个 AsyncHTTPClient 并配上独立的 IOLoop；它在 IOLoop 运行期间不可用（见 tornado/httpclient.py#L81）。

这也是本文反复强调的要点：在 Tornado 应用（即正在运行 IOLoop 的进程）中，永远使用 AsyncHTTPClient，绝不使用 HTTPClient——否则会阻塞整个事件循环，拖垮所有并发用户。

异步代码的实战工具箱：IOLoop 的四个关键方法

结合 docs/guide/coroutines.rst（即 async 指南的下一节，协程专章）与 IOLoop 源码，异步应用离不开下面四个方法：

1. run_sync：顶层入口

IOLoop.current().run_sync(func) 会启动 IOLoop、运行给定的协程、再停止 IOLoop，并返回协程结果；若协程抛异常则重新抛出（见 tornado/ioloop.py#L455）。它常用于批量程序的 main 函数，也可以指定 timeout 参数，超时抛出 asyncio.TimeoutError。HTTPClient 内部正是靠它把异步 fetch 包装成同步调用的。

2. spawn_callback：后台运行协程

IOLoop.current().spawn_callback(coro_func, *args) 让 IOLoop 负责调用协程，失败时 IOLoop 会把堆栈打印到日志（见 tornado/ioloop.py#L667）。对于 async def 协程，这种方式是必须的（否则协程运行器不会启动）；对 @gen.coroutine 则强烈推荐。例如：

IOLoop.current().spawn_callback(divide, 1, 0)  # 异常会被 IOLoop 捕获并打日志

3. run_in_executor：在协程里调用阻塞函数

如果协程里必须调用一个无法异步化的阻塞函数，最简做法是：

async def call_blocking():
    await IOLoop.current().run_in_executor(None, blocking_func, args)

run_in_executor 把函数提交到 concurrent.futures.Executor（见 tornado/ioloop.py#L709）。从源码可见，executor 传 None 时使用默认执行器，其线程池大小按 cpu_count() * 5 计算（见 tornado/ioloop.py#L722）。它返回与协程兼容的 Future，从而把 CPU 型阻塞（比如文档中提到的 bcrypt 哈希）隔离到线程池，不阻塞事件循环。

4. add_future：注册完成回调

IOLoop.current().add_future(future, callback) 在 Future 完成时把回调调度到下一轮事件循环迭代（见 tornado/ioloop.py#L676）。它只接受 Future 对象，不接受其他 awaitable。

异步并发模式：并行与交错

除了"异步"本身，异步系统还提供了一些同步代码难以实现的并发模式（详见 docs/guide/coroutines.rst）：

• 并行等待：tornado.gen.multi（tornado/gen.py#L425）接受列表或字典，其值为 Future，并行等待全部完成。装饰器协程里也可以直接 yield [f1, f2]。
• 交错执行：先保存 Future 而不是立刻 await 它，从而在等待前启动另一项操作；原生协程可用 tornado.gen.convert_yielded（tornado/gen.py#L856）把协程转成后台运行的 Future，其作用等价于 asyncio.ensure_future()。
• 定时循环：协程里用 while True 配合 tornado.gen.sleep（tornado/gen.py#L657）代替 PeriodicCallback 实现周期性任务；若要求精确间隔，可用"先启动定时器、再执行任务、最后等待定时器"的交错写法。

小结

Tornado 以单线程事件循环支撑数万并发长连接的关键，在于让所有 I/O 都以异步、非阻塞的方式运作：函数在完成前即返回 Future，事件循环在等待期间继续服务其他请求，协程（原生 async def 或 @gen.coroutine）在保留同步代码可读性的同时消除线程开销。理解本文的阻塞/异步/非阻塞概念辨析，掌握 Future 约定与 IOLoop 的 run_sync、spawn_callback、run_in_executor、add_future 等工具，你就可以写出真正高并发、不阻塞的 Tornado 应用。下一步建议继续阅读协程专章 docs/guide/coroutines.rst，以及配套的 demos/websocket/chatdemo.py、demos/chat/chatdemo.py 等真实异步应用示例。