Implement WakeLock so that the system does not enter sleep

docs/articles/guides/console-args.md

@@ -243,6 +243,7 @@ dotnet run -c Release -- --filter * --runtimes net6.0 net8.0 --statisticalTest 5
 * `--platform` the Platform that should be used. If not specified, the host process platform is used (default). AnyCpu/X86/X64/Arm/Arm64/LoongArch64.
 * `--runOncePerIteration` run the benchmark exactly once per iteration.
 * `--buildTimeout` build timeout in seconds.
+* `--wakeLock` prevents the system from entering sleep or turning off the display. None/System/Display.
 * `--wasmEngine` full path to a java script engine used to run the benchmarks, used by Wasm toolchain.
 * `--wasmMainJS` path to the test-main.js file used by Wasm toolchain. Mandatory when using \"--runtimes wasm\"
 * `--expose_wasm` arguments for the JavaScript engine used by Wasm toolchain.

docs/articles/samples/IntroWakeLock.md

@@ -0,0 +1,32 @@
+---
+uid: BenchmarkDotNet.Samples.IntroWakeLock
+---
+
+## Sample: IntroWakeLock
+
+Running benchmarks may sometimes take enough time such that the system enters sleep or turns off the display.
+
+Using a WakeLock prevents the Windows system doing so.
+
+### Source code
+
+[!code-csharp[IntroWakeLock.cs](../../../samples/BenchmarkDotNet.Samples/IntroWakeLock.cs)]
+
+### Command line
+
+```
+--wakeLock None
+```
+```
+--wakeLock System
+```
+```
+--wakeLock Display
+```
+
+### Links
+
+* @BenchmarkDotNet.Attributes.WakeLockAttribute
+* The permanent link to this sample: @BenchmarkDotNet.Samples.IntroWakeLock
+
+---

docs/articles/samples/toc.yml

@@ -126,6 +126,8 @@
   href: IntroTailcall.md
 - name: IntroVisualStudioProfiler
   href: IntroVisualStudioProfiler.md
+- name: IntroWakeLock
+  href: IntroWakeLock.md
 - name: IntroWasm
   href: IntroWasm.md
 - name: IntroUnicode

samples/BenchmarkDotNet.Samples/IntroWakeLock.cs

@@ -0,0 +1,30 @@
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Configs;
+using System;
+using System.Threading;
+
+// *** Attribute Style applied to Assembly ***
+[assembly: WakeLock(WakeLockType.System)]
+
+namespace BenchmarkDotNet.Samples;
+
+// *** Attribute Style ***
+[WakeLock(WakeLockType.Display)]
+public class IntroWakeLock
+{
+    [Benchmark]
+    public void LongRunning() => Thread.Sleep(TimeSpan.FromSeconds(10));
+}
+
+// *** Object Style ***
+[Config(typeof(Config))]
+public class IntroWakeLockObjectStyle
+{
+    private class Config : ManualConfig
+    {
+        public Config() => WakeLock = WakeLockType.System;
+    }
+
+    [Benchmark]
+    public void LongRunning() => Thread.Sleep(TimeSpan.FromSeconds(10));
+}

src/BenchmarkDotNet/Attributes/WakeLockAttribute.cs

@@ -0,0 +1,18 @@
+using BenchmarkDotNet.Configs;
+using System;
+
+namespace BenchmarkDotNet.Attributes
+{
+    /// <summary>
+    /// Placing a <see cref="WakeLockAttribute"/> on your assembly or class controls whether the
+    /// Windows system enters sleep or turns off the display while benchmarks run.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Assembly | AttributeTargets.Class)]
+    public sealed class WakeLockAttribute : Attribute, IConfigSource
+    {
+        public WakeLockAttribute(WakeLockType wakeLockType) =>
+            Config = ManualConfig.CreateEmpty().WithWakeLock(wakeLockType);
+
+        public IConfig Config { get; }
+    }
+}

