144 lines
9.3 KiB
C#
144 lines
9.3 KiB
C#
using System;
|
|
|
|
namespace Unity.PerformanceTesting.Benchmark
|
|
{
|
|
/// <summary>
|
|
/// Mark a class containing performance tests for use in benchmark comparison generation. Each variant defined in the enum Type
|
|
/// will be ran and measured for comparison when running benchmarking. The variants in the enum also create mulitple
|
|
/// appropriate Performance Test Framework tests for regression testing. See <see cref="BenchmarkComparisonAttribute"/> for more information
|
|
/// on the enum definition.
|
|
/// </summary>
|
|
[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
|
|
public class BenchmarkAttribute : Attribute
|
|
{
|
|
/// <summary>
|
|
/// Specify the enum Type to form benchmark comparisons around.
|
|
/// </summary>
|
|
/// <param name="benchmarkComparisonEnum">The enum Type which defines variants of a performance test to compare with each other in benchmarking</param>
|
|
/// <param name="ignoreInSuite">If true, when <see cref="BenchmarkGenerator.GenerateMarkdown(string, Type, string, string, string, string[])"/> is called
|
|
/// with this `benchmarkComparisonEnum` type, don't include this class of performance in benchmark report generation.</param>
|
|
public BenchmarkAttribute(Type benchmarkComparisonEnum, bool ignoreInSuite = false) { }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Mark an enum as defining benchmarking variants.<para />
|
|
/// Each variant defined in the enum Type will be ran and measured for comparison when running benchmarking. The variants in the
|
|
/// enum also create multiple appropriate Performance Test Framework tests for regression testing.<para />
|
|
/// When defining a benchmark, a baseline must also be specified. This can be part of the enum values, or external. Any non-baseline variants meant
|
|
/// for benchmarking only and not for Performance Test Framework tests can be defined external to the enum using <see cref="BenchmarkComparisonExternalAttribute"/>.
|
|
/// </summary>
|
|
[AttributeUsage(AttributeTargets.Enum, AllowMultiple = false, Inherited = false)]
|
|
public class BenchmarkComparisonAttribute : Attribute
|
|
{
|
|
/// <summary>
|
|
/// Mark the enum for use in Benchmark comparisons and specify the enum value which will also serve as the baseline for speed-up calculations
|
|
/// </summary>
|
|
/// <param name="baselineEnumValue">The enum value, cast to int, to be the baseline</param>
|
|
public BenchmarkComparisonAttribute(int baselineEnumValue) { }
|
|
|
|
/// <summary>
|
|
/// Mark the enum for use in Benchmark comparisons and specify the a non-enum value which will also serve as the baseline for speed-up calculations.
|
|
/// This external value will not be included in Performance Test Framework testing.
|
|
/// </summary>
|
|
/// <param name="externalBaselineValue">The external value, unique from any of the enum values, to be the baseline</param>
|
|
/// <param name="externalBaselineFormat">The string format such as "Native{0}" or "Unsafe{0}" for name formatting in report generation. Only index 0 is supported here.</param>
|
|
public BenchmarkComparisonAttribute(int externalBaselineValue, string externalBaselineFormat) { }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Further define a benchmark comparison (see <see cref="BenchmarkComparisonAttribute"/>) which is not defined in the enum and is not a baseline
|
|
/// measurement. Some benchmarks may want to compare against multiple other implementations that aren't intended for Performance Test Framework
|
|
/// and regression testing, so this provides a means of specifying these.
|
|
/// </summary>
|
|
[AttributeUsage(AttributeTargets.Enum, AllowMultiple = true, Inherited = false)]
|
|
public class BenchmarkComparisonExternalAttribute : Attribute
|
|
{
|
|
/// <summary>
|
|
/// Specify the value to include in benchmarking which is not defined by the enum itself. See <see cref="BenchmarkComparisonAttribute"/>
|
|
/// </summary>
|
|
/// <param name="externalValue">A value unique to both other external values as well as the enum values</param>
|
|
/// <param name="externalFormat">The string format such as "Native{0}" or "Unsafe{0}" for name formatting in report generation. Only index 0 is supported here.
|
|
/// See <see cref="BenchmarkNameAttribute"/> for more information.</param>
|
|
public BenchmarkComparisonExternalAttribute(int externalValue, string externalFormat) { }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Override the display behaviour of benchmarking results. Be default, results are displayed as the median sample in milliseconds with 3 decimal places.
|
|
/// This is a global setting which effects any benchmark defined by this enum. See <see cref="BenchmarkComparisonAttribute"/>
|
|
/// </summary>
|
|
[AttributeUsage(AttributeTargets.Enum, AllowMultiple = false, Inherited = false)]
|
|
public class BenchmarkComparisonDisplayAttribute : Attribute
|
|
{
|
|
/// <summary>
|
|
/// Specify the display configuration for this benchmark.
|
|
/// </summary>
|
|
/// <param name="unit">Specify the unit type for time measurements, such as milliseconds, seconds, etc. See <see cref="SampleUnit"/></param>
|
|
/// <param name="decimalPlaces">Specify the decimal places for measurement results. Note this is constant and will fill with 0s if needed.</param>
|
|
/// <param name="rankingStatistic">The statistic to display in benchmarking comparisons, such as median, max, etc. See <see cref="BenchmarkRankingStatistic"/></param>
|
|
public BenchmarkComparisonDisplayAttribute(SampleUnit unit, int decimalPlaces, BenchmarkRankingStatistic rankingStatistic) { }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Required with each benchmark enum value. Describes the formatting string for naming benchmarks for this comparison type.<para />
|
|
/// For example `BenchmarkName["Native{0}"]` combined with a class named "HashSet" containing performance test/benchmark methods
|
|
/// will generate "NativeHashSet" in the benchmark results table header. To override the behaviour of inserting the class name
|
|
/// into the {0} format parameter, such as if the class is named "HashSetBenchmarks" and the table header should just insert "HashSet"
|
|
/// for the {0} format parameter, use <see cref="BenchmarkNameOverrideAttribute"/> with the class ("HashSetBenchmarks" in this example).<para />
|
|
/// </summary>
|
|
[AttributeUsage(AttributeTargets.Field, AllowMultiple = false, Inherited = false)]
|
|
public class BenchmarkNameAttribute : Attribute
|
|
{
|
|
/// <summary>
|
|
/// Define the formatting string for an enum value.
|
|
/// </summary>
|
|
/// <param name="name">The string format such as "Native{0}" or "Unsafe{0}" for name formatting in report generation. Only index 0 is supported here.</param>
|
|
public BenchmarkNameAttribute(string name) { }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Overrides the name used in benchmark report table headers as defined with <see cref="BenchmarkNameAttribute"/>. By default the name of the class containing tests is used.
|
|
/// </summary>
|
|
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = false)]
|
|
public class BenchmarkNameOverrideAttribute : Attribute
|
|
{
|
|
/// <summary>
|
|
/// Override the name for all benchmark variants.
|
|
/// </summary>
|
|
/// <param name="name">The name to be used in place of the class name. See <see cref="BenchmarkNameAttribute"/>.</param>
|
|
public BenchmarkNameOverrideAttribute(string name) { }
|
|
|
|
/// <summary>
|
|
/// Override the name for a specified benchmark variant.
|
|
/// </summary>
|
|
/// <param name="benchmarkComparisonValue">The enum defined comparison value (<see cref="BenchmarkComparisonAttribute"/> cast to int or the externally defined
|
|
/// comparison value (<see cref="BenchmarkComparisonExternalAttribute"/>)</param>
|
|
/// <param name="name">The name to be used in place of the class name. See <see cref="BenchmarkNameAttribute"/>.</param>
|
|
public BenchmarkNameOverrideAttribute(int benchmarkComparisonValue, string name) { }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Generate a footnote for this performance test when used in benchmark report generation. This attribute will always insert
|
|
/// a footnote describing the parameters in the performance test, sans the benchmark comparison enum. For example:<para />
|
|
/// <c>public unsafe void AddGrow(<br />
|
|
/// [Values(4, 65536)] int capacity,<br />
|
|
/// [Values(1024 * 1024)] int growTo,<br />
|
|
/// [Values] BenchmarkContainerType type)<br />
|
|
/// {</c><para />
|
|
/// will generate a footnote with "AddGrow(capacity, growTo)" with any use of this attribute on the `AddGrow` method.
|
|
/// </summary>
|
|
[AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = false)]
|
|
public class BenchmarkTestFootnoteAttribute : Attribute
|
|
{
|
|
/// <summary>
|
|
/// Generate a footnote describing the parameter names used in the method.
|
|
/// </summary>
|
|
public BenchmarkTestFootnoteAttribute() { }
|
|
|
|
/// <summary>
|
|
/// Generate a footnote describing the parameters used in the method, as well as a user-defined description.
|
|
/// </summary>
|
|
/// <param name="description">The user defined description to follow the automatically generated method parameters</param>
|
|
public BenchmarkTestFootnoteAttribute(string description) { }
|
|
}
|
|
}
|