Documentation for special comments

[thwd]

Is there a place where special comments (those starting with "//go:") are documented?

Grep reveals these exist:

    //go:generate (this one is clear)

    //go:linkname

    //go:name

    //go:noescape

    //go:norace

    //go:nosplit

    //go:nowritebarrier

    //go:systemstack

And these for CGO:

    //go:cgo_dynamic_linker

    //go:cgo_export_dynamic

    //go:cgo_export_static

    //go:cgo_import_dynamic

    //go:cgo_import_static

    //go:cgo_ldflag

But I'd like to learn more. Especially about noescape, norace, nosplit, nowritebarrier and systemstack.

- Tom

[Ian Lance Taylor]

Some of the //go: comments are documented at
https://golang.org/cmd/compile. All of the //go:cgo comments are
documented in cmd/cgo/doc.go, in a comment that does not appear on the
web.

I think everything is documented except norace, nowritebarrier, and
systemstack. nowritebarrier is only permitted when compiling the
runtime package itself (it means to not generate write barriers in the
function). Feel free to open an issue to document norace: it means to
not generate calls for the race detector even when building with
-race.

go:systemstack was used while converting the runtime from C to Go. It
helped detect cases where we ran C code on the Go stack. Now that the
conversion has been completed, I think it can be removed. There seems
to be exactly one remaining use of it, and frankly I'm not sure why it
is there. I filed https://golang.org/issue/12454 .

Ian

[thwd]

Thank you. Regarding the issue you opened:

Is runtime.systemstack() not a suitable replacement for the comment?

Defined: https://golang.org/src/runtime/stubs.go

Implemented: https://golang.org/src/runtime/asm_amd64.s

I'm asking cause it seems redundant to have both if they are interchangeable.

[Ian Lance Taylor]

On Thu, Sep 3, 2015 at 1:50 AM, thwd <sedevel...@gmail.com> wrote:
> Thank you. Regarding the issue you opened:
>
> Is runtime.systemstack() not a suitable replacement for the comment?
>
> Defined: https://golang.org/src/runtime/stubs.go
> Implemented: https://golang.org/src/runtime/asm_amd64.s
>
> I'm asking cause it seems redundant to have both if they are
> interchangeable.

They are not interchangeable. The go:systemstack comment means that
it is an error if the function is not run on the system stack. The
systemstack function runs something on the system stack. A function
can run on the system stack because it is called by a function started
by systemstack. The systemstack function can be used to run a
function that is also permitted to run on the normal stack.

Ian