From b43368882ec2496be4e3b11c87e34a16a9068b5a Mon Sep 17 00:00:00 2001
From: Alex Hong <9397363+hongalex@users.noreply.github.com>
Date: Thu, 3 Mar 2022 10:20:27 -0800
Subject: [PATCH] docs(pubsub): clarify ack/nack cannot be called from
 goroutine (#5718)

---
 pubsub/doc.go | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/pubsub/doc.go b/pubsub/doc.go
index 2b081bfb01c9..425db9b10a82 100644
--- a/pubsub/doc.go
+++ b/pubsub/doc.go
@@ -74,8 +74,12 @@ The callback is invoked concurrently by multiple goroutines, maximizing
 throughput. To terminate a call to Receive, cancel its context.
 
 Once client code has processed the message, it must call Message.Ack or
-message.Nack, otherwise the message will eventually be redelivered. If the
-client cannot or doesn't want to process the message, it can call Message.Nack
+Message.Nack, otherwise the message will eventually be redelivered. Ack/Nack
+MUST be called within the Receive handler function, and not from a goroutine.
+Otherwise, flow control (e.g. ReceiveSettings.MaxOutstandingMessages) will
+not be respected, and messages can get orphaned when cancelling Receive.
+
+If the client cannot or doesn't want to process the message, it can call Message.Nack
 to speed redelivery. For more information and configuration options, see
 "Deadlines" below.