Fix exampleGui speed buttons: bridge SimulationController -> ShuntingLoop

Speed-control buttons in exampleGui mode had no effect because the
simulation paced via RealTimeSynch, which read speedMultiplier from a
ShuntingLoop constructor val frozen at 1.0 in ExampleRegistry.
SimulationController.setSpeed only updated SimulationRunner.speedMultiplier
(whose throttle() is currently uncalled per its own KDoc), so the chain
button -> controller -> simulation was broken at the last hop.

Introduces SpeedControllable in core/commonMain (KMP-clean, generic — any
main-process can opt in, not ShuntingLoop-specific). ShuntingLoop now
implements it with an @kotlin.concurrent.Volatile var so RealTimeSynch
on the simulation thread reads each iteration's current value.
SimulationController casts the live main process via getMainProcess()
and propagates setSpeed() through both the runner and the controllable,
covering the active pacing path today and the throttle path when wired.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: bedaHovorka

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/context/DefaultSimulationContext.kt

@@ -1533,4 +1533,12 @@ open class DefaultSimulationContext(
 	fun setMainProcess(process: LoopProcess) {
 		mainProcess = process
 	}
+
+	/**
+	 * Returns the currently registered main process, or `null` if none has been set
+	 * via [setMainProcess]. Callers may downcast to runtime-control interfaces such
+	 * as [cz.vutbr.fit.interlockSim.sim.SpeedControllable] to retune the live
+	 * simulation (e.g. wall-clock pacing) from the EDT.
+	 */
+	fun getMainProcess(): LoopProcess? = mainProcess
 }

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/sim/ShuntingLoop.kt

@@ -67,12 +67,22 @@ class ShuntingLoop(
 	context: SimulationContext,
 	private val endTime: Long,
 	private val enableRealTimeSync: Boolean = false,
-	private val speedMultiplier: Double = 1.0,
+	initialSpeedMultiplier: Double = 1.0,
 	private val pathReservationService: PathReservationService = context.getPathReservationService()
 ) : Interlocking(context),
+	SpeedControllable,
 	KoinComponent {
+	@kotlin.concurrent.Volatile
+	override var speedMultiplier: Double = initialSpeedMultiplier
+		set(value) {
+			require(value > 0.0) { "Speed multiplier must be positive, got: $value" }
+			field = value
+		}
+
 	init {
-		require(speedMultiplier > 0.0) { "Speed multiplier must be positive, got: $speedMultiplier" }
+		require(initialSpeedMultiplier > 0.0) {
+			"Speed multiplier must be positive, got: $initialSpeedMultiplier"
+		}
 	}
 
 	// Inject registry for idempotent path reservation checks

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/sim/SpeedControllable.kt

@@ -0,0 +1,26 @@
+/* Brno University of Technology
+ * Faculty of Information Technology
+ *
+ * BSc Thesis  2006/2007
+ *
+ * Railway Interlocking Simulator
+ *
+ * Bedrich Hovorka
+ */
+package cz.vutbr.fit.interlockSim.sim
+
+/**
+ * Implemented by simulation processes whose wall-clock pacing can be retuned at runtime.
+ *
+ * Implementations MUST treat the property as thread-safe: reads happen on the kDisco
+ * simulation thread (e.g. inside a real-time-sync loop), writes happen on the EDT
+ * (or any thread driving GUI controls / keyboard shortcuts). Use `@kotlin.concurrent.Volatile`
+ * on the backing field.
+ *
+ * Range validation is left to the implementation; the canonical bounds used by the
+ * desktop GUI live on `SimulationRunner.MIN_SPEED`/`MAX_SPEED`.
+ */
+interface SpeedControllable {
+	/** Wall-clock speed multiplier. 1.0 = real-time, 2.0 = twice as fast, 0.5 = half-speed. */
+	var speedMultiplier: Double
+}

core/src/jvmTest/kotlin/cz/vutbr/fit/interlockSim/sim/ShuntingLoopTest.kt

@@ -310,7 +310,7 @@ class ShuntingLoopTest : KoinTestBase() {
 					validContext,
 					60L,
 					enableRealTimeSync = true,
-					speedMultiplier = 2.0
+					initialSpeedMultiplier = 2.0
 				)
 			assertThat(shuntingLoop).isNotNull()
 		}
@@ -335,7 +335,7 @@ class ShuntingLoopTest : KoinTestBase() {
 					validContext,
 					60L,
 					enableRealTimeSync = true,
-					speedMultiplier = 0.5
+					initialSpeedMultiplier = 0.5
 				)
 			assertThat(shuntingLoop).isNotNull()
 		}
