Kotlin Finite-state machine
This work is licensed under Apache License 2.0
This is a small implementation of an FSM in Kotlin.
Resources
Getting Started
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.
Features
- Event driven state machine.
- External and internal transitions
- State entry and exit actions.
- Default state actions.
- Default entry and exit actions.
- Determine allowed events.
- Multiple state maps with push / pop transitions
- Automatic transitions
- Externalisation of state.
- Typed event parameters and return values.
Todo
Authors
Star History

Quick Tutorial
This is the classic turnstile FSM model from SMC
Simple turnstile example
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:
State Diagram

State Table
Context class
Enums for States and Events
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
}
Packaged definition and execution
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.
Usage
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:
fsm.coin()
fsm.pass()
fsm.pass()
fsm.coin()
fsm.coin()
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:
Repository
Use this repository for SNAPSHOT builds. Releases are on Maven Central
repositories {
maven {
url 'https://oss.sonatype.org/content/groups/public'
}
}
Dependencies
KMP Projects
The dependency used in common modules.
dependencies {
implementation 'io.jumpco.open:kfsm:1.9.0-RC1'
}
JVM Projects
dependencies {
implementation 'io.jumpco.open:kfsm-jvm:1.9.0-RC1'
}
KotlinJS Projects
dependencies {
implementation 'io.jumpco.open:kfsm-js:1.9.0-RC1'
}
Kotlin/Native Projects using LinuxX64
dependencies {
implementation 'io.jumpco.open:kfsm-linuxX64:1.9.0-RC1'
}
Kotlin/Native Projects using MinGW64
dependencies {
implementation 'io.jumpco.open:kfsm-mingwX64:1.9.0-RC1'
}
Kotlin/Native Projects using macOS
dependencies {
implementation 'io.jumpco.open:kfsm-macosX64:1.9.0-RC1'
}
Visualisation
For more information about visualization options use kfsm-io.jumpco.open.kfsm.viz
Plantuml Examples
Turnstile FSM
TurnstileTypes.kt

Paying Turnstile FSM
PayingTurnstileTypes.kt

Secure Turnstile FSM
SecureTurnstile.kt

Packer Reader FSM
PacketReaderTests.kt

Questions:
- Should entry / exit actions receive state or event as arguments?
- Should default actions receive state or event as arguments?
- Is there a more elegant way to define States and Events using sealed classes?
- Are any features missing from the implementation?