TcpConnection

TcpConnection 的设计精髓在于 事件驱动 和 回调机制。它将底层的socket读写、连接状态变化等事件都封装好，然后通过回调函数通知给用户，用户只需要关心如何处理这些事件（比如收到消息后该做什么业务处理），而不需要关心具体的网络I/O细节。

下面我将 TcpConnection.h 中定义的API分为几类来介绍：

1. 生命周期管理 (Lifecycle Management)

这类API负责连接的建立、状态变更和销毁。

• 构造函数 TcpConnection(...) 和析构函数 ~TcpConnection()
  • 构造函数通常不是由用户直接调用的，而是由 TcpServer (当接受一个新连接时) 或 TcpClient (当成功连接到服务器时) 在内部创建 TcpConnection 对象。它需要一个 EventLoop 对象、连接名称、已连接的socket文件描述符 sockfd 以及本地和对端的地址。
• connectEstablished() 和 connectDestroyed()
  • 这两个是内部接口，TcpServer 在接受新连接并创建好 TcpConnection 后会调用 connectEstablished()。这个函数会把连接状态设为 kConnected，启用读事件，并触发用户设置的 ConnectionCallback。
  • connectDestroyed() 则在连接彻底销毁前被调用，用于清理工作。
• shutdown()
  • 优雅关闭。调用后，muduo 会确保 outputBuffer_ 中待发送的数据全部发送完毕后，再关闭写端（发送FIN包），但此时仍然可以接收数据。这是TCP的"半关闭"（half-close）功能。它是非线程安全的，需要在IO线程中调用。
• forceClose() 和 forceCloseWithDelay()
  • 强制关闭。立即或延迟一段时间后，直接关闭连接，outputBuffer_ 中未发送的数据可能会丢失。

2. 数据收发 (Data Transfer)

用户通过这类API来发送数据和获取接收到的数据。

• send() 系列函数
  • 这是用户发送数据的核心API。它有多个重载版本，可以发送 const void* + len、StringPiece 或 Buffer*。
  • 关键特性：线程安全 。send() 可以在任何线程中调用。如果当前在 TcpConnection 所属的I/O线程，它会直接尝试发送；如果不在，它会把发送任务派发（runInLoop）到那个I/O线程去执行，从而避免了多线程并发写socket的问题。
• inputBuffer() 和 outputBuffer()
  • 分别返回指向内部输入/输出缓冲区的指针。用户在 MessageCallback 中通过 inputBuffer() 来读取和处理收到的数据。outputBuffer() 主要供库内部使用，用户一般不需要直接操作它。

3. 回调函数设置 (Callback Setup)

这是 TcpConnection 用法的核心，用户通过设置不同的回调函数来注入自己的业务逻辑。

• setConnectionCallback(const ConnectionCallback& cb)
  • 设置连接建立和断开时的回调。当一个连接成功建立或断开时，这个回调函数会被调用。
• setMessageCallback(const MessageCallback& cb)
  • 设置消息到达时的回调。当TcpConnection从socket读到数据并存入inputBuffer_后，会调用这个回调。这是处理业务逻辑最主要的地方。
• setWriteCompleteCallback(const WriteCompleteCallback& cb)
  • 设置发送完成回调。当 outputBuffer_ 中的数据全部被发送到内核缓冲区后，这个回调会被触发。
• setHighWaterMarkCallback(const HighWaterMarkCallback& cb, size_t highWaterMark)
  • 设置"高水位"回调。用于防止发送速度过快，导致outputBuffer_积压过多数据耗尽内存。当待发送数据量超过 highWaterMark 时，会触发此回调，用户可以在回调中暂停写入，等 WriteCompleteCallback 被触发（说明缓冲区数据量下降了）后再恢复写入，实现流量控制。

4. 状态查询与控制 (State Query & Control)

• connected() 和 disconnected()
  • 检查当前连接的状态。
• getLoop(), name(), localAddress(), peerAddress()
  • 获取连接所属的EventLoop、连接名、本地地址和对端地址等信息。
• setTcpNoDelay(bool on)
  • 开启或关闭 TCP_NODELAY 选项（Nagle算法），默认关闭。开启后可以降低小数据包的延迟。
• startRead() / stopRead()
  • 在连接上开启或停止读数据。这也常用于实现上层应用的流量控制。

内部工作流程 (TcpConnection.cc 实现)

TcpConnection 内部通过一个 Channel 对象来关注socket上的IO事件。

