Merge pull request #223 from eliben/addwaitgroup

Add "Waiting For Goroutines To Finish" example.

examples.txt

@@ -32,6 +32,7 @@ Range over Channels
 Timers
 Tickers
 Worker Pools
+WaitGroups
 Rate Limiting
 Atomic Counters
 Mutexes

examples/channel-synchronization/channel-synchronization.go

@@ -1,6 +1,8 @@
 // We can use channels to synchronize execution
 // across goroutines. Here's an example of using a
 // blocking receive to wait for a goroutine to finish.
+// When waiting for multiple goroutines to finish,
+// you may prefer to use a [WaitGroup](waitgroups).
 
 package main
 

examples/channel-synchronization/channel-synchronization.hash

@@ -1,2 +1,2 @@
-fe3e2ea1a67d0f95ce4cb18f3e8aa16d416de0ce
+eb022977181884c2ab0f2b69e50311769e67a509
-0DfW-1RMqi
+8lmP8beav0p

examples/waitgroups/waitgroups.go

@@ -0,0 +1,42 @@
+// To wait for multiple goroutines to finish, we can
+// use a *wait group*.
+
+package main
+
+import (
+    "fmt"
+    "sync"
+    "time"
+)
+
+// This is the function we'll run in every goroutine.
+// Note that a WaitGroup must be passed to functions by
+// pointer.
+func worker(id int, wg *sync.WaitGroup) {
+    fmt.Printf("Worker %d starting\n", id)
+
+    // Sleep to simulate an expensive task.
+    time.Sleep(time.Second)
+    fmt.Printf("Worker %d done\n", id)
+
+    // Notify the WaitGroup that this worker is done.
+    wg.Done()
+}
+
+func main() {
+
+    // This WaitGroup is used to wait for all the
+    // goroutines launched here to finish.
+    var wg sync.WaitGroup
+
+    // Launch several goroutines and increment the WaitGroup
+    // counter for each.
+    for i := 1; i <= 5; i++ {
+        wg.Add(1)
+        go worker(i, &wg)
+    }
+
+    // Block until the WaitGroup counter goes back to 0;
+    // all the workers notified they're done.
+    wg.Wait()
+}

examples/waitgroups/waitgroups.hash

@@ -0,0 +1,2 @@
+499c7ee59b2ae06d2d3171768d9cf11762121a87
+gLLmgcR7YkP

examples/waitgroups/waitgroups.sh

@@ -0,0 +1,14 @@
+$ go run waitgroups.go
+Worker 5 starting
+Worker 3 starting
+Worker 4 starting
+Worker 1 starting
+Worker 2 starting
+Worker 4 done
+Worker 1 done
+Worker 2 done
+Worker 5 done
+Worker 3 done
+
+# The order of workers starting up and finishing
+# is likely to be different for each invocation.

examples/worker-pools/worker-pools.go

