Class BenchmarkRunInfos

A wrapper and extension for BenchmarkConverter, collecting the converted benchmarks, executing them, and optionally overriding any global and local Job configurations.

As a minor benefit, BenchmarkRunInfos simplifies the use of BenchmarkConverter:

• You can store the global config to use in the Config property instead of passing it as an argument in each call to a conversion method.
• The results of all conversions are automatically collected and by calling RunAll() afterwards, you can execute them.
• BenchmarkRunInfos also provides two additional conversion methods for converting an entire Assembly and for converting methods by their name instead of their MethodInfo.

However, the main purpose of BenchmarkRunInfos is the support of debugging scenarios:

• Specifying an OverrideJob will override all Job configurations, regardless whether they are defined globally or locally, as an explit, default or mutator job, via custom config or via attribute annotation.
• Even if your config contains multiple jobs or you have annotated your benchmark classes with multiple jobs (e.g. via [DryJob, ShortRunJob] or similar attributes), each converted benchmark method will only be executed with the override job.
• To achieve that, you don't have to change the coding of your configurations, just add a few extra statements to your Main method that will get executed under certain conditions.

Note

It may seem that instead of using BenchmarkRunInfos and OverrideJob in a debugging scenario, you could just create a different global config and set its UnionRule property to ConfigUnionRule.AlwaysUseGlobal.

That however will have no effect at all, because BenchmarkDotNet always takes the UnionRule from the local config.

Inheritance

Object

BenchmarkRunInfos

Namespace: Mawosoft.Extensions.BenchmarkDotNet

Assembly: Mawosoft.Extensions.BenchmarkDotNet.dll

Syntax

public class BenchmarkRunInfos : Object

Examples

public static void Main(string[] args)
{
    // Your customized global config (Default used here for simplicity)
    ManualConfig config = ManualConfig.Create(DefaultConfig.Instance);
    if (Debugger.IsAttached && args.Length == 0)
    {
        // Debugging scenario
        BenchmarkRunInfos runInfos = new();
        runInfos.Config = config
            .WithOption(ConfigOptions.DisableOptimizationsValidator, true);
        runInfos.OverrideJob = BenchmarkRunInfos.FastInProcessJob;
        // Pick only the methods you want to debug
        runInfos.ConvertMethodsToBenchmarks(typeof(MyClass1), "Method1", "Method2");
        runInfos.ConvertMethodsToBenchmarks(typeof(MyClass2), "Method3");
        runInfos.RunAll();
    }
    else
    {
        // Regular scenario
        BenchmarkRunner.Run(typeof(Program).Assembly, config, args);
    }
}

Constructors

BenchmarkRunInfos()

Initializes a new instance of the BenchmarkRunInfos class.

Declaration

public BenchmarkRunInfos()

BenchmarkRunInfos(IConfig, Job)

Initializes a new instance of the BenchmarkRunInfos class with an optional global config and an optional override job.

Declaration

public BenchmarkRunInfos(IConfig globalConfig, Job overrideJob)

Parameters

Type	Name	Description
IConfig	globalConfig	The global config to use for conversions, or null to use BenchmarkDotNet's default config.
Job	overrideJob	The override job to use, or null to not use an override job at all.

Remarks

You can change the Config and OverrideJob properties at any time. This will not affect any benchmarks already converted, only subsequent benchmark conversions.

The predefined FastInProcessJob is the best choice for debugging, but you can also define your own job if you prefer.

Fields

FastInProcessJob

A predefined Job instance that can be used as override job.

Declaration

public static readonly Job FastInProcessJob

Field Value

Type	Description
Job	The predefined Job instance.

Remarks

FastInProcessJob is equivalent to Job.Dry.WithToolchain(InProcessEmitToolchain.Instance).

Properties

Config

Gets or sets the global config to use for subsequent benchmark conversions.

Declaration

public IConfig Config { get; set; }

Property Value

Type	Description
IConfig	The global config to use for conversions, or null to use BenchmarkDotNet's default config.

Remarks

You can change the Config property at any time. This will not affect any benchmarks already converted, only subsequent benchmark conversions.

Count

Gets the number of converted BenchmarkRunInfo elements.

Declaration

public int Count { get; }

Property Value

Type	Description
Int32	The number of converted benchmarks.

Item[Int32]

Gets the converted BenchmarkRunInfo element at the specified index.

Declaration

public BenchmarkRunInfo this[int index] { get; }

Parameters

Type	Name	Description
Int32	index	The zero-based index of the element to get.

Property Value

Type	Description
BenchmarkRunInfo	The element at the specified index.

Items

Gets a read-only collection of the converted benchmarks.

Declaration

