summaryrefslogtreecommitdiff
path: root/opendc-harness/src/main/kotlin/org/opendc/harness/dsl
diff options
context:
space:
mode:
authorFabian Mastenbroek <mail.fabianm@gmail.com>2021-04-25 16:01:14 +0200
committerFabian Mastenbroek <mail.fabianm@gmail.com>2021-04-25 16:01:14 +0200
commitcd0b45627f0d8da8c8dc4edde223f3c36e9bcfbf (patch)
tree6ae1681630a0e270c23804e6dbb3bd414ebe5d6e /opendc-harness/src/main/kotlin/org/opendc/harness/dsl
parent128a1db017545597a5c035b7960eb3fd36b5f987 (diff)
build: Migrate to flat project structure
This change updates the project structure to become flattened. Previously, the simulator, frontend and API each lived into their own directory. With this change, all modules of the project live in the top-level directory of the repository. This should improve discoverability of modules of the project.
Diffstat (limited to 'opendc-harness/src/main/kotlin/org/opendc/harness/dsl')
-rw-r--r--opendc-harness/src/main/kotlin/org/opendc/harness/dsl/Experiment.kt99
-rw-r--r--opendc-harness/src/main/kotlin/org/opendc/harness/dsl/ParameterProvider.kt39
-rw-r--r--opendc-harness/src/main/kotlin/org/opendc/harness/dsl/Parameters.kt44
3 files changed, 182 insertions, 0 deletions
diff --git a/opendc-harness/src/main/kotlin/org/opendc/harness/dsl/Experiment.kt b/opendc-harness/src/main/kotlin/org/opendc/harness/dsl/Experiment.kt
new file mode 100644
index 00000000..41d4207a
--- /dev/null
+++ b/opendc-harness/src/main/kotlin/org/opendc/harness/dsl/Experiment.kt
@@ -0,0 +1,99 @@
+/*
+ * 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.harness.dsl
+
+import org.junit.platform.commons.annotation.Testable
+import org.opendc.harness.api.ExperimentDefinition
+import org.opendc.harness.api.Scenario
+import org.opendc.harness.api.Trial
+import org.opendc.harness.internal.ParameterDelegate
+
+/**
+ * An [Experiment] defines a blueprint for a repeatable experiment consisting of multiple scenarios based on pre-defined
+ * experiment parameters.
+ *
+ * @param name The name of the experiment or `null` to select the class name.
+ */
+@Testable
+public abstract class Experiment(name: String? = null) : Cloneable {
+ /**
+ * The name of the experiment.
+ */
+ public val name: String = name ?: javaClass.simpleName
+
+ /**
+ * An identifier that uniquely identifies a single point in the design space of this [Experiment].
+ */
+ public val id: Int
+ get() {
+ val scenario = scenario ?: throw IllegalStateException("Cannot use id before activation")
+ return scenario.id
+ }
+
+ /**
+ * Convert this experiment to an [ExperimentDefinition].
+ */
+ public fun toDefinition(): ExperimentDefinition =
+ ExperimentDefinition(name, HashSet(delegates.map { it.parameter }), this::run, mapOf("class.name" to javaClass.name))
+
+ /**
+ * Perform a single execution of the experiment based on the experiment parameters.
+ *
+ * @param repeat A number representing the repeat index of an identical scenario.
+ */
+ protected abstract fun doRun(repeat: Int)
+
+ /**
+ * A map to track the parameter delegates registered with this experiment.
+ */
+ private val delegates: MutableSet<ParameterDelegate<*>> = mutableSetOf()
+
+ /**
+ * The current active scenario.
+ */
+ internal var scenario: Scenario? = null
+
+ /**
+ * Perform a single execution of the experiment based on the experiment parameters.
+ *
+ * This operation will cause the [ParameterProvider]s of this group to be instantiated to some value in its design
+ * space.
+ *
+ * @param trial The experiment trial to run.
+ */
+ private fun run(trial: Trial) {
+ val scenario = trial.scenario
+
+ // XXX We clone the current class to prevent concurrency issues.
+ val res = clone() as Experiment
+ res.scenario = scenario
+ res.doRun(trial.repeat)
+ }
+
+ /**
+ * Register a delegate for this experiment.
+ */
+ internal fun register(delegate: ParameterDelegate<*>) {
+ delegates += delegate
+ }
+}
diff --git a/opendc-harness/src/main/kotlin/org/opendc/harness/dsl/ParameterProvider.kt b/opendc-harness/src/main/kotlin/org/opendc/harness/dsl/ParameterProvider.kt
new file mode 100644
index 00000000..e4bb9c64
--- /dev/null
+++ b/opendc-harness/src/main/kotlin/org/opendc/harness/dsl/ParameterProvider.kt
@@ -0,0 +1,39 @@
+/*
+ * 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.harness.dsl
+
+import kotlin.properties.ReadOnlyProperty
+import kotlin.reflect.KProperty
+
+/**
+ * A [ParameterProvider] defines a single dimension of exploration in the design space of an [Experiment].
+ */
+public interface ParameterProvider<T> {
+ /**
+ * Provide a delegate defining a parameter for the specified [Experiment][experiment].
+ *
+ * @param experiment The experiment for which the parameter is defined.
+ * @param prop The property to create the delegate for.
+ */
+ public operator fun provideDelegate(experiment: Experiment, prop: KProperty<*>): ReadOnlyProperty<Experiment, T>
+}
diff --git a/opendc-harness/src/main/kotlin/org/opendc/harness/dsl/Parameters.kt b/opendc-harness/src/main/kotlin/org/opendc/harness/dsl/Parameters.kt
new file mode 100644
index 00000000..7d269ba1
--- /dev/null
+++ b/opendc-harness/src/main/kotlin/org/opendc/harness/dsl/Parameters.kt
@@ -0,0 +1,44 @@
+/*
+ * 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.harness.dsl
+
+import org.opendc.harness.api.Parameter
+import org.opendc.harness.internal.ParameterDelegate
+import kotlin.properties.ReadOnlyProperty
+import kotlin.reflect.KProperty
+
+/**
+ * Define a dimension in the design space of an [Experiment] of type [T] consisting of the specified collection of
+ * [values].
+ *
+ * @param values The values in the dimension to define..
+ */
+public fun <T> anyOf(vararg values: T): ParameterProvider<T> = object : ParameterProvider<T> {
+ override fun provideDelegate(experiment: Experiment, prop: KProperty<*>): ReadOnlyProperty<Experiment, T> {
+ val delegate = ParameterDelegate(Parameter.Generic(prop.name, listOf(*values)))
+ experiment.register(delegate)
+ return delegate
+ }
+
+ override fun toString(): String = "GenericParameter"
+}