src/BenchmarkDotNet/Configs/DebugConfig.cs

@@ -71,6 +71,7 @@ public abstract class DebugConfig : IConfig
         public SummaryStyle SummaryStyle => SummaryStyle.Default;
         public ConfigUnionRule UnionRule => ConfigUnionRule.Union;
         public TimeSpan BuildTimeout => DefaultConfig.Instance.BuildTimeout;
+        public WakeLockType WakeLock => WakeLockType.None;
 
         public string ArtifactsPath => null; // DefaultConfig.ArtifactsPath will be used if the user does not specify it in explicit way
 

src/BenchmarkDotNet/Configs/DefaultConfig.cs

@@ -87,6 +87,8 @@ public IEnumerable<IValidator> GetValidators()
 
         public TimeSpan BuildTimeout => TimeSpan.FromSeconds(120);
 
+        public WakeLockType WakeLock => WakeLockType.System;
+
         public string ArtifactsPath
         {
             get

src/BenchmarkDotNet/Configs/IConfig.cs

@@ -55,6 +55,8 @@ public interface IConfig
         /// </summary>
         TimeSpan BuildTimeout { get; }
 
+        public WakeLockType WakeLock { get; }
+
         /// <summary>
         /// Collect any errors or warnings when composing the configuration
         /// </summary>

src/BenchmarkDotNet/Configs/ImmutableConfig.cs

@@ -56,6 +56,7 @@ internal ImmutableConfig(
             SummaryStyle summaryStyle,
             ConfigOptions options,
             TimeSpan buildTimeout,
+            WakeLockType wakeLock,
             IReadOnlyList<Conclusion> configAnalysisConclusion)
         {
             columnProviders = uniqueColumnProviders;
@@ -78,6 +79,7 @@ internal ImmutableConfig(
             SummaryStyle = summaryStyle;
             Options = options;
             BuildTimeout = buildTimeout;
+            WakeLock = wakeLock;
             ConfigAnalysisConclusion = configAnalysisConclusion;
         }
 
@@ -89,6 +91,7 @@ internal ImmutableConfig(
         public ICategoryDiscoverer CategoryDiscoverer { get; }
         public SummaryStyle SummaryStyle { get; }
         public TimeSpan BuildTimeout { get; }
+        public WakeLockType WakeLock { get; }
 
         public IEnumerable<IColumnProvider> GetColumnProviders() => columnProviders;
         public IEnumerable<IExporter> GetExporters() => exporters;

src/BenchmarkDotNet/Configs/ImmutableConfigBuilder.cs

@@ -76,6 +76,7 @@ public static ImmutableConfig Create(IConfig source)
                 source.SummaryStyle ?? SummaryStyle.Default,
                 source.Options,
                 source.BuildTimeout,
+                source.WakeLock,
                 configAnalyse.AsReadOnly()
             );
         }

src/BenchmarkDotNet/Configs/ManualConfig.cs

@@ -58,6 +58,7 @@ public class ManualConfig : IConfig
         [PublicAPI] public ICategoryDiscoverer CategoryDiscoverer { get; set; }
         [PublicAPI] public SummaryStyle SummaryStyle { get; set; }
         [PublicAPI] public TimeSpan BuildTimeout { get; set; } = DefaultConfig.Instance.BuildTimeout;
+        [PublicAPI] public WakeLockType WakeLock { get; set; } = DefaultConfig.Instance.WakeLock;
 
         public IReadOnlyList<Conclusion> ConfigAnalysisConclusion => emptyConclusion;
 
@@ -109,6 +110,12 @@ public ManualConfig WithBuildTimeout(TimeSpan buildTimeout)
             return this;
         }
 
+        public ManualConfig WithWakeLock(WakeLockType wakeLockType)
+        {
+            WakeLock = wakeLockType;
+            return this;
+        }
+
         [EditorBrowsable(EditorBrowsableState.Never)]
         [Obsolete("This method will soon be removed, please start using .AddColumn() instead.")]
         public void Add(params IColumn[] newColumns) => AddColumn(newColumns);
