From 6116f463722c595e5b24c47d01e554d4c00c897b Mon Sep 17 00:00:00 2001
From: "Nelo-T. Wallus" <nelo@wallus.de>
Date: Wed, 9 Jul 2025 21:43:30 +0200
Subject: [PATCH] Update docs on shutdown and draining

Kubernetes-commit: 67aaa956da3e6110e8155cc08539c488fc5e1298
---
 util/workqueue/queue.go | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/util/workqueue/queue.go b/util/workqueue/queue.go
index aaef3c5d..78b072da 100644
--- a/util/workqueue/queue.go
+++ b/util/workqueue/queue.go
@@ -212,7 +212,9 @@ type Typed[t comparable] struct {
 	clock                      clock.WithTicker
 }
 
-// Add marks item as needing processing.
+// Add marks item as needing processing. When the queue is shutdown new
+// items will silently be ignored and not queued or marked as dirty for
+// reprocessing.
 func (q *Typed[T]) Add(item T) {
 	q.cond.L.Lock()
 	defer q.cond.L.Unlock()
@@ -290,8 +292,9 @@ func (q *Typed[T]) Done(item T) {
 	}
 }
 
-// ShutDown will cause q to ignore all new items added to it and
-// immediately instruct the worker goroutines to exit.
+// ShutDown will cause q to ignore all new items added to it. Worker
+// goroutines will continue processing items in the queue until it is
+// empty and then receive the shutdown signal.
 func (q *Typed[T]) ShutDown() {
 	q.cond.L.Lock()
 	defer q.cond.L.Unlock()
@@ -301,15 +304,12 @@ func (q *Typed[T]) ShutDown() {
 	q.cond.Broadcast()
 }
 
-// ShutDownWithDrain will cause q to ignore all new items added to it. As soon
-// as the worker goroutines have "drained", i.e: finished processing and called
-// Done on all existing items in the queue; they will be instructed to exit and
-// ShutDownWithDrain will return. Hence: a strict requirement for using this is;
-// your workers must ensure that Done is called on all items in the queue once
-// the shut down has been initiated, if that is not the case: this will block
-// indefinitely. It is, however, safe to call ShutDown after having called
-// ShutDownWithDrain, as to force the queue shut down to terminate immediately
-// without waiting for the drainage.
+// ShutDownWithDrain is equivalent to ShutDown but waits until all items
+// in the queue have been processed.
+// ShutDown can be called after ShutDownWithDrain to force
+// ShutDownWithDrain to stop waiting.
+// Workers must call Done on an item after processing it, otherwise
+// ShutDownWithDrain will block indefinitely.
 func (q *Typed[T]) ShutDownWithDrain() {
 	q.cond.L.Lock()
 	defer q.cond.L.Unlock()