Update "Shared mutable state and concurrency" guide with best practices

* Properly use structured concurrency in the example code.
* Also remove a special not on <= 2 core CPU, which is no longer needed
because default dispatcher has always at least two CPUs.

Fixed #1241

Author: elizarov

docs/shared-mutable-state-and-concurrency.md

@@ -8,27 +8,30 @@ package kotlinx.coroutines.guide.sync01
 import kotlinx.coroutines.*
 import kotlin.system.*    
 
-suspend fun CoroutineScope.massiveRun(action: suspend () -> Unit) {
+suspend fun massiveRun(action: suspend () -> Unit) {
     val n = 100  // number of coroutines to launch
     val k = 1000 // times an action is repeated by each coroutine
     val time = measureTimeMillis {
-        val jobs = List(n) {
-            launch {
-                repeat(k) { action() }
+        coroutineScope { // scope for coroutines 
+            repeat(n) {
+                launch {
+                    repeat(k) { action() }
+                }
             }
         }
-        jobs.forEach { it.join() }
     }
     println("Completed ${n * k} actions in $time ms")    
 }
 
+//sampleStart
 var counter = 0
 
-fun main() = runBlocking<Unit> {
-//sampleStart
-    GlobalScope.massiveRun {
-        counter++
+fun main() = runBlocking {
+    withContext(Dispatchers.Default) {
+        massiveRun {
+            counter++
+        }
     }
     println("Counter = $counter")
-//sampleEnd    
 }
+//sampleEnd    

kotlinx-coroutines-core/jvm/test/guide/example-sync-01.kt

@@ -8,26 +8,31 @@ package kotlinx.coroutines.guide.sync02
 import kotlinx.coroutines.*
 import kotlin.system.*
 
-suspend fun CoroutineScope.massiveRun(action: suspend () -> Unit) {
+suspend fun massiveRun(action: suspend () -> Unit) {
     val n = 100  // number of coroutines to launch
     val k = 1000 // times an action is repeated by each coroutine
     val time = measureTimeMillis {
-        val jobs = List(n) {
-            launch {
-                repeat(k) { action() }
+        coroutineScope { // scope for coroutines 
+            repeat(n) {
+                launch {
+                    repeat(k) { action() }
+                }
             }
         }
-        jobs.forEach { it.join() }
     }
     println("Completed ${n * k} actions in $time ms")    
 }
 
+//sampleStart
 @Volatile // in Kotlin `volatile` is an annotation 
 var counter = 0
 
-fun main() = runBlocking<Unit> {
-    GlobalScope.massiveRun {
-        counter++
+fun main() = runBlocking {
+    withContext(Dispatchers.Default) {
+        massiveRun {
+            counter++
+        }
     }
     println("Counter = $counter")
 }
+//sampleEnd    

kotlinx-coroutines-core/jvm/test/guide/example-sync-01b.kt

@@ -9,27 +9,30 @@ import kotlinx.coroutines.*
 import java.util.concurrent.atomic.*
 import kotlin.system.*
 
-suspend fun CoroutineScope.massiveRun(action: suspend () -> Unit) {
+suspend fun massiveRun(action: suspend () -> Unit) {
     val n = 100  // number of coroutines to launch
     val k = 1000 // times an action is repeated by each coroutine
     val time = measureTimeMillis {
-        val jobs = List(n) {
-            launch {
-                repeat(k) { action() }
+        coroutineScope { // scope for coroutines 
+            repeat(n) {
+                launch {
+                    repeat(k) { action() }
+                }
             }
         }
-        jobs.forEach { it.join() }
     }
     println("Completed ${n * k} actions in $time ms")    
 }
 
+//sampleStart
 var counter = AtomicInteger()
 
-fun main() = runBlocking<Unit> {
-//sampleStart
-    GlobalScope.massiveRun {
-        counter.incrementAndGet()
+fun main() = runBlocking {
+    withContext(Dispatchers.Default) {
+        massiveRun {
+            counter.incrementAndGet()
+        }
     }
-    println("Counter = ${counter.get()}")
-//sampleEnd    
+    println("Counter = $counter")
 }
+//sampleEnd    

kotlinx-coroutines-core/jvm/test/guide/example-sync-02.kt

@@ -8,30 +8,34 @@ package kotlinx.coroutines.guide.sync04
 import kotlinx.coroutines.*
 import kotlin.system.*
 
-suspend fun CoroutineScope.massiveRun(action: suspend () -> Unit) {
+suspend fun massiveRun(action: suspend () -> Unit) {
     val n = 100  // number of coroutines to launch
     val k = 1000 // times an action is repeated by each coroutine
     val time = measureTimeMillis {
-        val jobs = List(n) {
-            launch {
-                repeat(k) { action() }
+        coroutineScope { // scope for coroutines 
+            repeat(n) {
+                launch {
+                    repeat(k) { action() }
+                }
             }
         }
-        jobs.forEach { it.join() }
     }
     println("Completed ${n * k} actions in $time ms")    
 }
 
+//sampleStart
 val counterContext = newSingleThreadContext("CounterContext")
 var counter = 0
 
-fun main() = runBlocking<Unit> {
-//sampleStart
-    GlobalScope.massiveRun { // run each coroutine with DefaultDispathcer
-        withContext(counterContext) { // but confine each increment to the single-threaded context
-            counter++
+fun main() = runBlocking {
+    withContext(Dispatchers.Default) {
+        massiveRun {
+            // confine each increment to a single-threaded context
+            withContext(counterContext) {
+                counter++
+            }
         }
     }
     println("Counter = $counter")
-//sampleEnd    
 }
+//sampleEnd      

kotlinx-coroutines-core/jvm/test/guide/example-sync-03.kt

@@ -8,28 +8,32 @@ package kotlinx.coroutines.guide.sync05
 import kotlinx.coroutines.*
 import kotlin.system.*
 
-suspend fun CoroutineScope.massiveRun(action: suspend () -> Unit) {
+suspend fun massiveRun(action: suspend () -> Unit) {
     val n = 100  // number of coroutines to launch
     val k = 1000 // times an action is repeated by each coroutine
     val time = measureTimeMillis {
-        val jobs = List(n) {
-            launch {
-                repeat(k) { action() }
+        coroutineScope { // scope for coroutines 
+            repeat(n) {
+                launch {
+                    repeat(k) { action() }
+                }
             }
         }
-        jobs.forEach { it.join() }
     }
     println("Completed ${n * k} actions in $time ms")    
 }
 
+//sampleStart
 val counterContext = newSingleThreadContext("CounterContext")
 var counter = 0
 
-fun main() = runBlocking<Unit> {
-//sampleStart
-    CoroutineScope(counterContext).massiveRun { // run each coroutine in the single-threaded context
-        counter++
+fun main() = runBlocking {
+    // confine everything to a single-threaded context
+    withContext(counterContext) {
+        massiveRun {
+            counter++
+        }
     }
     println("Counter = $counter")
-//sampleEnd    
 }
+//sampleEnd     

kotlinx-coroutines-core/jvm/test/guide/example-sync-04.kt

@@ -9,30 +9,34 @@ import kotlinx.coroutines.*
 import kotlinx.coroutines.sync.*
 import kotlin.system.*
 
-suspend fun CoroutineScope.massiveRun(action: suspend () -> Unit) {
+suspend fun massiveRun(action: suspend () -> Unit) {
     val n = 100  // number of coroutines to launch
     val k = 1000 // times an action is repeated by each coroutine
     val time = measureTimeMillis {
-        val jobs = List(n) {
-            launch {
-                repeat(k) { action() }
+        coroutineScope { // scope for coroutines 
+            repeat(n) {
+                launch {
+                    repeat(k) { action() }
+                }
             }
         }
-        jobs.forEach { it.join() }
     }
     println("Completed ${n * k} actions in $time ms")    
 }
 
+//sampleStart
 val mutex = Mutex()
 var counter = 0
 
-fun main() = runBlocking<Unit> {
-//sampleStart
-    GlobalScope.massiveRun {
-        mutex.withLock {
-            counter++        
+fun main() = runBlocking {
+    withContext(Dispatchers.Default) {
+        massiveRun {
+            // protect each increment with lock
+            mutex.withLock {
+                counter++
+            }
         }
     }
     println("Counter = $counter")
-//sampleEnd    
 }
+//sampleEnd    

kotlinx-coroutines-core/jvm/test/guide/example-sync-05.kt

@@ -9,16 +9,17 @@ import kotlinx.coroutines.*
 import kotlinx.coroutines.channels.*
 import kotlin.system.*
 
-suspend fun CoroutineScope.massiveRun(action: suspend () -> Unit) {
+suspend fun massiveRun(action: suspend () -> Unit) {
     val n = 100  // number of coroutines to launch
     val k = 1000 // times an action is repeated by each coroutine
     val time = measureTimeMillis {
-        val jobs = List(n) {
-            launch {
-                repeat(k) { action() }
+        coroutineScope { // scope for coroutines 
+            repeat(n) {
+                launch {
+                    repeat(k) { action() }
+                }
             }
         }
-        jobs.forEach { it.join() }
     }
     println("Completed ${n * k} actions in $time ms")    
 }
@@ -39,16 +40,18 @@ fun CoroutineScope.counterActor() = actor<CounterMsg> {
     }
 }
 
-fun main() = runBlocking<Unit> {
 //sampleStart
+fun main() = runBlocking {
     val counter = counterActor() // create the actor
-    GlobalScope.massiveRun {
-        counter.send(IncCounter)
+    withContext(Dispatchers.Default) {
+        massiveRun {
+            counter.send(IncCounter)
+        }
     }
     // send a message to get a counter value from an actor
     val response = CompletableDeferred<Int>()
     counter.send(GetCounter(response))
     println("Counter = ${response.await()}")
     counter.close() // shutdown the actor
-//sampleEnd    
 }
+//sampleEnd    

kotlinx-coroutines-core/jvm/test/guide/example-sync-06.kt

@@ -13,14 +13,6 @@ class SharedStateGuideTest {
         )
     }
 
-    @Test
-    fun testKotlinxCoroutinesGuideSync01b() {
-        test("KotlinxCoroutinesGuideSync01b") { kotlinx.coroutines.guide.sync01b.main() }.verifyLinesStart(
-            "Completed 100000 actions in",
-            "Counter ="
-        )
-    }
-
     @Test
     fun testKotlinxCoroutinesGuideSync02() {
         test("KotlinxCoroutinesGuideSync02") { kotlinx.coroutines.guide.sync02.main() }.verifyLinesStart(