1. handleRead() : 当Channel检测到socket可读时被调用。它会从socket读取数据到inputBuffer_，然后调用用户设置的MessageCallback。如果read返回0，表示对端关闭连接，就会调用handleClose()。
2. handleWrite() : 当outputBuffer_中有数据且socket可写时被调用。它会把outputBuffer_中的数据写入socket。如果数据全部写完，它会停止关注可写事件（节省CPU），并调用WriteCompleteCallback。
3. handleClose() : 当对端关闭连接、本端主动关闭连接或发生错误时被调用。它会清理资源，禁用Channel上的所有事件，并依次调用ConnectionCallback和内部的CloseCallback（通知TcpServer将自己移除）。
4. handleError(): 当socket发生错误时被调用，用于记录日志。

好的，没问题。时序图（Sequence Diagram）确实能更清晰地展示对象之间的交互和时间顺序。
User Thread IO Thread / EventLoop TcpConnection Socket / OS 1. 连接建立 new TcpConnection(loop, fd, ...) connectEstablished() setState(kConnected) enableReading() via Channel ConnectionCallback (连接成功) 2. 数据接收 数据到达, socket可读 handleRead() read(fd, inputBuffer) MessageCallback(conn, inputBuffer) 在回调中处理业务逻辑 3. 跨线程发送数据 send(data) 判断出调用者不在IO线程 runInLoop(bind(&sendInLoop, ...)) sendInLoop(data) write(fd, data) 尝试直接写入socket append data to outputBuffer alt outputBuffer 为空 outputBuffer 不为空 将剩余数据存入outputBuffer enableWriting() via Channel WriteCompleteCallback alt 数据未完全写入 数据写完且outputBuffer为空 4. 处理待发送数据 Socket 变为可写 handleWrite() write(fd, outputBuffer.peek()) disableWriting() via Channel WriteCompleteCallback alt outputBuffer 被清空 5. 优雅关闭 shutdown() runInLoop(bind(&shutdownInLoop, ...)) shutdownInLoop() shutdownWrite() 发送 FIN 将在handleWrite写完数据后, 再调用shutdownInLoop alt outputBuffer 已清空 outputBuffer 仍有数据 收到对端的FIN, socket可读 handleRead() read(fd) 返回 0 handleClose() setState(kDisconnected) disableAll() via Channel ConnectionCallback (连接断开) closeCallback() (通知TcpServer移除自己) 析构TcpConnection对象 User Thread IO Thread / EventLoop TcpConnection Socket / OS

时序图解读:

1. 连接建立 : TcpServer 在其所在的 IO Thread / EventLoop 中创建 TcpConnection 对象，并调用 connectEstablished 初始化连接，最终通过 ConnectionCallback 通知用户。
2. 数据接收 : 物理socket收到数据后，EventLoop 监听到可读事件，并调用 TcpConnection 的 handleRead 方法。handleRead 负责读取数据到缓冲区，然后通过 MessageCallback 将数据交给用户处理。
3. 跨线程发送数据 : 当 User Thread 调用 send 时，TcpConnection 会将发送任务 sendInLoop 抛给 IO Thread 去执行，以保证线程安全。sendInLoop 会尝试直接发送，如果发送不完，就把剩余数据放入 outputBuffer_。
4. 处理待发送数据 : 当 outputBuffer_ 中有数据时，TcpConnection 会监听socket的可写事件。一旦socket可写，EventLoop 就会调用 handleWrite，将缓冲区的数据发送出去。
5. 优雅关闭 : 用户调用 shutdown 发起半关闭。TcpConnection 会确保 outputBuffer_ 的数据发送完毕后，再向对端发送FIN包。当收到对端的FIN后（体现为read返回0），handleClose 被调用，执行最后的清理工作，并再次通过 ConnectionCallback 通知用户连接已断开。

1. 精巧的线程模型：one loop per thread + 跨线程调用

• 核心思想 : 每个 I/O 线程（EventLoop 所在的线程）独立管理自己的一组 TcpConnection。一个 TcpConnection 的所有 I/O 操作（读、写、关闭）都必须在它所属的那个 EventLoop 线程中执行。这彻底避免了多线程访问 socket 和相关数据结构的竞态条件，因此完全不需要使用锁 来保护 TcpConnection 内部的状态（如 state_, inputBuffer_, outputBuffer_）。

