From 157d30beb52c75831e29a1a22c199b95d6d30b42 Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Wed, 14 Feb 2018 12:32:57 +0100 Subject: refactor(#18): Create distinction between kernel and simulation This change creates a distinction between a kernel and a simulation. A single simulation is represented by a `Simulation` object which provides control over the simulation, while the `Kernel` interface allows users to create a new simulation using that kernel as backend. --- .../com/atlarge/opendc/simulator/Bootstrap.kt | 20 +++--- .../com/atlarge/opendc/simulator/kernel/Kernel.kt | 50 ++------------- .../opendc/simulator/kernel/KernelFactory.kt | 42 ------------ .../atlarge/opendc/simulator/kernel/Simulation.kt | 74 ++++++++++++++++++++++ .../opendc/simulator/platform/Experiment.kt | 6 +- 5 files changed, 94 insertions(+), 98 deletions(-) delete mode 100644 opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt create mode 100644 opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Simulation.kt (limited to 'opendc-core/src/main') diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt index 10a89704..5f41c727 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt @@ -9,15 +9,15 @@ package com.atlarge.opendc.simulator */ interface Bootstrap { /** - * Bootstrap a model `M` for a kernel in the given context. + * Apply the apply procedure for model `M` for a simulation in the given context. * - * @param context The context to bootstrap to model in. - * @return The initialised model for the simulation. + * @param context The context to apply to model in. + * @return The initialised, resulting model for the simulation. */ - fun bootstrap(context: Context): M + fun apply(context: Context): M /** - * A context for the bootstrap of some model type `M` that allows the model to register the entities of the model to + * A context for the apply of some model type `M` that allows the model to register the entities of the model to * the simulation kernel. * * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) @@ -40,7 +40,7 @@ interface Bootstrap { fun deregister(entity: Entity<*, M>): Boolean /** - * Schedule a message for processing by a [Context]. + * Schedule a message to be received by the given [Entity]. * * @param message The message to schedule. * @param destination The destination of the message. @@ -52,13 +52,13 @@ interface Bootstrap { companion object { /** - * Create a [Bootstrap] procedure using the given block to produce a bootstrap for a model of type `M`. + * Create a [Bootstrap] procedure using the given block to produce a apply for a model of type `M`. * - * @param block The block to produce the bootstrap. - * @return The bootstrap procedure that has been built. + * @param block The block to produce the apply. + * @return The apply procedure that has been built. */ fun create(block: (Context) -> M): Bootstrap = object : Bootstrap { - override fun bootstrap(context: Context) = block(context) + override fun apply(context: Context) = block(context) } } } diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt index 29b3bdee..d4995283 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt @@ -25,55 +25,19 @@ package com.atlarge.opendc.simulator.kernel import com.atlarge.opendc.simulator.Bootstrap -import com.atlarge.opendc.simulator.Entity -import com.atlarge.opendc.simulator.Instant /** - * A message based discrete event simulation kernel. + * A message-based discrete event simulator (DES). This interface is a factory for creating [Simulation]s using the + * provided [Bootstrap] for the model. * - * The kernel is created by bootstrapping some model `M` (see [Bootstrap]) to simulate and controls the simulation by - * allowing the user to step over cycles in the simulation and inspect the internal state using [Entity.state]. - * - * A kernel should provide additionally a [KernelFactory] to create new kernel instances given a certain model - * [Bootstrap]. - * - * @param M The shape of the model over which the simulation runs. * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) */ -interface Kernel { - /** - * The model in which the simulation runs. - */ - val model: M - - /** - * The simulation time. - */ - var time: Instant - - /** - * The observable state of an [Entity] in simulation, which is provided by the simulation context. - */ - val , S> E.state: S - - /** - * Step through one cycle in the simulation. This method will process all events in a single tick, update the - * internal clock and then return the control to the user. - */ - fun step() - - /** - * Run a simulation over the specified model. - * This method will step through multiple cycles in the simulation until no more message exist in the queue. - */ - fun run() - +interface Kernel { /** - * Run a simulation over the specified model, stepping through cycles until the specified clock tick has - * occurred. The control is then handed back to the user. + * Create a simulation over the given model facilitated by this simulation kernel. * - * @param until The point in simulation time at which the simulation should be paused and the control is handed - * back to the user. + * @param bootstrap The apply procedure to apply the simulation with. + * @return A [Simulation] instance representing the simulation. */ - fun run(until: Instant) + fun create(bootstrap: Bootstrap): Simulation } diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt deleted file mode 100644 index 30abb7ca..00000000 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/KernelFactory.kt +++ /dev/null @@ -1,42 +0,0 @@ -/* - * MIT License - * - * Copyright (c) 2017 atlarge-research - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in all - * copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -package com.atlarge.opendc.simulator.kernel - -import com.atlarge.opendc.simulator.Bootstrap - -/** - * A factory for bootstrapping simulation [Kernel] instances. - * - * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) - */ -interface KernelFactory { - /** - * Create a simulation over the given model facilitated by this simulation kernel. - * - * @param bootstrap The bootstrap procedure to bootstrap the simulation with. - * @return A [Kernel] instance to control the simulation. - */ - fun create(bootstrap: Bootstrap): Kernel -} diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Simulation.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Simulation.kt new file mode 100644 index 00000000..bb2ef818 --- /dev/null +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Simulation.kt @@ -0,0 +1,74 @@ +/* + * MIT License + * + * Copyright (c) 2017 atlarge-research + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package com.atlarge.opendc.simulator.kernel + +import com.atlarge.opendc.simulator.Entity +import com.atlarge.opendc.simulator.Instant + +/** + * A message based discrete event simulation over some model `M`. This interface provides direct control over the + * simulation, allowing the user to step over cycles of the simulation and inspecting the state of the simulation via + * [Entity.state]. + * + * @param M The shape of the model over which the simulation runs. + * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl) + */ +interface Simulation { + /** + * The model in which the simulation runs. + */ + val model: M + + /** + * The simulation time. + */ + var time: Instant + + /** + * The observable state of an [Entity] in simulation, which is provided by the simulation context. + */ + val , S> E.state: S + + /** + * Step through one cycle in the simulation. This method will process all events in a single tick, update the + * internal clock and then return the control to the user. + */ + fun step() + + /** + * Run a simulation over the specified model. + * This method will step through multiple cycles in the simulation until no more message exist in the queue. + */ + fun run() + + /** + * Run a simulation over the specified model, stepping through cycles until the specified clock tick has + * occurred. The control is then handed back to the user. + * + * @param until The point in simulation time at which the simulation should be paused and the control is handed + * back to the user. + */ + fun run(until: Instant) +} diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt index 92d56be1..eb959ded 100644 --- a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt +++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt @@ -25,7 +25,7 @@ package com.atlarge.opendc.simulator.platform import com.atlarge.opendc.simulator.Duration -import com.atlarge.opendc.simulator.kernel.KernelFactory +import com.atlarge.opendc.simulator.kernel.Kernel /** * A blueprint for a reproducible simulation in a pre-defined setting. @@ -39,7 +39,7 @@ interface Experiment { * @param factory The factory to create the simulation kernel with. * @return The result of the experiment. */ - fun run(factory: KernelFactory): T + fun run(factory: Kernel): T /** * Run the experiment on the specified kernel implementation. @@ -48,5 +48,5 @@ interface Experiment { * @param timeout The maximum duration of the experiment before returning to the caller. * @return The result of the experiment or `null`. */ - fun run(factory: KernelFactory, timeout: Duration): T? + fun run(factory: Kernel, timeout: Duration): T? } -- cgit v1.2.3