@@ -273,6 +280,7 @@ public void Add(IConfig config)
             columnHidingRules.AddRange(config.GetColumnHidingRules());
             Options |= config.Options;
             BuildTimeout = GetBuildTimeout(BuildTimeout, config.BuildTimeout);
+            WakeLock = GetWakeLock(WakeLock, config.WakeLock);
         }
 
         /// <summary>
@@ -327,5 +335,12 @@ private static TimeSpan GetBuildTimeout(TimeSpan current, TimeSpan other)
             => current == DefaultConfig.Instance.BuildTimeout
                 ? other
                 : TimeSpan.FromMilliseconds(Math.Max(current.TotalMilliseconds, other.TotalMilliseconds));
+
+        private static WakeLockType GetWakeLock(WakeLockType current, WakeLockType other)
+        {
+            if (current == DefaultConfig.Instance.WakeLock) { return other; }
+            if (other == DefaultConfig.Instance.WakeLock) { return current; }
+            return current.CompareTo(other) > 0 ? current : other;
+        }
     }
 }

src/BenchmarkDotNet/Configs/WakeLockType.cs

@@ -0,0 +1,20 @@
+namespace BenchmarkDotNet.Configs
+{
+    public enum WakeLockType
+    {
+        /// <summary>
+        /// Allows the system to enter sleep and/or turn off the display while benchmarks are running.
+        /// </summary>
+        None,
+
+        /// <summary>
+        /// Forces the system to be in the working state while benchmarks are running.
+        /// </summary>
+        System,
+
+        /// <summary>
+        /// Forces the display to be on while benchmarks are running.
+        /// </summary>
+        Display
+    }
+}

src/BenchmarkDotNet/ConsoleArguments/CommandLineOptions.cs

@@ -2,6 +2,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Linq;
+using BenchmarkDotNet.Configs;
 using BenchmarkDotNet.ConsoleArguments.ListBenchmarks;
 using BenchmarkDotNet.Diagnosers;
 using BenchmarkDotNet.Engines;
@@ -179,6 +180,9 @@ public bool UseDisassemblyDiagnoser
         [Option("buildTimeout", Required = false, HelpText = "Build timeout in seconds.")]
         public int? TimeOutInSeconds { get; set; }
 
+        [Option("wakeLock", Required = false, HelpText = "Prevents the system from entering sleep or turning off the display. None/System/Display.")]
+        public WakeLockType? WakeLock { get; set; }
+
         [Option("stopOnFirstError", Required = false, Default = false, HelpText = "Stop on first error.")]
         public bool StopOnFirstError { get; set; }
 

src/BenchmarkDotNet/ConsoleArguments/ConfigParser.cs

@@ -392,6 +392,9 @@ private static IConfig CreateConfig(CommandLineOptions options, IConfig globalCo
             if (options.TimeOutInSeconds.HasValue)
                 config.WithBuildTimeout(TimeSpan.FromSeconds(options.TimeOutInSeconds.Value));
 
+            if (options.WakeLock.HasValue)
+                config.WithWakeLock(options.WakeLock.Value);
+
             return config;
         }
 

src/BenchmarkDotNet/Running/BenchmarkRunnerClean.cs

