"Fossies" - the Fresh Open Source Software Archive

Member "go/doc/go_mem.html" (9 Sep 2020, 13578 Bytes) of package /windows/misc/go1.14.9.windows-386.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!--{
    2     "Title": "The Go Memory Model",
    3     "Subtitle": "Version of May 31, 2014",
    4     "Path": "/ref/mem"
    5 }-->
    6 
    7 <style>
    8 p.rule {
    9   font-style: italic;
   10 }
   11 span.event {
   12   font-style: italic;
   13 }
   14 </style>
   15 
   16 <h2>Introduction</h2>
   17 
   18 <p>
   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.
   22 </p>
   23 
   24 
   25 <h2>Advice</h2>
   26 
   27 <p>
   28 Programs that modify data being simultaneously accessed by multiple goroutines
   29 must serialize such access.
   30 </p>
   31 
   32 <p>
   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.
   36 </p>
   37 
   38 <p>
   39 If you must read the rest of this document to understand the behavior of your program,
   40 you are being too clever.
   41 </p>
   42 
   43 <p>
   44 Don't be clever.
   45 </p>
   46 
   47 <h2>Happens Before</h2>
   48 
   49 <p>
   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>.
   61 </p>
   62 
   63 <p>
   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.
   70 </p>
   71 
   72 <p class="rule">
   73 Within a single goroutine, the happens-before order is the
   74 order expressed by the program.
   75 </p>
   76 
   77 <p>
   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:
   80 </p>
   81 
   82 <ol>
   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>
   86 </ol>
   87 
   88 <p>
   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:
   93 </p>
   94 
   95 <ol>
   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>
   99 </ol>
  100 
  101 <p>
  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>.
  105 </p>
  106 
  107 <p>
  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
  114 desired writes.
  115 </p>
  116 
  117 <p>
  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.
  120 </p>
  121 
  122 <p>
  123 Reads and writes of values larger than a single machine word
  124 behave as multiple machine-word-sized operations in an
  125 unspecified order.
  126 </p>
  127 
  128 <h2>Synchronization</h2>
  129 
  130 <h3>Initialization</h3>
  131 
  132 <p>
  133 Program initialization runs in a single goroutine,
  134 but that goroutine may create other goroutines,
  135 which run concurrently.
  136 </p>
  137 
  138 <p class="rule">
  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.
  141 </p>
  142 
  143 <p class="rule">
  144 The start of the function <code>main.main</code> happens after
  145 all <code>init</code> functions have finished.
  146 </p>
  147 
  148 <h3>Goroutine creation</h3>
  149 
  150 <p class="rule">
  151 The <code>go</code> statement that starts a new goroutine
  152 happens before the goroutine's execution begins.
  153 </p>
  154 
  155 <p>
  156 For example, in this program:
  157 </p>
  158 
  159 <pre>
  160 var a string
  161 
  162 func f() {
  163     print(a)
  164 }
  165 
  166 func hello() {
  167     a = "hello, world"
  168     go f()
  169 }
  170 </pre>
  171 
  172 <p>
  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).
  175 </p>
  176 
  177 <h3>Goroutine destruction</h3>
  178 
  179 <p>
  180 The exit of a goroutine is not guaranteed to happen before
  181 any event in the program.  For example, in this program:
  182 </p>
  183 
  184 <pre>
  185 var a string
  186 
  187 func hello() {
  188     go func() { a = "hello" }()
  189     print(a)
  190 }
  191 </pre>
  192 
  193 <p>
  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.
  198 </p>
  199 
  200 <p>
  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.
  204 </p>
  205 
  206 <h3>Channel communication</h3>
  207 
  208 <p>
  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.
  213 </p>
  214 
  215 <p class="rule">
  216 A send on a channel happens before the corresponding
  217 receive from that channel completes.
  218 </p>
  219 
  220 <p>
  221 This program:
  222 </p>
  223 
  224 <pre>
  225 var c = make(chan int, 10)
  226 var a string
  227 
  228 func f() {
  229     a = "hello, world"
  230     c &lt;- 0
  231 }
  232 
  233 func main() {
  234     go f()
  235     &lt;-c
  236     print(a)
  237 }
  238 </pre>
  239 
  240 <p>
  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>.
  245 </p>
  246 
  247 <p class="rule">
  248 The closing of a channel happens before a receive that returns a zero value
  249 because the channel is closed.
  250 </p>
  251 
  252 <p>
  253 In the previous example, replacing
  254 <code>c &lt;- 0</code> with <code>close(c)</code>
  255 yields a program with the same guaranteed behavior.
  256 </p>
  257 
  258 <p class="rule">
  259 A receive from an unbuffered channel happens before
  260 the send on that channel completes.
  261 </p>
  262 
  263 <p>
  264 This program (as above, but with the send and receive statements swapped and
  265 using an unbuffered channel):
  266 </p>
  267 
  268 <pre>
  269 var c = make(chan int)
  270 var a string
  271 
  272 func f() {
  273     a = "hello, world"
  274     &lt;-c
  275 }
  276 </pre>
  277 
  278 <pre>
  279 func main() {
  280     go f()
  281     c &lt;- 0
  282     print(a)
  283 }
  284 </pre>
  285 
  286 <p>
  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>.
  291 </p>
  292 
  293 <p>
  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.)
  298 </p>
  299 
  300 <p class="rule">
  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.
  302 </p>
  303 
  304 <p>
  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
  310 the semaphore.
  311 This is a common idiom for limiting concurrency.
  312 </p>
  313 
  314 <p>
  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.
  318 </p>
  319 
  320 <pre>
  321 var limit = make(chan int, 3)
  322 
  323 func main() {
  324     for _, w := range work {
  325         go func(w func()) {
  326             limit &lt;- 1
  327             w()
  328             &lt;-limit
  329         }(w)
  330     }
  331     select{}
  332 }
  333 </pre>
  334 
  335 <h3>Locks</h3>
  336 
  337 <p>
  338 The <code>sync</code> package implements two lock data types,
  339 <code>sync.Mutex</code> and <code>sync.RWMutex</code>.
  340 </p>
  341 
  342 <p class="rule">
  343 For any <code>sync.Mutex</code> or <code>sync.RWMutex</code> variable <code>l</code> and <i>n</i> &lt; <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.
  345 </p>
  346 
  347 <p>
  348 This program:
  349 </p>
  350 
  351 <pre>
  352 var l sync.Mutex
  353 var a string
  354 
  355 func f() {
  356     a = "hello, world"
  357     l.Unlock()
  358 }
  359 
  360 func main() {
  361     l.Lock()
  362     go f()
  363     l.Lock()
  364     print(a)
  365 }
  366 </pre>
  367 
  368 <p>
  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>.
  373 </p>
  374 
  375 <p class="rule">
  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>.
  380 </p>
  381 
  382 <h3>Once</h3>
  383 
  384 <p>
  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.
  391 </p>
  392 
  393 <p class="rule">
  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.
  395 </p>
  396 
  397 <p>
  398 In this program:
  399 </p>
  400 
  401 <pre>
  402 var a string
  403 var once sync.Once
  404 
  405 func setup() {
  406     a = "hello, world"
  407 }
  408 
  409 func doprint() {
  410     once.Do(setup)
  411     print(a)
  412 }
  413 
  414 func twoprint() {
  415     go doprint()
  416     go doprint()
  417 }
  418 </pre>
  419 
  420 <p>
  421 calling <code>twoprint</code> will call <code>setup</code> exactly
  422 once.
  423 The <code>setup</code> function will complete before either call
  424 of <code>print</code>.
  425 The result will be that <code>"hello, world"</code> will be printed
  426 twice.
  427 </p>
  428 
  429 <h2>Incorrect synchronization</h2>
  430 
  431 <p>
  432 Note that a read <span class="event">r</span> may observe the value written by a write <span class="event">w</span>
  433 that happens concurrently with <span class="event">r</span>.
  434 Even if this occurs, it does not imply that reads happening after <span class="event">r</span>
  435 will observe writes that happened before <span class="event">w</span>.
  436 </p>
  437 
  438 <p>
  439 In this program:
  440 </p>
  441 
  442 <pre>
  443 var a, b int
  444 
  445 func f() {
  446     a = 1
  447     b = 2
  448 }
  449 
  450 func g() {
  451     print(b)
  452     print(a)
  453 }
  454 
  455 func main() {
  456     go f()
  457     g()
  458 }
  459 </pre>
  460 
  461 <p>
  462 it can happen that <code>g</code> prints <code>2</code> and then <code>0</code>.
  463 </p>
  464 
  465 <p>
  466 This fact invalidates a few common idioms.
  467 </p>
  468 
  469 <p>
  470 Double-checked locking is an attempt to avoid the overhead of synchronization.
  471 For example, the <code>twoprint</code> program might be
  472 incorrectly written as:
  473 </p>
  474 
  475 <pre>
  476 var a string
  477 var done bool
  478 
  479 func setup() {
  480     a = "hello, world"
  481     done = true
  482 }
  483 
  484 func doprint() {
  485     if !done {
  486         once.Do(setup)
  487     }
  488     print(a)
  489 }
  490 
  491 func twoprint() {
  492     go doprint()
  493     go doprint()
  494 }
  495 </pre>
  496 
  497 <p>
  498 but there is no guarantee that, in <code>doprint</code>, observing the write to <code>done</code>
  499 implies observing the write to <code>a</code>.  This
  500 version can (incorrectly) print an empty string
  501 instead of <code>"hello, world"</code>.
  502 </p>
  503 
  504 <p>
  505 Another incorrect idiom is busy waiting for a value, as in:
  506 </p>
  507 
  508 <pre>
  509 var a string
  510 var done bool
  511 
  512 func setup() {
  513     a = "hello, world"
  514     done = true
  515 }
  516 
  517 func main() {
  518     go setup()
  519     for !done {
  520     }
  521     print(a)
  522 }
  523 </pre>
  524 
  525 <p>
  526 As before, there is no guarantee that, in <code>main</code>,
  527 observing the write to <code>done</code>
  528 implies observing the write to <code>a</code>, so this program could
  529 print an empty string too.
  530 Worse, there is no guarantee that the write to <code>done</code> will ever
  531 be observed by <code>main</code>, since there are no synchronization
  532 events between the two threads.  The loop in <code>main</code> is not
  533 guaranteed to finish.
  534 </p>
  535 
  536 <p>
  537 There are subtler variants on this theme, such as this program.
  538 </p>
  539 
  540 <pre>
  541 type T struct {
  542     msg string
  543 }
  544 
  545 var g *T
  546 
  547 func setup() {
  548     t := new(T)
  549     t.msg = "hello, world"
  550     g = t
  551 }
  552 
  553 func main() {
  554     go setup()
  555     for g == nil {
  556     }
  557     print(g.msg)
  558 }
  559 </pre>
  560 
  561 <p>
  562 Even if <code>main</code> observes <code>g != nil</code> and exits its loop,
  563 there is no guarantee that it will observe the initialized
  564 value for <code>g.msg</code>.
  565 </p>
  566 
  567 <p>
  568 In all these examples, the solution is the same:
  569 use explicit synchronization.
  570 </p>