From be176910eb870209576326ffaad8bf21241fccbd Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Wed, 5 Oct 2022 14:10:11 +0200 Subject: refactor(sim/core): Rename runBlockingSimulation to runSimulation This change renames the method `runBlockingSimulation` to `runSimulation` to put more emphasis on the simulation part of the method. The blocking part is not that important, but this behavior is still described in the method documentation. --- .../opendc/simulator/kotlin/SimulationBuilders.kt | 38 +++++++++++++++++----- 1 file changed, 30 insertions(+), 8 deletions(-) (limited to 'opendc-simulator/opendc-simulator-core/src') diff --git a/opendc-simulator/opendc-simulator-core/src/main/kotlin/org/opendc/simulator/kotlin/SimulationBuilders.kt b/opendc-simulator/opendc-simulator-core/src/main/kotlin/org/opendc/simulator/kotlin/SimulationBuilders.kt index a291b4e2..c4cc0171 100644 --- a/opendc-simulator/opendc-simulator-core/src/main/kotlin/org/opendc/simulator/kotlin/SimulationBuilders.kt +++ b/opendc-simulator/opendc-simulator-core/src/main/kotlin/org/opendc/simulator/kotlin/SimulationBuilders.kt @@ -29,10 +29,32 @@ import kotlin.coroutines.CoroutineContext import kotlin.coroutines.EmptyCoroutineContext /** - * Executes a [body] inside an immediate execution dispatcher. + * Executes [body] as a simulation in a new coroutine. + * + * This function behaves similarly to [runBlocking], with the difference that the code that it runs will skip delays. + * This allows to use [delay] in without causing the simulation to take more time than necessary. + * + * ``` + * @Test + * fun exampleSimulation() = runSimulation { + * val deferred = async { + * delay(1_000) + * async { + * delay(1_000) + * }.await() + * } + * + * deferred.await() // result available immediately + * } + * ``` + * + * The simulation is run in a single thread, unless other [CoroutineDispatcher] are used for child coroutines. + * Because of this, child coroutines are not executed in parallel to [body]. + * In order for the spawned-off asynchronous code to actually be executed, one must either [yield] or suspend the + * body some other way, or use commands that control scheduling (see [SimulationScheduler]). */ @OptIn(ExperimentalCoroutinesApi::class) -public fun runBlockingSimulation( +public fun runSimulation( context: CoroutineContext = EmptyCoroutineContext, scheduler: SimulationScheduler = SimulationScheduler(), body: suspend SimulationCoroutineScope.() -> Unit @@ -54,16 +76,16 @@ public fun runBlockingSimulation( } /** - * Convenience method for calling [runBlockingSimulation] on an existing [SimulationCoroutineScope]. + * Convenience method for calling [runSimulation] on an existing [SimulationCoroutineScope]. */ -public fun SimulationCoroutineScope.runBlockingSimulation(block: suspend SimulationCoroutineScope.() -> Unit): Unit = - runBlockingSimulation(coroutineContext, scheduler, block) +public fun SimulationCoroutineScope.runSimulation(block: suspend SimulationCoroutineScope.() -> Unit): Unit = + runSimulation(coroutineContext, scheduler, block) /** - * Convenience method for calling [runBlockingSimulation] on an existing [SimulationCoroutineDispatcher]. + * Convenience method for calling [runSimulation] on an existing [SimulationCoroutineDispatcher]. */ -public fun SimulationCoroutineDispatcher.runBlockingSimulation(block: suspend SimulationCoroutineScope.() -> Unit): Unit = - runBlockingSimulation(this, scheduler, block) +public fun SimulationCoroutineDispatcher.runSimulation(block: suspend SimulationCoroutineScope.() -> Unit): Unit = + runSimulation(this, scheduler, block) private fun CoroutineContext.checkArguments(scheduler: SimulationScheduler): Pair { val dispatcher = get(ContinuationInterceptor).run { -- cgit v1.2.3