HTTP、WebSocket 与 TCP 的缓冲区复用
t-io 为 HTTP、WebSocket 和 TCP 提供统一的读取缓冲区管理，并通过 EncodedBuffer 将编码输出和回收责任一同交给异步发送任务。接收侧连续读取、发送侧池化编码与完成后回收相互配合，减少重复分配，适合长期运行的网络服务。
三种协议的使用方式
下表描述框架通过 encodeBuffer() 发送的默认路径。
| 路径 | 分配与使用方式 | 复用机制 |
|---|---|---|
| HTTP 接收 | BufferPoolUtils.allocateRequest() 返回 VirtualBuffer | 连续读取复用同一缓冲区，归还后可再次分配 |
| WebSocket 接收 | 升级后继续使用核心读取流程 | 与 HTTP、TCP 共用读取缓冲区管理 |
| TCP 接收 | 服务端接入与客户端连接完成时申请 VirtualBuffer | 容量变化或连接结束时归还 |
| HTTP 普通响应与文件响应头 | HttpResponseEncoder.encodeBuffer() | 从 VirtualBuffer 响应池分配，发送结束后归还 |
| WebSocket 服务端与客户端帧 | 对应编码器的 encodeBuffer() | 帧头和正文写入池化输出，发送结束后归还 |
| WebSocket 客户端 HTTP 握手请求 | HttpRequestEncoder.encodeBuffer() | 使用相同的响应池管理编码输出 |
| 自定义 TCP 编码 | handler 的 encodeBuffer() | 可使用池化输出；原有 encode() 继续兼容 |
| 内置 TCP 字节包、字符串包、ByteBuffer 包 | 包装已有正文或使用已有缓冲区 | 借用正文存储，避免为池化再复制一份数据 |
| TLS 或普通异步通道的文件分片 | 发送器申请池化分片 | 明文分片使用 VirtualBuffer，加密完成或写入结束后归还 |
| 增强通道上的明文文件正文 | FileChannel.transferTo() | 保留文件传输路径，无需为整个正文申请应用层缓冲区 |
HTTP keep-alive、WebSocket 和 TCP 长连接继续沿用各自的连接策略，单次发送缓冲区的回收不需要关闭连接。TLS 的加解密工作区与密文输出仍有独立的缓冲区管理流程。
复用现有 BufferPoolUtils
BufferPoolUtils 已经提供请求池和响应池入口：
allocateRequest() / allocateResponse()
→ BufferPagePool
→ BufferPage
→ VirtualBuffer + ByteBufferVirtualBuffer 保存底层 ByteBuffer、所属 BufferPage 和回收状态。socket 实际读写 virtualBuffer.buffer()；调用 virtualBuffer.clean() 后，容量匹配的后续分配可以重新使用底层内存。
当前 BufferPage 使用完整缓冲区的回收队列，检查取出的候选缓冲区容量是否匹配；未命中时创建新缓冲区。空闲回收任务逐步清理队列。堆内存或直接内存由配置决定，VirtualBuffer 本身不等同于直接内存。
EncodedBuffer.allocate(size) 使用 allocateResponse(WRITE_CHUNK_SIZE, size) 对齐容量，并把有效 limit 限制为实际申请长度。编码器写完后调用 flip()，发送器只发送有效数据。
clear() 只重置位置，不会清零内存。编码器应完整写入每个字段；WebSocket 编码器会显式写入完整帧头，包括扩展长度字段。客户端掩码写入输出缓冲区，调用方的原始正文可以继续保留。
EncodedBuffer 管理发送所有权
EncodedBuffer 将 ByteBuffer 和对应回收入口绑定在一起，由发送任务持有。
| 创建方式 | 用途 | 完成时的行为 |
|---|---|---|
allocate(size) | 申请新的池化编码输出 | 归还 VirtualBuffer 响应池 |
encodePooled(encoder) | 在一次分配中完成编码 | 编码异常时自动归还；成功后交给发送任务 |
owned(virtualBuffer) | 接收已有 VirtualBuffer 的所有权 | 调用对应包装对象的 clean() |
owned(byteBuffer) | 兼容普通 ByteBuffer 编码器 | 交给 BufferPoolUtils.clean() |
borrowed(byteBuffer) | 借用已有可读数据 | 保留调用方位置，不回收调用方存储 |
异步提交成功表示 IO 已开始。发送任务在部分写入期间继续持有缓冲区，直到这块数据写完或操作失败。连接关闭时，尚在写入的缓冲区仍等待 IO 回调结束再归还。close() 的回收动作只执行一次。
TLS 加密生成独立密文后，明文输出即可归还；密文缓冲区继续由发送任务持有到写入结束。文件分片同样按实际使用期限回收。
借用缓冲区的调用方应确保正文在发送完成前保持有效且不被修改。预编码数据也遵循此约定。
自定义 TCP 编码
原有 encode() 接口继续可用。需要池化编码时，可以额外覆盖 encodeBuffer()，把完整所有权交给发送器。下面的方法加入现有 handler，示例采用四字节长度加正文的协议，其中 PayloadPacket 表示应用自己的消息类型：
@Override
public EncodedBuffer encodeBuffer(Packet packet, TioConfig config,
ChannelContext context) {
byte[] body = ((PayloadPacket) packet).getBody();
int length = Math.addExact(Integer.BYTES, body.length);
return EncodedBuffer.encodePooled(allocate -> {
ByteBuffer output = allocate.apply(length);
output.putInt(body.length);
output.put(body);
output.flip();
return output;
});
}EncodedBuffer 位于 nexus.io.tio.core.pool 包。encodePooled() 的回调只申请一次输出，并返回这个输出；如果编码抛出异常，已分配的缓冲区会自动归还。
也可以直接接入已有工具类：
VirtualBuffer virtualBuffer = BufferPoolUtils.allocateResponse(
TioConfig.WRITE_CHUNK_SIZE, length);
EncodedBuffer encoded = EncodedBuffer.owned(virtualBuffer);
try {
ByteBuffer output = encoded.buffer();
output.order(ByteOrder.BIG_ENDIAN);
output.limit(length);
output.putInt(body.length);
output.put(body);
output.flip();
return encoded;
} catch (RuntimeException | Error error) {
encoded.close();
throw error;
}方法成功返回后，所有权已经交给发送器，编码器不要提前关闭它。只返回 virtualBuffer.buffer() 会丢失其回收入口；也不要将这块底层内存单独放入普通 ByteBuffer 回收队列。
框架保留静态 encode() 以及 handler 的旧编码接口。内置 handler 的子类继续通过旧接口调用其自定义 encode()，需要使用新路径时可显式覆盖 encodeBuffer()。直接调用静态 encodeBuffer() 而不经过框架发送器时，由调用者在使用完成后关闭返回对象。
长连接读取与业务数据
读取侧具有两层复用：同一连接连续读取时使用同一个 VirtualBuffer；连接结束或容量变化时归还池，供后续匹配容量的分配使用。这套机制适用于 HTTP keep-alive、WebSocket 和 TCP。
解码回调结束后，读取缓冲区可能立即投入下一次 IO。交给异步业务的消息应持有自己可独立使用的正文。slice() 和 duplicate() 共享底层内存，应用需要管理其使用期限。内置 HTTP、WebSocket 正文以及核心半包处理使用独立数据保存对应内容。
VirtualBuffer.wrap(existingBuffer) 只是包装已有存储，没有关联 BufferPage，不会自动加入池化复用。
观察复用效果
通过 BufferPoolUtils.getBufferMomeryInfo() 可查看请求池、响应池及普通 ByteBuffer 池的分配、命中与回收统计。容量分布、并发连接数量、发送速度及空闲清理都会影响命中率。对实际业务进行吞吐量、延迟、内存与 GC 测量，可帮助选择分配粒度和连接资源预算。
进一步阅读：稳定性设计与资源管理、HTTP 长连接与高效文件传输。