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)
285 is also guaranteed to print <code>"hello, world"</code>. The write to <code>a</code>
286 happens before the receive on <code>c</code>, which happens before
287 the corresponding send on <code>c</code> completes, which happens
288 before the <code>print</code>.
292 If the channel were buffered (e.g., <code>c = make(chan int, 1)</code>)
293 then the program would not be guaranteed to print
294 <code>"hello, world"</code>. (It might print the empty string,
295 crash, or do something else.)
299 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.
303 This rule generalizes the previous rule to buffered channels.
304 It allows a counting semaphore to be modeled by a buffered channel:
305 the number of items in the channel corresponds to the number of active uses,
306 the capacity of the channel corresponds to the maximum number of simultaneous uses,
307 sending an item acquires the semaphore, and receiving an item releases
309 This is a common idiom for limiting concurrency.
313 This program starts a goroutine for every entry in the work list, but the
314 goroutines coordinate using the <code>limit</code> channel to ensure
315 that at most three are running work functions at a time.
319 var limit = make(chan int, 3)
322 for _, w := range work {
336 The <code>sync</code> package implements two lock data types,
337 <code>sync.Mutex</code> and <code>sync.RWMutex</code>.
341 For any <code>sync.Mutex</code> or <code>sync.RWMutex</code> variable <code>l</code> and <i>n</i> < <i>m</i>,
342 call <i>n</i> of <code>l.Unlock()</code> happens before call <i>m</i> of <code>l.Lock()</code> returns.
367 is guaranteed to print <code>"hello, world"</code>.
368 The first call to <code>l.Unlock()</code> (in <code>f</code>) happens
369 before the second call to <code>l.Lock()</code> (in <code>main</code>) returns,
370 which happens before the <code>print</code>.
374 For any call to <code>l.RLock</code> on a <code>sync.RWMutex</code> variable <code>l</code>,
375 there is an <i>n</i> such that the <code>l.RLock</code> happens (returns) after call <i>n</i> to
376 <code>l.Unlock</code> and the matching <code>l.RUnlock</code> happens
377 before call <i>n</i>+1 to <code>l.Lock</code>.
383 The <code>sync</code> package provides a safe mechanism for
384 initialization in the presence of multiple goroutines
385 through the use of the <code>Once</code> type.
386 Multiple threads can execute <code>once.Do(f)</code> for a particular <code>f</code>,
387 but only one will run <code>f()</code>, and the other calls block
388 until <code>f()</code> has returned.
392 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.
419 calling <code>twoprint</code> will call <code>setup</code> exactly
421 The <code>setup</code> function will complete before either call
422 of <code>print</code>.
423 The result will be that <code>"hello, world"</code> will be printed
427 <h2>Incorrect synchronization</h2>
430 Note that a read <span class="event">r</span> may observe the value written by a write <span class="event">w</span>
431 that happens concurrently with <span class="event">r</span>.
432 Even if this occurs, it does not imply that reads happening after <span class="event">r</span>
433 will observe writes that happened before <span class="event">w</span>.
460 it can happen that <code>g</code> prints <code>2</code> and then <code>0</code>.
464 This fact invalidates a few common idioms.
468 Double-checked locking is an attempt to avoid the overhead of synchronization.
469 For example, the <code>twoprint</code> program might be
470 incorrectly written as:
496 but there is no guarantee that, in <code>doprint</code>, observing the write to <code>done</code>
497 implies observing the write to <code>a</code>. This
498 version can (incorrectly) print an empty string
499 instead of <code>"hello, world"</code>.
503 Another incorrect idiom is busy waiting for a value, as in:
524 As before, there is no guarantee that, in <code>main</code>,
525 observing the write to <code>done</code>
526 implies observing the write to <code>a</code>, so this program could
527 print an empty string too.
528 Worse, there is no guarantee that the write to <code>done</code> will ever
529 be observed by <code>main</code>, since there are no synchronization
530 events between the two threads. The loop in <code>main</code> is not
531 guaranteed to finish.
535 There are subtler variants on this theme, such as this program.
547 t.msg = "hello, world"
560 Even if <code>main</code> observes <code>g != nil</code> and exits its loop,
561 there is no guarantee that it will observe the initialized
562 value for <code>g.msg</code>.
566 In all these examples, the solution is the same:
567 use explicit synchronization.