From: Changkun Ou <hi@changkun.us>
Date: Sun, 16 Feb 2020 00:11:53 +0000 (+0100)
Subject: doc: race condition in unsynchronized send/close
X-Git-Tag: go1.15beta1~975
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=acac535c3ca571beeb168c953d6d672f61387ef1;p=gostls13.git

doc: race condition in unsynchronized send/close

This CL documents that unsynchronized send and close operations
on a channel are detected as a race condition.

Fixes #27769

Change-Id: I7495a2d0dd834c3f3b6339f8ca18ea21ae979aa8
Reviewed-on: https://go-review.googlesource.com/c/go/+/219637
Reviewed-by: Rob Pike <r@golang.org>
---

diff --git a/doc/articles/race_detector.html b/doc/articles/race_detector.html
index 014411d948..63a658f870 100644
--- a/doc/articles/race_detector.html
+++ b/doc/articles/race_detector.html
@@ -379,6 +379,38 @@ func (w *Watchdog) Start() {
 }
 </pre>
 
+<h3 id="Unsynchronized_send_and_close_operations">Unsynchronized send and close operations</h3>
+
+<p>
+As this example demonstrates, unsynchronized send and close operations
+on the same channel can also be a race condition:
+</p>
+
+<pre>
+c := make(chan struct{}) // or buffered channel
+
+// The race detector cannot derive the happens before relation
+// for the following send and close operations. These two operations
+// are unsynchronized and happen concurrently.
+go func() { c <- struct{}{} }()
+close(c)
+</pre>
+
+<p>
+According to the Go memory model, a send on a channel happens before
+the corresponding receive from that channel completes. To synchronize
+send and close operations, use a receive operation that guarantees
+the send is done before the close:
+</p>
+
+<pre>
+c := make(chan struct{}) // or buffered channel
+
+go func() { c <- struct{}{} }()
+<-c
+close(c)
+</pre>
+
 <h2 id="Supported_Systems">Supported Systems</h2>
 
 <p>