runtime: use AST-derivable names for Frame.Function names

[dsnet]

Go version

go1.25.6

Output of go env in your module/workspace:

n/a

What did you do?

I want to reverse lookup a runtime.Function name back to the original Go source declaration.

What did you see happen?

Today, the exact runtime.Function name too closely matches what the backend compiler chose to do rather than being more closely associated with what the Go AST declares.

For example, if you have a qualified function symbol named path/to/package.FooFunc and it inlines another function named InlinedFunc, the symbol chosen might be something like path/to/package.FooFunc.InlinedFunc. This does produce a unique symbol name, but it is somewhat deceptive since it makes it look like InlinedFunc is declared within FooFunc (which it isn't, it just happens to be inlined). Also the numbering of anonymous functions is not simply numeration based on declaration order in a function, but also affected by how inlining occurred.

What did you expect to see?

My desire is that the function names can be primarily derived purely from the AST of the Go package, rather than depending on artifacts of the backend compiler such as inlining. Thus, looking up a function name would be possible purely by analyzing the Go source code without needing to build the Go binary and use go tool objdump to extract the exact symbol names. This perhaps implies that there is a helper function in the Go AST to derive a stable base name for a declaration that would be used both by the compiler backend and also be Go tools that want to reverse lookup a function by name.

Understandably, the backend compiler may need to emit unique instantiations of a function (e.g., for inlining or type parameterization), which then requires unique symbol names. I suspect that unique names can be derived by amending the base name in such a way that syntactic parsing can remove those alterations. For example, type instantiation always occurs in [...], which can be syntactically parsed and removed.

I don't have a concrete proposal for the exact naming convention, but just wanted to state the desired outcome.

\cc @adonovan @prattmic @aclements

[gabyhelp]

Related Issues

• x/telemetry: stack counters should use logical symbol names #66517
• runtime/trace: don't omit runtime (internal) stack frames #76457
• runtime: mid-stack inlining vs. FuncForPC #29582 (closed)
• cmd/compile: FuncForPC not returning correct function #58300 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[adonovan]

The current symbol naming scheme is as an implementation detail of the compiler, and has evolved as various optimizations have been implemented. I suspect that from the point of view of the compiler team the opacity and instability of the name mapping may be more of a feature than a bug since it affords them latitude to change things. If this issue is asking for a stable contract governing the interpretation of symbol name strings, it should be a proposal.

My preference would be to provide two kinds of information at clearly different levels: linker-level information about symbols and program counters, and source-level information about true Go functions and source line numbers. The mapping from the latter to the former is many to one, for example because of inlining, generic instantiations, and the way that range-over-func is implemented. I don't think a single string can serve both roles. Of course there may be similarities in the two domains: we would need a stable numbering scheme for source-level anonymous functions, init functions and so on, just as the compiler does internally.

[prattmic]

My preference would be to provide two kinds of information at clearly different levels: linker-level information about symbols and program counters, and source-level information about true Go functions and source line numbers.

From my brief discussion with Joe last week, I think that is the intention of this issue. i.e., that runtime.Frame.Function would provide the latter, "source-level" function name, rather than the object file symbol name.

runtime.Frame.Function should probably provide the same name used in traceback, but I think we'd want that to be the source name as well.

I think this sounds nice overall. I'm not sure if it would be problematic that there is no longer a way to get the object file symbol name of a frame, but that was already somewhat true since type-parameterized functions already replaced the shape name with ....

This is pretty closely related to #60324, which is a long discussion about better naming of closures.

cc @golang/runtime @golang/compiler

[adonovan]

From my brief discussion with Joe last week, I think that is the intention of this issue. i.e., that runtime.Frame.Function would provide the latter, "source-level" function name, rather than the object file symbol name.

runtime.Frame.Function should probably provide the same name used in traceback, but I think we'd want that to be the source name as well.

I think this sounds nice overall. I'm not sure if it would be problematic that there is no longer a way to get the object file symbol name of a frame, but that was already somewhat true since type-parameterized functions already replaced the shape name with ....

To rephrase myself more bluntly: the API should provide both. Frame.Function today is the linker symbol name, so it should probably remain that way to avoid breaking things, and we should add a new field with the source name.

Which one should appear in the traceback? I suspect most users want to see the source name and line number. But some tools (e.g. crash reporting) need accurate program counter info. Perhaps it should depend on the GOTRACEBACK level?

[prattmic]

Frame.Function today is the linker symbol name

It is not the linker symbol name for functions with type parameters, as it strips out the shape name from the symbol name, but this is true for all other symbols.

[DanielMorsing]

How close would adding line column info to DWARF5 or runtime.Frame get us? It might be a bigger task than nailing down a symbol mangling that allows looking up AST constructions unambiguously, but it is well-defined and can be kept consistent regardless of how we change the compiler internals

[cherrymui]

How close would adding line column info to DWARF5 or runtime.Frame get us?

It shouldn't be hard technically to add the column numbers. One major question is the impact on binary size.

[dsnet]

My key goal is that I want a way to (as @prattmic summarized) to go from a runtime.Frame.Function to a Go source declaration by only depending on AST parsing of the Go source code (i.e., I should never need to build the binary and extract symbols).

The problem is that runtime.Frame.Function is neither a purely linker symbol nor a purely a Go source declaration reference. I'm not a compilar author, so the exact linker symbol isn't of interest to me 😅 (but if we want to add a separate field to provide that, I'm not opposed).

That said, I would expect the two to be correlated in some way.

I suspect that from the point of view of the compiler team the opacity and instability of the name mapping may be more of a feature ...

I don't think we need to guarantee stability, but rather determinism. There should exist a function either in the stdlib or hosted by golang.org/x/tools that derives qualified names from the AST, which the compiler would then use as the basis of their naming own convention. I'd be okay if the exact naming convention was subject to change, so long as there is logic I can depend on and automatically pick up the changed conventions.

The mapping from the latter to the former is many to one...

I was imaging a naming scheme where the linker is welcome to inject syntactic artifacts to produce a unique name, but using a common AST-derived name as the basis. We already some degree of this with type parameters. For example, both linker symbols for:

• path/to/package.FooType[tar.Header].MethodName
• path/to/package.FooType[zip.Header].MethodName
  can be syntactically reduced down to:
• path/to/package.FooType[...].MethodName

since [ and ] delimiters can't appear in Go source identifiers, so they're easy to syntactically identify and strip out.

[adonovan]

Understood, but I think repurposing the existing Frame.Function in this way may be more disruptive than adding a new field. Currently Frame.Function is often the same as the linker symbol name, and this is relied upon by code as such as x/telemetry. See for example internal/counter.EncodeStack, which emits symbol names based on Frame.Function that are later cross-referenced with the pclntab by x/telemetry/cmd/stacks.frameURL). If this proposal is accepted, the Function strings would rarely be exactly the same as the linker symbol name.

(Doubly so if the new Go symbol name places the parens around the receiver type, such as (*"pkg/path".T[K, V]).Method, which is closer to Go syntax than pkg/path.(*T).Method.)