http://golang.org/ref/mem

The Go Memory Model

Version of March 6, 2012

Introduction

The Go memory model specifies the conditions under whichreads of a variable in one goroutine can be guaranteed toobserve values produced by writes to the same variable in a different goroutine.

Happens Before

Within a single goroutine, reads and writes must behaveas if they executed in the order specified by the program.That is, compilers and processors may reorder the reads and writesexecuted within a single goroutine only when the reorderingdoes not change the behavior within that goroutineas defined by the language specification.Because of this reordering, the execution order observedby one goroutine may differ from the order perceivedby another. For example, if one goroutineexecutes a = 1; b = 2;, another might observethe updated value of b before the updated value of a.

To specify the requirements of reads and writes, we definehappens before, a partial order on the executionof memory operations in a Go program. If event e₁ happensbefore event e₂, then we say that e₂ happens after e₁.Also, if e₁ does not happen before e₂ and does not happenafter e₂, then we say that e₁ and e₂ happen concurrently.

Within a single goroutine, the happens-before order is theorder expressed by the program.

A read r of a variable v is allowed to observe a write w to vif both of the following hold:

1. r does not happen before w.
2. There is no other write w' to v that happens after w but before r.

To guarantee that a read r of a variable v observes aparticular write w to v, ensure that w is the onlywrite r is allowed to observe.That is, r is guaranteed to observe w if both of the following hold:

1. w happens before r.
2. Any other write to the shared variable veither happens before w or after r.

This pair of conditions is stronger than the first pair;it requires that there are no other writes happeningconcurrently with w or r.

Within a single goroutine,there is no concurrency, so the two definitions are equivalent:a read r observes the value written by the most recent write w to v.When multiple goroutines access a shared variable v,they must use synchronization events to establishhappens-before conditions that ensure reads observe thedesired writes.

The initialization of variable v with the zero valuefor v's type behaves as a write in the memory model.

Reads and writes of values larger than a single machine wordbehave as multiple machine-word-sized operations in anunspecified order.

Synchronization

Initialization

Program initialization runs in a single goroutine,but that goroutine may create other goroutines,which run concurrently.

If a package p imports package q, the completion ofq's init functions happens before the start of any of p's.

The start of the function main.main happens afterall init functions have finished.

Goroutine creation

The go statement that starts a new goroutinehappens before the goroutine's execution begins.

For example, in this program:

var a string

func f() {
	print(a)
}

func hello() {
	a = "hello, world"
	go f()
}

calling hello will print "hello, world"at some point in the future (perhaps after hello has returned).

Goroutine destruction

The exit of a goroutine is not guaranteed to happen beforeany event in the program. For example, in this program:

var a string

func hello() {
	go func() { a = "hello" }()
	print(a)
}

the assignment to a is not followed byany synchronization event, so it is not guaranteed to beobserved by any other goroutine.In fact, an aggressive compiler might delete the entire go statement.

If the effects of a goroutine must be observed by another goroutine,use a synchronization mechanism such as a lock or channelcommunication to establish a relative ordering.

Channel communication

Channel communication is the main method of synchronizationbetween goroutines. Each send on a particular channelis matched to a corresponding receive from that channel,usually in a different goroutine.

A send on a channel happens before the correspondingreceive from that channel completes.

This program:

var c = make(chan int, 10)
var a string

func f() {
	a = "hello, world"
	c <- 0
}

func main() {
	go f()
	<-c
	print(a)
}

is guaranteed to print "hello, world". The write to ahappens before the send on c, which happens beforethe corresponding receive on c completes, which happens beforethe print.

The closing of a channel happens before a receive that returns a zero valuebecause the channel is closed.

In the previous example, replacingc <- 0 with close(c)yields a program with the same guaranteed behavior.

A receive from an unbuffered channel happens beforethe send on that channel completes.

This program (as above, but with the send and receive statements swapped andusing an unbuffered channel):

var c = make(chan int)
var a string

func f() {
	a = "hello, world"
	<-c
}

func main() {
	go f()
	c <- 0
	print(a)
}

is also guaranteed to print "hello, world". The write to ahappens before the receive on c, which happens beforethe corresponding send on c completes, which happensbefore the print.

If the channel were buffered (e.g., c = make(chan int, 1))then the program would not be guaranteed to print"hello, world". (It might print the empty string,crash, or do something else.)

Locks

The sync package implements two lock data types,sync.Mutex and sync.RWMutex.

For any sync.Mutex or sync.RWMutex variable l and n < m,call n of l.Unlock() happens before call m of l.Lock() returns.

This program:

var l sync.Mutex
var a string

func f() {
	a = "hello, world"
	l.Unlock()
}

func main() {
	l.Lock()
	go f()
	l.Lock()
	print(a)
}

is guaranteed to print "hello, world".The first call to l.Unlock() (in f) happensbefore the second call to l.Lock() (in main) returns,which happens before the print.

For any call to l.RLock on a sync.RWMutex variable l,there is an n such that the l.RLock happens (returns) after call n tol.Unlock and the matching l.RUnlock happensbefore call n+1 to l.Lock.

Once

The sync package provides a safe mechanism forinitialization in the presence of multiple goroutinesthrough the use of the Once type.Multiple threads can execute once.Do(f) for a particular f,but only one will run f(), and the other calls blockuntil f() has returned.

A single call of f() from once.Do(f) happens (returns) before any call of once.Do(f) returns.

In this program:

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()
}

calling twoprint causes "hello, world" to be printed twice.The first call to twoprint runs setup once.

Incorrect synchronization

Note that a read r may observe the value written by a write wthat happens concurrently with r.Even if this occurs, it does not imply that reads happening after rwill observe writes that happened before w.

In this program:

var a, b int

func f() {
	a = 1
	b = 2
}

func g() {
	print(b)
	print(a)
}

func main() {
	go f()
	g()
}

it can happen that g prints 2 and then 0.

This fact invalidates a few common idioms.

Double-checked locking is an attempt to avoid the overhead of synchronization.For example, the twoprint program might beincorrectly written as:

var a string
var done bool

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

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

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

but there is no guarantee that, in doprint, observing the write to doneimplies observing the write to a. Thisversion can (incorrectly) print an empty stringinstead of "hello, world".

Another incorrect idiom is busy waiting for a value, as in:

var a string
var done bool

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

func main() {
	go setup()
	for !done {
	}
	print(a)
}

As before, there is no guarantee that, in main,observing the write to doneimplies observing the write to a, so this program couldprint an empty string too.Worse, there is no guarantee that the write to done will everbe observed by main, since there are no synchronizationevents between the two threads. The loop in main is notguaranteed to finish.

There are subtler variants on this theme, such as this program.

type T struct {
	msg string
}

var g *T

func setup() {
	t := new(T)
	t.msg = "hello, world"
	g = t
}

func main() {
	go setup()
	for g == nil {
	}
	print(g.msg)
}

Even if main observes g != nil and exits its loop,there is no guarantee that it will observe the initializedvalue for g.msg.

In all these examples, the solution is the same:use explicit synchronization.