@@ -348,7 +348,7 @@ class ShuntingLoopTest : KoinTestBase() {
 					validContext,
 					60L,
 					enableRealTimeSync = true,
-					speedMultiplier = 1.0
+					initialSpeedMultiplier = 1.0
 				)
 			assertThat(shuntingLoop).isNotNull()
 		}
@@ -361,7 +361,7 @@ class ShuntingLoopTest : KoinTestBase() {
 					validContext,
 					60L,
 					enableRealTimeSync = true,
-					speedMultiplier = 2.0
+					initialSpeedMultiplier = 2.0
 				)
 			assertThat(shuntingLoop).isNotNull()
 		}
@@ -374,7 +374,7 @@ class ShuntingLoopTest : KoinTestBase() {
 					validContext,
 					60L,
 					enableRealTimeSync = true,
-					speedMultiplier = 5.0
+					initialSpeedMultiplier = 5.0
 				)
 			assertThat(shuntingLoop).isNotNull()
 		}
@@ -394,7 +394,7 @@ class ShuntingLoopTest : KoinTestBase() {
 					validContext,
 					60L,
 					enableRealTimeSync = true,
-					speedMultiplier = 0.1
+					initialSpeedMultiplier = 0.1
 				)
 			assertThat(shuntingLoop).isNotNull()
 		}
@@ -407,7 +407,7 @@ class ShuntingLoopTest : KoinTestBase() {
 					validContext,
 					60L,
 					enableRealTimeSync = true,
-					speedMultiplier = 10.0
+					initialSpeedMultiplier = 10.0
 				)
 			assertThat(shuntingLoop).isNotNull()
 		}
@@ -420,7 +420,7 @@ class ShuntingLoopTest : KoinTestBase() {
 					validContext,
 					60L,
 					enableRealTimeSync = true,
-					speedMultiplier = 0.0
+					initialSpeedMultiplier = 0.0
 				)
 			}.withMessage("Speed multiplier must be positive")
 				.isFailure()
@@ -435,12 +435,54 @@ class ShuntingLoopTest : KoinTestBase() {
 					validContext,
 					60L,
 					enableRealTimeSync = true,
-					speedMultiplier = -1.0
+					initialSpeedMultiplier = -1.0
 				)
 			}.withMessage("Speed multiplier must be positive")
 				.isFailure()
 				.isInstanceOf(IllegalArgumentException::class)
 		}
+
+		@Test
+		@DisplayName("speedMultiplier is mutable post-construction (RealTimeSynch reads live value)")
+		fun speedMultiplier_isMutableAtRuntime() {
+			val shuntingLoop = ShuntingLoop(validContext, 60L, enableRealTimeSync = true)
+
+			// Default initial value
+			assertThat(shuntingLoop.speedMultiplier).isEqualTo(1.0)
+
+			// Mutating from the EDT side (or any thread) must stick — RealTimeSynch.iteration()
+			// reads from this @Volatile field on the simulation thread, so the value seen by
+			// the wall-clock pacing must match the latest write.
+			shuntingLoop.speedMultiplier = 2.5
+			assertThat(shuntingLoop.speedMultiplier).isEqualTo(2.5)
+
+			shuntingLoop.speedMultiplier = 0.1
+			assertThat(shuntingLoop.speedMultiplier).isEqualTo(0.1)
+		}
+
+		@Test
+		@DisplayName("speedMultiplier setter rejects zero")
+		fun speedMultiplier_setter_zero_throwsException() {
+			val shuntingLoop = ShuntingLoop(validContext, 60L, enableRealTimeSync = true)
+
+			assertThatBlock {
+				shuntingLoop.speedMultiplier = 0.0
+			}.withMessage("Speed multiplier must be positive")
+				.isFailure()
+				.isInstanceOf(IllegalArgumentException::class)
+		}
+
+		@Test
+		@DisplayName("speedMultiplier setter rejects negative")
+		fun speedMultiplier_setter_negative_throwsException() {
+			val shuntingLoop = ShuntingLoop(validContext, 60L, enableRealTimeSync = true)
+
+			assertThatBlock {
+				shuntingLoop.speedMultiplier = -1.0
+			}.withMessage("Speed multiplier must be positive")
+				.isFailure()
+				.isInstanceOf(IllegalArgumentException::class)
+		}
 	}
 
 	@Nested

