docs: align comments with the code they describe

- multi_coalesce/batch: the ordering contract now states what Flush
  actually guarantees -- per-flow DATA order -- and names the two
  shapes later data may legally overtake (pure ACKs by design, and
  unparseable in-flow shapes as an accepted tradeoff).
- validVnetHdr claimed DATA_VALID makes the stack skip L4 checksum
  verification; the tun write path ignores that bit entirely. What the
  header buys is the absence of NEEDS_CSUM.
- tun_darwin Write said "only valid for single threaded use"; it is
  concurrency-safe and concurrent callers exist.
- udp_coalesce eviction comment said "Seal it" but never sets sealed.
- recordCapability: note the gauges are process-global while the state
  is per-socket (last writer wins).
- drop a stale tunReadBufSize reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014ugV2edVqoz3tBvq9J6yWp
This commit is contained in:
JackDoan
2026-07-29 17:48:47 -05:00
parent 9c68c60ba6
commit 7ee5e29758
6 changed files with 38 additions and 11 deletions
+6 -1
View File
@@ -5,7 +5,12 @@ import "net/netip"
type RxBatcher interface {
// Commit commits pkt to be flushed by the batch. The caller must keep pkt valid until the next Flush, and not re-use it.
Commit(pkt []byte) error
// Flush emits every queued packet in arrival order.
// Flush emits every queued packet. The guarantee is per-flow DATA order:
// a flow's payload-bearing packets are never reordered relative to each
// other. Cross-flow and cross-lane order is not preserved, and two shapes
// may legally be overtaken by later same-flow data: pure ACKs (by design,
// stale ACKs are ignored) and unparseable shapes such as fragments (an
// accepted tradeoff; see MultiCoalescer).
// Returns the first error observed; keeps draining so one bad packet doesn't hold up the rest.
// After Flush returns, committed payload slices may be recycled.
Flush() error