Add ParallelExecutionHelper for partitioning

Author: JimBobSquarePants

src/ImageSharp.Drawing/Processing/Backends/DefaultDrawingBackend.cs

@@ -87,14 +87,12 @@ private static void ExecuteScene<TPixel>(
         }
 
         int requestedParallelism = configuration.MaxDegreeOfParallelism;
-        int partitionCount = Math.Min(
-            scene.RowCount,
-            requestedParallelism == -1 ? Environment.ProcessorCount : requestedParallelism);
+        int partitionCount = ParallelExecutionHelper.GetPartitionCount(requestedParallelism, scene.RowCount);
 
         _ = Parallel.For(
             fromInclusive: 0,
             toExclusive: scene.RowCount,
-            parallelOptions: new ParallelOptions { MaxDegreeOfParallelism = partitionCount },
+            parallelOptions: ParallelExecutionHelper.CreateParallelOptions(requestedParallelism, partitionCount),
             localInit: () => new WorkerState<TPixel>(configuration.MemoryAllocator, destinationFrame.Width, scene.MaxLayerDepth + 1),
             body: (rowIndex, _, state) =>
             {

src/ImageSharp.Drawing/Processing/Backends/FlushScene.cs

@@ -120,7 +120,7 @@ private FlushScene(
     /// <param name="targetBounds">The destination bounds of the flush.</param>
     /// <param name="allocator">The allocator used for retained row storage.</param>
     /// <param name="maxDegreeOfParallelism">
-    /// The maximum degree of parallelism to use when building the scene, or -1 to use the default number of processors.
+    /// The maximum degree of parallelism to use when building the scene, or -1 to leave the degree of parallelism unbounded.
     /// </param>
     /// <returns>A flush-ready scene.</returns>
     public static FlushScene Create(
@@ -149,14 +149,13 @@ public static FlushScene Create(
 
         FillSceneItem?[] fillItems = new FillSceneItem?[commandCount];
         StrokeSceneItem?[] strokeItems = new StrokeSceneItem?[commandCount];
-        int availableParallelism = maxDegreeOfParallelism == -1 ? Environment.ProcessorCount : maxDegreeOfParallelism;
-        int partitionCount = Math.Min(commandCount, Math.Min(availableParallelism, targetRowCount));
+        int partitionCount = ParallelExecutionHelper.GetPartitionCount(maxDegreeOfParallelism, commandCount, targetRowCount);
         PartitionState[] partitions = new PartitionState[partitionCount];
 
         _ = Parallel.For(
             0,
             partitionCount,
-            new ParallelOptions { MaxDegreeOfParallelism = partitionCount },
+            ParallelExecutionHelper.CreateParallelOptions(maxDegreeOfParallelism, partitionCount),
             partitionIndex =>
             {
                 // Integer division splits the commands into contiguous half-open ranges,

src/ImageSharp.Drawing/Processing/Backends/ParallelExecutionHelper.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
+
+/// <summary>
+/// Centralizes the conversion from configuration parallelism settings to partition counts and
+/// <see cref="ParallelOptions"/> instances used by retained-scene CPU execution paths.
+/// </summary>
+internal static class ParallelExecutionHelper
+{
+    /// <summary>
+    /// Computes the number of partitions to schedule for work constrained by a single work-item limit.
+    /// </summary>
+    /// <param name="maxDegreeOfParallelism">
+    /// The configured maximum degree of parallelism. A value of <c>-1</c> leaves the degree of
+    /// parallelism unbounded, so the work-item count is used as the effective partition cap.
+    /// </param>
+    /// <param name="workItemCount">The total number of work items available for partitioning.</param>
+    /// <returns>The number of partitions to schedule.</returns>
+    public static int GetPartitionCount(int maxDegreeOfParallelism, int workItemCount)
+        => maxDegreeOfParallelism == -1 ? workItemCount : Math.Min(maxDegreeOfParallelism, workItemCount);
+
+    /// <summary>
+    /// Computes the number of partitions to schedule for work constrained by two independent limits.
+    /// </summary>
+    /// <param name="maxDegreeOfParallelism">
+    /// The configured maximum degree of parallelism. A value of <c>-1</c> leaves the degree of
+    /// parallelism unbounded, so only the supplied work limits constrain the partition count.
+    /// </param>
+    /// <param name="workItemCount">The total number of work items available for partitioning.</param>
+    /// <param name="secondaryLimit">An additional caller-specific upper bound on useful partitions.</param>
+    /// <returns>The number of partitions to schedule.</returns>
+    public static int GetPartitionCount(int maxDegreeOfParallelism, int workItemCount, int secondaryLimit)
+        => maxDegreeOfParallelism == -1
+            ? Math.Min(workItemCount, secondaryLimit)
+            : Math.Min(maxDegreeOfParallelism, Math.Min(workItemCount, secondaryLimit));
+
+    /// <summary>
+    /// Creates the <see cref="ParallelOptions"/> for a partitioned operation while preserving the
+    /// special meaning of <c>-1</c> as unbounded parallelism.
+    /// </summary>
+    /// <param name="maxDegreeOfParallelism">
+    /// The configured maximum degree of parallelism. A value of <c>-1</c> is propagated directly
+    /// to <see cref="ParallelOptions.MaxDegreeOfParallelism"/>.
+    /// </param>
+    /// <param name="partitionCount">The computed number of useful partitions for the operation.</param>
+    /// <returns>The <see cref="ParallelOptions"/> instance for the operation.</returns>
+    public static ParallelOptions CreateParallelOptions(int maxDegreeOfParallelism, int partitionCount)
+        => new() { MaxDegreeOfParallelism = maxDegreeOfParallelism == -1 ? -1 : partitionCount };
+}

src/ImageSharp.Drawing/Processing/DrawingCanvasBatcher{TPixel}.cs

@@ -151,9 +151,7 @@ private void PrepareCommands()
         // to the backend. This avoids complicating the backend with clipping logic
         // and allows us to reuse the same optimized backend code for clipped and unclipped paths.
         int requestedParallelism = this.configuration.MaxDegreeOfParallelism;
-        int partitionCount = Math.Min(
-            this.commandCount,
-            requestedParallelism == -1 ? Environment.ProcessorCount : requestedParallelism);
+        int partitionCount = ParallelExecutionHelper.GetPartitionCount(requestedParallelism, this.commandCount);
 
         if (partitionCount <= 1)
         {
@@ -168,7 +166,7 @@ private void PrepareCommands()
         _ = Parallel.For(
             0,
             partitionCount,
-            new ParallelOptions() { MaxDegreeOfParallelism = partitionCount },
+            ParallelExecutionHelper.CreateParallelOptions(requestedParallelism, partitionCount),
             partitionIndex =>
             {
                 // Integer division splits the commands into contiguous half-open ranges,

tests/ImageSharp.Drawing.Tests/Processing/Backends/ParallelExecutionHelperTests.cs

@@ -0,0 +1,30 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+using SixLabors.ImageSharp.Drawing.Processing.Backends;
+
+namespace SixLabors.ImageSharp.Drawing.Tests.Processing.Backends;
+
+public class ParallelExecutionHelperTests
+{
+    [Theory]
+    [InlineData(-1, 8, 8)]
+    [InlineData(4, 8, 4)]
+    [InlineData(1, 8, 1)]
+    public void GetPartitionCountSingleLimit(int maxDegreeOfParallelism, int workItemCount, int expected)
+        => Assert.Equal(expected, ParallelExecutionHelper.GetPartitionCount(maxDegreeOfParallelism, workItemCount));
+
+    [Theory]
+    [InlineData(-1, 8, 3, 3)]
+    [InlineData(8, 8, 3, 3)]
+    [InlineData(2, 8, 3, 2)]
+    public void GetPartitionCountDualLimit(int maxDegreeOfParallelism, int workItemCount, int secondaryLimit, int expected)
+        => Assert.Equal(expected, ParallelExecutionHelper.GetPartitionCount(maxDegreeOfParallelism, workItemCount, secondaryLimit));
+
+    [Theory]
+    [InlineData(-1, 8, -1)]
+    [InlineData(4, 8, 8)]
+    [InlineData(2, 2, 2)]
+    public void CreateParallelOptionsPreservesUnboundedSetting(int maxDegreeOfParallelism, int partitionCount, int expected)
+        => Assert.Equal(expected, ParallelExecutionHelper.CreateParallelOptions(maxDegreeOfParallelism, partitionCount).MaxDegreeOfParallelism);
+}