Introduce CategoryDiscoverer, fix #2306

Author: AndreyAkinshin

docs/articles/samples/IntroCategoryDiscoverer.md

@@ -0,0 +1,26 @@
+---
+uid: BenchmarkDotNet.Samples.IntroCategoryDiscoverer
+---
+
+## Sample: IntroCategoryDiscoverer
+
+The category discovery strategy can be overridden using an instance of `ICategoryDiscoverer`.
+
+### Source code
+
+[!code-csharp[IntroCategoryDiscoverer.cs](../../../samples/BenchmarkDotNet.Samples/IntroCategoryDiscoverer.cs)]
+
+### Output
+
+```markdown
+| Method | Categories | Mean | Error |
+|------- |----------- |---------:|------:|
+| Bar | All,B | 126.5 us | NA |
+| Foo | All,F | 114.0 us | NA |
+```
+
+### Links
+
+* The permanent link to this sample: @BenchmarkDotNet.Samples.IntroCategoryDiscoverer
+
+---

docs/articles/samples/toc.yml

@@ -12,6 +12,8 @@
  href: IntroCategories.md
 - name: IntroCategoryBaseline
  href: IntroCategoryBaseline.md
+- name: IntroCategoryDiscoverer
+ href: IntroCategoryDiscoverer.md
 - name: IntroColdStart
  href: IntroColdStart.md
 - name: IntroComparableComplexParam

samples/BenchmarkDotNet.Samples/IntroCategoryDiscoverer.cs

@@ -0,0 +1,46 @@
+using System;
+using System.Collections.Generic;
+using System.Reflection;
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Configs;
+using BenchmarkDotNet.Running;
+
+namespace BenchmarkDotNet.Samples
+{
+ [DryJob]
+ [CategoriesColumn]
+ [CustomCategoryDiscoverer]
+ public class IntroCategoryDiscoverer
+ {
+ private class CustomCategoryDiscoverer : DefaultCategoryDiscoverer
+ {
+ public override string[] GetCategories(MethodInfo method)
+ {
+ var categories = new List<string>();
+ categories.AddRange(base.GetCategories(method));
+ categories.Add("All");
+ categories.Add(method.Name.Substring(0, 1));
+ return categories.ToArray();
+ }
+ }
+
+ [AttributeUsage(AttributeTargets.Class)]
+ private class CustomCategoryDiscovererAttribute : Attribute, IConfigSource
+ {
+ public CustomCategoryDiscovererAttribute()
+ {
+ Config = ManualConfig.CreateEmpty()
+ .WithCategoryDiscoverer(new CustomCategoryDiscoverer());
+ }
+
+ public IConfig Config { get; }
+ }
+
+
+ [Benchmark]
+ public void Foo() { }
+
+ [Benchmark]
+ public void Bar() { }
+ }
+}

src/BenchmarkDotNet/Attributes/CategoryDiscovererAttribute.cs

@@ -0,0 +1,17 @@
+using System;
+using BenchmarkDotNet.Configs;
+using BenchmarkDotNet.Running;
+
+namespace BenchmarkDotNet.Attributes
+{
+ [AttributeUsage(AttributeTargets.Class)]
+ public class CategoryDiscovererAttribute : Attribute, IConfigSource
+ {
+ public CategoryDiscovererAttribute(bool inherit = true)
+ {
+ Config = ManualConfig.CreateEmpty().WithCategoryDiscoverer(new DefaultCategoryDiscoverer(inherit));
+ }
+
+ public IConfig Config { get; }
+ }
+}

src/BenchmarkDotNet/Configs/DebugConfig.cs

@@ -12,6 +12,7 @@
 using BenchmarkDotNet.Order;
 using BenchmarkDotNet.Portability;
 using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Running;
 using BenchmarkDotNet.Toolchains.InProcess.Emit;
 using BenchmarkDotNet.Validators;
 
@@ -66,6 +67,7 @@ public abstract class DebugConfig : IConfig
  public IEnumerable<IColumnHidingRule> GetColumnHidingRules() => Array.Empty<IColumnHidingRule>();
 
  public IOrderer Orderer => DefaultOrderer.Instance;
+ public ICategoryDiscoverer? CategoryDiscoverer => DefaultCategoryDiscoverer.Instance;
  public SummaryStyle SummaryStyle => SummaryStyle.Default;
  public ConfigUnionRule UnionRule => ConfigUnionRule.Union;
  public TimeSpan BuildTimeout => DefaultConfig.Instance.BuildTimeout;

src/BenchmarkDotNet/Configs/DefaultConfig.cs

@@ -13,6 +13,7 @@
 using BenchmarkDotNet.Order;
 using BenchmarkDotNet.Portability;
 using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Running;
 using BenchmarkDotNet.Validators;
 
 namespace BenchmarkDotNet.Configs
@@ -72,6 +73,7 @@ public IEnumerable<IValidator> GetValidators()
  }
 
  public IOrderer Orderer => null;
+ public ICategoryDiscoverer? CategoryDiscoverer => null;
 
  public ConfigUnionRule UnionRule => ConfigUnionRule.Union;
 

