From e4f73769bcb06fca7b22d4ac3ec17c7247e84f39 Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Mon, 6 Mar 2017 14:13:24 -0500 Subject: [PATCH] runtime: strongly encourage CallersFrames with the result of Callers For historical reasons, it's still commonplace to iterate over the slice returned by runtime.Callers and call FuncForPC on each PC. This is broken in gccgo and somewhat broken in gc and will become more broken in gc with mid-stack inlining. In Go 1.7, we introduced runtime.CallersFrames to deal with these problems, but didn't strongly direct people toward using it. Reword the documentation on runtime.Callers to more strongly encourage people to use CallersFrames and explicitly discourage them from iterating over the PCs or using FuncForPC on the results. Fixes #19426. Change-Id: Id0d14cb51a0e9521c8fdde9612610f2c2b9383c4 Reviewed-on: https://go-review.googlesource.com/37726 Reviewed-by: Ian Lance Taylor --- src/runtime/extern.go | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/runtime/extern.go b/src/runtime/extern.go index 896bfc4fcb..319d6495bd 100644 --- a/src/runtime/extern.go +++ b/src/runtime/extern.go @@ -202,11 +202,13 @@ func Caller(skip int) (pc uintptr, file string, line int, ok bool) { // 1 identifying the caller of Callers. // It returns the number of entries written to pc. // -// Note that since each slice entry pc[i] is a return program counter, -// looking up the file and line for pc[i] (for example, using (*Func).FileLine) -// will normally return the file and line number of the instruction immediately -// following the call. -// To easily look up file/line information for the call sequence, use Frames. +// To translate these PCs into symbolic information such as function +// names and line numbers, use CallersFrames. CallersFrames accounts +// for inlined functions and adjusts the return program counters into +// call program counters. Iterating over the returned slice of PCs +// directly is discouraged, as is using FuncForPC on any of the +// returned PCs, since these cannot account for inlining or return +// program counter adjustment. func Callers(skip int, pc []uintptr) int { // runtime.callers uses pc.array==nil as a signal // to print a stack trace. Pick off 0-length pc here -- 2.48.1