diff --git a/doc/go1.9.html b/doc/go1.9.html index ea91843006..9110ab7de4 100644 --- a/doc/go1.9.html +++ b/doc/go1.9.html @@ -257,6 +257,47 @@ We expect that the next release, GCC 8, will contain the Go 1.10 version of gccgo.
+
+ Users of
+ runtime.Callers
+ should avoid directly inspecting the resulting PC slice and instead use
+ runtime.CallersFrames
+ to get a complete view of the call stack, or
+ runtime.Caller
+ to get information about a single caller.
+ This is because an individual element of the PC slice cannot account
+ for inlined frames or other nuances of the call stack.
+
+ Specifically, code that directly iterates over the PC slice and uses
+ functions such as
+ runtime.FuncForPC
+ to resolve each PC individually will miss inlined frames.
+ To get a complete view of the stack, such code should instead use
+ CallersFrames
.
+ Likewise, code should not assume that the length returned by
+ Callers
is any indication of the call depth.
+ It should instead count the number of frames returned by
+ CallersFrames
.
+
+ Code that queries a single caller at a specific depth should use
+ Caller
rather than passing a slice of length 1 to
+ Callers
.
+
+ runtime.CallersFrames
+ has been available since Go 1.7, so code can be updated prior to
+ upgrading to Go 1.9.
+