@@ -55,6 +55,7 @@ internal static Summary[] Run(BenchmarkRunInfo[] benchmarkRunInfos)
             using (var streamLogger = new StreamLogger(GetLogFileStreamWriter(benchmarkRunInfos, logFilePath)))
             {
                 var compositeLogger = CreateCompositeLogger(benchmarkRunInfos, streamLogger);
+                using var wakeLock = WakeLock.Request(WakeLock.GetWakeLockType(benchmarkRunInfos), "BenchmarkDotNet Running Benchmarks", streamLogger);
                 var eventProcessor = new CompositeEventProcessor(benchmarkRunInfos);
 
                 eventProcessor.OnStartValidationStage();

src/BenchmarkDotNet/Running/WakeLock.PInvoke.cs

@@ -0,0 +1,77 @@
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+
+namespace BenchmarkDotNet.Running;
+
+internal partial class WakeLock
+{
+    private static class PInvoke
+    {
+        public static SafePowerHandle PowerCreateRequest(string reason)
+        {
+            REASON_CONTEXT context = new REASON_CONTEXT()
+            {
+                Version = POWER_REQUEST_CONTEXT_VERSION,
+                Flags = POWER_REQUEST_CONTEXT_FLAGS.POWER_REQUEST_CONTEXT_SIMPLE_STRING,
+                SimpleReasonString = reason
+            };
+            SafePowerHandle safePowerHandle = PowerCreateRequest(context);
+            if (safePowerHandle.IsInvalid) { throw new Win32Exception(); }
+            return safePowerHandle;
+        }
+
+        [DllImport("kernel32.dll", ExactSpelling = true, SetLastError = true)]
+        private static extern SafePowerHandle PowerCreateRequest(REASON_CONTEXT Context);
+
+        public static void PowerSetRequest(SafePowerHandle safePowerHandle, POWER_REQUEST_TYPE requestType)
+        {
+            if (!InvokePowerSetRequest(safePowerHandle, requestType))
+            {
+                throw new Win32Exception();
+            }
+        }
+
+        [DllImport("kernel32.dll", EntryPoint = "PowerSetRequest", ExactSpelling = true, SetLastError = true)]
+        private static extern bool InvokePowerSetRequest(SafePowerHandle PowerRequest, POWER_REQUEST_TYPE RequestType);
+
+        public static void PowerClearRequest(SafePowerHandle safePowerHandle, POWER_REQUEST_TYPE requestType)
+        {
+            if (!InvokePowerClearRequest(safePowerHandle, requestType))
+            {
+                throw new Win32Exception();
+            }
+        }
+
+        [DllImport("kernel32.dll", EntryPoint = "PowerClearRequest", ExactSpelling = true, SetLastError = true)]
+        private static extern bool InvokePowerClearRequest(SafePowerHandle PowerRequest, POWER_REQUEST_TYPE RequestType);
+
+        [DllImport("kernel32.dll", ExactSpelling = true, SetLastError = true)]
+        public static extern bool CloseHandle(nint hObject);
+
+        private struct REASON_CONTEXT
+        {
+            public uint Version;
+
+            public POWER_REQUEST_CONTEXT_FLAGS Flags;
+
+            [MarshalAs(UnmanagedType.LPWStr)]
+            public string SimpleReasonString;
+        }
+
+        private const uint POWER_REQUEST_CONTEXT_VERSION = 0U;
+
+        private enum POWER_REQUEST_CONTEXT_FLAGS : uint
+        {
+            POWER_REQUEST_CONTEXT_DETAILED_STRING = 2U,
+            POWER_REQUEST_CONTEXT_SIMPLE_STRING = 1U,
+        }
+
+        public enum POWER_REQUEST_TYPE
+        {
+            PowerRequestDisplayRequired = 0,
+            PowerRequestSystemRequired = 1,
+            PowerRequestAwayModeRequired = 2,
+            PowerRequestExecutionRequired = 3,
+        }
+    }
+}

src/BenchmarkDotNet/Running/WakeLock.SafePowerHandle.cs

@@ -0,0 +1,13 @@
+using Microsoft.Win32.SafeHandles;
+
+namespace BenchmarkDotNet.Running;
+
+internal partial class WakeLock
+{
+    private sealed class SafePowerHandle : SafeHandleZeroOrMinusOneIsInvalid
+    {
+        private SafePowerHandle() : base(true) { }
+
+        protected override bool ReleaseHandle() => PInvoke.CloseHandle(handle);
+    }
+}