KSLCore/ksl.modeling.agent/StateBuilder

StateBuilder

Builder for an individual StatechartState. Triggers and lifecycle hooks are configured by calling onEntry, onExit, onMessage, onTimeout, onCondition, or onSignal inside the state { } block. Composite states declare substates by nesting more state(...) { ... } calls inside the block and naming one via initial.

Each state may have at most one onTimeout and at most one onCondition; declaring more than one will fail at build time. Multiple onMessage / onSignal / onEntry / onExit are allowed and run in declaration order.

Functions

final

fun final(substateName: String, block: StateBuilder.() -> Unit = {})

Declare a final (terminal) substate. Entering it auto-stops the whole statechart and fires its onCompletion. See StatechartBuilder.final.

initial

fun initial(stateName: String)

Designate stateName as the initial substate of this composite state. Required if this state has any substates; ignored otherwise.

onCondition

fun onCondition(test: () -> Boolean, block: StateAction.() -> Unit)

When test first returns true while this state is active, run block. Each level has its own independent condition.

onEntry

fun onEntry(block: StateAction.() -> Unit)

Run block when this state is entered, before any triggers are installed for the state. For composite states, entry runs the parent's actions first, then descends into the initial substate (whose entry actions then run).

onExit

fun onExit(block: StateAction.() -> Unit)

Run block when this state is exited, after the state's triggers have been torn down and before the next state is entered. For composite states, substates exit first (bottom-up).

onMessage

inline fun <T : AgentMessage> onMessage(noinline predicate: (T) -> Boolean = { true }, noinline block: StateAction.(T) -> Unit)

Handle messages of type T arriving in the owner's mailbox while this state (or any substate) is active. When a message arrives, the runtime walks the active chain leaf-to-root and fires the first matching handler — most-specific wins.

onSignal

fun onSignal(signal: AgentSignal, block: StateAction.() -> Unit)

When signal fires while this state (or any substate) is active, run block. If both this state and one of its substates listen to the same signal, the more-specific (deeper) handler wins — only it runs.

onTimeout

fun onTimeout(duration: Double, block: StateAction.() -> Unit)

After duration simulated time units elapse with this state active, run block. Each level (composite or leaf) has its own independent timeout; a composite-state timeout is scheduled when the composite is entered and cancelled when the composite is exited, regardless of substate transitions within.

state

fun state(substateName: String, block: StateBuilder.() -> Unit)

Declare a substate with the given substateName. Multiple substates can be declared; one must be designated as the initial via initial.