• 精巧之处 : 如何让用户在任何线程 都能安全地调用 send() 和 shutdown() 呢？

  • 在 TcpConnection.cc 的 send 方法里，你会看到这样的判断：

    if (loop_->isInLoopThread())
    {
      sendInLoop(message);
    }
    else
    {
      loop_->runInLoop(
          std::bind(fp,
                    this,
                    message.as_string()));
    }

  • 这就是关键：isInLoopThread() 判断当前线程是否就是管理此 TcpConnection 的 I/O 线程。

    • 如果是 ，就直接执行 sendInLoop。
    • 如果不是 （即用户在自己的工作线程中调用），则通过 loop_->runInLoop() 将 sendInLoop 这个任务打包，发送给目标 I/O 线程，让 I/O 线程在未来的某个时间点（通常是下一次事件循环）来执行它。

  • 优点 : 这种"任务派发"机制，既保证了 send 接口的线程安全性，又避免了锁带来的性能开销和死锁风险，是现代高性能网络库的典范设计。

2. 精巧的生命周期管理：shared_ptr + enable_shared_from_this + Channel::tie

在异步回调的环境中，对象的生命周期管理是个大难题。比如，一个 TcpConnection 可能在它的一个回调函数还没来得及执行时就被销毁了，导致野指针访问。muduo 用一套组合拳完美解决了这个问题。

• shared_ptr<TcpConnection> : TcpServer 中用一个 map 持有所有 TcpConnection 的 shared_ptr，确保了只要连接存在，对象就不会被销毁。
• enable_shared_from_this : 这让 TcpConnection 对象内部能安全地获取到自身的 shared_ptr（通过 shared_from_this()）。这在注册回调函数时至关重要，因为回调函数需要持有 TcpConnection 的 shared_ptr，以延长其生命周期，确保回调执行时对象依然有效。例如 handleClose 中的 TcpConnectionPtr guardThis(shared_from_this()); 就是一个经典的用法。
• 最精巧的一点：Channel::tie
  • Channel 对象是 TcpConnection 和 EventLoop 之间的桥梁，它直接和 Poller 交互。Channel 的生命周期和 TcpConnection 绑定，但 Channel 的回调函数是在 EventLoop 中被调用的。
  • 考虑一个场景：TcpConnection 析构了，但 Poller 中可能还有该连接的残留事件，EventLoop 稍后处理这个事件时，会通过 Channel 调用 handleRead 等成员函数，此时 TcpConnection 对象已经销毁，程序崩溃。
  • muduo 的解决方案是：在 connectEstablished 中调用 channel_->tie(shared_from_this());。tie 内部存储了一个 weak_ptr<void> 指向 TcpConnection。
  • 当 Channel 准备执行回调（如 handleEvent）时，它会先尝试将这个 weak_ptr提升（lock()）为 shared_ptr。
    • 如果提升成功 ，说明 TcpConnection 对象还活着，就安全地执行回调。
    • 如果提升失败 ，说明 TcpConnection 对象已经被销毁了，那就放弃执行回调。
  • 这个 tie 机制像一根安全绳，优雅地解决了跨对象的生命周期依赖问题，防止了 use-after-free。

3. 精巧的缓冲区设计：Buffer 类

• 解决 TCP 粘包/半包问题 : Buffer 是处理 TCP 字节流的基础。handleRead 一次性将 socket 中所有可读数据读入 Buffer，然后 MessageCallback 从 Buffer 中按照应用层协议解析出完整的消息包，解决了 TCP 本身不提供消息边界的问题。
• 内存使用效率 : Buffer 内部维护了 prependable bytes、readable bytes 和 writable bytes 三个区域。当已读数据（readable bytes）被消耗后，这部分空间并不会立即释放，而是变成了 prependable bytes。这样可以避免频繁的内存移动。当 writable bytes 不够用时，才会考虑移动数据或重新分配内存。
• 零拷贝操作 : Buffer::readFd 内部使用了 readv 这个 scatter/gather I/O 操作。它可以直接将数据从内核缓冲区读到 Buffer 的 writable 空间，同时还可以利用一个栈上的临时缓冲区，避免了"内核 -> 用户临时buffer -> Buffer"的两次拷贝，提升了读取效率。

4. 精巧的流量控制与关闭机制

• 高水位回调 (HighWaterMarkCallback) : 这是防止发送速度远大于接收速度导致内存耗尽的关键机制。当 outputBuffer_ 中积压的数据超过一个阈值（highWaterMark_）时，会触发回调。用户可以在这个回调中暂停产生数据（比如停止读取上游数据源）。当 outputBuffer_ 的数据量降下来后，WriteCompleteCallback 会被触发，用户此时可以恢复产生数据。这是一个简单的应用层反压/流控机制。
• 优雅关闭 (shutdown) : shutdown 并非直接 close 套接字，而是调用 socket->shutdownWrite()，这对应于 TCP 的半关闭（half-close）。它会向对端发送 FIN 包，表示"我这边的数据已经发完了"，但仍然可以接收来自对端的数据。这对于需要确保所有待发数据都成功送达的协议至关重要。