Implement WakeLock so that the system does not enter sleep (#2670)

leonvandermeer · timcassell · adamsitnik · web-flow · commit de8fb91be736 · 2025-01-30T16:43:49.000-05:00
* Implement WakeLock so that the system does not enter sleep while benchmarks are running

* Apply rework from code review

Co-authored-by: Tim Cassell &lt;35501420+timcassell@users.noreply.github.com&gt;

* Apply suggestions from code review

Co-authored-by: Adam Sitnik &lt;adam.sitnik@gmail.com&gt;

* Apply rework from code review

---------

Co-authored-by: Tim Cassell &lt;35501420+timcassell@users.noreply.github.com&gt;
Co-authored-by: Adam Sitnik &lt;adam.sitnik@gmail.com&gt;
diff --git a/docs/articles/guides/console-args.md b/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.
diff --git a/docs/articles/samples/IntroWakeLock.md b/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
+
+---
diff --git a/docs/articles/samples/toc.yml b/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
diff --git a/samples/BenchmarkDotNet.Samples/IntroWakeLock.cs b/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));
+}
diff --git a/src/BenchmarkDotNet/Attributes/WakeLockAttribute.cs b/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; }
+    }
+}
diff --git a/src/BenchmarkDotNet/Configs/DebugConfig.cs b/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
 
diff --git a/src/BenchmarkDotNet/Configs/DefaultConfig.cs b/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
diff --git a/src/BenchmarkDotNet/Configs/IConfig.cs b/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>
diff --git a/src/BenchmarkDotNet/Configs/ImmutableConfig.cs b/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;
diff --git a/src/BenchmarkDotNet/Configs/ImmutableConfigBuilder.cs b/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()
             );
         }
diff --git a/src/BenchmarkDotNet/Configs/ManualConfig.cs b/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;
+        }
     }
 }
diff --git a/src/BenchmarkDotNet/Configs/WakeLockType.cs b/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
+    }
+}
diff --git a/src/BenchmarkDotNet/ConsoleArguments/CommandLineOptions.cs b/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; }
 
diff --git a/src/BenchmarkDotNet/ConsoleArguments/ConfigParser.cs b/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;
         }
 
diff --git a/src/BenchmarkDotNet/Running/BenchmarkRunnerClean.cs b/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();
diff --git a/src/BenchmarkDotNet/Running/WakeLock.PInvoke.cs b/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,
+        }
+    }
+}
diff --git a/src/BenchmarkDotNet/Running/WakeLock.SafePowerHandle.cs b/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);
+    }
+}
diff --git a/src/BenchmarkDotNet/Running/WakeLock.cs b/src/BenchmarkDotNet/Running/WakeLock.cs
diff --git a/tests/BenchmarkDotNet.IntegrationTests/PowerRequest.cs b/tests/BenchmarkDotNet.IntegrationTests/PowerRequest.cs
diff --git a/tests/BenchmarkDotNet.IntegrationTests/PowerRequestsParser.cs b/tests/BenchmarkDotNet.IntegrationTests/PowerRequestsParser.cs
diff --git a/tests/BenchmarkDotNet.IntegrationTests/WakeLockTests.cs b/tests/BenchmarkDotNet.IntegrationTests/WakeLockTests.cs
diff --git a/tests/BenchmarkDotNet.Tests/ConfigParserTests.cs b/tests/BenchmarkDotNet.Tests/ConfigParserTests.cs
diff --git a/tests/BenchmarkDotNet.Tests/Configs/ImmutableConfigTests.cs b/tests/BenchmarkDotNet.Tests/Configs/ImmutableConfigTests.cs
diff --git a/tests/BenchmarkDotNet.Tests/XUnit/EnvRequirement.cs b/tests/BenchmarkDotNet.Tests/XUnit/EnvRequirement.cs
diff --git a/tests/BenchmarkDotNet.Tests/XUnit/EnvRequirementChecker.cs b/tests/BenchmarkDotNet.Tests/XUnit/EnvRequirementChecker.cs

Original file line number	Diff line number	Diff line change
`@@ -87,6 +87,8 @@ public IEnumerable<IValidator> GetValidators()`
`87`	`87`
`88`	`88`	`public TimeSpan BuildTimeout => TimeSpan.FromSeconds(120);`
`89`	`89`
	`90`	`+ public WakeLockType WakeLock => WakeLockType.System;`
	`91`	`+`
`90`	`92`	`public string ArtifactsPath`
`91`	`93`	`{`
`92`	`94`	`get`
Original file line number	Diff line number	Diff line change
`@@ -76,6 +76,7 @@ public static ImmutableConfig Create(IConfig source)`
`76`	`76`	`source.SummaryStyle ?? SummaryStyle.Default,`
`77`	`77`	`source.Options,`
`78`	`78`	`source.BuildTimeout,`
	`79`	`+ source.WakeLock,`
`79`	`80`	`configAnalyse.AsReadOnly()`
`80`	`81`	`);`
`81`	`82`	`}`