Merge pull request #91 from nsk90/multiple-targets

Allow specify multiple target states for transitions

Author: nsk90

docs/index.md

@@ -577,7 +577,8 @@ createStateMachine(scope, childMode = ChildMode.PARALLEL) {
 ```
 
 Currently, there is no way to process multiple transitions for one event by using parallel states, only one transition
-may be triggered for each event.
+may be triggered for each event. Such behaviour might be easily emulated using separated events for each
+parallel branch (region).
 
 ## Pseudo states
 

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/BaseStateImpl.kt

@@ -178,13 +178,13 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
     }
 
     override suspend fun recursiveEnterStatePath(
-        path: MutableList<InternalState>,
+        path: ListIterator<InternalState>,
         transitionParams: TransitionParams<*>
     ) {
-        if (path.isEmpty()) {
+        if (!path.hasPrevious()) {
             recursiveEnterInitialStates(transitionParams)
         } else {
-            val state = path.removeLast()
+            val state = path.previous()
             when (childMode) {
                 EXCLUSIVE -> {
                     setCurrentState(state, transitionParams)
@@ -204,6 +204,40 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
         }
     }
 
+    override suspend fun recursiveEnterStatePath(
+        pathHead: PathNode,
+        transitionParams: TransitionParams<*>
+    ) {
+        if (pathHead.children.isEmpty()) {
+            recursiveEnterInitialStates(transitionParams)
+        } else {
+            when (childMode) {
+                EXCLUSIVE -> {
+                    val exclusivePath = pathHead.children.single()
+                    val state = exclusivePath.state as InternalState
+                    setCurrentState(state, transitionParams)
+                    if (state !is StateMachine) // inner state machine manages its internal state by its own
+                        state.recursiveEnterStatePath(exclusivePath, transitionParams)
+                }
+                PARALLEL -> data.states.forEach { childState ->
+                    val paths = pathHead.children
+                    handleStateEntry(childState, transitionParams)
+                    if (childState !is StateMachine) { // inner state machine manages its internal state by its own
+                        val regionPath = paths.find { it.state === childState }
+                        if (regionPath != null) {
+                            childState.recursiveEnterStatePath(
+                                regionPath,
+                                transitionParams.repackForRegion(regionPath.requireFirstLeaf().state as IState)
+                            )
+                        } else {
+                            childState.recursiveEnterInitialStates(transitionParams)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     override suspend fun recursiveExit(transitionParams: TransitionParams<*>) {
         getCurrentStates().forEachState { it.recursiveExit(transitionParams) }
         doExit(transitionParams)
@@ -277,15 +311,38 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
             FinishedEvent(this)
     }
 
-    internal suspend fun switchToTargetState(
-        targetState: InternalState,
+    internal suspend fun switchToTargetStates(
+        targetStates: Set<InternalState>,
         fromState: InternalState,
         transitionParams: TransitionParams<*>
     ) {
-        val path = fromState.findPathFromTargetToLca(targetState)
-        if (transitionParams.transition.type == EXTERNAL)
-            path.last().internalParent?.let { path.add(it) }
-        val lca = path.removeLast()
-        lca.recursiveEnterStatePath(path, transitionParams)
+        when {
+            targetStates.isEmpty() -> return
+            targetStates.size == 1 -> {
+                @Suppress("UNCHECKED_CAST")
+                val path = fromState.findPathFromTargetToLca(
+                    targetStates.single(),
+                    transitionParams.transition.type == EXTERNAL
+                ) as List<InternalState>
+                val iterator = path.listIterator(path.size)
+                iterator.previous().recursiveEnterStatePath(iterator, transitionParams)
+            }
+            else -> {
+                val pathHead = fromState.findTreePathFromTargetsToLca(
+                    targetStates,
+                    transitionParams.transition.type == EXTERNAL
+                )
+                val state = pathHead.state as InternalState
+                state.recursiveEnterStatePath(pathHead, transitionParams)
+            }
+        }
+    }
+}
+
+private fun TransitionParams<*>.repackForRegion(regionTargetState: IState): TransitionParams<*> {
+    return if (direction.targetState === regionTargetState) {
+        this
+    } else {
+        copy(direction = TargetState(direction.targetStates, regionTargetState))
     }
 }

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/DataExtractor.kt

@@ -12,6 +12,8 @@ interface DataExtractor<D : Any> {
 }
 
 inline fun <reified D : Any> defaultDataExtractor() = object : DataExtractor<D> {
-    override suspend fun extractFinishedEvent(transitionParams: TransitionParams<*>, event: FinishedEvent) = event.data as? D
+    override suspend fun extractFinishedEvent(transitionParams: TransitionParams<*>, event: FinishedEvent) =
+        event.data as? D
+
     override suspend fun extract(transitionParams: TransitionParams<*>) = null
 }

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/InternalState.kt

@@ -2,29 +2,54 @@ package ru.nsk.kstatemachine
 
 import ru.nsk.kstatemachine.TransitionDirectionProducerPolicy.DefaultPolicy
 
+/**
+ * Contains tree composition api for [InternalState].
+ * Necessary for tree algorithms testing purpose, to be able not create full states in tests.
+ * This is safe to cast any [InternalNode] to [InternalState] by design.
+ */
+internal interface InternalNode {
+    val internalParent: InternalNode?
+}
+
+internal fun InternalNode.requireParentNode(): InternalNode =
+    requireNotNull(internalParent) { "$this parent is not set" }
+
 /**
  * Defines state API for internal library usage. All states must implement this class.
  * Unfortunately cannot use interface for this purpose.
+ * This is safe to cast any [IState] to [InternalState] by design.
  */
-abstract class InternalState : IState {
+abstract class InternalState : IState, InternalNode {
     override val parent: IState? get() = internalParent
-    internal abstract val internalParent: InternalState?
+    abstract override val internalParent: InternalState?
     internal abstract fun setParent(parent: InternalState)
 
     internal abstract fun getCurrentStates(): List<InternalState>
 
     internal abstract suspend fun doEnter(transitionParams: TransitionParams<*>)
     internal abstract suspend fun doExit(transitionParams: TransitionParams<*>)
-    internal abstract suspend fun afterChildFinished(finishedChild: InternalState, transitionParams: TransitionParams<*>)
+    internal abstract suspend fun afterChildFinished(
+        finishedChild: InternalState,
+        transitionParams: TransitionParams<*>
+    )
+
     internal open fun onParentCurrentStateChanged(currentState: InternalState) = Unit
 
     internal abstract suspend fun <E : Event> recursiveFindUniqueResolvedTransition(
         eventAndArgument: EventAndArgument<E>
     ): ResolvedTransition<E>?
 
     internal abstract suspend fun recursiveEnterInitialStates(transitionParams: TransitionParams<*>)
+
+    /** Enters single branch path */
+    internal abstract suspend fun recursiveEnterStatePath(
+        path: ListIterator<InternalState>,
+        transitionParams: TransitionParams<*>
+    )
+
+    /** Enters path with multiple branches */
     internal abstract suspend fun recursiveEnterStatePath(
-        path: MutableList<InternalState>,
+        pathHead: PathNode,
         transitionParams: TransitionParams<*>
     )
 
@@ -38,12 +63,12 @@ abstract class InternalState : IState {
     internal abstract suspend fun cleanup()
 }
 
-internal fun InternalState.requireInternalParent() = requireNotNull(internalParent) { "$this parent is not set" }
+internal fun InternalState.requireInternalParent(): InternalState =
+    requireNotNull(internalParent) { "$this parent is not set" }
 
 internal suspend fun <E : Event> InternalState.findTransitionsByEvent(event: E): List<InternalTransition<E>> {
-    val triggeringTransitions = transitions.filter { it.isMatchingEvent(event) }
     @Suppress("UNCHECKED_CAST")
-    return triggeringTransitions as List<InternalTransition<E>>
+    return transitions.filter { it.isMatchingEvent(event) } as List<InternalTransition<E>>
 }
 
 internal suspend fun <E : Event> InternalState.findUniqueResolvedTransition(eventAndArgument: EventAndArgument<E>): ResolvedTransition<E>? {

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/InternalTransition.kt

@@ -2,6 +2,7 @@ package ru.nsk.kstatemachine
 
 /**
  * Defines transition API for internal library usage. All transitions must implement this interface.
+ * This is safe to cast any [Transition] to [InternalTransition] by design.
  */
 interface InternalTransition<E : Event> : Transition<E> {
     override val sourceState: InternalState

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/StateMachineImpl.kt

@@ -232,21 +232,23 @@ internal class StateMachineImpl(
 
         val transitionParams = TransitionParams(transition, direction, event, argument)
 
-        val targetState = (direction.targetState as? InternalState)?.also {
-            check(it === this || it.isSubStateOf(this)) {
-                "Transitioning to state $it from another state machine is not possible"
+        @Suppress("UNCHECKED_CAST")
+        val targetStates = (direction.targetStates as Set<InternalState>).also { targetStates ->
+            val alienState = targetStates.find { it !== this && !it.isSubStateOf(this) }
+            check(alienState == null) {
+                "Transitioning to targetState $alienState from another state machine is not possible"
             }
         }
 
         log {
-            val targetText = if (targetState != null) "to $targetState" else "[target-less]"
-            "${event::class.simpleName} triggers $transition from ${transition.sourceState} $targetText"
+            val targetsText = if (targetStates.isNotEmpty()) "to [${targetStates.joinToString()}]" else "[target-less]"
+            "${event::class.simpleName} triggers $transition from ${transition.sourceState} $targetsText"
         }
 
         transition.transitionNotify { onTriggered(transitionParams) }
         machineNotify { onTransitionTriggered(transitionParams) }
 
-        targetState?.let { switchToTargetState(it, transition.sourceState, transitionParams) }
+        switchToTargetStates(targetStates, transition.sourceState, transitionParams)
 
         recursiveAfterTransitionComplete(transitionParams)
 

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/Transition.kt

@@ -1,5 +1,7 @@
 package ru.nsk.kstatemachine
 
+import ru.nsk.kstatemachine.TransitionType.EXTERNAL
+import ru.nsk.kstatemachine.TransitionType.LOCAL
 import ru.nsk.kstatemachine.visitors.CoVisitor
 import ru.nsk.kstatemachine.visitors.Visitor
 import ru.nsk.kstatemachine.visitors.VisitorAcceptor
@@ -50,9 +52,10 @@ interface Transition<E : Event> : VisitorAcceptor {
 
 /**
  * Most of the cases [EXTERNAL] and [LOCAL] transition are functionally equivalent except in cases where transition
- * is happening between super and sub states. Local transition doesn't cause exit and entry to source state if
+ * is happening between super and sub-states. Local transition doesn't cause exit and entry to source state if
  * target state is a sub-state of a source state.
- * Other way around, local transition doesn't cause exit and entry to target state if target is a superstate of a source state.
+ * Other way around, local transition doesn't cause exit and entry to target state if target is a superstate
+ * of a source state.
  */
 enum class TransitionType {
     /** Default */

kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/TransitionDirection.kt

@@ -1,43 +1,91 @@
 package ru.nsk.kstatemachine
 
-sealed class TransitionDirection {
+sealed interface TransitionDirection {
     /**
      * Already resolved target state of conditional transition or [PseudoState] computation
+     * This is always one of [targetStates] list elements or null, if the list is empty.
      */
-    open val targetState: IState? = null
+    val targetState: IState? get() = null
+
+    /**
+     * Transition can target multiple states if they all are located at different regions of a parallel state.
+     */
+    val targetStates: Set<IState>
 }
 
 /**
  * [Transition] is triggered, but state is not changed
  */
-internal object Stay : TransitionDirection()
+internal object Stay : TransitionDirection {
+    override val targetStates = emptySet<IState>()
+}
 
 fun stay(): TransitionDirection = Stay
 
 /**
  * [Transition] should not be triggered
  */
-internal object NoTransition : TransitionDirection()
+internal object NoTransition : TransitionDirection {
+    override val targetStates = emptySet<IState>()
+}
 
 fun noTransition(): TransitionDirection = NoTransition
 
 /**
- * [Transition] is triggered with a [targetState].
+ * [Transition] is triggered with [targetStates] (usually with single [targetState])
  */
-internal open class TargetState(override val targetState: IState) : TransitionDirection()
+internal data class TargetState(
+    override val targetStates: Set<IState>,
+    override val targetState: IState = targetStates.first()
+) : TransitionDirection {
+    init {
+        require(targetStates.contains(targetState)) {
+            "Internal logical error, invalid ${TargetState::class.simpleName} construction, this should never happen"
+        }
+    }
+}
 
 /**
  * [Transition] is triggered with a targetState, resolving it in place if it is a [PseudoState]
  */
 suspend fun EventAndArgument<*>.targetState(targetState: IState): TransitionDirection = resolveTargetState(targetState)
 
+suspend fun EventAndArgument<*>.targetParallelStates(targetStates: Set<IState>): TransitionDirection {
+    require(targetStates.size >= 2) {
+        "There should be at least two targetStates, current amount ${targetStates.size}," +
+                " check that you are not using the same state multiple times"
+    }
+    val resolvedStates = mutableSetOf<IState>()
+    targetStates.mapNotNullTo(resolvedStates) { recursiveResolveTargetState(it) }
+    if (resolvedStates.isEmpty()) return NoTransition
+
+    @Suppress("UNCHECKED_CAST")
+    val lca = findLca(resolvedStates as Set<InternalNode>) as InternalState
+    check(lca.findParallelAncestor() != null) {
+        "Resolved states does not have common ancestor with ${ChildMode.PARALLEL} child mode. " +
+                "Only children of a state with ${ChildMode.PARALLEL} child mode" +
+                " might be used as effective (resolved) targets here."
+    }
+    return TargetState(resolvedStates)
+}
+
+private fun InternalState.findParallelAncestor(): InternalState? {
+    return if (childMode == ChildMode.PARALLEL) this else internalParent?.findParallelAncestor()
+}
+
+suspend fun EventAndArgument<*>.targetParallelStates(
+    targetState1: IState,
+    targetState2: IState,
+    vararg targetStates: IState
+) = targetParallelStates(setOf(targetState1, targetState2, *targetStates))
+
 private suspend fun EventAndArgument<*>.resolveTargetState(targetState: IState): TransitionDirection {
     val resolvedState = recursiveResolveTargetState(targetState)
-    return if (resolvedState != null) TargetState(resolvedState) else NoTransition
+    return if (resolvedState != null) TargetState(setOf(resolvedState)) else NoTransition
 }
 
 private suspend fun EventAndArgument<*>.recursiveResolveTargetState(targetState: IState): IState? {
-    val resolvedTarget =  when (targetState) {
+    val resolvedTarget = when (targetState) {
         is RedirectPseudoState -> recursiveResolveTargetState(targetState.resolveTargetState(this))
         is HistoryState -> targetState.storedState
         is UndoState -> targetState.popState()
@@ -56,7 +104,7 @@ private suspend fun EventAndArgument<*>.recursiveResolveTargetState(targetState:
 /**
  * Internal use only. TODO remove it when possible
  */
-internal fun unresolvedTargetState(targetState: IState): TransitionDirection = TargetState(targetState)
+internal fun unresolvedTargetState(targetState: IState): TransitionDirection = TargetState(setOf(targetState))
 
 /**
  * Transition that matches event and has a meaningful direction (except [NoTransition])