Channel Write And Flush

rs-netty 明确区分 write 和 flush。这一点对延迟、吞吐和测试都很重要。

Handler Context Writes

TCP Context<W>：

• write(msg)：把消息放入当前 handler 的 local outbox。返回的 WriteHandle 立即 ready，await 只是兼容 async 风格。
• flush()：请求 flush 当前 handler 已暂存的消息。返回的 handle 可以丢弃，也可以 await。
• write_and_flush(msg)：暂存消息并创建 flush 边界。

UDP DatagramContext<W> 类似，但写入目标可以是当前 peer 或显式 peer：

• write(msg)
• write_to(peer_addr, msg)
• flush()
• write_and_flush(msg)
• write_to_and_flush(peer_addr, msg)

Await Vs Fire And Forget

flush() 和 write_and_flush() 返回的 handle 可以直接丢弃：

#![allow(unused)]
fn main() {
ctx.write_and_flush("first".to_string());
}

这会请求 runtime 在 handler future 仍 pending 时就 drain outbox。tests/server_lifecycle.rs 验证了 fire-and-forget flush 在 handler return 之前也能把第一条响应发出去。

如果 await：

#![allow(unused)]
fn main() {
ctx.write_and_flush("first".to_string()).await?;
}

await 的含义是等待本地 socket write 完成这个 flush 边界。它不是远端确认，也不表示远端 handler 已处理。

Plain Write Buffers

plain write 不会自动 flush。测试覆盖了：

• tcp_context_write_buffers_until_explicit_flush
• udp_context_write_buffers_until_explicit_flush
• tcp_channel_write_buffers_until_flush
• udp_client_write_preserves_datagrams_until_flush

需要发送时使用：

#![allow(unused)]
fn main() {
ctx.write("sent".to_string()).await?;
ctx.flush().await?;
}

或：

#![allow(unused)]
fn main() {
ctx.write_and_flush("sent".to_string()).await?;
}

External Channel Writes

Channel<W> 是 TCP external handle。它通过 bounded mpsc 向 connection task 发送命令：

• write(msg)：等待 queue capacity，把消息排队并 encode 到 write buffer；不 flush。
• flush()：等待之前排队的写 flush 到 socket。
• write_and_flush(msg)：排队消息并等待本地 socket write 完成。
• close()：请求本地连接关闭。

DatagramChannel<W> 是 UDP external handle：

• write_to(peer, msg)：排队 datagram；不发送。
• flush()：send 所有 pending datagrams。
• write_to_and_flush(peer, msg)：排队并 send。
• close()：请求 socket task 退出。

UdpClientHandle<W> 对默认 remote peer 包装了 write、flush 和 write_and_flush。

Bounded Queue Boundary

outbound_queue_size 控制 channel command queue 容量，默认 1024。队列满时 external write/flush/write_and_flush 会等待容量，而不是无限增长。

handler-local outbox 和 external channel queue 是两个不同边界。handler 内部的 Context 写入先进入 local outbox，再由 runtime drain 到 codec/write buffer 或 pending datagrams。