code review 75130045: doc: allow buffered channel as semaphore without initia...

doc/effective_go.html

 <!--{
         "Title": "Effective Go",
         "Template": true
 }-->
 
 <h2 id="introduction">Introduction</h2>
 
 <p>
 Go is a new language.  Although it borrows ideas from
 existing languages,
@@ skipping 2924 matching lines @@
 Receivers always block until there is data to receive.
 If the channel is unbuffered, the sender blocks until the receiver has
 received the value.
 If the channel has a buffer, the sender blocks only until the
 value has been copied to the buffer; if the buffer is full, this
 means waiting until some receiver has retrieved a value.
 </p>
 <p>
 A buffered channel can be used like a semaphore, for instance to
 limit throughput.  In this example, incoming requests are passed
-to <code>handle</code>, which receives a value from the channel, processes
-the request, and then sends a value back to the channel
-to ready the "semaphore" for the next consumer.
+to <code>handle</code>, which sends a value into the channel, processes
+the request, and then receives a value from the channel
+to ready the &ldquo;semaphore&rdquo; for the next consumer.
 The capacity of the channel buffer limits the number of
-simultaneous calls to <code>process</code>,
-so during initialization we prime the channel by filling it to capacity.
+simultaneous calls to <code>process</code>.
 </p>
 <pre>
 var sem = make(chan int, MaxOutstanding)
 
 func handle(r *Request) {
-    &lt;-sem          // Wait for active queue to drain.
-    process(r)     // May take a long time.
-    sem &lt;- 1       // Done; enable next request to run.
-}
-
-func init() {
-    for i := 0; i &lt; MaxOutstanding; i++ {
-        sem &lt;- 1
-    }
+    sem &lt;- 1    // Wait for active queue to drain.
+    process(r)  // May take a long time.
+    &lt;-sem       // Done; enable next request to run.
 }
 
 func Serve(queue chan *Request) {
     for {
         req := &lt;-queue
         go handle(req)  // Don't wait for handle to finish.
     }
 }
 </pre>
 
 <p>
-Because data synchronization occurs on a receive from a channel
-(that is, the send "happens before" the receive; see
-<a href="/ref/mem">The Go Memory Model</a>),
-acquisition of the semaphore must be on a channel receive, not a send.
+Once <code>MaxOutstanding</code> handlers are executing <code>process</code>,
+any more will block trying to send into the filled channel buffer,
+until one of the existing handlers finishes and receives from the buffer.
 </p>
 
 <p>
 This design has a problem, though: <code>Serve</code>
 creates a new goroutine for
 every incoming request, even though only <code>MaxOutstanding</code>
 of them can run at any moment.
 As a result, the program can consume unlimited resources if the requests come in too fast.
 We can address that deficiency by changing <code>Serve</code> to
 gate the creation of the goroutines.
 Here's an obvious solution, but beware it has a bug we'll fix subsequently:
 </p>
 
 <pre>
 func Serve(queue chan *Request) {
     for req := range queue {
-        &lt;-sem
+        sem &lt;- 1
         go func() {
             process(req) // Buggy; see explanation below.
-            sem &lt;- 1
+            &lt;-sem
         }()
     }
 }</pre>
 
 <p>
 The bug is that in a Go <code>for</code> loop, the loop variable
 is reused for each iteration, so the <code>req</code>
 variable is shared across all goroutines.
 That's not what we want.
 We need to make sure that <code>req</code> is unique for each goroutine.
 Here's one way to do that, passing the value of <code>req</code> as an argument
 to the closure in the goroutine:
 </p>
 
 <pre>
 func Serve(queue chan *Request) {
     for req := range queue {
-        &lt;-sem
+        sem &lt;- 1
         go func(req *Request) {
             process(req)
-            sem &lt;- 1
+            &lt;-sem
         }(req)
     }
 }</pre>
 
 <p>
 Compare this version with the previous to see the difference in how
 the closure is declared and run.
 Another solution is just to create a new variable with the same
 name, as in this example:
 </p>
 
 <pre>
 func Serve(queue chan *Request) {
     for req := range queue {
-        &lt;-sem
         req := req // Create new instance of req for the goroutine.
+        sem &lt;- 1
         go func() {
             process(req)
-            sem &lt;- 1
+            &lt;-sem
         }()
     }
 }</pre>
 
 <p>
 It may seem odd to write
 </p>
 
 <pre>
 req := req
@@ skipping 587 matching lines @@
 <pre>
 verifying implementation
 type Color uint32
 
 // Check that Color implements image.Color and image.Image
 var _ image.Color = Black
 var _ image.Image = Black
 </pre>
 -->