Add coroutine tests and update docs

Author: nsk90

docs/index.md

@@ -707,8 +707,15 @@ Note that `Blocking` versions internally use `kotlinx.coroutines.runBlocking` fu
 may cause deadlocks if used not properly. That is why you should avoid using `Blocking` APIs from coroutines and
 recursively (from library callbacks).
 
-Such suspendable functions preserve state machines coroutine context (using `kotlinx.coroutines.withContext`),
-so it should be ok to call them from any thread.
+When you create a state machine with `createStateMachine`/`createStateMachineBlocking` functions you have to provide 
+`CoroutineScope` on which machine will work, this scope also contains `CoroutineContext` by design. 
+This is how you can control a thread where state machine works.
+
+Suspendable functions and their `Blocking` analogs internally switch current execution coroutine context 
+(from which they are called) to state machines one using `kotlinx.coroutines.withContext` or
+`kotlinx.coroutines.runBlocking` arguments respectively.
+Note that if you created machine with a scope containing `kotlinx.coroutines.EmptyCoroutineContext` switching will not 
+be performed.
 
 ### Migration guide from versions older than v0.20.0
 

tests/src/test/kotlin/ru/nsk/kstatemachine/CoroutinesTest.kt

@@ -2,8 +2,8 @@ package ru.nsk.kstatemachine
 
 import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.core.spec.style.StringSpec
+import io.kotest.matchers.shouldBe
 import kotlinx.coroutines.*
-import java.lang.UnsupportedOperationException
 import kotlin.coroutines.EmptyCoroutineContext
 
 class CoroutinesTest : StringSpec({
@@ -50,7 +50,7 @@ class CoroutinesTest : StringSpec({
         shouldThrow<UnsupportedOperationException> {
             createStdLibStateMachine {
                 initialState()
-                onStarted { delay(1) }
+                onStarted { delay(100) }
             }
         }
     }
@@ -76,4 +76,50 @@ class CoroutinesTest : StringSpec({
             scope.cancel()
         }
     }
+
+    "test context preserving by suspend methods called from threads" test@{
+        val thread = Thread.currentThread()
+        withContext(Dispatchers.IO) {
+            println("${Thread.currentThread()}")
+            createStateMachine(this@test) {
+                onStarted { Thread.currentThread() shouldBe thread }
+                initialState()
+            }
+        }
+    }
+
+    "empty context does not preserve machine if suspend methods called from threads" {
+        val scope = CoroutineScope(EmptyCoroutineContext)
+        withContext(Dispatchers.IO) {
+            val thread = Thread.currentThread()
+            createStateMachine(scope) {
+                onStarted { Thread.currentThread() shouldBe thread }
+                initialState()
+            }
+        }
+    }
+
+    "threaded context preserving by suspend methods called from threads" {
+        val scope = CoroutineScope(Dispatchers.Default.limitedParallelism(1))
+        val thread = runBlocking(scope.coroutineContext) { Thread.currentThread() }
+
+        withContext(Dispatchers.IO) {
+            createStateMachine(scope) {
+                onStarted { Thread.currentThread() shouldBe thread }
+                initialState()
+            }
+        }
+    }
+
+    "current thread context preserving by suspend methods called from threads" {
+        runBlocking {
+            val thread = Thread.currentThread()
+            withContext(Dispatchers.IO) {
+                createStateMachine(this@runBlocking) {
+                    onStarted { Thread.currentThread()  shouldBe thread }
+                    initialState()
+                }
+            }
+        }
+    }
 })