# Channel Write And Flush
rs-netty intentionally separates write from flush. This matters for latency, throughput, and tests.
## Handler Context Writes
TCP `Context<W>`:
- `write(msg)`: puts the message into the current handler's local outbox. The returned `WriteHandle` is ready immediately; awaiting it is only async-style compatibility.
- `flush()`: requests a flush of messages staged by the current handler. The returned handle may be dropped or awaited.
- `write_and_flush(msg)`: stages a message and creates a flush boundary.
UDP `DatagramContext<W>` is similar, but the target may be the current peer or an explicit 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
The handles returned by `flush()` and `write_and_flush()` may be dropped:
```rust
ctx.write_and_flush("first".to_string());
```
This requests the runtime to drain the outbox even while the handler future is still pending. `tests/server_lifecycle.rs` verifies that fire-and-forget flushes can send the first response before the handler returns.
If you await:
```rust
ctx.write_and_flush("first".to_string()).await?;
```
the await waits until the local socket write completes for that flush boundary. It is not a remote acknowledgement and does not mean the peer's handler processed the data.
## Plain Write Buffers
Plain `write` does not automatically flush. Tests cover this behavior:
- `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`
To send data:
```rust
ctx.write("sent".to_string()).await?;
ctx.flush().await?;
```
or:
```rust
ctx.write_and_flush("sent".to_string()).await?;
```
## External Channel Writes
`Channel<W>` is the TCP external handle. It sends commands to the connection task through a bounded `mpsc` queue:
- `write(msg)`: waits for queue capacity, queues the message, and encodes it into the write buffer; it does not flush.
- `flush()`: waits until previously queued writes have been flushed to the socket.
- `write_and_flush(msg)`: queues a message and waits until the local socket write completes.
- `close()`: requests local connection shutdown.
`DatagramChannel<W>` is the UDP external handle:
- `write_to(peer, msg)`: queues a datagram; it does not send.
- `flush()`: sends all pending datagrams.
- `write_to_and_flush(peer, msg)`: queues and sends.
- `close()`: requests the socket task to exit.
`UdpClientHandle<W>` wraps `write`, `flush`, and `write_and_flush` for the default remote peer.
## Bounded Queue Boundary
`outbound_queue_size` controls the channel command queue capacity. The default is 1024. When the queue is full, external `write`/`flush`/`write_and_flush` calls wait for capacity instead of growing without bound.
The handler-local outbox and the external channel queue are separate boundaries. Writes from `Context` first enter the local outbox, then the runtime drains them into the codec/write buffer or pending datagram queue.