runtime: document when cgo traceback function is called

Fixes #24518.

Change-Id: I99c79c5a2ab9dbe7f0d257c263da9d2b5d1d55c4
Reviewed-on: https://go-review.googlesource.com/121917
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/runtime/traceback.go b/src/runtime/traceback.go
index cc5e01eb8b3fa4e60408cc67bc5ebbec49d6c2dd..495365390087bd446cfbb1113fb764606ea96285 100644 (file)
--- a/src/runtime/traceback.go
+++ b/src/runtime/traceback.go
@@ -1115,6 +1115,13 @@ func isSystemGoroutine(gp *g) bool {
 // to the symbolizer function, return the file/line of the call
 // instruction.  No additional subtraction is required or appropriate.
 //
+// On all platforms, the traceback function is invoked when a call from
+// Go to C to Go requests a stack trace. On linux/amd64, linux/ppc64le,
+// and freebsd/amd64, the traceback function is also invoked when a
+// signal is received by a thread that is executing a cgo call. The
+// traceback function should not make assumptions about when it is
+// called, as future versions of Go may make additional calls.
+//
 // The symbolizer function will be called with a single argument, a
 // pointer to a struct:
 //