doc/go_mem: "hello, world" will not always be printed twice

[ehsangifani]

It seems like the referenced doc is misleading:

go/doc/go_mem.html

Line 425 in 66ff373

The result will be that <code>"hello, world"</code> will be printed

What did you do?

package main

import "sync"

var a string
var once sync.Once

func setup() {
	a = "hello, world"
}

func doprint() {
	once.Do(setup)
	print(a)
}

func twoprint() {
	go doprint()
	go doprint()
}

func main() {
	twoprint()
}

What did you expect to see?

The result will be that "hello, world" will be printed twice.

What did you see instead?

Sometimes it was printed twice, and sometimes it was not printed at all.

System details

go version go1.12.9 windows/amd64
GOARCH="amd64"
GOBIN=""
GOCACHE="C:\Users\*****\AppData\Local\go-build"
GOEXE=".exe"
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="windows"
GOOS="windows"
GOPATH="C:\Users\******\go"
GOPROXY=""
GORACE=""
GOROOT="c:\go"
GOTMPDIR=""
GOTOOLDIR="c:\go\pkg\tool\windows_amd64"
GCCGO="gccgo"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
GOROOT/bin/go version: go version go1.12.9 windows/amd64
GOROOT/bin/go tool compile -V: compile version go1.12.9

[DisposaBoy]

You need some kind of synchronization like a channel or sync.WaitGroup to wait for the goroutines to complete before returning from main().

Quoting https://golang.org/ref/spec#Program_execution

Program execution begins by initializing the main package and then invoking the function main. When that function invocation returns, the program exits. It does not wait for other (non-main) goroutines to complete.

[ehsangifani]

Yes, of course. But the problem is with the documentation that states printing twice happens without any mention of a synchronization method.
Here is my proposed change to the example code that shows the functionality of Once.Do while being correct:

var a string
var once sync.Once

func setup() {
	a += "hello, world" //change: to show that it doesn't run twice
}

func doprint(done chan int) {
	once.Do(setup)
	print(a)
	done <- 1
}

func twoprint() {
	var done = make(chan int) //change: synchronization
	go doprint(done)
	go doprint(done)
	<-done
	<-done
}

[bcmills]

You assumed a particular func main(). This one is guaranteed to always execute both prints — just not guaranteed to terminate!

[bcmills]

On the one hand, the missing func main() does leave out an interesting detail.

On the other hand, the document is full of interesting details already — and adding that detail to one example implies that we would need to add it to the other examples, obscuring the more important point about the specific synchronization mechanism that is the focus of the example.

Is there a way to make the examples more correct without making them substantially more verbose?

[bcmills]

CC @dvyukov @ianlancetaylor

See previously #27808.

[ehsangifani]

@bcmills
Actually, I didn't assume anything. As you can see on this line , it says calling twoprint will call setup exactly once.
So it's the issue of wording in my opinion, which could create a wrong impression to someone new to Go, that sync.Once somehow stops main from returning before its spawned go-routines return.

I think changing the sentence to something like:
calling twoprint , assuming main() won't return yet, will call setup exactly once.
can somewhat mitigate the situtation.

[seankhliao]

it seems to be an unnecessary detail.