Merge branch 'transition-types'

Author: nsk90

docs/index.md

@@ -187,6 +187,25 @@ greenState {
 }
 ```
 
+_Note: Such transitions are also called internal._
+
+### Transition type
+
+There are two types of transitions `TransitionType.LOCAL` (default) and `TransitionType.EXTERNAL`.
+Most of the cases both transitions 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
+target state is a sub-state of a source state.
+Local transition doesn't cause exit and entry to target state if target is a superstate of a source
+state.
+
+Use `type` argument or property of transition builder functions to set transition type:
+```kotlin
+transition<SwitchEvent> {
+   type = EXTERNAL
+   targetState = state2
+}
+```
+
 ### Listen to all transitions in one place
 
 There might be many transitions from one state to another. It is possible to listen to all of them in state machine
@@ -392,7 +411,8 @@ Notifications about finishing are available in two forms:
    Transition for `FinishedEvent` is detected by the library and matched by special kind of `EventMatcher`,
    so such transition is triggered only for `FinishedEvent` that corresponds to this state.
    `FinishingEvent` generated by finishing of another state will not trigger such transition.
-   See [transition on FinishedEvent sample](https://github.com/nsk90/kstatemachine/tree/master/samples/src/main/kotlin/ru/nsk/samples/FinishedEventSample.kt).
+   See [transition on FinishedEvent sample](https://github.com/nsk90/kstatemachine/tree/master/samples/src/main/kotlin/ru/nsk/samples/FinishedEventSample.kt)
+   .
 
 ## Nested states
 

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

@@ -1,6 +1,6 @@
 package ru.nsk.kstatemachine
 
-import ru.nsk.kstatemachine.TransitionDirectionProducerPolicy.DefaultPolicy
+import ru.nsk.kstatemachine.TransitionType.EXTERNAL
 import ru.nsk.kstatemachine.TreeAlgorithms.findPathFromTargetToLca
 import ru.nsk.kstatemachine.visitors.GetActiveStatesVisitor
 
@@ -146,10 +146,14 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
             .filter { it !is StateMachine } // exclude nested machines
             .mapNotNull { it.recursiveFindUniqueResolvedTransition(eventAndArgument) }
             .ifEmpty { listOfNotNull(findUniqueResolvedTransition(eventAndArgument)) } // allow transition override
-        check(resolvedTransitions.size <= 1) {
-            "Multiple transitions match ${eventAndArgument.event}, $transitions in $this"
+        return if (!machine.doNotThrowOnMultipleTransitionsMatch) {
+            check(resolvedTransitions.size <= 1) {
+                "Multiple transitions match ${eventAndArgument.event}, $transitions in $this"
+            }
+            resolvedTransitions.singleOrNull()
+        } else {
+            resolvedTransitions.firstOrNull()
         }
-        return resolvedTransitions.singleOrNull()
     }
 
     override fun recursiveEnterInitialStates(transitionParams: TransitionParams<*>) {
@@ -213,7 +217,7 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
         require(childMode == ChildMode.EXCLUSIVE) { "Cannot set current state in child mode $childMode" }
         require(states.contains(state)) { "$state is not a child of $this" }
 
-        if (data.currentState == state) return
+        if (data.currentState == state && transitionParams.transition.type != EXTERNAL) return
         data.currentState?.recursiveExit(transitionParams)
         data.currentState = state
 
@@ -258,32 +262,9 @@ open class BaseStateImpl(override val name: String?, override val childMode: Chi
         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)
     }
-
-    /**
-     * Initial event which is processed on state machine start
-     */
-    internal object StartEvent : Event
-
-    internal fun makeStartTransitionParams(
-        sourceState: IState,
-        targetState: IState = sourceState,
-        argument: Any?
-    ): TransitionParams<*> {
-        val transition = DefaultTransition(
-            "Starting",
-            EventMatcher.isInstanceOf<StartEvent>(),
-            sourceState,
-            targetState,
-        )
-
-        return TransitionParams(
-            transition,
-            transition.produceTargetStateDirection(DefaultPolicy(EventAndArgument(StartEvent, argument))),
-            StartEvent,
-            argument,
-        )
-    }
-}
+}

kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/DefaultTransition.kt

@@ -3,7 +3,8 @@ package ru.nsk.kstatemachine
 open class DefaultTransition<E : Event>(
     override val name: String?,
     override val eventMatcher: EventMatcher<E>,
-    sourceState: IState
+    override val type: TransitionType,
+    sourceState: IState,
 ) : InternalTransition<E> {
     private val _listeners = mutableSetOf<Transition.Listener>()
     override val listeners: Collection<Transition.Listener> get() = _listeners
@@ -23,18 +24,20 @@ open class DefaultTransition<E : Event>(
     constructor(
         name: String?,
         eventMatcher: EventMatcher<E>,
+        type: TransitionType,
         sourceState: IState,
         targetState: IState?
-    ) : this(name, eventMatcher, sourceState) {
+    ) : this(name, eventMatcher, type, sourceState) {
         targetStateDirectionProducer = { it.targetStateOrStay(targetState) }
     }
 
     constructor(
         name: String?,
         eventMatcher: EventMatcher<E>,
+        type: TransitionType,
         sourceState: IState,
         targetStateDirectionProducer: TransitionDirectionProducer<E>
-    ) : this(name, eventMatcher, sourceState) {
+    ) : this(name, eventMatcher, type, sourceState) {
         this.targetStateDirectionProducer = targetStateDirectionProducer
     }
 

kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/IState.kt

@@ -180,7 +180,7 @@ inline fun <reified S : IState> IState.requireState(recursive: Boolean = true) =
 operator fun <S : IState> S.invoke(block: StateBlock<S>) = block()
 
 /**
- * Most common methods [onEntry] and [onExit] are shipped with [once] argument, to remove listener
+ * The most commonly used methods [onEntry] and [onExit] are shipped with [once] argument, to remove listener
  * after it is triggered the first time.
  * Looks that it is not necessary in other similar methods.
  */

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

@@ -56,6 +56,10 @@ internal fun <E : Event> InternalState.findUniqueResolvedTransition(eventAndArgu
     val transitions = findTransitionsByEvent(eventAndArgument.event)
         .map { it to it.produceTargetStateDirection(policy) }
         .filter { it.second !is NoTransition }
-    check(transitions.size <= 1) { "Multiple transitions match ${eventAndArgument.event}, $transitions in $this" }
-    return transitions.singleOrNull()
+    return if (!machine.doNotThrowOnMultipleTransitionsMatch) {
+        check(transitions.size <= 1) { "Multiple transitions match ${eventAndArgument.event}, $transitions in $this" }
+        transitions.singleOrNull()
+    } else {
+        transitions.firstOrNull()
+    }
 }

kstatemachine/src/main/kotlin/ru/nsk/kstatemachine/StateMachine.kt

@@ -1,5 +1,6 @@
 package ru.nsk.kstatemachine
 
+import ru.nsk.kstatemachine.StateMachine.PendingEventHandler
 import ru.nsk.kstatemachine.visitors.Visitor
 
 @DslMarker
@@ -34,6 +35,13 @@ interface StateMachine : State {
 
     val isUndoEnabled: Boolean
 
+    /**
+     * If set to true, when multiple transitions match event the first matching transition is selected.
+     * if set to false, when multiple transitions match event exception is thrown.
+     * Default if false.
+     */
+    val doNotThrowOnMultipleTransitionsMatch: Boolean
+
     fun <L : Listener> addListener(listener: L): L
     fun removeListener(listener: Listener)
 
@@ -48,9 +56,13 @@ interface StateMachine : State {
     fun stop()
 
     /**
-     * Machine must be started to process events
+     * Processes [Event].
+     * Machine must be started to be able to process events.
+     * @return [ProcessingResult] for current event.
+     * If more events will be queued while this method is working, there results will not be taken to account.
+     * Their [processEvent] calls will return [ProcessingResult.PENDING] in this case.
      */
-    fun processEvent(event: Event, argument: Any? = null)
+    fun processEvent(event: Event, argument: Any? = null): ProcessingResult
 
     /**
      * Destroys machine structure clearing all listeners, states etc.
@@ -111,6 +123,9 @@ interface StateMachine : State {
     }
 }
 
+/**
+ * Shortcut for [StateMachine.stop] and [StateMachine.start] sequence calls
+ */
 fun StateMachine.restart(argument: Any? = null) {
     stop()
     start(argument)
@@ -166,8 +181,22 @@ fun createStateMachine(
     start: Boolean = true,
     autoDestroyOnStatesReuse: Boolean = true,
     enableUndo: Boolean = false,
+    doNotThrowOnMultipleTransitionsMatch: Boolean = false,
     init: StateMachineBlock
-): StateMachine = StateMachineImpl(name, childMode, autoDestroyOnStatesReuse, enableUndo).apply {
-    init()
-    if (start) start()
+): StateMachine {
+    return StateMachineImpl(name, childMode, autoDestroyOnStatesReuse, enableUndo, doNotThrowOnMultipleTransitionsMatch).apply {
+        init()
+        if (start) start()
+    }
+}
+
+enum class ProcessingResult {
+    /** Event was sent to [PendingEventHandler] */
+    PENDING,
+
+    /** Event was processed */
+    PROCESSED,
+
+    /** Event was ignored */
+    IGNORED,
 }

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

@@ -1,5 +1,6 @@
 package ru.nsk.kstatemachine
 
+import ru.nsk.kstatemachine.TransitionDirectionProducerPolicy.DefaultPolicy
 import ru.nsk.kstatemachine.visitors.CheckUniqueNamesVisitor
 import ru.nsk.kstatemachine.visitors.CleanupVisitor
 
@@ -16,6 +17,7 @@ internal class StateMachineImpl(
     childMode: ChildMode,
     override val autoDestroyOnStatesReuse: Boolean,
     override val isUndoEnabled: Boolean,
+    override val doNotThrowOnMultipleTransitionsMatch: Boolean,
 ) : InternalStateMachine(name, childMode) {
     private val _machineListeners = mutableSetOf<StateMachine.Listener>()
     override val machineListeners: Collection<StateMachine.Listener> get() = _machineListeners
@@ -105,7 +107,7 @@ internal class StateMachineImpl(
         }
     }
 
-    override fun processEvent(event: Event, argument: Any?) {
+    override fun processEvent(event: Event, argument: Any?): ProcessingResult {
         check(!isDestroyed) { "$this is already destroyed" }
         check(isRunning) { "$this is not started, call start() first" }
 
@@ -116,10 +118,10 @@ internal class StateMachineImpl(
             // pending event cannot be processed while previous event is still processing
             // even if PendingEventHandler does not throw. QueuePendingEventHandler implementation stores such events
             // to be processed later.
-            return
+            return ProcessingResult.PENDING
         }
 
-        eventProcessingScope {
+        return eventProcessingScope {
             process(eventAndArgument)
         }
     }
@@ -133,32 +135,32 @@ internal class StateMachineImpl(
         }
     }
 
-    private fun process(eventAndArgument: EventAndArgument<*>) {
-        var eventProcessed: Boolean? = null
-
+    private fun process(eventAndArgument: EventAndArgument<*>): ProcessingResult {
         val wrappedEventAndArgument = eventAndArgument.wrap()
 
-        runCheckingExceptions {
-            eventProcessed = doProcessEvent(wrappedEventAndArgument)
+        val eventProcessed = runCheckingExceptions {
+            doProcessEvent(wrappedEventAndArgument)
         }
 
-        if (eventProcessed == false) {
+        if (!eventProcessed) {
             log { "$this ignored ${wrappedEventAndArgument.event::class.simpleName}" }
             ignoredEventHandler.onIgnoredEvent(wrappedEventAndArgument.event, wrappedEventAndArgument.argument)
         }
+        return if (eventProcessed) ProcessingResult.PROCESSED else ProcessingResult.IGNORED
     }
 
     /**
      * Runs block of code that processes event, and processes all pending events from queue after it if
      * [QueuePendingEventHandler] is used.
      */
-    private fun eventProcessingScope(block: () -> Unit) {
+    private fun <R> eventProcessingScope(block: () -> R): R {
         val queue = pendingEventHandler as? QueuePendingEventHandler
         queue?.checkEmpty()
 
+        val result: R
         isProcessingEvent = true
         try {
-            block()
+            result = block()
 
             queue?.let {
                 var eventAndArgument = it.nextEventAndArgument()
@@ -174,14 +176,16 @@ internal class StateMachineImpl(
         } finally {
             isProcessingEvent = false
         }
+        return result
     }
 
     /**
      * Runs block of code that triggers notification listeners
      */
-    private fun runCheckingExceptions(block: () -> Unit) {
+    private fun <R> runCheckingExceptions(block: () -> R): R {
+        val result: R
         try {
-            block()
+            result = block()
         } catch (e: Exception) {
             log { "Fatal exception happened, $this machine is in unpredictable state and will be destroyed: $e" }
             runCatching { destroy(false) }
@@ -191,6 +195,7 @@ internal class StateMachineImpl(
             delayedListenerException = null
             listenerExceptionHandler.onException(it)
         }
+        return result
     }
 
     private fun <E : Event> doProcessEvent(eventAndArgument: EventAndArgument<E>): Boolean {
@@ -261,4 +266,23 @@ internal fun InternalStateMachine.runDelayingException(block: () -> Unit) =
         block()
     } catch (e: Exception) {
         delayListenerException(e)
-    }
+    }
+
+internal fun makeStartTransitionParams(sourceState: IState, targetState: IState = sourceState, argument: Any?):
+        TransitionParams<*> {
+    val transition = DefaultTransition(
+        "Starting",
+        EventMatcher.isInstanceOf<StartEvent>(),
+        TransitionType.LOCAL,
+        sourceState,
+        targetState,
+    )
+
+    val event = StartEvent()
+    return TransitionParams(
+        transition,
+        transition.produceTargetStateDirection(DefaultPolicy(EventAndArgument(event, argument))),
+        event,
+        argument,
+    )
+}

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

@@ -10,6 +10,7 @@ interface Transition<E : Event> : VisitorAcceptor {
     val name: String?
     val eventMatcher: EventMatcher<E>
     val sourceState: IState
+    val type: TransitionType
 
     /**
      * This parameter may be used to pass arbitrary data with a transition to targetState.
@@ -40,3 +41,15 @@ inline fun <reified E : Event> Transition<E>.onTriggered(
     @Suppress("UNCHECKED_CAST")
     override fun onTriggered(transitionParams: TransitionParams<*>) = block(transitionParams as TransitionParams<E>)
 })
+
+/**
+ * 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
+ * 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.
+ */
+enum class TransitionType {
+    /** Default */
+    LOCAL,
+    EXTERNAL
+}