From 4a8b32d288ba3ee986ecef7933fa77554d34e762 Mon Sep 17 00:00:00 2001 From: Fabian Mastenbroek Date: Tue, 4 May 2021 19:19:47 +0200 Subject: harness: Split harness into separate modules This change splits the OpenDC Experiment Harness into separate modules. This prevents users from pulling in unnecessary dependencies when depending on the harness API. --- .../org/opendc/harness/api/ExperimentDefinition.kt | 39 +++++++++ .../kotlin/org/opendc/harness/api/Parameter.kt | 38 +++++++++ .../main/kotlin/org/opendc/harness/api/Scenario.kt | 46 ++++++++++ .../main/kotlin/org/opendc/harness/api/Trial.kt | 28 ++++++ .../kotlin/org/opendc/harness/dsl/Experiment.kt | 99 ++++++++++++++++++++++ .../org/opendc/harness/dsl/ParameterProvider.kt | 39 +++++++++ .../kotlin/org/opendc/harness/dsl/Parameters.kt | 44 ++++++++++ .../opendc/harness/internal/ParameterDelegate.kt | 43 ++++++++++ 8 files changed, 376 insertions(+) create mode 100644 opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/ExperimentDefinition.kt create mode 100644 opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Parameter.kt create mode 100644 opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Scenario.kt create mode 100644 opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Trial.kt create mode 100644 opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/dsl/Experiment.kt create mode 100644 opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/dsl/ParameterProvider.kt create mode 100644 opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/dsl/Parameters.kt create mode 100644 opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/internal/ParameterDelegate.kt (limited to 'opendc-harness/opendc-harness-api/src') diff --git a/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/ExperimentDefinition.kt b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/ExperimentDefinition.kt new file mode 100644 index 00000000..c90717d2 --- /dev/null +++ b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/ExperimentDefinition.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.api + +/** + * A definition for a repeatable experiment which consists of multiple scenarios derived from pre-defined experiment + * parameters. + * + * @property name The name of the experiment. + * @property parameters The parameters of the experiments. + * @property evaluator The function to evaluate a single experiment trial. + * @property meta The metadata for the experiment. + */ +public data class ExperimentDefinition( + val name: String, + val parameters: Set>, + val evaluator: (Trial) -> Unit, + val meta: Map = emptyMap() +) diff --git a/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Parameter.kt b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Parameter.kt new file mode 100644 index 00000000..1f4fdde1 --- /dev/null +++ b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Parameter.kt @@ -0,0 +1,38 @@ +/* + * 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.api + +/** + * A [Parameter] defines a single dimension of exploration in the design space of an experiment. + */ +public sealed class Parameter { + /** + * The name of the parameter. + */ + public abstract val name: String + + /** + * A generic dimension of the experiment design space that is defined fully by a collection of [values]. + */ + public data class Generic(override val name: String, val values: Collection) : Parameter() +} diff --git a/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Scenario.kt b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Scenario.kt new file mode 100644 index 00000000..a8dbf01e --- /dev/null +++ b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Scenario.kt @@ -0,0 +1,46 @@ +/* + * 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.api + +/** + * A [Scenario] represents a single point in the design space of an experiment. + */ +public interface Scenario { + /** + * A unique identifier that identifies a single scenario. + */ + public val id: Int + + /** + * The [ExperimentDefinition] describing the experiment this scenario is part of. + */ + public val experiment: ExperimentDefinition + + /** + * Obtain the instantiated value for a [parameter][param] of the experiment. + * + * @param param The parameter to obtain the value of. + * @throws IllegalArgumentException if [param] is not defined for the experiment. + */ + public operator fun get(param: Parameter): T +} diff --git a/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Trial.kt b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Trial.kt new file mode 100644 index 00000000..2d6ecd19 --- /dev/null +++ b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/api/Trial.kt @@ -0,0 +1,28 @@ +/* + * 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.api + +/** + * A [Trial] represents a single trial (run) of an experiment. + */ +public data class Trial(val scenario: Scenario, val repeat: Int) diff --git a/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/dsl/Experiment.kt b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/dsl/Experiment.kt new file mode 100644 index 00000000..41d4207a --- /dev/null +++ b/opendc-harness/opendc-harness-api/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> = 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/opendc-harness-api/src/main/kotlin/org/opendc/harness/dsl/ParameterProvider.kt b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/dsl/ParameterProvider.kt new file mode 100644 index 00000000..e4bb9c64 --- /dev/null +++ b/opendc-harness/opendc-harness-api/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 { + /** + * 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 +} diff --git a/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/dsl/Parameters.kt b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/dsl/Parameters.kt new file mode 100644 index 00000000..7d269ba1 --- /dev/null +++ b/opendc-harness/opendc-harness-api/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 anyOf(vararg values: T): ParameterProvider = object : ParameterProvider { + override fun provideDelegate(experiment: Experiment, prop: KProperty<*>): ReadOnlyProperty { + val delegate = ParameterDelegate(Parameter.Generic(prop.name, listOf(*values))) + experiment.register(delegate) + return delegate + } + + override fun toString(): String = "GenericParameter" +} diff --git a/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/internal/ParameterDelegate.kt b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/internal/ParameterDelegate.kt new file mode 100644 index 00000000..aaf90b99 --- /dev/null +++ b/opendc-harness/opendc-harness-api/src/main/kotlin/org/opendc/harness/internal/ParameterDelegate.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.harness.internal + +import org.opendc.harness.api.Parameter +import org.opendc.harness.dsl.Experiment +import kotlin.properties.ReadOnlyProperty +import kotlin.reflect.KProperty + +/** + * A delegate for an experiment parameter. + * + * @property parameter The parameter descriptor of this delegate. + */ +internal class ParameterDelegate(val parameter: Parameter) : ReadOnlyProperty { + /** + * Obtain the value for the parameter. + */ + override fun getValue(thisRef: Experiment, property: KProperty<*>): T { + val scenario = thisRef.scenario ?: throw IllegalStateException("Cannot use parameters before activation") + return scenario[parameter] + } +} -- cgit v1.2.3