gopls/internal/cache: add a note about GOMEMLIMIT and ballasts As suggested post-submit in CL 608796, add a note explaining why GOMEMLIMIT doesn't help gopls solve its GC CPU problems, and a ballast is still necessary. Change-Id: Ia452129e259c6f44a0f807028543699d3dd19495 Reviewed-on: https://go-review.googlesource.com/c/tools/+/609236 Reviewed-by: Alan Donovan <adonovan@google.com> Reviewed-by: Michael Pratt <mpratt@google.com> Auto-Submit: Robert Findley <rfindley@google.com> LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/gopls/internal/cache/cache.go b/gopls/internal/cache/cache.go
index 80e94b1..9f85846 100644
--- a/gopls/internal/cache/cache.go
+++ b/gopls/internal/cache/cache.go

@@ -38,6 +38,18 @@
 // cache in front the filecache package, and the throughput of type checking.
 // Gopls already requires hundreds of megabytes of RAM to function.
 //
+// Note that while other use cases for a ballast were made obsolete by
+// GOMEMLIMIT, ours is not. GOMEMLIMIT helps in cases where you have a
+// containerized service and want to optimize its latency and throughput by
+// taking advantage of available memory. However, in our case gopls is running
+// on the developer's machine alongside other applications, and can have a wide
+// range of memory footprints depending on the size of the user's workspace.
+// Setting GOMEMLIMIT to too low a number would make gopls perform poorly on
+// large repositories, and setting it to too high a number would make gopls a
+// badly behaved tenant. Short of calibrating GOMEMLIMIT based on the user's
+// workspace (an intractible problem), there is no way for gopls to use
+// GOMEMLIMIT to solve its GC CPU problem.
+//
 // Because this allocation is large and occurs early, there is a good chance
 // that rather than being recycled, it comes directly from the OS already
 // zeroed, and since it is never accessed, the memory region may avoid being