Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
xaionaro opened this issue Jan 16, 2020 · 11 comments
Open

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

xaionaro opened this issue Jan 16, 2020 · 11 comments
Labels
compiler/runtime Issues related to the Go compiler and/or runtime. Documentation NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone
Backlog

Comments

@xaionaro
Copy link
Contributor

xaionaro commented Jan 16, 2020 •
edited

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.
@xaionaro xaionaro mentioned this issue Jan 16, 2020
Closed
@xaionaro xaionaro changed the title cmd/compile: doc: cmd/compile: doc: no description of option -wb=false Jan 16, 2020
@mvdan
Copy link
Member

mvdan commented Jan 16, 2020

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
Copy link
Member

mvdan commented Jan 16, 2020

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
Copy link
Contributor Author

xaionaro commented Jan 16, 2020 •
edited

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
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor

Maybe we should just remove it.

Agreed.

@bradfitz bradfitz added this to the Go1.15 milestone Jan 16, 2020
@bradfitz bradfitz added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Jan 16, 2020
@bradfitz bradfitz changed the title cmd/compile: doc: no description of option -wb=false cmd/compile: document or remove -wb write barrier flag Jan 16, 2020
@tpaschalis
Copy link
Contributor

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

@ALTree
Copy link
Member

ALTree commented Feb 3, 2020

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

@ianlancetaylor
Copy link
Contributor

Moving to backlog milestone.

@ianlancetaylor ianlancetaylor modified the milestones: Go1.15, Backlog Jun 16, 2020
@gopherbot
Copy link

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

@ALTree
Copy link
Member

ALTree commented Oct 8, 2020

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.

@ALTree ALTree changed the title cmd/compile: document or remove -wb write barrier flag cmd/compile: decide how to better document -wb write barrier flag Oct 8, 2020
@gopherbot gopherbot added the compiler/runtime Issues related to the Go compiler and/or runtime. label Jul 13, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
compiler/runtime Issues related to the Go compiler and/or runtime. Documentation NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
Go Compiler / Runtime
Status: Triage Backlog
Milestone
Backlog
Development

No branches or pull requests
8 participants
@bradfitz @xaionaro @ianlancetaylor @mvdan @ALTree @randall77 @gopherbot @tpaschalis