Improve Concurrency Documentation

[brendanw]

It would be great if it were clarified in https://github.com/JetBrains/kotlin-native/blob/master/CONCURRENCY.md  that any time an object is referenced by two functions that can change the coroutine context (eg async, launch, withContext, suspending function) that the object will be frozen. It'd be helpful to drive home the point by showing an example where the coroutine is executed on a single thread but objects are still frozen.

This came up as a problem here ktorio/ktor#1537

[elizarov]

It seems to be covered in this document: https://github.com/Kotlin/kotlinx.coroutines/blob/native-mt/kotlin-native-sharing.md

[brendanw]

   private val dispatcher = newSingleThreadContext("WorkerCoroutineDispatcherTest")

   @Test
   fun flowCollector() {
      runBlocking {
         var x = 0
         print("isMainThread: ${isMainThread()}") //prints isMainThread: true
         flow {
            emit(0)
         }.flowOn(dispatcher)
            .collect {
               print("isMainThread: ${isMainThread()}") //prints isMainThread: true
               assert(x.isFrozen == true)
            }
      }
   }

This is an example that I found tricky when I opened this issue and even still now. If x is referenced only on the same thread, then I would think it does not need to be frozen.

I am guessing that the documentation covers this with this line "However, when flowOn operator is used to change the thread, then objects crossing the thread boundary get frozen". I read "objects crossing thread boundary" as meaning an object is emitted on one thread and collected on a different thread.

[elizarov]

@brendanw But here you clearly capture x into the collect { ... } lambda that gets executed on another thread.