KSLCore/ksl.app.session/RunHandle

RunHandle

Live reference to a simulation run submitted via Runner.submit.

A RunHandle is returned immediately by Runner.submit; the simulation executes asynchronously on a background thread. Callers observe progress by collecting events and obtain the terminal outcome by awaiting result.

val handle = runner.submit(RunRequest.SingleRun(model))

// Collect lifecycle events (usually in a dedicated coroutine):
launch { handle.events.collect { event -> updateUi(event) } }

// Await the terminal result:
when (val r = handle.result.await()) {
    is RunResult.Completed -> showResults(r.summary)
    is RunResult.Cancelled -> showCancelled(r.reason)
    is RunResult.Failed    -> showError(r.error)
}

Properties

events

abstract val events: SharedFlow<RunEvent>

Hot SharedFlow of lifecycle events emitted during the run.

result

abstract val result: Deferred<RunResult>

Deferred terminal result of the run.

runId

abstract val runId: String

Unique identifier for this run, assigned by Runner.

Functions

awaitResultBlocking

open fun awaitResultBlocking(): RunResult

Synchronously waits for result and returns it.

cancel

abstract fun cancel(reason: String = "Cancelled by user")

Requests cooperative cancellation of the run.

cancelScenario

open fun cancelScenario(scenarioName: String): Boolean

Cancel a single scenario by name without stopping the enclosing run. Only meaningful for scenario sweeps — other orchestrators return false from the default implementation.