Implements finite-state machines supporting event-driven transitions, entry/exit actions, default actions, multiple state maps, automatic transitions, typed event parameters, and state externalization. Offers extensive visualization and example projects.
This work is licensed under Apache License 2.0
This is a small implementation of an FSM in Kotlin.
The state machine implementation supports events triggering transitions from one state to another while performing an optional action as well as entry and exit actions.
This is the classic turnstile FSM model from SMC
Assume we and to manage the state on a simple lock.
We want to ensure that the lock() function is only called when the lock is not locked and we want unlock() to be called when locked.
Then we use the DSL to declare a definition of a statemachine matching the diagram:
We declare 2 enums, one for the possible states and one for the possible events.
enum class TurnstileStates {
LOCKED,
UNLOCKED
}
enum class TurnstileEvents {
COIN,
PASS
}
With this definition we are saying:
When the state is LOCKED and on a COIN event then transition to UNLOCKED and execute the lambda which is treated
as a member of the context { unlock() }
When the state is LOCKED and on event PASS we perform the action alarm() without changing the end state.
Then we instantiate the FSM and provide a context to operate on:
val turnstile = Turnstile()
val fsm = TurnstileFSM(turnstile)
Now we have a context that is independent of the FSM.
Sending events may invoke actions:
// State state is LOCKED
fsm.coin()
// Expect unlock action end state is UNLOCKED
fsm.pass()
// Expect lock() action and end state is LOCKED
fsm.pass()
// Expect alarm() action and end state is LOCKED
fsm.coin()
// Expect unlock() and end state is UNLOCKED
fsm.coin()
// Expect returnCoin() and end state is UNLOCKED
This model means the FSM can be instantiated as needed if the context has values that represent the state. The idea is that the context will properly maintain it's internal state.
The FSM can derive the formal state from the value(s) of properties of the context.
The Documentation contains more detail on creating finite state machine implementations.
The documentation contains examples for:
Use this repository for SNAPSHOT builds. Releases are on Maven Central
repositories {
maven {
url 'https://oss.sonatype.org/content/groups/public'
}
}
The dependency used in common modules.
dependencies {
implementation 'io.jumpco.open:kfsm:1.9.0-RC1'
}
dependencies {
implementation 'io.jumpco.open:kfsm-jvm:1.9.0-RC1'
}
dependencies {
implementation 'io.jumpco.open:kfsm-js:1.9.0-RC1'
}
dependencies {
implementation 'io.jumpco.open:kfsm-linuxX64:1.9.0-RC1'
}
dependencies {
implementation 'io.jumpco.open:kfsm-mingwX64:1.9.0-RC1'
}
dependencies {
implementation 'io.jumpco.open:kfsm-macosX64:1.9.0-RC1'
}
For more information about visualization options use kfsm-io.jumpco.open.kfsm.viz
| Start State | Event | End State | Action |
|---|
| LOCKED | PASS | LOCKED | alarm |
| LOCKED | COIN | UNLOCKED | unlock |
| UNLOCKED | PASS | LOCKED | lock |
| UNLOCKED | COIN | UNLOCKED | returnCoin |
class Turnstile(var locked: Boolean = true) {
fun unlock() {
assert(locked) { "Cannot unlock when not locked" }
println("Unlock")
locked = false
}
fun lock() {
assert(!locked) { "Cannot lock when locked" }
println("Lock")
locked = true
}
fun alarm() {
println("Alarm")
}
fun returnCoin() {
println("Return coin")
}
override fun toString(): String {
return "Turnstile(locked=$locked)"
}
}
class TurnstileFSM(turnstile: Turnstile) {
private val fsm = definition.create(turnstile)
fun coin() = fsm.sendEvent(TurnstileEvents.COIN)
fun pass() = fsm.sendEvent(TurnstileEvents.PASS)
companion object {
private val definition = stateMachine(
TurnstileStates.values().toSet(),
TurnstileEvents::class,
Turnstile::class
) {
initialState {
if (locked)
TurnstileStates.LOCKED
else
TurnstileStates.UNLOCKED
}
default {
onEntry { startState, targetState, _ ->
println("entering:$startState -> $targetState for $this")
}
// default transition will invoke alarm
action { state, event, _ ->
println("Default action for state($state) -> event($event) for $this")
alarm()
}
onExit { startState, targetState, _ ->
println("exiting:$startState -> $targetState for $this")
}
}
// when current state is LOCKED
whenState(TurnstileStates.LOCKED) {
// external transition on COIN to UNLOCKED state
onEvent(TurnstileEvents.COIN to TurnstileStates.UNLOCKED) {
unlock()
}
}
// when current state is UNLOCKED
whenState(TurnstileStates.UNLOCKED) {
// internal transition on COIN
onEvent(TurnstileEvents.COIN) {
returnCoin()
}
// external transition on PASS to LOCKED state
onEvent(TurnstileEvents.PASS to TurnstileStates.LOCKED) {
lock()
}
}
}.build()
}
}
Surfaced from shared tags and platforms — no rankings paid for.