Add configurable update wait for Live and Run

Author: xoofx

site/docs/hosting.md

@@ -56,6 +56,25 @@ Terminal.Live(
     options: new TerminalLiveOptions { EnableMouse = true, MouseMode = TerminalMouseMode.Move });
 ```
 
+### Update tick wait (default: 1ms)
+
+`Terminal.Live(...)` and `Terminal.Run(...)` use a 1ms wait between loop ticks by default.
+You can increase this wait if you want to reduce update frequency and CPU usage:
+
+```csharp
+Terminal.Live(
+    visual,
+    onUpdate: () => TerminalLoopResult.Continue,
+    options: new TerminalLiveOptions { UpdateWaitDuration = TimeSpan.FromMilliseconds(20) });
+
+Terminal.Run(
+    visual,
+    onUpdate: () => TerminalLoopResult.Continue,
+    options: new TerminalRunOptions { UpdateWaitDuration = TimeSpan.FromMilliseconds(20) });
+```
+
+Larger values can make animations (for example spinners) update less smoothly.
+
 ### Filling the viewport height
 
 Inline live regions measure with an "infinite" height by default, so a simple visual like a `VStack("Hello")` will

src/XenoAtom.Terminal.UI.Tests/TerminalExtensionsTests.cs

@@ -2,6 +2,7 @@
 // Licensed under the BSD-Clause 2 license.
 // See license.txt file in the project root for full license information.
 
+using System.Diagnostics;
 using XenoAtom.Terminal;
 using XenoAtom.Terminal.Backends;
 using XenoAtom.Terminal.UI.Controls;
@@ -141,4 +142,58 @@ await session.Instance.LiveAsync(root, async _ =>
         StringAssert.Contains(screen.GetText(), "Count: 3");
         StringAssert.Contains(screen.GetText(), "Done");
     }
+
+    [TestMethod]
+    public void Live_Options_UpdateWaitDuration_IsApplied()
+    {
+        var backend = new InMemoryTerminalBackend(new TerminalSize(30, 10));
+        using var session = Terminal.Open(backend, new TerminalOptions { ImplicitStartInput = true }, force: true);
+
+        var tickCount = 0;
+        var wait = TimeSpan.FromMilliseconds(35);
+        var stopwatch = Stopwatch.StartNew();
+
+        session.Instance.Live(
+            new TextBlock("Wait test"),
+            _ =>
+            {
+                tickCount++;
+                return tickCount >= 2 ? TerminalLoopResult.Stop : TerminalLoopResult.Continue;
+            },
+            new TerminalLiveOptions { UpdateWaitDuration = wait });
+
+        stopwatch.Stop();
+
+        Assert.AreEqual(2, tickCount);
+        Assert.IsTrue(
+            stopwatch.Elapsed >= TimeSpan.FromMilliseconds(50),
+            $"Expected configured wait duration to slow down loop ticks. Elapsed: {stopwatch.Elapsed}.");
+    }
+
+    [TestMethod]
+    public void Run_Options_UpdateWaitDuration_IsApplied()
+    {
+        var backend = new InMemoryTerminalBackend(new TerminalSize(30, 10));
+        using var session = Terminal.Open(backend, new TerminalOptions { ImplicitStartInput = true }, force: true);
+
+        var tickCount = 0;
+        var wait = TimeSpan.FromMilliseconds(35);
+        var stopwatch = Stopwatch.StartNew();
+
+        session.Instance.Run(
+            new TextBlock("Wait test"),
+            _ =>
+            {
+                tickCount++;
+                return tickCount >= 2 ? TerminalLoopResult.Stop : TerminalLoopResult.Continue;
+            },
+            new TerminalRunOptions { UpdateWaitDuration = wait });
+
+        stopwatch.Stop();
+
+        Assert.AreEqual(2, tickCount);
+        Assert.IsTrue(
+            stopwatch.Elapsed >= TimeSpan.FromMilliseconds(50),
+            $"Expected configured wait duration to slow down loop ticks. Elapsed: {stopwatch.Elapsed}.");
+    }
 }

src/XenoAtom.Terminal.UI/TerminalApp.cs

@@ -194,6 +194,10 @@ public TerminalApp(Visual root, TerminalInstance? terminal = null, TerminalAppOp
         ArgumentNullException.ThrowIfNull(root);
         _terminal = terminal ?? global::XenoAtom.Terminal.Terminal.Instance;
         _options = options ?? new TerminalAppOptions();
+        if (_options.UpdateWaitDuration < TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(nameof(options), "The update wait duration cannot be negative.");
+        }
 
         ContentRoot = root;
         if (_options.HostKind == TerminalHostKind.Fullscreen)
@@ -651,7 +655,11 @@ private void RunCore(CancellationToken cancellationToken, ManualResetEventSlim?
             while (!token.IsCancellationRequested)
             {
                 Tick();
-                Thread.Sleep(1);
+                var updateWaitDuration = _options.UpdateWaitDuration;
+                if (updateWaitDuration > TimeSpan.Zero)
+                {
+                    Thread.Sleep(updateWaitDuration);
+                }
             }
         }
         finally

src/XenoAtom.Terminal.UI/TerminalAppOptions.cs

@@ -77,6 +77,15 @@ public sealed class TerminalAppOptions
     /// by setting <see cref="Styling.CultureStyle.Key"/>.
     /// </remarks>
     public CultureInfo Culture { get; init; } = CultureInfo.InvariantCulture;
+
+    /// <summary>
+    /// Gets the wait duration between host loop ticks.
+    /// </summary>
+    /// <remarks>
+    /// The default is 1ms to keep animation updates responsive while yielding the CPU.
+    /// Increase this value to reduce CPU usage when frequent updates are not required.
+    /// </remarks>
+    public global::System.TimeSpan UpdateWaitDuration { get; init; } = global::System.TimeSpan.FromMilliseconds(1);
 }
 
 /// <summary>

src/XenoAtom.Terminal.UI/TerminalExtensions.cs

@@ -351,6 +351,7 @@ public TerminalInstance Live(Visual visual, Func<TerminalRunningContext, Termina
                 Culture = options.Culture ?? CultureInfo.InvariantCulture,
                 EnableMouse = options.EnableMouse,
                 MouseMode = options.MouseMode,
+                UpdateWaitDuration = options.UpdateWaitDuration,
             };
             RunHostedAsync(instance, visual, appOptions, onUpdate, CancellationToken.None)
                 .AsTask()
@@ -418,6 +419,7 @@ public async ValueTask<TerminalInstance> LiveAsync(Visual visual, Func<TerminalR
                 Culture = options.Culture ?? CultureInfo.InvariantCulture,
                 EnableMouse = options.EnableMouse,
                 MouseMode = options.MouseMode,
+                UpdateWaitDuration = options.UpdateWaitDuration,
             };
             await RunHostedAsync(instance, visual, appOptions, onUpdate, cancellationToken).ConfigureAwait(false);
 
@@ -436,6 +438,7 @@ public async ValueTask<TerminalInstance> LiveAsync(Visual visual, Func<TerminalR
                 Culture = options.Culture ?? CultureInfo.InvariantCulture,
                 EnableMouse = options.EnableMouse,
                 MouseMode = options.MouseMode,
+                UpdateWaitDuration = options.UpdateWaitDuration,
             };
             await RunHostedAsync(instance, visual, appOptions, onUpdate, cancellationToken).ConfigureAwait(false);
 
@@ -459,6 +462,7 @@ public TerminalInstance Run(Visual visual, Func<TerminalRunningContext, Terminal
                 HostKind = TerminalHostKind.Fullscreen,
                 ExitGesture = options.ExitGesture,
                 Culture = options.Culture ?? CultureInfo.InvariantCulture,
+                UpdateWaitDuration = options.UpdateWaitDuration,
             };
             RunHostedAsync(instance, visual, appOptions, onUpdate, CancellationToken.None)
                 .AsTask()
@@ -485,6 +489,7 @@ public async ValueTask<TerminalInstance> RunAsync(Visual visual, Func<TerminalRu
                 HostKind = TerminalHostKind.Fullscreen,
                 ExitGesture = options.ExitGesture,
                 Culture = options.Culture ?? CultureInfo.InvariantCulture,
+                UpdateWaitDuration = options.UpdateWaitDuration,
             };
             await RunHostedAsync(instance, visual, appOptions, onUpdate, cancellationToken).ConfigureAwait(false);
 
@@ -508,6 +513,7 @@ public async ValueTask<TerminalInstance> RunAsync(Visual visual, Func<TerminalRu
                 HostKind = TerminalHostKind.Fullscreen,
                 ExitGesture = options.ExitGesture,
                 Culture = options.Culture ?? CultureInfo.InvariantCulture,
+                UpdateWaitDuration = options.UpdateWaitDuration,
             };
             await RunHostedAsync(instance, visual, appOptions, onUpdate, cancellationToken).ConfigureAwait(false);
 

src/XenoAtom.Terminal.UI/TerminalLiveOptions.cs

@@ -33,4 +33,12 @@ public readonly record struct TerminalLiveOptions()
     /// Gets the mouse reporting mode used when <see cref="EnableMouse"/> is <see langword="true"/>.
     /// </summary>
     public TerminalMouseMode MouseMode { get; init; } = TerminalMouseMode.Move;
+
+    /// <summary>
+    /// Gets the wait duration between update ticks.
+    /// </summary>
+    /// <remarks>
+    /// The default is 1ms. Increase this value to reduce update frequency and CPU usage.
+    /// </remarks>
+    public global::System.TimeSpan UpdateWaitDuration { get; init; } = global::System.TimeSpan.FromMilliseconds(1);
 }

src/XenoAtom.Terminal.UI/TerminalRunOptions.cs

@@ -8,7 +8,7 @@ namespace XenoAtom.Terminal.UI;
 /// Provides options for fullscreen hosting via
 /// <see cref="TerminalExtensions.Run(Visual, System.Func{TerminalRunningContext, TerminalLoopResult}, TerminalRunOptions)"/>.
 /// </summary>
-public readonly record struct TerminalRunOptions
+public readonly record struct TerminalRunOptions()
 {
     /// <summary>
     /// Gets the culture used for formatting values (for example when converting numbers to strings).
@@ -25,4 +25,12 @@ public readonly record struct TerminalRunOptions
     /// When <see langword="null"/>, the default gesture is used (<c>Ctrl+Q</c>).
     /// </remarks>
     public global::XenoAtom.Terminal.UI.Input.KeyGesture? ExitGesture { get; init; }
+
+    /// <summary>
+    /// Gets the wait duration between update ticks.
+    /// </summary>
+    /// <remarks>
+    /// The default is 1ms. Increase this value to reduce update frequency and CPU usage.
+    /// </remarks>
+    public global::System.TimeSpan UpdateWaitDuration { get; init; } = global::System.TimeSpan.FromMilliseconds(1);
 }