desktop-ui/src/main/kotlin/cz/vutbr/fit/interlockSim/ExampleRegistry.kt

@@ -135,7 +135,7 @@ class ExampleRegistry {
 				// Initialize dynamic wrapper map by calling getInOuts()
 				context.getInOuts()
 				// Enable real-time synchronization for GUI mode with 1x speed multiplier
-				context.setMainProcess(ShuntingLoop(context, time, enableRealTimeSync = true, speedMultiplier = 1.0))
+				context.setMainProcess(ShuntingLoop(context, time, enableRealTimeSync = true, initialSpeedMultiplier = 1.0))
 				context
 			}
 	}

desktop-ui/src/main/kotlin/cz/vutbr/fit/interlockSim/gui/SimulationController.kt

@@ -10,7 +10,9 @@
 
 package cz.vutbr.fit.interlockSim.gui
 
+import cz.vutbr.fit.interlockSim.context.DefaultSimulationContext
 import cz.vutbr.fit.interlockSim.context.SimulationContext
+import cz.vutbr.fit.interlockSim.sim.SpeedControllable
 import io.github.oshai.kotlinlogging.KotlinLogging
 import java.beans.PropertyChangeListener
 
@@ -62,6 +64,16 @@ internal class SimulationController(
 	/** Listener registered on the active runner for speed changes; removed on stop. */
 	private var speedListener: PropertyChangeListener? = null
 
+	/**
+	 * Reference to the running main process when it implements [SpeedControllable]
+	 * (e.g. [cz.vutbr.fit.interlockSim.sim.ShuntingLoop]). `setSpeed` propagates
+	 * speed changes here so the simulation thread's wall-clock pacing actually
+	 * tracks the GUI controls — without this link the runner-side `speedMultiplier`
+	 * is dead-state w.r.t. RealTimeSynch.
+	 */
+	@Volatile
+	private var speedControllable: SpeedControllable? = null
+
 	/**
 	 * Desired speed multiplier applied to new and currently running simulations.
 	 *
@@ -107,6 +119,10 @@ internal class SimulationController(
 		val newRunner = SimulationRunner(context)
 		newRunner.speedMultiplier = desiredSpeed
 		runner = newRunner
+		val mainProcess = (context as? DefaultSimulationContext)?.getMainProcess()
+		val controllable = mainProcess as? SpeedControllable
+		speedControllable = controllable
+		controllable?.speedMultiplier = desiredSpeed
 
 		// Start synchronously BEFORE enabling the Stop button or launching the monitor
 		// thread. This ensures stopSimulation() always has a live thread to interrupt.
@@ -155,6 +171,7 @@ internal class SimulationController(
 						if (runner === newRunner) {
 							cleanupSpeedListener(newRunner)
 							runner = null
+							speedControllable = null
 							onSpeedChanged(SimulationRunner.DEFAULT_SPEED)
 							onStateChanged(SimulationStatus.STOPPED)
 							onCompleted()
@@ -177,6 +194,7 @@ internal class SimulationController(
 		cleanupSpeedListener(r)
 		r.stop()
 		runner = null
+		speedControllable = null
 		onSpeedChanged(SimulationRunner.DEFAULT_SPEED)
 		onStateChanged(SimulationStatus.STOPPED)
 	}
@@ -205,6 +223,7 @@ internal class SimulationController(
 		}
 		desiredSpeed = multiplier
 		runner?.speedMultiplier = multiplier
+		speedControllable?.speedMultiplier = multiplier
 	}
 
 	companion object {

desktop-ui/src/test/kotlin/cz/vutbr/fit/interlockSim/gui/SimulationControllerBridgeIntegrationTest.kt

@@ -0,0 +1,133 @@
+/*
+	Brno University of Technology
+	Faculty of Information Technology
+
+	BSc Thesis       2006/2007
+	Railway Interlocking Simulator
+
+	Bridge integration test (Goal 7 / Issue #187): with real DefaultSimulationContext
+	and a real ShuntingLoop, SimulationController.setSpeed must reach the live
+	ShuntingLoop instance through DefaultSimulationContext.getMainProcess() and the
+	SpeedControllable cast — closing the loop the user observed broken in
+	`exampleGui shuntingLoop`.
+*/
+
+package cz.vutbr.fit.interlockSim.gui
+
+import assertk.assertThat
+import assertk.assertions.isEqualTo
+import assertk.assertions.isSameAs
+import assertk.assertions.isTrue
+import cz.vutbr.fit.interlockSim.context.DefaultSimulationContext
+import cz.vutbr.fit.interlockSim.context.SimulationContextFactory
+import cz.vutbr.fit.interlockSim.sim.ShuntingLoop
+import cz.vutbr.fit.interlockSim.sim.SpeedControllable
+import cz.vutbr.fit.interlockSim.testutil.KoinTestBase
+import cz.vutbr.fit.interlockSim.testutil.TestFixtures
+import cz.vutbr.fit.interlockSim.testutil.integrationTestModule
+import org.junit.jupiter.api.DisplayName
+import org.junit.jupiter.api.Tag
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.Timeout
+import org.koin.core.module.Module
+import org.koin.test.get
+import java.util.concurrent.TimeUnit
+
+@Tag("integration-test")
+@DisplayName("SimulationController -> ShuntingLoop bridge (real types)")
+class SimulationControllerBridgeIntegrationTest : KoinTestBase() {
+
+	override fun getTestModule(): Module = integrationTestModule
+
+	@Test
+	@DisplayName("Real ShuntingLoop is recognised as SpeedControllable via getMainProcess()")
+	fun realShuntingLoopIsRecognizedAsSpeedControllable() {
+		val factory = get<SimulationContextFactory>()
+		val ctx = TestFixtures.loadShuntingXml().use { factory.createContext(it) as DefaultSimulationContext }
+
+		ctx.use { context ->
+			context.getInOuts()
+			val loop = ShuntingLoop(context, 60L, enableRealTimeSync = true)
+			context.setMainProcess(loop)
+
+			val mainProcess = context.getMainProcess()
+			assertThat(mainProcess).isSameAs(loop)
+			assertThat(mainProcess is SpeedControllable).isTrue()
+
+			val controllable = mainProcess as SpeedControllable
+			controllable.speedMultiplier = 2.5
+			// Same instance — RealTimeSynch on the simulation thread reads through
+			// the same @Volatile-backed field on its next iteration.
+			assertThat(loop.speedMultiplier).isEqualTo(2.5)
+		}
+	}
+
+	@Test
+	@Timeout(value = 15, unit = TimeUnit.SECONDS)
+	@DisplayName("controller.setSpeed propagates to live ShuntingLoop while simulation runs")
+	fun controllerSetSpeedPropagatesToLiveShuntingLoop() {
+		val factory = get<SimulationContextFactory>()
+		val ctx = TestFixtures.loadShuntingXml().use { factory.createContext(it) as DefaultSimulationContext }
+
+		ctx.use { context ->
+			context.getInOuts()
+			// Long simulated end time + real-time sync so the simulation thread is
+			// active when we change speed. We stop() it explicitly in finally.
+			val loop = ShuntingLoop(
+				context,
+				endTime = 600L,
+				enableRealTimeSync = true,
+				initialSpeedMultiplier = 1.0
+			)
+			context.setMainProcess(loop)
+
+			val controller = SimulationController()
+			try {
+				controller.start(context)
+
+				// SimulationController wires its `speedControllable` reference
+				// synchronously inside start(), before launching the simulation thread,
+				// so the bridge is live by the time we get here.
+				controller.setSpeed(2.0)
+				assertThat(loop.speedMultiplier).isEqualTo(2.0)
+
+				controller.setSpeed(0.5)
+				assertThat(loop.speedMultiplier).isEqualTo(0.5)
+
+				controller.setSpeed(10.0)
+				assertThat(loop.speedMultiplier).isEqualTo(10.0)
+			} finally {
+				controller.stop()
+			}
+		}
+	}
+
+	@Test
+	@Timeout(value = 15, unit = TimeUnit.SECONDS)
+	@DisplayName("setSpeed before start applies on start() to the real ShuntingLoop")
+	fun preStartSpeedAppliedToRealShuntingLoopOnStart() {
+		val factory = get<SimulationContextFactory>()
+		val ctx = TestFixtures.loadShuntingXml().use { factory.createContext(it) as DefaultSimulationContext }
+
+		ctx.use { context ->
+			context.getInOuts()
+			val loop = ShuntingLoop(
+				context,
+				endTime = 600L,
+				enableRealTimeSync = true,
+				initialSpeedMultiplier = 1.0
+			)
+			context.setMainProcess(loop)
+
+			val controller = SimulationController()
+			try {
+				controller.setSpeed(3.0)
+				controller.start(context)
+
+				assertThat(loop.speedMultiplier).isEqualTo(3.0)
+			} finally {
+				controller.stop()
+			}
+		}
+	}
+}