src/BenchmarkDotNet/Configs/IConfig.cs

@@ -10,6 +10,7 @@
 using BenchmarkDotNet.Loggers;
 using BenchmarkDotNet.Order;
 using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Running;
 using BenchmarkDotNet.Validators;
 using JetBrains.Annotations;
 
@@ -30,6 +31,7 @@ public interface IConfig
  IEnumerable<IColumnHidingRule> GetColumnHidingRules();
 
  IOrderer? Orderer { get; }
+ ICategoryDiscoverer? CategoryDiscoverer { get; }
 
  SummaryStyle SummaryStyle { get; }
 
@@ -57,4 +59,4 @@ public interface IConfig
  /// </summary>
  IReadOnlyList<Conclusion> ConfigAnalysisConclusion { get; }
  }
-}
+}

src/BenchmarkDotNet/Configs/ImmutableConfig.cs

@@ -14,7 +14,6 @@
 using BenchmarkDotNet.Reports;
 using BenchmarkDotNet.Running;
 using BenchmarkDotNet.Validators;
-using JetBrains.Annotations;
 using RunMode = BenchmarkDotNet.Diagnosers.RunMode;
 
 namespace BenchmarkDotNet.Configs
@@ -50,6 +49,7 @@ internal ImmutableConfig(
  string artifactsPath,
  CultureInfo cultureInfo,
  IOrderer orderer,
+ ICategoryDiscoverer categoryDiscoverer,
  SummaryStyle summaryStyle,
  ConfigOptions options,
  TimeSpan buildTimeout,
@@ -70,6 +70,7 @@ internal ImmutableConfig(
  ArtifactsPath = artifactsPath;
  CultureInfo = cultureInfo;
  Orderer = orderer;
+ CategoryDiscoverer = categoryDiscoverer;
  SummaryStyle = summaryStyle;
  Options = options;
  BuildTimeout = buildTimeout;
@@ -81,6 +82,7 @@ internal ImmutableConfig(
  public CultureInfo CultureInfo { get; }
  public ConfigOptions Options { get; }
  public IOrderer Orderer { get; }
+ public ICategoryDiscoverer CategoryDiscoverer { get; }
  public SummaryStyle SummaryStyle { get; }
  public TimeSpan BuildTimeout { get; }
 

src/BenchmarkDotNet/Configs/ImmutableConfigBuilder.cs

@@ -7,6 +7,7 @@
 using BenchmarkDotNet.Jobs;
 using BenchmarkDotNet.Order;
 using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Running;
 using BenchmarkDotNet.Validators;
 
 namespace BenchmarkDotNet.Configs
@@ -69,6 +70,7 @@ public static ImmutableConfig Create(IConfig source)
  source.ArtifactsPath ?? DefaultConfig.Instance.ArtifactsPath,
  source.CultureInfo,
  source.Orderer ?? DefaultOrderer.Instance,
+ source.CategoryDiscoverer ?? DefaultCategoryDiscoverer.Instance,
  source.SummaryStyle ?? SummaryStyle.Default,
  source.Options,
  source.BuildTimeout,

src/BenchmarkDotNet/Configs/ManualConfig.cs

@@ -13,6 +13,7 @@
 using BenchmarkDotNet.Loggers;
 using BenchmarkDotNet.Order;
 using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Running;
 using BenchmarkDotNet.Validators;
 using JetBrains.Annotations;
 
@@ -51,6 +52,7 @@ public class ManualConfig : IConfig
  [PublicAPI] public string ArtifactsPath { get; set; }
  [PublicAPI] public CultureInfo CultureInfo { get; set; }
  [PublicAPI] public IOrderer Orderer { get; set; }
+ [PublicAPI] public ICategoryDiscoverer CategoryDiscoverer { get; set; }
  [PublicAPI] public SummaryStyle SummaryStyle { get; set; }
  [PublicAPI] public TimeSpan BuildTimeout { get; set; } = DefaultConfig.Instance.BuildTimeout;
 
@@ -92,6 +94,12 @@ public ManualConfig WithOrderer(IOrderer orderer)
  return this;
  }
 
+ public ManualConfig WithCategoryDiscoverer(ICategoryDiscoverer categoryDiscoverer)
+ {
+ CategoryDiscoverer = categoryDiscoverer;
+ return this;
+ }
+
  public ManualConfig WithBuildTimeout(TimeSpan buildTimeout)
  {
  BuildTimeout = buildTimeout;
@@ -247,6 +255,7 @@ public void Add(IConfig config)
  hardwareCounters.AddRange(config.GetHardwareCounters());
  filters.AddRange(config.GetFilters());
  Orderer = config.Orderer ?? Orderer;
+ CategoryDiscoverer = config.CategoryDiscoverer ?? CategoryDiscoverer;
  ArtifactsPath = config.ArtifactsPath ?? ArtifactsPath;
  CultureInfo = config.CultureInfo ?? CultureInfo;
  SummaryStyle = config.SummaryStyle ?? SummaryStyle;