阅读指南：先搭骨架，再追一条下载链路

目标不是记住 174 个核心文件，而是建立一套能解释运行时行为的心智模型。读完主线后，你应该能从一个 UI 操作一路追到网络包、磁盘写入与状态回传。

一、为什么不能从 main() 开始一路单步

Transmission 有多个 main()：daemon、CLI、GTK、Qt、macOS 都能启动产品；真正共享的行为在 libtransmission。如果只跟某个入口，很快会陷入 UI 初始化或平台代码，反而看不见核心。

更有效的顺序是：

核心原因是：tr_session 和 tr_torrent 是绝大多数调用链的稳定坐标。先知道“状态归谁所有”，再理解“事件从哪里来”，源码会突然变得有层次。

二、三条推荐路线

路线 A：完整通读

按第 1～14 章顺序阅读。适合第一次系统学习 BitTorrent 客户端或 C++ 系统软件的人。前四章建立对象模型；第 5～10 章是内核；第 11～14 章解释产品化与工程质量。

路线 B：只追下载数据

按 03 → 04 → 05 → 06 → 07 → 08 → 09 阅读。你会得到这条闭环：

Session 启动 Torrent
  → Tracker/DHT/LPD/PEX 提供候选地址
  → Peer Manager 发起 TCP/µTP 连接
  → Handshake 绑定 info_hash 并协商能力
  → Peer Messages 进入 interested/unchoked 状态
  → Wishlist 选择 piece/block
  → REQUEST / PIECE 消息交换
  → tr_ioWrite 跨文件写入
  → SHA-1 校验 piece
  → completion/stat/RPC/UI 更新

路线 C：只看服务端与前端解耦

按 02 → 03 → 11 → 12 → 13 阅读。适合要做 daemon、NAS 管理端、RPC SDK 或 Web UI 的读者。

三、读源码时记住四类“边界”

边界	问题	典型实现
线程边界	谁能修改核心状态？	tr_session_thread::run/queue
协议边界	不可信字节在哪里变成结构化状态？	tr_handshake、tr_peerMsgsImpl、tr_variant
资源边界	谁能用多少连接、带宽和文件句柄？	tr_peerMgr、tr_bandwidth、tr_open_files
产品边界	UI 如何控制内核而不复制业务逻辑？	C API、tr_rpc_request_exec、JSON-RPC

碰到一个函数时，先问它跨没跨这四种边界，往往比逐行解释更有用。

四、符号命名速记

• tr_session：一次 Transmission 运行实例，拥有全局配置、事件线程和子系统。
• tr_torrent：一个下载任务的长期状态与领域行为。
• tr_swarm：某个 torrent 的 Peer 集合与请求调度上下文。
• tr_peerIo：连接上的缓冲、加密、带宽和 socket 适配层。
• tr_peerMsgsImpl：BitTorrent Peer Wire/LTEP 消息状态机。
• tr_variant：JSON 与 bencode 共用的动态值树。
• Mediator：把子系统需要的最小能力反向注入，避免直接依赖整个 Session/Torrent。

五、如何使用“源码锚点”

每章末尾列出 3～8 个最值得打开的文件。建议先读头文件中的数据成员和公开方法，再在 .cc 中搜索同名实现。不要一开始就全文阅读 torrent.cc、peer-mgr.cc 或 rpcimpl.cc：它们都超过两千行。

源码链接默认指向 Transmission 官方仓库。由于上游 main 会继续演进，定位时优先搜索文档给出的符号名，不要依赖固定行号。

六、关于图与伪代码

图中的箭头表示主要控制流或数据流，不代表每一步都是直接函数调用。文中的伪代码会省略日志、断言、平台分支和兼容层；紧邻的源码锚点才是精确实现依据。

下一章先从全景开始：为什么 Transmission 不是“六套客户端”，而是“一个内核加多种控制面”。