unslop a bit

overlay/tio/blockon_linux.go

@@ -9,10 +9,9 @@ import (
 	"golang.org/x/sys/unix"
 )
 
-// blockOn parks the calling goroutine until fd is ready (events is POLLIN for
+// blockOn parks the calling goroutine until fd is ready or shutdownFd signals teardown.
-// reads, POLLOUT for writes) or shutdownFd signals teardown. It builds the
+// (events is POLLIN for reads, POLLOUT for writes)
-// pollfd array on the stack every call, so concurrent callers on the same
+// It builds the pollfd array on the stack every call, so concurrent callers on the same Queue never share Revents storage.
-// Queue never share Revents storage.
 //
 // Returns os.ErrClosed when shutdown was signaled (POLLIN on shutdownFd)
 // or either fd reported a problem condition (POLLHUP|POLLNVAL|POLLERR).

overlay/tio/queueset_gso_linux.go

@@ -17,17 +17,14 @@ type offloadQueueSet struct {
 	// pqi is exactly the same as pq, but stored as the interface type
 	pqi        []Queue
 	shutdownFd int
-	// usoEnabled is true when newTun successfully negotiated TUN_F_USO4|6
+	// usoEnabled is true when newTun successfully negotiated TUN_F_USO4|6 with the kernel.
-	// with the kernel. Queues created by Add inherit this and surface it
+	// Queues created by Add inherit this and surface it via Offload.USOSupported so coalescers can gate USO emission.
-	// via Offload.USOSupported so coalescers can gate USO emission.
 	usoEnabled bool
 	closed     atomic.Bool
 }
 
-// NewOffloadQueueSet creates a QueueSet that uses virtio_net_hdr to do
+// NewOffloadQueueSet creates a QueueSet that uses virtio_net_hdr to do TSO segmentation.
-// TSO segmentation in userspace. usoEnabled tells downstream queues whether
+// usoEnabled tells downstream queues whether the kernel agreed to deliver/accept GSO_UDP_L4 superpackets.
-// the kernel agreed to deliver/accept GSO_UDP_L4 superpackets — coalescers
-// should fall back to per-packet writes when this is false.
 func NewOffloadQueueSet(usoEnabled bool) (QueueSet, error) {
 	shutdownFd, err := unix.Eventfd(0, unix.EFD_NONBLOCK|unix.EFD_CLOEXEC)
 	if err != nil {
@@ -73,23 +70,21 @@ func (c *offloadQueueSet) Close() error {
 
 	errs := []error{}
 
-	// Signal all readers blocked in poll to wake up and exit. They observe
+	// Signal all readers blocked in poll to wake up and exit.
-	// POLLIN on the shutdown eventfd and return os.ErrClosed.
+	// They observe POLLIN on the shutdown eventfd and return os.ErrClosed.
 	if err := c.wakeForShutdown(); err != nil {
 		errs = append(errs, err)
 	}
 
 	// Close the per-queue tun fds; this also unblocks any in-flight reads.
-	// The per-queue Close deliberately leaves shutdownFd alone - it belongs
-	// to this container.
 	for _, x := range c.pq {
 		if err := x.Close(); err != nil {
 			errs = append(errs, err)
 		}
 	}
 
-	// Close the shutdown eventfd last: every reader's pollfd set references
+	// Close the shutdown eventfd last: every reader's pollfd set references it,
-	// it, so it must outlive the wake + per-queue teardown above.
+	// so it must outlive the wake + per-queue teardown above.
 	if err := unix.Close(c.shutdownFd); err != nil {
 		errs = append(errs, err)
 	}

overlay/tio/queueset_poll_linux.go

@@ -64,23 +64,21 @@ func (c *pollQueueSet) Close() error {
 
 	errs := []error{}
 
-	// Wake any reader blocked in poll so it observes POLLIN on the shutdown
+	// Signal all readers blocked in poll to wake up and exit.
-	// eventfd and returns os.ErrClosed.
+	// They observe POLLIN on the shutdown eventfd and return os.ErrClosed.
 	if err := c.wakeForShutdown(); err != nil {
 		errs = append(errs, err)
 	}
 
 	// Close the per-queue tun fds; this also unblocks any in-flight reads.
-	// The per-queue Close deliberately leaves shutdownFd alone - it belongs
-	// to this container.
 	for _, x := range c.pq {
 		if err := x.Close(); err != nil {
 			errs = append(errs, err)
 		}
 	}
 
-	// Close the shutdown eventfd last: every reader's pollfd set references
+	// Close the shutdown eventfd last: every reader's pollfd set references it,
-	// it, so it must outlive the wake + per-queue teardown above.
+	// so it must outlive the wake + per-queue teardown above.
 	if err := unix.Close(c.shutdownFd); err != nil {
 		errs = append(errs, err)
 	}