feat(minor): Add Benchmark parameters

Sometimes it is convenient to run the same benchmark multiple times under slightly different scenarios.
For example, benchmarking `func foo(_ n: Int)` for various parameterizations of `n`.
This adds support for specifying the parameters of a benchmark but makes no functional changes beyond the name/identifier of a benchmark now including a parameter list when one was provided.

This unlocks the potential for the benchmark exporters (such as the Influx exporter) to leverage these parameters (by emitting appropriate tags/fields in the case of Influx) in their output.

Sources/Benchmark/Benchmark.swift

@@ -69,8 +69,28 @@ public final class Benchmark: Codable, Hashable {
     #endif
     public static var benchmarks: [Benchmark] = [] // Bookkeeping of all registered benchmarks
 
+    /// The default name used for display purposes of the benchmark when no parameters exist.
+    private var baseName: String
+
     /// The name used for display purposes of the benchmark (also used for matching when comparing to baselines)
-    public var name: String
+    public var name: String {
+        get {
+            if configuration.parameters.isEmpty {
+                baseName
+            } else {
+                baseName
+                    + " ("
+                    + configuration.parameters
+                        .sorted(by: { $0.name < $1.name })
+                        .map({ "\($0.name): \($0.value)" })
+                        .joined(separator: ", ")
+                    + ")"
+            }
+        }
+        set {
+            baseName = newValue
+        }
+    }
 
     /// The reason for a benchmark failure, not set if successful
     public var failureReason: String?
@@ -119,6 +139,7 @@ public final class Benchmark: Codable, Hashable {
 
     /// Hook for setting defaults for a whole benchmark suite
     public static var defaultConfiguration: Configuration = .init(metrics: BenchmarkMetric.default,
+                                                                  parameters: [],
                                                                   timeUnits: .automatic,
                                                                   warmupIterations: 1,
                                                                   scalingFactor: .one,
@@ -131,7 +152,7 @@ public final class Benchmark: Codable, Hashable {
     var measurementCompleted = false // Keep track so we skip multiple 'end of measurement'
 
     enum CodingKeys: String, CodingKey {
-        case name
+        case baseName = "name"
         case target
         case executablePath
         case configuration
@@ -168,7 +189,7 @@ public final class Benchmark: Codable, Hashable {
             return nil
         }
         target = ""
-        self.name = name
+        self.baseName = name
         self.configuration = configuration
         self.closure = closure
         self.setup = setup
@@ -193,7 +214,7 @@ public final class Benchmark: Codable, Hashable {
             return nil
         }
         target = ""
-        self.name = name
+        self.baseName = name
         self.configuration = configuration
         asyncClosure = closure
         self.setup = setup
@@ -362,6 +383,8 @@ public extension Benchmark {
     struct Configuration: Codable {
         /// Defines the metrics that should be measured for the benchmark
         public var metrics: [BenchmarkMetric]
+        /// Specifies the parameters used to define the benchmark.
+        public var parameters: [BenchmarkParameter]
         /// Override the automatic detection of timeunits for metrics related to time to a specific
         /// one (auto should work for most use cases)
         public var timeUnits: BenchmarkTimeUnits
@@ -386,6 +409,7 @@ public extension Benchmark {
         public var teardown: BenchmarkTeardownHook?
 
         public init(metrics: [BenchmarkMetric] = defaultConfiguration.metrics,
+                    parameters: [BenchmarkParameter] = defaultConfiguration.parameters,
                     timeUnits: BenchmarkTimeUnits = defaultConfiguration.timeUnits,
                     warmupIterations: Int = defaultConfiguration.warmupIterations,
                     scalingFactor: BenchmarkScalingFactor = defaultConfiguration.scalingFactor,
@@ -397,6 +421,7 @@ public extension Benchmark {
                     setup: BenchmarkSetupHook? = nil,
                     teardown: BenchmarkTeardownHook? = nil) {
             self.metrics = metrics
+            self.parameters = parameters
             self.timeUnits = timeUnits
             self.warmupIterations = warmupIterations
             self.scalingFactor = scalingFactor
@@ -411,6 +436,7 @@ public extension Benchmark {
         // swiftlint:disable nesting
         enum CodingKeys: String, CodingKey {
             case metrics
+            case parameters
             case timeUnits
             case warmupIterations
             case scalingFactor

Sources/Benchmark/BenchmarkParameter.swift

@@ -0,0 +1,58 @@
+
+/// Represents a parameter used to define the implementation of a benchmark.
+/// Useful for running the same benchmark under a set of unique scenarios.
+///
+/// For example, running multiple benchmarks of `func foo(_ n:Int)`
+/// for various parameterizations of `n`.
+public struct BenchmarkParameter: Codable {
+    public let name: String
+
+    /// Describes the range of possible values for this parameter.
+    public let range: Range
+    public enum Range: Codable { case finite, infinite }
+
+    public let value: Value
+
+    /// Represents a value that may be one of a set of allowed types.
+    public enum Value: Codable {
+        case string(String)
+        case int(Int)
+        case double(Double)
+    }
+
+    public init(_ name: String, _ value: Value, range: Range) {
+        self.name = name
+        self.value = value
+        self.range = range
+    }
+}
+
+extension BenchmarkParameter.Value: CustomStringConvertible {
+    public var description: String {
+        switch self {
+            case let .string(string):
+                string
+            case let .int(int):
+                int.description
+            case let .double(double):
+                double.description
+        }
+    }
+}
+
+
+extension BenchmarkParameter.Value: ExpressibleByStringLiteral {
+    public init(stringLiteral value: StringLiteralType) {
+        self = .string(value)
+    }
+}
+extension BenchmarkParameter.Value: ExpressibleByIntegerLiteral {
+    public init(integerLiteral value: IntegerLiteralType) {
+        self = .int(value)
+    }
+}
+extension BenchmarkParameter.Value: ExpressibleByFloatLiteral {
+    public init(floatLiteral value: FloatLiteralType) {
+        self = .double(value)
+    }
+}

Tests/BenchmarkTests/BenchmarkTests.swift

@@ -73,4 +73,16 @@ final class BenchmarkTests: XCTestCase {
         XCTAssertNotNil(benchmark)
         benchmark?.run()
     }
+
+    func testBenchmarkParameterizedDescription() throws {
+        let benchmark = Benchmark("testBenchmarkParameterizedDescription benchmark",
+                                  configuration: .init(
+                                    parameters: [
+                                        BenchmarkParameter("foo", .string("bar"), range: .finite),
+                                        BenchmarkParameter("bin", .int(42), range: .infinite),
+                                    ]
+                                  )) { _ in }
+        XCTAssertNotNil(benchmark)
+        XCTAssertEqual(benchmark?.name, "testBenchmarkParameterizedDescription benchmark (bin: 42, foo: bar)")
+    }
 }