refactor(#18): Redesign core simulation API

This change contains the redesign of the core simulation API and
provides a cleaner interface for developing simulation models for the
users.

Closes #18

8 files changed, 507 insertions, 0 deletions

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
new file mode 100644
index 00000000..5f41c727
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Bootstrap.kt
@@ -0,0 +1,64 @@
+package com.atlarge.opendc.simulator
+
+/**
+ * A bootstrapping interface for a conceptual model that is a logical representation of some system of entities,
+ * relationships and processes, as a basis for simulations.
+ *
+ * @param M The shape of the model that is bootstrapped.
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Bootstrap<M> {
+    /**
+     * Apply the apply procedure for model `M` for a simulation in the given context.
+     *
+     * @param context The context to apply to model in.
+     * @return The initialised, resulting model for the simulation.
+     */
+    fun apply(context: Context<M>): M
+
+    /**
+     * 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)
+     */
+    interface Context<out M> {
+        /**
+         * Register the given entity to the simulation kernel.
+         *
+         * @param entity The entity to register.
+         * @return `true` if the entity had not yet been registered, `false` otherwise.
+         */
+        fun register(entity: Entity<*, M>): Boolean
+
+        /**
+         * Deregister the given entity from the simulation kernel.
+         *
+         * @param entity The entity to deregister.
+         * @return `true` if the entity had not yet been unregistered, `false` otherwise.
+         */
+        fun deregister(entity: Entity<*, M>): Boolean
+
+        /**
+         * Schedule a message to be received by the given [Entity].
+         *
+         * @param message The message to schedule.
+         * @param destination The destination of the message.
+         * @param sender The sender of the message.
+         * @param delay The amount of time to wait before processing the message.
+         */
+        fun schedule(message: Any, destination: Entity<*, *>, sender: Entity<*, *>? = null, delay: Duration = 0)
+    }
+
+    companion object {
+        /**
+         * 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 apply.
+         * @return The apply procedure that has been built.
+         */
+        fun <M> create(block: (Context<M>) -> M): Bootstrap<M> = object : Bootstrap<M> {
+            override fun apply(context: Context<M>) = block(context)
+        }
+    }
+}
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt
new file mode 100644
index 00000000..23d10e8f
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Context.kt
@@ -0,0 +1,168 @@
+/*
+ * 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
+
+import java.util.*
+import kotlin.coroutines.experimental.CoroutineContext
+
+/**
+ * This interface provides a context for simulation of [Entity] instances, by defining the environment in which the
+ * simulation is run and provides means of communicating with other entities in the environment and control its own
+ * behaviour.
+ *
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Context<S, M> : CoroutineContext.Element {
+    /**
+     * The model of simulation in which the entity exists.
+     */
+    val model: M
+
+    /**
+     * The current point in simulation time.
+     */
+    val time: Instant
+
+    /**
+     * The duration between the current point in simulation time and the last point in simulation time where the
+     * [Entity] has done some work. This means the `run()` co-routine has been resumed.
+     */
+    val delta: Duration
+
+    /**
+     * The [Entity] associated with this context.
+     */
+    val self: Entity<S, M>
+
+    /**
+     * The sender of the last received message or `null` in case the process has not received any messages yet.
+     *
+     * Note that this property is only guaranteed to be correct when accessing after a single suspending call. Methods
+     * like `hold()` and `interrupt()` may change the value of this property.
+     */
+    val sender: Entity<*, *>?
+
+    /**
+     * The observable state of the entity bound to this scope.
+     */
+    var state: S
+
+    /**
+     * The observable state of an [Entity] in simulation, which is provided by the simulation context.
+     */
+    val <E : Entity<S, *>, S> E.state: S
+
+    /**
+     * Interrupt an [Entity] process in simulation.
+     *
+     * If an [Entity] process has been suspended, the suspending call will throw an [Interrupt] object as a result of
+     * this call.
+     * Make sure the [Entity] process actually has error handling in place, so it won't take down the whole [Entity]
+     * process as result of the interrupt.
+     *
+     * @param interrupt The interrupt to throw at the entity.
+     */
+    suspend fun Entity<*, *>.interrupt(interrupt: Interrupt)
+
+    /**
+     * Interrupt an [Entity] process in simulation.
+     *
+     * @see [Entity.interrupt(Interrupt)]
+     * @param reason The reason for interrupting the entity.
+     */
+    suspend fun Entity<*, *>.interrupt(reason: String) = interrupt(Interrupt(reason))
+
+    /**
+     * Suspend the [Context] of the [Entity] in simulation for the given duration of simulation time before resuming
+     * execution and drop all messages that are received during this period.
+     *
+     * A call to this method will not make the [Context] sleep for the actual duration of time, but instead suspend
+     * the process until the no more messages at an earlier point in time have to be processed.
+     *
+     * @param duration The duration of simulation time to hold before resuming execution.
+     */
+    suspend fun hold(duration: Duration)
+
+    /**
+     * Suspend the [Context] of the [Entity] in simulation for the given duration of simulation time before resuming
+     * execution and push all messages that are received during this period to the given queue.
+     *
+     * A call to this method will not make the [Context] sleep for the actual duration of time, but instead suspend
+     * the process until the no more messages at an earlier point in time have to be processed.
+     *
+     * @param duration The duration of simulation time to wait before resuming execution.
+     * @param queue The mutable queue to push the messages to.
+     */
+    suspend fun hold(duration: Duration, queue: Queue<Any>)
+
+    /**
+     * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is
+     * empty. The execution is resumed after the head of the mailbox is removed and returned.
+     *
+     * @return The received message.
+     */
+    suspend fun receive(): Any
+
+    /**
+     * Retrieve and remove a single message from the instance's mailbox, suspending the function if the mailbox is
+     * empty. The execution is either resumed after the head of the mailbox is removed and returned or when the timeout
+     * has been reached.
+     *
+     * @return The received message or `null` if the timeout was reached.
+     */
+    suspend fun receive(timeout: Duration): Any?
+
+    /**
+     * Send the given message to the specified entity, without providing any guarantees about the actual delivery of
+     * the message.
+     *
+     * @param msg The message to send.
+     * @param sender The sender of the message.
+     * @param delay The amount of time to wait before the message should be received by the entity.
+     */
+    suspend fun Entity<*, *>.send(msg: Any, sender: Entity<*, *>, delay: Duration = 0)
+
+    /**
+     * Send the given message to the specified entity, without providing any guarantees about the actual delivery of
+     * the message.
+     *
+     * @param msg The message to send.
+     * @param delay The amount of time to wait before the message should be received by the entity.
+     */
+    suspend fun Entity<*, *>.send(msg: Any, delay: Duration = 0) = send(msg, self, delay)
+
+    /**
+     * This key provides users access to an untyped process context in case the coroutine runs inside a simulation.
+     */
+    companion object Key : CoroutineContext.Key<Context<*, *>>
+}
+
+/**
+ * An [Interrupt] message is sent to an [Entity] process in order to interrupt its suspended state.
+ *
+ * @param reason The reason for the interruption of the process.
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+open class Interrupt(reason: String) : Throwable(reason)
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt
new file mode 100644
index 00000000..56704c5d
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Entity.kt
@@ -0,0 +1,44 @@
+/*
+ * 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
+
+/**
+ * An entity in some model `M`.
+ *
+ * <p>A [Entity] directly contains its immutable properties that remain unchanged during simulation.
+ *
+ * <p>In addition, other entities in simulation have direct, immutable access to the observable state of this entity.
+ *
+ * @param S The shape of the observable state of this entity, which is directly accessible by other components within
+ * a simulation.
+ * @param M The shape of the model in which the entity exists.
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Entity<out S, in M> {
+    /**
+     * The initial state of the entity.
+     */
+    val initialState: S
+}
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt
new file mode 100644
index 00000000..f2b8a52b
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Process.kt
@@ -0,0 +1,27 @@
+package com.atlarge.opendc.simulator
+
+/**
+ * A process is dynamic entity within a simulation, that interacts with the model environment by the interchange of
+ * messages.
+ *
+ * @param S The shape of the observable state of the process.
+ * @param M The shape of the model in which the process exists.
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Process<S, M> : Entity<S, M> {
+    /**
+     * This method is invoked to start the simulation a process.
+     *
+     * This method is assumed to be running during a simulation, but should hand back control to the simulator at
+     * some point by suspending the process. This allows other processes to do work at the current point in time of the
+     * simulation.
+     * Suspending the process can be achieved by calling suspending method in the context:
+     * 	- [Context.hold]	- Hold for `n` units of time before resuming execution.
+     * 	- [Context.receive]	- Wait for a message to be received in the mailbox of the [Entity] before resuming
+     * 	execution.
+     *
+     * If this method exits early, before the simulation has finished, the entity is assumed to be shutdown and its
+     * simulation will not run any further.
+     */
+    suspend fun Context<S, M>.run()
+}
diff --git a/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Time.kt b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Time.kt
new file mode 100644
index 00000000..64e3cb80
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/Time.kt
@@ -0,0 +1,35 @@
+/*
+ * 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
+
+/**
+ * An instantaneous point on the time-line, used to record event time-stamps in a simulation.
+ */
+typealias Instant = Long
+
+/**
+ * A time interval which represents the amount of elapsed time between two events.
+ */
+typealias Duration = Long
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
new file mode 100644
index 00000000..d4995283
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/kernel/Kernel.kt
@@ -0,0 +1,43 @@
+/*
+ * 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 message-based discrete event simulator (DES). This interface is a factory for creating [Simulation]s using the
+ * provided [Bootstrap] for the model.
+ *
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Kernel {
+    /**
+     * Create a simulation over the given model facilitated by this simulation kernel.
+     *
+     * @param bootstrap The apply procedure to apply the simulation with.
+     * @return A [Simulation] instance representing the simulation.
+     */
+    fun <M> create(bootstrap: Bootstrap<M>): Simulation<M>
+}
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<out M> {
+    /**
+     * 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 <E : Entity<S, *>, 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
new file mode 100644
index 00000000..eb959ded
--- /dev/null
+++ b/opendc-core/src/main/kotlin/com/atlarge/opendc/simulator/platform/Experiment.kt
@@ -0,0 +1,52 @@
+/*
+ * 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.platform
+
+import com.atlarge.opendc.simulator.Duration
+import com.atlarge.opendc.simulator.kernel.Kernel
+
+/**
+ * A blueprint for a reproducible simulation in a pre-defined setting.
+ *
+ * @author Fabian Mastenbroek (f.s.mastenbroek@student.tudelft.nl)
+ */
+interface Experiment<out T> {
+    /**
+     * Run the experiment on the specified kernel implementation.
+     *
+     * @param factory The factory to create the simulation kernel with.
+     * @return The result of the experiment.
+     */
+    fun run(factory: Kernel): T
+
+    /**
+     * Run the experiment on the specified kernel implementation.
+     *
+     * @param factory The factory to create the simulation kernel with.
+     * @param timeout The maximum duration of the experiment before returning to the caller.
+     * @return The result of the experiment or `null`.
+     */
+    fun run(factory: Kernel, timeout: Duration): T?
+}