go_mem.html 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977
  1. <!--{
  2. "Title": "The Go Memory Model",
  3. "Subtitle": "Version of June 6, 2022",
  4. "Path": "/ref/mem"
  5. }-->
  6. <style>
  7. p.rule {
  8. font-style: italic;
  9. }
  10. </style>
  11. <h2 id="introduction">Introduction</h2>
  12. <p>
  13. The Go memory model specifies the conditions under which
  14. reads of a variable in one goroutine can be guaranteed to
  15. observe values produced by writes to the same variable in a different goroutine.
  16. </p>
  17. <h3 id="advice">Advice</h3>
  18. <p>
  19. Programs that modify data being simultaneously accessed by multiple goroutines
  20. must serialize such access.
  21. </p>
  22. <p>
  23. To serialize access, protect the data with channel operations or other synchronization primitives
  24. such as those in the <a href="/pkg/sync/"><code>sync</code></a>
  25. and <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> packages.
  26. </p>
  27. <p>
  28. If you must read the rest of this document to understand the behavior of your program,
  29. you are being too clever.
  30. </p>
  31. <p>
  32. Don't be clever.
  33. </p>
  34. <h3 id="overview">Informal Overview</h3>
  35. <p>
  36. Go approaches its memory model in much the same way as the rest of the language,
  37. aiming to keep the semantics simple, understandable, and useful.
  38. This section gives a general overview of the approach and should suffice for most programmers.
  39. The memory model is specified more formally in the next section.
  40. </p>
  41. <p>
  42. A <em>data race</em> is defined as
  43. a write to a memory location happening concurrently with another read or write to that same location,
  44. unless all the accesses involved are atomic data accesses as provided by the <code>sync/atomic</code> package.
  45. As noted already, programmers are strongly encouraged to use appropriate synchronization
  46. to avoid data races.
  47. In the absence of data races, Go programs behave as if all the goroutines
  48. were multiplexed onto a single processor.
  49. This property is sometimes referred to as DRF-SC: data-race-free programs
  50. execute in a sequentially consistent manner.
  51. </p>
  52. <p>
  53. While programmers should write Go programs without data races,
  54. there are limitations to what a Go implementation can do in response to a data race.
  55. An implementation may always react to a data race by reporting the race and terminating the program.
  56. Otherwise, each read of a single-word-sized or sub-word-sized memory location
  57. must observe a value actually written to that location (perhaps by a concurrent executing goroutine)
  58. and not yet overwritten.
  59. These implementation constraints make Go more like Java or JavaScript,
  60. in that most races have a limited number of outcomes,
  61. and less like C and C++, where the meaning of any program with a race
  62. is entirely undefined, and the compiler may do anything at all.
  63. Go's approach aims to make errant programs more reliable and easier to debug,
  64. while still insisting that races are errors and that tools can diagnose and report them.
  65. </p>
  66. <h2 id="model">Memory Model</h2>
  67. <p>
  68. The following formal definition of Go's memory model closely follows
  69. the approach presented by Hans-J. Boehm and Sarita V. Adve in
  70. “<a href="https://www.hpl.hp.com/techreports/2008/HPL-2008-56.pdf">Foundations of the C++ Concurrency Memory Model</a>”,
  71. published in PLDI 2008.
  72. The definition of data-race-free programs and the guarantee of sequential consistency
  73. for race-free programs are equivalent to the ones in that work.
  74. </p>
  75. <p>
  76. The memory model describes the requirements on program executions,
  77. which are made up of goroutine executions,
  78. which in turn are made up of memory operations.
  79. </p>
  80. <p>
  81. A <i>memory operation</i> is modeled by four details:
  82. </p>
  83. <ul>
  84. <li>its kind, indicating whether it is an ordinary data read, an ordinary data write,
  85. or a <i>synchronizing operation</i> such as an atomic data access,
  86. a mutex operation, or a channel operation,</li>
  87. <li>its location in the program,</li>
  88. <li>the memory location or variable being accessed, and</li>
  89. <li>the values read or written by the operation.</li>
  90. </ul>
  91. <p>
  92. Some memory operations are <i>read-like</i>, including read, atomic read, mutex lock, and channel receive.
  93. Other memory operations are <i>write-like</i>, including write, atomic write, mutex unlock, channel send, and channel close.
  94. Some, such as atomic compare-and-swap, are both read-like and write-like.
  95. </p>
  96. <p>
  97. A <i>goroutine execution</i> is modeled as a set of memory operations executed by a single goroutine.
  98. </p>
  99. <p>
  100. <b>Requirement 1</b>:
  101. The memory operations in each goroutine must correspond to a correct sequential execution of that goroutine,
  102. given the values read from and written to memory.
  103. That execution must be consistent with the <i>sequenced before</i> relation,
  104. defined as the partial order requirements set out by the <a href="/ref/spec">Go language specification</a>
  105. for Go's control flow constructs as well as the <a href="/ref/spec#Order_of_evaluation">order of evaluation for expressions</a>.
  106. </p>
  107. <p>
  108. A Go <i>program execution</i> is modeled as a set of goroutine executions,
  109. together with a mapping <i>W</i> that specifies the write-like operation that each read-like operation reads from.
  110. (Multiple executions of the same program can have different program executions.)
  111. </p>
  112. <p>
  113. <b>Requirement 2</b>:
  114. For a given program execution, the mapping <i>W</i>, when limited to synchronizing operations,
  115. must be explainable by some implicit total order of the synchronizing operations
  116. that is consistent with sequencing and the values read and written by those operations.
  117. </p>
  118. <p>
  119. The <i>synchronized before</i> relation is a partial order on synchronizing memory operations,
  120. derived from <i>W</i>.
  121. If a synchronizing read-like memory operation <i>r</i>
  122. observes a synchronizing write-like memory operation <i>w</i>
  123. (that is, if <i>W</i>(<i>r</i>) = <i>w</i>),
  124. then <i>w</i> is synchronized before <i>r</i>.
  125. Informally, the synchronized before relation is a subset of the implied total order
  126. mentioned in the previous paragraph,
  127. limited to the information that <i>W</i> directly observes.
  128. </p>
  129. <p>
  130. The <i>happens before</i> relation is defined as the transitive closure of the
  131. union of the sequenced before and synchronized before relations.
  132. </p>
  133. <p>
  134. <b>Requirement 3</b>:
  135. For an ordinary (non-synchronizing) data read <i>r</i> on a memory location <i>x</i>,
  136. <i>W</i>(<i>r</i>) must be a write <i>w</i> that is <i>visible</i> to <i>r</i>,
  137. where visible means that both of the following hold:
  138. </p>
  139. <ol>
  140. <li><i>w</i> happens before <i>r</i>.</li>
  141. <li><i>w</i> does not happen before any other write <i>w'</i> (to <i>x</i>) that happens before <i>r</i>.</li>
  142. </ol>
  143. <p>
  144. A <i>read-write data race</i> on memory location <i>x</i>
  145. consists of a read-like memory operation <i>r</i> on <i>x</i>
  146. and a write-like memory operation <i>w</i> on <i>x</i>,
  147. at least one of which is non-synchronizing,
  148. which are unordered by happens before
  149. (that is, neither <i>r</i> happens before <i>w</i>
  150. nor <i>w</i> happens before <i>r</i>).
  151. </p>
  152. <p>
  153. A <i>write-write data race</i> on memory location <i>x</i>
  154. consists of two write-like memory operations <i>w</i> and <i>w'</i> on <i>x</i>,
  155. at least one of which is non-synchronizing,
  156. which are unordered by happens before.
  157. </p>
  158. <p>
  159. Note that if there are no read-write or write-write data races on memory location <i>x</i>,
  160. then any read <i>r</i> on <i>x</i> has only one possible <i>W</i>(<i>r</i>):
  161. the single <i>w</i> that immediately precedes it in the happens before order.
  162. </p>
  163. <p>
  164. More generally, it can be shown that any Go program that is data-race-free,
  165. meaning it has no program executions with read-write or write-write data races,
  166. can only have outcomes explained by some sequentially consistent interleaving
  167. of the goroutine executions.
  168. (The proof is the same as Section 7 of Boehm and Adve's paper cited above.)
  169. This property is called DRF-SC.
  170. </p>
  171. <p>
  172. The intent of the formal definition is to match
  173. the DRF-SC guarantee provided to race-free programs
  174. by other languages, including C, C++, Java, JavaScript, Rust, and Swift.
  175. </p>
  176. <p>
  177. Certain Go language operations such as goroutine creation and memory allocation
  178. act as synchronization operations.
  179. The effect of these operations on the synchronized-before partial order
  180. is documented in the “Synchronization” section below.
  181. Individual packages are responsible for providing similar documentation
  182. for their own operations.
  183. </p>
  184. <h2 id="restrictions">Implementation Restrictions for Programs Containing Data Races</h2>
  185. <p>
  186. The preceding section gave a formal definition of data-race-free program execution.
  187. This section informally describes the semantics that implementations must provide
  188. for programs that do contain races.
  189. </p>
  190. <p>
  191. Any implementation can, upon detecting a data race,
  192. report the race and halt execution of the program.
  193. Implementations using ThreadSanitizer
  194. (accessed with “<code>go</code> <code>build</code> <code>-race</code>”)
  195. do exactly this.
  196. </p>
  197. <p>
  198. A read of an array, struct, or complex number
  199. may by implemented as a read of each individual sub-value
  200. (array element, struct field, or real/imaginary component),
  201. in any order.
  202. Similarly, a write of an array, struct, or complex number
  203. may be implemented as a write of each individual sub-value,
  204. in any order.
  205. </p>
  206. <p>
  207. A read <i>r</i> of a memory location <i>x</i>
  208. holding a value
  209. that is not larger than a machine word must observe
  210. some write <i>w</i> such that <i>r</i> does not happen before <i>w</i>
  211. and there is no write <i>w'</i> such that <i>w</i> happens before <i>w'</i>
  212. and <i>w'</i> happens before <i>r</i>.
  213. That is, each read must observe a value written by a preceding or concurrent write.
  214. </p>
  215. <p>
  216. Additionally, observation of acausal and “out of thin air” writes is disallowed.
  217. </p>
  218. <p>
  219. Reads of memory locations larger than a single machine word
  220. are encouraged but not required to meet the same semantics
  221. as word-sized memory locations,
  222. observing a single allowed write <i>w</i>.
  223. For performance reasons,
  224. implementations may instead treat larger operations
  225. as a set of individual machine-word-sized operations
  226. in an unspecified order.
  227. This means that races on multiword data structures
  228. can lead to inconsistent values not corresponding to a single write.
  229. When the values depend on the consistency
  230. of internal (pointer, length) or (pointer, type) pairs,
  231. as can be the case for interface values, maps,
  232. slices, and strings in most Go implementations,
  233. such races can in turn lead to arbitrary memory corruption.
  234. </p>
  235. <p>
  236. Examples of incorrect synchronization are given in the
  237. “Incorrect synchronization” section below.
  238. </p>
  239. <p>
  240. Examples of the limitations on implementations are given in the
  241. “Incorrect compilation” section below.
  242. </p>
  243. <h2 id="synchronization">Synchronization</h2>
  244. <h3 id="init">Initialization</h3>
  245. <p>
  246. Program initialization runs in a single goroutine,
  247. but that goroutine may create other goroutines,
  248. which run concurrently.
  249. </p>
  250. <p class="rule">
  251. If a package <code>p</code> imports package <code>q</code>, the completion of
  252. <code>q</code>'s <code>init</code> functions happens before the start of any of <code>p</code>'s.
  253. </p>
  254. <p class="rule">
  255. The completion of all <code>init</code> functions is synchronized before
  256. the start of the function <code>main.main</code>.
  257. </p>
  258. <h3 id="go">Goroutine creation</h3>
  259. <p class="rule">
  260. The <code>go</code> statement that starts a new goroutine
  261. is synchronized before the start of the goroutine's execution.
  262. </p>
  263. <p>
  264. For example, in this program:
  265. </p>
  266. <pre>
  267. var a string
  268. func f() {
  269. print(a)
  270. }
  271. func hello() {
  272. a = "hello, world"
  273. go f()
  274. }
  275. </pre>
  276. <p>
  277. calling <code>hello</code> will print <code>"hello, world"</code>
  278. at some point in the future (perhaps after <code>hello</code> has returned).
  279. </p>
  280. <h3 id="goexit">Goroutine destruction</h3>
  281. <p>
  282. The exit of a goroutine is not guaranteed to be synchronized before
  283. any event in the program.
  284. For example, in this program:
  285. </p>
  286. <pre>
  287. var a string
  288. func hello() {
  289. go func() { a = "hello" }()
  290. print(a)
  291. }
  292. </pre>
  293. <p>
  294. the assignment to <code>a</code> is not followed by
  295. any synchronization event, so it is not guaranteed to be
  296. observed by any other goroutine.
  297. In fact, an aggressive compiler might delete the entire <code>go</code> statement.
  298. </p>
  299. <p>
  300. If the effects of a goroutine must be observed by another goroutine,
  301. use a synchronization mechanism such as a lock or channel
  302. communication to establish a relative ordering.
  303. </p>
  304. <h3 id="chan">Channel communication</h3>
  305. <p>
  306. Channel communication is the main method of synchronization
  307. between goroutines. Each send on a particular channel
  308. is matched to a corresponding receive from that channel,
  309. usually in a different goroutine.
  310. </p>
  311. <p class="rule">
  312. A send on a channel is synchronized before the completion of the
  313. corresponding receive from that channel.
  314. </p>
  315. <p>
  316. This program:
  317. </p>
  318. <pre>
  319. var c = make(chan int, 10)
  320. var a string
  321. func f() {
  322. a = "hello, world"
  323. c &lt;- 0
  324. }
  325. func main() {
  326. go f()
  327. &lt;-c
  328. print(a)
  329. }
  330. </pre>
  331. <p>
  332. is guaranteed to print <code>"hello, world"</code>. The write to <code>a</code>
  333. is sequenced before the send on <code>c</code>, which is synchronized before
  334. the corresponding receive on <code>c</code> completes, which is sequenced before
  335. the <code>print</code>.
  336. </p>
  337. <p class="rule">
  338. The closing of a channel is synchronized before a receive that returns a zero value
  339. because the channel is closed.
  340. </p>
  341. <p>
  342. In the previous example, replacing
  343. <code>c &lt;- 0</code> with <code>close(c)</code>
  344. yields a program with the same guaranteed behavior.
  345. </p>
  346. <p class="rule">
  347. A receive from an unbuffered channel is synchronized before the completion of
  348. the corresponding send on that channel.
  349. </p>
  350. <p>
  351. This program (as above, but with the send and receive statements swapped and
  352. using an unbuffered channel):
  353. </p>
  354. <pre>
  355. var c = make(chan int)
  356. var a string
  357. func f() {
  358. a = "hello, world"
  359. &lt;-c
  360. }
  361. func main() {
  362. go f()
  363. c &lt;- 0
  364. print(a)
  365. }
  366. </pre>
  367. <p>
  368. is also guaranteed to print <code>"hello, world"</code>. The write to <code>a</code>
  369. is sequenced before the receive on <code>c</code>, which is synchronized before
  370. the corresponding send on <code>c</code> completes, which is sequenced
  371. before the <code>print</code>.
  372. </p>
  373. <p>
  374. If the channel were buffered (e.g., <code>c = make(chan int, 1)</code>)
  375. then the program would not be guaranteed to print
  376. <code>"hello, world"</code>. (It might print the empty string,
  377. crash, or do something else.)
  378. </p>
  379. <p class="rule">
  380. The <i>k</i>th receive on a channel with capacity <i>C</i> is synchronized before the completion of the <i>k</i>+<i>C</i>th send from that channel completes.
  381. </p>
  382. <p>
  383. This rule generalizes the previous rule to buffered channels.
  384. It allows a counting semaphore to be modeled by a buffered channel:
  385. the number of items in the channel corresponds to the number of active uses,
  386. the capacity of the channel corresponds to the maximum number of simultaneous uses,
  387. sending an item acquires the semaphore, and receiving an item releases
  388. the semaphore.
  389. This is a common idiom for limiting concurrency.
  390. </p>
  391. <p>
  392. This program starts a goroutine for every entry in the work list, but the
  393. goroutines coordinate using the <code>limit</code> channel to ensure
  394. that at most three are running work functions at a time.
  395. </p>
  396. <pre>
  397. var limit = make(chan int, 3)
  398. func main() {
  399. for _, w := range work {
  400. go func(w func()) {
  401. limit &lt;- 1
  402. w()
  403. &lt;-limit
  404. }(w)
  405. }
  406. select{}
  407. }
  408. </pre>
  409. <h3 id="locks">Locks</h3>
  410. <p>
  411. The <code>sync</code> package implements two lock data types,
  412. <code>sync.Mutex</code> and <code>sync.RWMutex</code>.
  413. </p>
  414. <p class="rule">
  415. For any <code>sync.Mutex</code> or <code>sync.RWMutex</code> variable <code>l</code> and <i>n</i> &lt; <i>m</i>,
  416. call <i>n</i> of <code>l.Unlock()</code> is synchronized before call <i>m</i> of <code>l.Lock()</code> returns.
  417. </p>
  418. <p>
  419. This program:
  420. </p>
  421. <pre>
  422. var l sync.Mutex
  423. var a string
  424. func f() {
  425. a = "hello, world"
  426. l.Unlock()
  427. }
  428. func main() {
  429. l.Lock()
  430. go f()
  431. l.Lock()
  432. print(a)
  433. }
  434. </pre>
  435. <p>
  436. is guaranteed to print <code>"hello, world"</code>.
  437. The first call to <code>l.Unlock()</code> (in <code>f</code>) is synchronized
  438. before the second call to <code>l.Lock()</code> (in <code>main</code>) returns,
  439. which is sequenced before the <code>print</code>.
  440. </p>
  441. <p class="rule">
  442. For any call to <code>l.RLock</code> on a <code>sync.RWMutex</code> variable <code>l</code>,
  443. there is an <i>n</i> such that the <i>n</i>th call to <code>l.Unlock</code>
  444. is synchronized before the return from <code>l.RLock</code>,
  445. and the matching call to <code>l.RUnlock</code> is synchronized before the return from call <i>n</i>+1 to <code>l.Lock</code>.
  446. </p>
  447. <p class="rule">
  448. A successful call to <code>l.TryLock</code> (or <code>l.TryRLock</code>)
  449. is equivalent to a call to <code>l.Lock</code> (or <code>l.RLock</code>).
  450. An unsuccessful call has no synchronizing effect at all.
  451. As far as the memory model is concerned,
  452. <code>l.TryLock</code> (or <code>l.TryRLock</code>)
  453. may be considered to be able to return false
  454. even when the mutex <i>l</i> is unlocked.
  455. </p>
  456. <h3 id="once">Once</h3>
  457. <p>
  458. The <code>sync</code> package provides a safe mechanism for
  459. initialization in the presence of multiple goroutines
  460. through the use of the <code>Once</code> type.
  461. Multiple threads can execute <code>once.Do(f)</code> for a particular <code>f</code>,
  462. but only one will run <code>f()</code>, and the other calls block
  463. until <code>f()</code> has returned.
  464. </p>
  465. <p class="rule">
  466. The completion of a single call of <code>f()</code> from <code>once.Do(f)</code>
  467. is synchronized before the return of any call of <code>once.Do(f)</code>.
  468. </p>
  469. <p>
  470. In this program:
  471. </p>
  472. <pre>
  473. var a string
  474. var once sync.Once
  475. func setup() {
  476. a = "hello, world"
  477. }
  478. func doprint() {
  479. once.Do(setup)
  480. print(a)
  481. }
  482. func twoprint() {
  483. go doprint()
  484. go doprint()
  485. }
  486. </pre>
  487. <p>
  488. calling <code>twoprint</code> will call <code>setup</code> exactly
  489. once.
  490. The <code>setup</code> function will complete before either call
  491. of <code>print</code>.
  492. The result will be that <code>"hello, world"</code> will be printed
  493. twice.
  494. </p>
  495. <h3 id="atomic">Atomic Values</h3>
  496. <p>
  497. The APIs in the <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a>
  498. package are collectively “atomic operations”
  499. that can be used to synchronize the execution of different goroutines.
  500. If the effect of an atomic operation <i>A</i> is observed by atomic operation <i>B</i>,
  501. then <i>A</i> is synchronized before <i>B</i>.
  502. All the atomic operations executed in a program behave as though executed
  503. in some sequentially consistent order.
  504. </p>
  505. <p>
  506. The preceding definition has the same semantics as C++’s sequentially consistent atomics
  507. and Java’s <code>volatile</code> variables.
  508. </p>
  509. <h3 id="finalizer">Finalizers</h3>
  510. <p>
  511. The <a href="/pkg/runtime/"><code>runtime</code></a> package provides
  512. a <code>SetFinalizer</code> function that adds a finalizer to be called when
  513. a particular object is no longer reachable by the program.
  514. A call to <code>SetFinalizer(x, f)</code> is synchronized before the finalization call <code>f(x)</code>.
  515. </p>
  516. <h3 id="more">Additional Mechanisms</h3>
  517. <p>
  518. The <code>sync</code> package provides additional synchronization abstractions,
  519. including <a href="/pkg/sync/#Cond">condition variables</a>,
  520. <a href="/pkg/sync/#Map">lock-free maps</a>,
  521. <a href="/pkg/sync/#Pool">allocation pools</a>,
  522. and
  523. <a href="/pkg/sync/#WaitGroup">wait groups</a>.
  524. The documentation for each of these specifies the guarantees it
  525. makes concerning synchronization.
  526. </p>
  527. <p>
  528. Other packages that provide synchronization abstractions
  529. should document the guarantees they make too.
  530. </p>
  531. <h2 id="badsync">Incorrect synchronization</h2>
  532. <p>
  533. Programs with races are incorrect and
  534. can exhibit non-sequentially consistent executions.
  535. In particular, note that a read <i>r</i> may observe the value written by any write <i>w</i>
  536. that executes concurrently with <i>r</i>.
  537. Even if this occurs, it does not imply that reads happening after <i>r</i>
  538. will observe writes that happened before <i>w</i>.
  539. </p>
  540. <p>
  541. In this program:
  542. </p>
  543. <pre>
  544. var a, b int
  545. func f() {
  546. a = 1
  547. b = 2
  548. }
  549. func g() {
  550. print(b)
  551. print(a)
  552. }
  553. func main() {
  554. go f()
  555. g()
  556. }
  557. </pre>
  558. <p>
  559. it can happen that <code>g</code> prints <code>2</code> and then <code>0</code>.
  560. </p>
  561. <p>
  562. This fact invalidates a few common idioms.
  563. </p>
  564. <p>
  565. Double-checked locking is an attempt to avoid the overhead of synchronization.
  566. For example, the <code>twoprint</code> program might be
  567. incorrectly written as:
  568. </p>
  569. <pre>
  570. var a string
  571. var done bool
  572. func setup() {
  573. a = "hello, world"
  574. done = true
  575. }
  576. func doprint() {
  577. if !done {
  578. once.Do(setup)
  579. }
  580. print(a)
  581. }
  582. func twoprint() {
  583. go doprint()
  584. go doprint()
  585. }
  586. </pre>
  587. <p>
  588. but there is no guarantee that, in <code>doprint</code>, observing the write to <code>done</code>
  589. implies observing the write to <code>a</code>. This
  590. version can (incorrectly) print an empty string
  591. instead of <code>"hello, world"</code>.
  592. </p>
  593. <p>
  594. Another incorrect idiom is busy waiting for a value, as in:
  595. </p>
  596. <pre>
  597. var a string
  598. var done bool
  599. func setup() {
  600. a = "hello, world"
  601. done = true
  602. }
  603. func main() {
  604. go setup()
  605. for !done {
  606. }
  607. print(a)
  608. }
  609. </pre>
  610. <p>
  611. As before, there is no guarantee that, in <code>main</code>,
  612. observing the write to <code>done</code>
  613. implies observing the write to <code>a</code>, so this program could
  614. print an empty string too.
  615. Worse, there is no guarantee that the write to <code>done</code> will ever
  616. be observed by <code>main</code>, since there are no synchronization
  617. events between the two threads. The loop in <code>main</code> is not
  618. guaranteed to finish.
  619. </p>
  620. <p>
  621. There are subtler variants on this theme, such as this program.
  622. </p>
  623. <pre>
  624. type T struct {
  625. msg string
  626. }
  627. var g *T
  628. func setup() {
  629. t := new(T)
  630. t.msg = "hello, world"
  631. g = t
  632. }
  633. func main() {
  634. go setup()
  635. for g == nil {
  636. }
  637. print(g.msg)
  638. }
  639. </pre>
  640. <p>
  641. Even if <code>main</code> observes <code>g != nil</code> and exits its loop,
  642. there is no guarantee that it will observe the initialized
  643. value for <code>g.msg</code>.
  644. </p>
  645. <p>
  646. In all these examples, the solution is the same:
  647. use explicit synchronization.
  648. </p>
  649. <h2 id="badcompiler">Incorrect compilation</h2>
  650. <p>
  651. The Go memory model restricts compiler optimizations as much as it does Go programs.
  652. Some compiler optimizations that would be valid in single-threaded programs are not valid in all Go programs.
  653. In particular, a compiler must not introduce writes that do not exist in the original program,
  654. it must not allow a single read to observe multiple values,
  655. and it must not allow a single write to write multiple values.
  656. </p>
  657. <p>
  658. All the following examples assume that `*p` and `*q` refer to
  659. memory locations accessible to multiple goroutines.
  660. </p>
  661. <p>
  662. Not introducing data races into race-free programs means not moving
  663. writes out of conditional statements in which they appear.
  664. For example, a compiler must not invert the conditional in this program:
  665. </p>
  666. <pre>
  667. *p = 1
  668. if cond {
  669. *p = 2
  670. }
  671. </pre>
  672. <p>
  673. That is, the compiler must not rewrite the program into this one:
  674. </p>
  675. <pre>
  676. *p = 2
  677. if !cond {
  678. *p = 1
  679. }
  680. </pre>
  681. <p>
  682. If <code>cond</code> is false and another goroutine is reading <code>*p</code>,
  683. then in the original program, the other goroutine can only observe any prior value of <code>*p</code> and <code>1</code>.
  684. In the rewritten program, the other goroutine can observe <code>2</code>, which was previously impossible.
  685. </p>
  686. <p>
  687. Not introducing data races also means not assuming that loops terminate.
  688. For example, a compiler must in general not move the accesses to <code>*p</code> or <code>*q</code>
  689. ahead of the loop in this program:
  690. </p>
  691. <pre>
  692. n := 0
  693. for e := list; e != nil; e = e.next {
  694. n++
  695. }
  696. i := *p
  697. *q = 1
  698. </pre>
  699. <p>
  700. If <code>list</code> pointed to a cyclic list,
  701. then the original program would never access <code>*p</code> or <code>*q</code>,
  702. but the rewritten program would.
  703. (Moving `*p` ahead would be safe if the compiler can prove `*p` will not panic;
  704. moving `*q` ahead would also require the compiler proving that no other
  705. goroutine can access `*q`.)
  706. </p>
  707. <p>
  708. Not introducing data races also means not assuming that called functions
  709. always return or are free of synchronization operations.
  710. For example, a compiler must not move the accesses to <code>*p</code> or <code>*q</code>
  711. ahead of the function call in this program
  712. (at least not without direct knowledge of the precise behavior of <code>f</code>):
  713. </p>
  714. <pre>
  715. f()
  716. i := *p
  717. *q = 1
  718. </pre>
  719. <p>
  720. If the call never returned, then once again the original program
  721. would never access <code>*p</code> or <code>*q</code>, but the rewritten program would.
  722. And if the call contained synchronizing operations, then the original program
  723. could establish happens before edges preceding the accesses
  724. to <code>*p</code> and <code>*q</code>, but the rewritten program would not.
  725. </p>
  726. <p>
  727. Not allowing a single read to observe multiple values means
  728. not reloading local variables from shared memory.
  729. For example, a compiler must not discard <code>i</code> and reload it
  730. a second time from <code>*p</code> in this program:
  731. </p>
  732. <pre>
  733. i := *p
  734. if i &lt; 0 || i &gt;= len(funcs) {
  735. panic("invalid function index")
  736. }
  737. ... complex code ...
  738. // compiler must NOT reload i = *p here
  739. funcs[i]()
  740. </pre>
  741. <p>
  742. If the complex code needs many registers, a compiler for single-threaded programs
  743. could discard <code>i</code> without saving a copy and then reload
  744. <code>i = *p</code> just before
  745. <code>funcs[i]()</code>.
  746. A Go compiler must not, because the value of <code>*p</code> may have changed.
  747. (Instead, the compiler could spill <code>i</code> to the stack.)
  748. </p>
  749. <p>
  750. Not allowing a single write to write multiple values also means not using
  751. the memory where a local variable will be written as temporary storage before the write.
  752. For example, a compiler must not use <code>*p</code> as temporary storage in this program:
  753. </p>
  754. <pre>
  755. *p = i + *p/2
  756. </pre>
  757. <p>
  758. That is, it must not rewrite the program into this one:
  759. </p>
  760. <pre>
  761. *p /= 2
  762. *p += i
  763. </pre>
  764. <p>
  765. If <code>i</code> and <code>*p</code> start equal to 2,
  766. the original code does <code>*p = 3</code>,
  767. so a racing thread can read only 2 or 3 from <code>*p</code>.
  768. The rewritten code does <code>*p = 1</code> and then <code>*p = 3</code>,
  769. allowing a racing thread to read 1 as well.
  770. </p>
  771. <p>
  772. Note that all these optimizations are permitted in C/C++ compilers:
  773. a Go compiler sharing a back end with a C/C++ compiler must take care
  774. to disable optimizations that are invalid for Go.
  775. </p>
  776. <p>
  777. Note that the prohibition on introducing data races
  778. does not apply if the compiler can prove that the races
  779. do not affect correct execution on the target platform.
  780. For example, on essentially all CPUs, it is valid to rewrite
  781. </p>
  782. <pre>
  783. n := 0
  784. for i := 0; i < m; i++ {
  785. n += *shared
  786. }
  787. </pre>
  788. into:
  789. <pre>
  790. n := 0
  791. local := *shared
  792. for i := 0; i < m; i++ {
  793. n += local
  794. }
  795. </pre>
  796. <p>
  797. provided it can be proved that <code>*shared</code> will not fault on access,
  798. because the potential added read will not affect any existing concurrent reads or writes.
  799. On the other hand, the rewrite would not be valid in a source-to-source translator.
  800. </p>
  801. <h2 id="conclusion">Conclusion</h2>
  802. <p>
  803. Go programmers writing data-race-free programs can rely on
  804. sequentially consistent execution of those programs,
  805. just as in essentially all other modern programming languages.
  806. </p>
  807. <p>
  808. When it comes to programs with races,
  809. both programmers and compilers should remember the advice:
  810. don't be clever.
  811. </p>