cmd/compile: decide how to better document -wb write barrier flag

[xaionaro]

What version of Go are you using (go version)?

$ go version
go version go1.13 linux/amd64

Does this issue reproduce with the latest release?

Yes.

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/experiment0/.cache/go-build"
GOENV="/home/experiment0/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/experiment0/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/experiment0/.gimme/versions/go1.13.linux.amd64"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/experiment0/.gimme/versions/go1.13.linux.amd64/pkg/tool/linux_amd64"
GCCGO="/usr/bin/gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build011542069=/tmp/go-build -gno-record-gcc-switches"

What did you do?

Opened go tool compile documentation

What did you expect to see?

Description of option -wb=false. As user of this tool, I need to understand what do I loose when I use this option and what risks I get. I see that the size of a binary could be reduced (through using this option), but I cannot make a decision if it is justified to use this option in my case, because I don't know about other possible effects.

The only information I found (before looking to the source code):

$ go tool compile --help 2>&1 | tail -2
  -wb
        enable write barrier (default true)

plus

As preparation for the concurrent garbage collector scheduled for the 1.5 release, writes to pointer values in the heap are now done by a function call, called a write barrier, rather than directly from the function updating the value. In this next release, this will permit the garbage collector to mediate writes to the heap while it is running. This change has no semantic effect on programs in 1.4, but was included in the release to test the compiler and the resulting performance.

plus

Some blogs which explains how this barrier works. But no explanation what will happen if I will disable it on Go1.13.

What did you see instead?

There's no description of the option.

[mvdan]

I think, in general, compiler flags should only be used if you know what you're doing. I don't think the help text could explain what disabling write barriers could do in a sentence or two, so the current line seems OK to me.

[mvdan]

That being said, I agree that a blog post would be interesting. But I don't know if this flag is something we want to encourage developers to use.

[xaionaro]

I think, in general, compiler flags should only be used if you know what you're doing.

Totally agree. And to understand what I'm doing I need a source of information.

I don't think the help text could explain what disabling write barriers could do in a sentence or two, so the current line seems OK to me. That being said, I agree that a blog post would be interesting.

I believe it should be described on the bottom of the documentation page of go tool compile (after section "Compiler Directives").

But I don't know if this flag is something we want to encourage developers to use.

Well, for example gcc has a lot of flags and each flag is documented, even if it can be dangerous or whatever (they just say something like ... must be used with caution since it can ..., ... can cause data corruption when ... etc). And it seems to be a good practice. So the application field of Go will expand (if it will follow the same practice), because it will be fine-tunable for more-and-more different use-cases (as gcc currently is).

[randall77]

I don't think we want to document this flag. It's not intended for the end user. Its mere existence is an accident of history, when we were moving from a non-write-barrier GC to a write-barrier GC we needed a way to turn the write barrier on/off for testing. Maybe we should just remove it. Go just won't work with the write barrier off. Unless you also turn the GC off (GOGC=off). But that really isn't a tenable way to run Go either.

[xaionaro]

Unless you also turn the GC off (GOGC=off). But that really isn't a tenable way to run Go either.

I have use cases where I don't need GC at all, but I need to reduce the size of a binary.

I don't think we want to document this flag. It's not intended for the end user. Its mere existence is an accident of history, when we were moving from a non-write-barrier GC to a write-barrier GC we needed a way to turn the write barrier on/off for testing. Maybe we should just remove it.

I see. Thank you :)

[bradfitz]

Maybe we should just remove it.

Agreed.

[tpaschalis]

Is the consensus that the flag should be removed? I could take a stab and prepare a PR for this.

[ALTree]

@tpaschalis There is no consensus yet (hence the "NeedsDecision" label).

[ianlancetaylor]

Moving to backlog milestone.

[gopherbot]

Change https://golang.org/cl/244961 mentions this issue: cmd/compile: remove legacy wb flag

[ALTree]

Cherry asked the flag not to be removed, so I'd say the options now are 1) do nothing 2) document it better. Changing the title accordingly.