qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-09-23 19:20:13 -06:00
Code Releases Activity

doc/go1.9: discuss runtime.Callers

Browse Source 
A lot of code that uses runtime.Callers makes assumptions about the
result that are not true today under gccgo and will not be true in the
future in gc. This adds a section to the release notes discussing how
to correctly use runtime.Callers.

Change-Id: I96b7c7ef183cee2061442fc3501fceceefa54c09
Reviewed-on: https://go-review.googlesource.com/47691
Reviewed-by: Russ Cox <rsc@golang.org>
This commit is contained in:
Austin Clements 2017-07-06 14:27:25 -04:00
parent d58125ecd2
commit 590f47558d
1 changed files with 41 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/go1.9.html
View File

@ -257,6 +257,47 @@ We expect that the next release, GCC 8, will contain the Go 1.10
version of gccgo.
</p>
<h2 id="runtime">Runtime</h2>
<h3 id="callersframes">Call stacks with inlined frames</h3>
<p>
Users of
<a href="/pkg/runtime#Callers"><code>runtime.Callers</code></a>
should avoid directly inspecting the resulting PC slice and instead use
<a href="/pkg/runtime#CallersFrames"><code>runtime.CallersFrames</code></a>
to get a complete view of the call stack, or
<a href="/pkg/runtime#Caller"><code>runtime.Caller</code></a>
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.
</p>
<p>
Specifically, code that directly iterates over the PC slice and uses
functions such as
<a href="/pkg/runtime#FuncForPC"><code>runtime.FuncForPC</code></a>
to resolve each PC individually will miss inlined frames.
To get a complete view of the stack, such code should instead use
<code>CallersFrames</code>.
Likewise, code should not assume that the length returned by
<code>Callers</code> is any indication of the call depth.
It should instead count the number of frames returned by
<code>CallersFrames</code>.
</p>
<p>
Code that queries a single caller at a specific depth should use
<code>Caller</code> rather than passing a slice of length 1 to
<code>Callers</code>.
</p>
<p>
<a href="/pkg/runtime#CallersFrames"><code>runtime.CallersFrames</code></a>
has been available since Go 1.7, so code can be updated prior to
upgrading to Go 1.9.
</p>
<h2 id="performance">Performance</h2>
<p>