2 "Title": "The Go Memory Model",
3 "Subtitle": "Version of May 31, 2014",
19 The Go memory model specifies the conditions under which
20 reads of a variable in one goroutine can be guaranteed to
21 observe values produced by writes to the same variable in a different goroutine.
28 Programs that modify data being simultaneously accessed by multiple goroutines
29 must serialize such access.
33 To serialize access, protect the data with channel operations or other synchronization primitives
34 such as those in the <a href="/pkg/sync/"><code>sync</code></a>
35 and <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> packages.
39 If you must read the rest of this document to understand the behavior of your program,
40 you are being too clever.
47 <h2>Happens Before</h2>
50 Within a single goroutine, reads and writes must behave
51 as if they executed in the order specified by the program.
52 That is, compilers and processors may reorder the reads and writes
53 executed within a single goroutine only when the reordering
54 does not change the behavior within that goroutine
55 as defined by the language specification.
56 Because of this reordering, the execution order observed
57 by one goroutine may differ from the order perceived
58 by another. For example, if one goroutine
59 executes <code>a = 1; b = 2;</code>, another might observe
60 the updated value of <code>b</code> before the updated value of <code>a</code>.
64 To specify the requirements of reads and writes, we define
65 <i>happens before</i>, a partial order on the execution
66 of memory operations in a Go program. If event <span class="event">e<sub>1</sub></span> happens
67 before event <span class="event">e<sub>2</sub></span>, then we say that <span class="event">e<sub>2</sub></span> happens after <span class="event">e<sub>1</sub></span>.
68 Also, if <span class="event">e<sub>1</sub></span> does not happen before <span class="event">e<sub>2</sub></span> and does not happen
69 after <span class="event">e<sub>2</sub></span>, then we say that <span class="event">e<sub>1</sub></span> and <span class="event">e<sub>2</sub></span> happen concurrently.
73 Within a single goroutine, the happens-before order is the
74 order expressed by the program.
78 A read <span class="event">r</span> of a variable <code>v</code> is <i>allowed</i> to observe a write <span class="event">w</span> to <code>v</code>
79 if both of the following hold:
83 <li><span class="event">r</span> does not happen before <span class="event">w</span>.</li>
84 <li>There is no other write <span class="event">w'</span> to <code>v</code> that happens
85 after <span class="event">w</span> but before <span class="event">r</span>.</li>
89 To guarantee that a read <span class="event">r</span> of a variable <code>v</code> observes a
90 particular write <span class="event">w</span> to <code>v</code>, ensure that <span class="event">w</span> is the only
91 write <span class="event">r</span> is allowed to observe.
92 That is, <span class="event">r</span> is <i>guaranteed</i> to observe <span class="event">w</span> if both of the following hold:
96 <li><span class="event">w</span> happens before <span class="event">r</span>.</li>
97 <li>Any other write to the shared variable <code>v</code>
98 either happens before <span class="event">w</span> or after <span class="event">r</span>.</li>
102 This pair of conditions is stronger than the first pair;
103 it requires that there are no other writes happening
104 concurrently with <span class="event">w</span> or <span class="event">r</span>.
108 Within a single goroutine,
109 there is no concurrency, so the two definitions are equivalent:
110 a read <span class="event">r</span> observes the value written by the most recent write <span class="event">w</span> to <code>v</code>.
111 When multiple goroutines access a shared variable <code>v</code>,
112 they must use synchronization events to establish
113 happens-before conditions that ensure reads observe the
118 The initialization of variable <code>v</code> with the zero value
119 for <code>v</code>'s type behaves as a write in the memory model.
123 Reads and writes of values larger than a single machine word
124 behave as multiple machine-word-sized operations in an
128 <h2>Synchronization</h2>
130 <h3>Initialization</h3>
133 Program initialization runs in a single goroutine,
134 but that goroutine may create other goroutines,
135 which run concurrently.
139 If a package <code>p</code> imports package <code>q</code>, the completion of
140 <code>q</code>'s <code>init</code> functions happens before the start of any of <code>p</code>'s.
144 The start of the function <code>main.main</code> happens after
145 all <code>init</code> functions have finished.
148 <h3>Goroutine creation</h3>
151 The <code>go</code> statement that starts a new goroutine
152 happens before the goroutine's execution begins.
156 For example, in this program:
173 calling <code>hello</code> will print <code>"hello, world"</code>
174 at some point in the future (perhaps after <code>hello</code> has returned).
177 <h3>Goroutine destruction</h3>
180 The exit of a goroutine is not guaranteed to happen before
181 any event in the program. For example, in this program:
188 go func() { a = "hello" }()
194 the assignment to <code>a</code> is not followed by
195 any synchronization event, so it is not guaranteed to be
196 observed by any other goroutine.
197 In fact, an aggressive compiler might delete the entire <code>go</code> statement.
201 If the effects of a goroutine must be observed by another goroutine,
202 use a synchronization mechanism such as a lock or channel
203 communication to establish a relative ordering.
206 <h3>Channel communication</h3>
209 Channel communication is the main method of synchronization
210 between goroutines. Each send on a particular channel
211 is matched to a corresponding receive from that channel,
212 usually in a different goroutine.
216 A send on a channel happens before the corresponding
217 receive from that channel completes.
225 var c = make(chan int, 10)
241 is guaranteed to print <code>"hello, world"</code>. The write to <code>a</code>
242 happens before the send on <code>c</code>, which happens before
243 the corresponding receive on <code>c</code> completes, which happens before
244 the <code>print</code>.
248 The closing of a channel happens before a receive that returns a zero value
249 because the channel is closed.
253 In the previous example, replacing
254 <code>c <- 0</code> with <code>close(c)</code>
255 yields a program with the same guaranteed behavior.
259 A receive from an unbuffered channel happens before
260 the send on that channel completes.
264 This program (as above, but with the send and receive statements swapped and
265 using an unbuffered channel):
269 var c = make(chan int)
287 is also guaranteed to print <code>"hello, world"</code>. The write to <code>a</code>
288 happens before the receive on <code>c</code>, which happens before
289 the corresponding send on <code>c</code> completes, which happens
290 before the <code>print</code>.
294 If the channel were buffered (e.g., <code>c = make(chan int, 1)</code>)
295 then the program would not be guaranteed to print
296 <code>"hello, world"</code>. (It might print the empty string,
297 crash, or do something else.)
301 The <i>k</i>th receive on a channel with capacity <i>C</i> happens before the <i>k</i>+<i>C</i>th send from that channel completes.
305 This rule generalizes the previous rule to buffered channels.
306 It allows a counting semaphore to be modeled by a buffered channel:
307 the number of items in the channel corresponds to the number of active uses,
308 the capacity of the channel corresponds to the maximum number of simultaneous uses,
309 sending an item acquires the semaphore, and receiving an item releases
311 This is a common idiom for limiting concurrency.
315 This program starts a goroutine for every entry in the work list, but the
316 goroutines coordinate using the <code>limit</code> channel to ensure
317 that at most three are running work functions at a time.
321 var limit = make(chan int, 3)
324 for _, w := range work {
338 The <code>sync</code> package implements two lock data types,
339 <code>sync.Mutex</code> and <code>sync.RWMutex</code>.
343 For any <code>sync.Mutex</code> or <code>sync.RWMutex</code> variable <code>l</code> and <i>n</i> < <i>m</i>,
344 call <i>n</i> of <code>l.Unlock()</code> happens before call <i>m</i> of <code>l.Lock()</code> returns.
369 is guaranteed to print <code>"hello, world"</code>.
370 The first call to <code>l.Unlock()</code> (in <code>f</code>) happens
371 before the second call to <code>l.Lock()</code> (in <code>main</code>) returns,
372 which happens before the <code>print</code>.
376 For any call to <code>l.RLock</code> on a <code>sync.RWMutex</code> variable <code>l</code>,
377 there is an <i>n</i> such that the <code>l.RLock</code> happens (returns) after call <i>n</i> to
378 <code>l.Unlock</code> and the matching <code>l.RUnlock</code> happens
379 before call <i>n</i>+1 to <code>l.Lock</code>.
385 The <code>sync</code> package provides a safe mechanism for
386 initialization in the presence of multiple goroutines
387 through the use of the <code>Once</code> type.
388 Multiple threads can execute <code>once.Do(f)</code> for a particular <code>f</code>,
389 but only one will run <code>f()</code>, and the other calls block
390 until <code>f()</code> has returned.
394 A single call of <code>f()</code> from <code>once.Do(f)</code> happens (returns) before any call of <code>once.Do(f)</code> returns.
421 calling <code>twoprint</code> causes <code>"hello, world"</code> to be printed twice.
422 The first call to <code>doprint</code> runs <code>setup</code> once.
425 <h2>Incorrect synchronization</h2>
428 Note that a read <span class="event">r</span> may observe the value written by a write <span class="event">w</span>
429 that happens concurrently with <span class="event">r</span>.
430 Even if this occurs, it does not imply that reads happening after <span class="event">r</span>
431 will observe writes that happened before <span class="event">w</span>.
458 it can happen that <code>g</code> prints <code>2</code> and then <code>0</code>.
462 This fact invalidates a few common idioms.
466 Double-checked locking is an attempt to avoid the overhead of synchronization.
467 For example, the <code>twoprint</code> program might be
468 incorrectly written as:
494 but there is no guarantee that, in <code>doprint</code>, observing the write to <code>done</code>
495 implies observing the write to <code>a</code>. This
496 version can (incorrectly) print an empty string
497 instead of <code>"hello, world"</code>.
501 Another incorrect idiom is busy waiting for a value, as in:
522 As before, there is no guarantee that, in <code>main</code>,
523 observing the write to <code>done</code>
524 implies observing the write to <code>a</code>, so this program could
525 print an empty string too.
526 Worse, there is no guarantee that the write to <code>done</code> will ever
527 be observed by <code>main</code>, since there are no synchronization
528 events between the two threads. The loop in <code>main</code> is not
529 guaranteed to finish.
533 There are subtler variants on this theme, such as this program.
545 t.msg = "hello, world"
558 Even if <code>main</code> observes <code>g != nil</code> and exits its loop,
559 there is no guarantee that it will observe the initialized
560 value for <code>g.msg</code>.
564 In all these examples, the solution is the same:
565 use explicit synchronization.