public IReadOnlyList<BenchmarkRunInfo> Items { get; }

Property Value

Type	Description
IReadOnlyList<BenchmarkRunInfo>	The read-only collection of the converted benchmarks.

OverrideJob

Gets or sets the override job to use for subsequent benchmark conversions.

Declaration

public Job OverrideJob { get; set; }

Property Value

Type	Description
Job	The override job to use, or null to not use an override job at all.

Remarks

You can change the OverrideJob property at any time. This will not affect any benchmarks already converted, only subsequent benchmark conversions.

The predefined FastInProcessJob is the best choice for debugging, but you can also define your own job if you prefer.

Methods

Add(BenchmarkRunInfo)

Adds a BenchmarkRunInfo element and applies the OverrideJob if one is specified.

Note

Since BenchmarkRunInfo already contains converted benchmarks, an eventual Config will not be applied.

Declaration

public void Add(BenchmarkRunInfo benchmarkRunInfo)

Parameters

Type	Name	Description
BenchmarkRunInfo	benchmarkRunInfo	The BenchmarkRunInfo element to be added.

AddRange(IEnumerable<BenchmarkRunInfo>)

Adds a collection of BenchmarkRunInfo elements and applies the OverrideJob if one is specified.

Note

Since BenchmarkRunInfo already contains converted benchmarks, an eventual Config will not be applied.

Declaration

public void AddRange(IEnumerable<BenchmarkRunInfo> benchmarkRunInfos)

Parameters

Type	Name	Description
IEnumerable<BenchmarkRunInfo>	benchmarkRunInfos	The collection of BenchmarkRunInfo elements to be added.

Clear(Boolean)

Clears the list of BenchmarkRunInfo elements and optionally disposes them.

Declaration

public void Clear(bool dispose)

Parameters

Type	Name	Description
Boolean	dispose	true to dispose all benchmarks, false to only remove them from the list without disposal.

ConvertAssemblyToBenchmarks(Assembly)

Converts all types with benchmarks in the given assembly and stores the results.

An eventual Config and OverrideJob will be applied.

Declaration

public void ConvertAssemblyToBenchmarks(Assembly assembly)

Parameters

Type	Name	Description
Assembly	assembly	The assembly containing the benchmark classes and methods.

ConvertMethodsToBenchmarks(Type, MethodInfo[])

Converts the specified benchmark methods of the given type and stores the results.

An eventual Config and OverrideJob will be applied.

Declaration

public void ConvertMethodsToBenchmarks(Type containingType, params MethodInfo[] benchmarkMethods)

Parameters

Type	Name	Description
Type	containingType	The Type of the class containing the benchmark methods.
MethodInfo[]	benchmarkMethods	An array of MethodInfo objects describing the benchmark methods.

ConvertMethodsToBenchmarks(Type, String[])

Converts the named benchmark methods of the given type and stores the results.

An eventual Config and OverrideJob will be applied.

Note

The method names must be unambigious, otherwise the conversion will fail.

Declaration

public void ConvertMethodsToBenchmarks(Type containingType, params string[] benchmarkMethodNames)

Parameters

Type	Name	Description
Type	containingType	The Type of the class containing the benchmark methods.
String[]	benchmarkMethodNames	An array of strings containing the names of the benchmark methods.

ConvertSourceToBenchmarks(String)

Compiles the given C# source code, converts the contained benchmark methods, and stores the results.

An eventual Config and OverrideJob will be applied.

Declaration

public void ConvertSourceToBenchmarks(string source)

Parameters

Type	Name	Description
String	source	A string containing the C# source code to compile.

ConvertTypeToBenchmarks(Type)

Converts all benchmark methods of the given type and stores the results.

An eventual Config and OverrideJob will be applied.

Declaration

public void ConvertTypeToBenchmarks(Type type)

Parameters

Type	Name	Description
Type	type	The Type of the class containing the benchmark methods.

ConvertUrlToBenchmarks(String)

Reads and compiles C# source code from the given Url, converts the contained benchmark methods, and stores the results.

An eventual Config and OverrideJob will be applied.

Declaration

public void ConvertUrlToBenchmarks(string url)

Parameters

Type	Name	Description
String	url	A string containing the Url to read the C# source code from.

DebugUseDefaultOverrideJob()

Sets the predefined override job (FastInProcessJob) when called from code compiled with the conditional DEBUG symbol defined.

Declaration

public void DebugUseDefaultOverrideJob()

RunAll()

Runs all converted benchmarks and returns the results.

Declaration

public Summary[] RunAll()

Returns

Type	Description
Summary[]	An array of Summary objects containing the benchmark results.

See Also

BenchmarkRunInfos Sample on GitHub