runtime/debug: clarify WriteHeapDump STW behavior

Change-Id: I049d2596fe8ce0e93391599f5c224779fd8e316f
Reviewed-on: https://go-review.googlesource.com/20761
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/runtime/debug/garbage.go b/src/runtime/debug/garbage.go
index 4d3ca79a819e4e944f57d83553da1d45c09c35c1..81444971774c070aacdde7edf03b0c5eb56b8cbc 100644 (file)
--- a/src/runtime/debug/garbage.go
+++ b/src/runtime/debug/garbage.go
@@ -155,6 +155,12 @@ func SetPanicOnFault(enabled bool) bool {
 
 // WriteHeapDump writes a description of the heap and the objects in
 // it to the given file descriptor.
+//
+// WriteHeapDump suspends the execution of all goroutines until the heap
+// dump is completely written.  Thus, the file descriptor must not be
+// connected to a pipe or socket whose other end is in the same Go
+// process; instead, use a temporary file or network socket.
+//
 // The heap dump format is defined at https://golang.org/s/go15heapdump.
 func WriteHeapDump(fd uintptr)