[release-branch.go1.14] doc/articles/race_detector: mention memory leak potential

As far as I can tell, there is no public documentation on this topic,
which cost me several days of debugging.

I am possibly unusual in that I run binaries in production with the
race detector turned on, but I think that others who do the same may
want to be aware of the risk.

Updates #26813.
Updates #37233.

Change-Id: I1f8111bd01d0000596e6057b7cb5ed017d5dc655
Reviewed-on: https://go-review.googlesource.com/c/go/+/220586
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
(cherry picked from commit ba093c4562e7464e95a4bde6505d270b71ed623f)
Reviewed-on: https://go-review.googlesource.com/c/go/+/221019
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

diff --git a/doc/articles/race_detector.html b/doc/articles/race_detector.html
index 1c449da5c099980a7f14e0182ba61c484003ba4b..014411d9484c1e23c2396600c8a47ffff1a5cd68 100644 (file)
--- a/doc/articles/race_detector.html
+++ b/doc/articles/race_detector.html
@@ -395,3 +395,14 @@ func (w *Watchdog) Start() {
 The cost of race detection varies by program, but for a typical program, memory
 usage may increase by 5-10x and execution time by 2-20x.
 </p>
+
+<p>
+The race detector currently allocates an extra 8 bytes per <code>defer</code>
+and <code>recover</code> statement. Those extra allocations <a
+href="https://golang.org/issue/26813">are not recovered until the goroutine
+exits</a>. This means that if you have a long-running goroutine that is
+periodically issuing <code>defer</code> and <code>recover</code> calls,
+the program memory usage may grow without bound. These memory allocations
+will not show up in the output of <code>runtime.ReadMemStats</code> or
+<code>runtime/pprof</code>.
+</p>