simulator: Add core module for network simulation

This change adds a basic framework as basis for network simulation support
in OpenDC. It is modelled similarly to the power system that has been
added recently.

3 files changed, 178 insertions, 0 deletions

diff --git a/opendc-simulator/opendc-simulator-network/src/main/kotlin/org/opendc/simulator/network/SimNetworkLink.kt b/opendc-simulator/opendc-simulator-network/src/main/kotlin/org/opendc/simulator/network/SimNetworkLink.kt
new file mode 100644
index 00000000..67562640
--- /dev/null
+++ b/opendc-simulator/opendc-simulator-network/src/main/kotlin/org/opendc/simulator/network/SimNetworkLink.kt
@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2021 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 org.opendc.simulator.network
+
+/**
+ * A physical bi-directional communication link between two [SimNetworkPort]s.
+ *
+ * @param left The first port of the link.
+ * @param right The second port of the link.
+ */
+public class SimNetworkLink(public val left: SimNetworkPort, public val right: SimNetworkPort) {
+    /**
+     * Determine whether the specified [port] participates in this network link.
+     */
+    public operator fun contains(port: SimNetworkPort): Boolean = port == left || port == right
+
+    /**
+     * Obtain the opposite port to which the specified [port] is connected through this link.
+     */
+    public fun opposite(port: SimNetworkPort): SimNetworkPort {
+        return when (port) {
+            left -> right
+            right -> left
+            else -> throw IllegalArgumentException("Invalid port given")
+        }
+    }
+
+    override fun toString(): String = "SimNetworkLink[left=$left,right=$right]"
+}
diff --git a/opendc-simulator/opendc-simulator-network/src/main/kotlin/org/opendc/simulator/network/SimNetworkPort.kt b/opendc-simulator/opendc-simulator-network/src/main/kotlin/org/opendc/simulator/network/SimNetworkPort.kt
new file mode 100644
index 00000000..e5b85dd1
--- /dev/null
+++ b/opendc-simulator/opendc-simulator-network/src/main/kotlin/org/opendc/simulator/network/SimNetworkPort.kt
@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2021 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 org.opendc.simulator.network
+
+import org.opendc.simulator.resources.SimResourceConsumer
+import org.opendc.simulator.resources.SimResourceProvider
+
+/**
+ * A network port allows network devices to be connected to network through links.
+ */
+public abstract class SimNetworkPort {
+    /**
+     * A flag to indicate that the network port is connected to another port.
+     */
+    public val isConnected: Boolean
+        get() = _link != null
+
+    /**
+     * The network link which connects this port to another port.
+     */
+    public val link: SimNetworkLink?
+        get() = _link
+    private var _link: SimNetworkLink? = null
+
+    /**
+     * Connect this port to the specified [port].
+     */
+    public fun connect(port: SimNetworkPort) {
+        require(port !== this) { "Circular reference" }
+        check(!isConnected) { "Port already connected" }
+        check(!port.isConnected) { "Target port already connected" }
+
+        val link = SimNetworkLink(this, port)
+        _link = link
+        port._link = link
+
+        // Start bi-directional flow channel between the two ports
+        provider.startConsumer(port.createConsumer())
+        port.provider.startConsumer(createConsumer())
+    }
+
+    /**
+     * Disconnect the current network link if it exists.
+     */
+    public fun disconnect() {
+        val link = _link ?: return
+        val opposite = link.opposite(this)
+        _link = null
+        opposite._link = null
+
+        provider.cancel()
+        opposite.provider.cancel()
+    }
+
+    /**
+     * Create a [SimResourceConsumer] which generates the outgoing traffic of this port.
+     */
+    protected abstract fun createConsumer(): SimResourceConsumer
+
+    /**
+     * The [SimResourceProvider] which processes the ingoing traffic of this port.
+     */
+    protected abstract val provider: SimResourceProvider
+
+    override fun toString(): String = "SimNetworkPort[isConnected=$isConnected]"
+}
diff --git a/opendc-simulator/opendc-simulator-network/src/main/kotlin/org/opendc/simulator/network/SimNetworkSink.kt b/opendc-simulator/opendc-simulator-network/src/main/kotlin/org/opendc/simulator/network/SimNetworkSink.kt
new file mode 100644
index 00000000..5efdbed9
--- /dev/null
+++ b/opendc-simulator/opendc-simulator-network/src/main/kotlin/org/opendc/simulator/network/SimNetworkSink.kt
@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2021 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 org.opendc.simulator.network
+
+import org.opendc.simulator.resources.*
+
+/**
+ * A network sink which discards all received traffic and does not generate any traffic itself.
+ */
+public class SimNetworkSink(
+    interpreter: SimResourceInterpreter,
+    public val capacity: Double
+) : SimNetworkPort() {
+    override fun createConsumer(): SimResourceConsumer = object : SimResourceConsumer {
+        override fun onNext(ctx: SimResourceContext): SimResourceCommand = SimResourceCommand.Idle()
+
+        override fun toString(): String = "SimNetworkSink.Consumer"
+    }
+
+    override val provider: SimResourceProvider = SimResourceSource(capacity, interpreter)
+
+    override fun toString(): String = "SimNetworkSink[capacity=$capacity]"
+}