Throw if using Dispatchers.Default or Dispatchers.IO

Author: nsk90

kstatemachine-coroutines/src/commonMain/kotlin/ru/nsk/kstatemachine/statemachine/CoroutinesStateMachine.kt

@@ -15,6 +15,7 @@ import ru.nsk.kstatemachine.state.ChildMode
 import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
+import kotlin.coroutines.ContinuationInterceptor
 import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.EmptyCoroutineContext
 
@@ -42,10 +43,31 @@ suspend fun createStateMachine(
     contract {
         callsInPlace(init, InvocationKind.EXACTLY_ONCE)
     }
+    checkCoroutineScopeValidity(scope, creationArguments)
     return CoroutinesLibCoroutineAbstraction(scope)
         .createStateMachine(name, childMode, start, creationArguments, init)
 }
 
+private fun checkCoroutineScopeValidity(scope: CoroutineScope, creationArguments: CreationArguments) {
+    if (creationArguments.skipCoroutineScopeValidityCheck) return
+
+    val dispatcher = scope.coroutineContext[ContinuationInterceptor]
+    val dispatcherName = dispatcher.toString()
+    if (dispatcher === Dispatchers.Default ||
+        dispatcherName == "Dispatchers.Default" ||
+        dispatcherName.startsWith("Dispatchers.Default.limitedParallelism") ||
+        dispatcherName == "Dispatchers.IO" || // can't get IO dispatcher in commonMain
+        dispatcherName.startsWith("Dispatchers.IO.limitedParallelism")
+    ) {
+        error(
+            "Using Dispatchers.Default or Dispatchers.IO for StateMachine even with limitedParallelism(1) is the most likely an error," +
+                    " as it is multi-threaded, see the docs: \n" +
+                    "https://kstatemachine.github.io/kstatemachine/pages/multithreading.html#use-single-threaded-coroutinescope" +
+            "You can opt-out this check by CreationArguments::skipCoroutineScopeValidityCheck flag."
+        )
+    }
+}
+
 /**
  * Processes event in async fashion (using launch() to start new coroutine).
  *

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/statemachine/CreationArguments.kt

@@ -48,6 +48,15 @@ interface CreationArguments {
      * Default: null
      */
     val eventRecordingArguments: EventRecordingArguments?
+
+    /**
+     * The library checks if you are trying to use multithreaded Dispatcher like
+     * Dispatchers.Default or Dispatcher.IO which is usually an error.
+     * @see [https://kstatemachine.github.io/kstatemachine/pages/multithreading.html#use-single-threaded-coroutinescope]
+     * You can skip this validation setting the flag to true.
+     * Default: false
+     */
+    val skipCoroutineScopeValidityCheck: Boolean
 }
 
 interface CreationArgumentsBuilder : CreationArguments {
@@ -56,14 +65,16 @@ interface CreationArgumentsBuilder : CreationArguments {
     override var doNotThrowOnMultipleTransitionsMatch: Boolean
     override var requireNonBlankNames: Boolean
     override var eventRecordingArguments: EventRecordingArguments?
+    override var skipCoroutineScopeValidityCheck: Boolean
 }
 
 private data class CreationArgumentsBuilderImpl(
     override var autoDestroyOnStatesReuse: Boolean = true,
     override var isUndoEnabled: Boolean = false,
     override var doNotThrowOnMultipleTransitionsMatch: Boolean = false,
     override var requireNonBlankNames: Boolean = false,
-    override var eventRecordingArguments: EventRecordingArguments? = null
+    override var eventRecordingArguments: EventRecordingArguments? = null,
+    override var skipCoroutineScopeValidityCheck: Boolean = false,
 ) : CreationArgumentsBuilder
 
 @OptIn(ExperimentalContracts::class)

tests/src/commonTest/kotlin/ru/nsk/kstatemachine/TestUtils.kt

@@ -79,7 +79,6 @@ enum class CoroutineStarterType {
      * but it should be ok as it happens sequentially.
      */
     COROUTINES_LIB_SINGLE_THREAD_DISPATCHER,
-    COROUTINES_LIB_DEFAULT_LIMITED_DISPATCHER,
 }
 
 @OptIn(ExperimentalCoroutinesApi::class)
@@ -132,13 +131,5 @@ suspend fun createTestStateMachine(
             creationArguments,
             init = init
         )
-        CoroutineStarterType.COROUTINES_LIB_DEFAULT_LIMITED_DISPATCHER -> createStateMachine(
-            CoroutineScope(Dispatchers.Default.limitedParallelism(1)), // does not guarantee same thread for each task
-            name,
-            childMode,
-            start,
-            creationArguments,
-            init = init
-        )
     }
 }

tests/src/commonTest/kotlin/ru/nsk/kstatemachine/statemachine/StateMachineTest.kt

@@ -19,6 +19,9 @@ import io.kotest.matchers.string.shouldEndWith
 import io.mockk.called
 import io.mockk.verify
 import io.mockk.verifySequence
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.cancel
 import ru.nsk.kstatemachine.*
 import ru.nsk.kstatemachine.event.Event
 import ru.nsk.kstatemachine.event.EventMatcher
@@ -35,6 +38,36 @@ private object StateMachineTestData {
 }
 
 class StateMachineTest : FreeSpec({
+    withData(
+        nameFn = { "dispatcher: $it" },
+        CoroutineScope(Dispatchers.Default),
+        CoroutineScope(Dispatchers.Default.limitedParallelism(1)),
+        CoroutineScope(Dispatchers.IO),
+        CoroutineScope(Dispatchers.IO.limitedParallelism(1)),
+    ) { scope ->
+        "scope validation" {
+            try {
+                createStateMachine(
+                    scope,
+                    creationArguments = buildCreationArguments { skipCoroutineScopeValidityCheck = true }
+                ) {
+                    initialState("initial")
+                }
+
+                shouldThrowWithMessage<IllegalStateException>(
+                    "Using Dispatchers.Default or Dispatchers.IO for StateMachine even with limitedParallelism(1) is the most likely an error, as it is multi-threaded, see the docs: \n" +
+                            "https://kstatemachine.github.io/kstatemachine/pages/multithreading.html#use-single-threaded-coroutinescopeYou can opt-out this check by CreationArguments::skipCoroutineScopeValidityCheck flag."
+                ) {
+                    createStateMachine(scope) {
+                        initialState("initial")
+                    }
+                }
+            } finally {
+                scope.cancel()
+            }
+        }
+    }
+
     CoroutineStarterType.entries.forEach { coroutineStarterType ->
         "$coroutineStarterType" - {
             "no initial state" {