@@ -42,6 +42,9 @@ func main() {
     close(jobs)
 
     // Finally we collect all the results of the work.
+    // This also ensures that the worker goroutines have
+    // finished. An alternative way to wait for multiple
+    // goroutines is to use a [WaitGroup](waitgroups).
     for a := 1; a <= 5; a++ {
         <-results
     }

examples/worker-pools/worker-pools.hash

@@ -1,2 +1,2 @@
-1f9acf1e50be05cad73e6b085ed3294892c67d42
+bc69c6602d438413dcb9ceac112299ee253e4575
-RTRcHA05vV
+yuHsGf712D1

public/channel-synchronization

@@ -27,7 +27,9 @@
           <td class="docs">
             <p>We can use channels to synchronize execution
 across goroutines. Here&rsquo;s an example of using a
-blocking receive to wait for a goroutine to finish.</p>
+blocking receive to wait for a goroutine to finish.
+When waiting for multiple goroutines to finish,
+you may prefer to use a <a href="waitgroups">WaitGroup</a>.</p>
 
           </td>
           <td class="code empty leading">
@@ -41,7 +43,7 @@ blocking receive to wait for a goroutine to finish.</p>
             
           </td>
           <td class="code leading">
-	        <a href="http://play.golang.org/p/0DfW-1RMqi"><img title="Run code" src="play.png" class="run" /></a>
+	        <a href="http://play.golang.org/p/8lmP8beav0p"><img title="Run code" src="play.png" class="run" /></a>
             <div class="highlight"><pre><span class="kn">package</span> <span class="nx">main</span>
 </pre></div>
 

public/index.html

@@ -103,6 +103,8 @@
       
         <li><a href="worker-pools">Worker Pools</a></li>
       
+        <li><a href="waitgroups">WaitGroups</a></li>
+      
         <li><a href="rate-limiting">Rate Limiting</a></li>
       
         <li><a href="atomic-counters">Atomic Counters</a></li>

public/waitgroups

@@ -0,0 +1,218 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Go by Example: WaitGroups</title>
+    <link rel=stylesheet href="site.css">
+  </head>
+  <script type="text/javascript">
+    if (window.location.host == "gobyexample.com") {
+      var _gaq = _gaq || [];
+      _gaq.push(['_setAccount', 'UA-34996217-1']);
+      _gaq.push(['_trackPageview']);
+      (function() {
+        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+      })();
+    }
+  </script>
+  <body>
+    <div class="example" id="waitgroups">
+      <h2><a href="./">Go by Example</a>: WaitGroups</h2>
+      
+      <table>
+        
+        <tr>
+          <td class="docs">
+            <p>To wait for multiple goroutines to finish, we can
+use a <em>wait group</em>.</p>
+
+          </td>
+          <td class="code empty leading">
+	        
+            
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            
+          </td>
+          <td class="code leading">
+	        <a href="http://play.golang.org/p/gLLmgcR7YkP"><img title="Run code" src="play.png" class="run" /></a>
+            <div class="highlight"><pre><span class="kn">package</span> <span class="nx">main</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            
+          </td>
+          <td class="code leading">
+	        
+            <div class="highlight"><pre><span class="kn">import</span> <span class="p">(</span>
+    <span class="s">&quot;fmt&quot;</span>
+    <span class="s">&quot;sync&quot;</span>
+    <span class="s">&quot;time&quot;</span>
+<span class="p">)</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            <p>This is the function we&rsquo;ll run in every goroutine.
+Note that a WaitGroup must be passed to functions by
+pointer.</p>
+
+          </td>
+          <td class="code leading">
+	        
+            <div class="highlight"><pre><span class="kd">func</span> <span class="nx">worker</span><span class="p">(</span><span class="nx">id</span> <span class="kt">int</span><span class="p">,</span> <span class="nx">wg</span> <span class="o">*</span><span class="nx">sync</span><span class="p">.</span><span class="nx">WaitGroup</span><span class="p">)</span> <span class="p">{</span>
+    <span class="nx">fmt</span><span class="p">.</span><span class="nx">Printf</span><span class="p">(</span><span class="s">&quot;Worker %d starting\n&quot;</span><span class="p">,</span> <span class="nx">id</span><span class="p">)</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            <p>Sleep to simulate an expensive task.</p>
+
+          </td>
+          <td class="code leading">
+	        
+            <div class="highlight"><pre>    <span class="nx">time</span><span class="p">.</span><span class="nx">Sleep</span><span class="p">(</span><span class="nx">time</span><span class="p">.</span><span class="nx">Second</span><span class="p">)</span>
+    <span class="nx">fmt</span><span class="p">.</span><span class="nx">Printf</span><span class="p">(</span><span class="s">&quot;Worker %d done\n&quot;</span><span class="p">,</span> <span class="nx">id</span><span class="p">)</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            <p>Notify the WaitGroup that this worker is done.</p>
+
+          </td>
+          <td class="code leading">
+	        
+            <div class="highlight"><pre>    <span class="nx">wg</span><span class="p">.</span><span class="nx">Done</span><span class="p">()</span>
+<span class="p">}</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            
+          </td>
+          <td class="code leading">
+	        
+            <div class="highlight"><pre><span class="kd">func</span> <span class="nx">main</span><span class="p">()</span> <span class="p">{</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            <p>This WaitGroup is used to wait for all the
+goroutines launched here to finish.</p>
+
+          </td>
+          <td class="code leading">
+	        
+            <div class="highlight"><pre>    <span class="kd">var</span> <span class="nx">wg</span> <span class="nx">sync</span><span class="p">.</span><span class="nx">WaitGroup</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            <p>Launch several goroutines and increment the WaitGroup
+counter for each.</p>
+
+          </td>
+          <td class="code leading">
+	        
+            <div class="highlight"><pre>    <span class="k">for</span> <span class="nx">i</span> <span class="o">:=</span> <span class="mi">1</span><span class="p">;</span> <span class="nx">i</span> <span class="o">&lt;=</span> <span class="mi">5</span><span class="p">;</span> <span class="nx">i</span><span class="o">++</span> <span class="p">{</span>
+        <span class="nx">wg</span><span class="p">.</span><span class="nx">Add</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
+        <span class="k">go</span> <span class="nx">worker</span><span class="p">(</span><span class="nx">i</span><span class="p">,</span> <span class="o">&amp;</span><span class="nx">wg</span><span class="p">)</span>
+    <span class="p">}</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            <p>Block until the WaitGroup counter goes back to 0;
+all the workers notified they&rsquo;re done.</p>
+
+          </td>
+          <td class="code">
+	        
+            <div class="highlight"><pre>    <span class="nx">wg</span><span class="p">.</span><span class="nx">Wait</span><span class="p">()</span>
+<span class="p">}</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+      </table>
+      
+      <table>
+        
+        <tr>
+          <td class="docs">
+            
+          </td>
+          <td class="code leading">
+	        
+            <div class="highlight"><pre><span class="gp">$</span> go run waitgroups.go
+<span class="go">Worker 5 starting</span>
+<span class="go">Worker 3 starting</span>
+<span class="go">Worker 4 starting</span>
+<span class="go">Worker 1 starting</span>
+<span class="go">Worker 2 starting</span>
+<span class="go">Worker 4 done</span>
+<span class="go">Worker 1 done</span>
+<span class="go">Worker 2 done</span>
+<span class="go">Worker 5 done</span>
+<span class="go">Worker 3 done</span>
+</pre></div>
+
+          </td>
+        </tr>
+        
+        <tr>
+          <td class="docs">
+            <p>The order of workers starting up and finishing
+is likely to be different for each invocation.</p>
+
+          </td>
+          <td class="code empty">
+	        
+            
+          </td>
+        </tr>
+        
+      </table>
+      
+      
+      <p class="next">
+        Next example: <a href="rate-limiting">Rate Limiting</a>.
+      </p>
+      
+      <p class="footer">
+        by <a href="https://markmcgranaghan.com">Mark McGranaghan</a> | <a href="https://github.com/mmcgrana/gobyexample/blob/master/examples/waitgroups">source</a> | <a href="https://github.com/mmcgrana/gobyexample#license">license</a>
+      </p>
+    </div>
+  </body>
+</html>

public/worker-pools

@@ -40,7 +40,7 @@ a <em>worker pool</em> using goroutines and channels.</p>
             
           </td>
           <td class="code leading">
-	        <a href="http://play.golang.org/p/RTRcHA05vV"><img title="Run code" src="play.png" class="run" /></a>
+	        <a href="http://play.golang.org/p/yuHsGf712D1"><img title="Run code" src="play.png" class="run" /></a>
             <div class="highlight"><pre><span class="kn">package</span> <span class="nx">main</span>
 </pre></div>
 
@@ -147,7 +147,10 @@ channel to indicate that&rsquo;s all the work we have.</p>
         
         <tr>
           <td class="docs">
-            <p>Finally we collect all the results of the work.</p>
+            <p>Finally we collect all the results of the work.
+This also ensures that the worker goroutines have
+finished. An alternative way to wait for multiple
+goroutines is to use a <a href="waitgroups">WaitGroup</a>.</p>
 
           </td>
           <td class="code">
@@ -207,7 +210,7 @@ there are 3 workers operating concurrently.</p>
       
       
       <p class="next">
-        Next example: <a href="rate-limiting">Rate Limiting</a>.
+        Next example: <a href="waitgroups">WaitGroups</a>.
       </p>
       
       <p class="footer">