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
