Fix parallel bounds, use configuration

Author: JimBobSquarePants

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

@@ -120,7 +120,8 @@ 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 leave the degree of parallelism unbounded.
+    /// The maximum degree of parallelism to use when building the scene, or <c>-1</c> to pass
+    /// through the runtime's unlimited sentinel for <see cref="ParallelOptions.MaxDegreeOfParallelism"/>.
     /// </param>
     /// <returns>A flush-ready scene.</returns>
     public static FlushScene Create(

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

@@ -13,39 +13,52 @@ internal static class ParallelExecutionHelper
     /// 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.
+    /// The configured maximum degree of parallelism. A value of <c>-1</c> leaves the runtime
+    /// parallelism cap unbounded, but partition planning remains capped to
+    /// <see cref="Environment.ProcessorCount"/> to avoid excessive fan-out.
     /// </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);
+        => Math.Min(GetPartitionLimit(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.
+    /// The configured maximum degree of parallelism. A value of <c>-1</c> leaves the runtime
+    /// parallelism cap unbounded, but partition planning remains capped to
+    /// <see cref="Environment.ProcessorCount"/> to avoid excessive fan-out.
     /// </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));
+        => Math.Min(GetPartitionLimit(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.
+    /// special meaning of <c>-1</c> in <see cref="ParallelOptions.MaxDegreeOfParallelism"/>.
     /// </summary>
     /// <param name="maxDegreeOfParallelism">
     /// The configured maximum degree of parallelism. A value of <c>-1</c> is propagated directly
-    /// to <see cref="ParallelOptions.MaxDegreeOfParallelism"/>.
+    /// to <see cref="ParallelOptions.MaxDegreeOfParallelism"/>; positive values are capped to the
+    /// smaller of the configured limit and the useful partition count.
     /// </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 };
+        => new() { MaxDegreeOfParallelism = maxDegreeOfParallelism == -1 ? -1 : Math.Min(maxDegreeOfParallelism, partitionCount) };
+
+    /// <summary>
+    /// Computes the internal partition-planning cap for the configured parallelism setting.
+    /// </summary>
+    /// <param name="maxDegreeOfParallelism">
+    /// The configured maximum degree of parallelism. A value of <c>-1</c> keeps the runtime
+    /// parallelism setting unbounded, but partition planning is capped to
+    /// <see cref="Environment.ProcessorCount"/>.
+    /// </param>
+    /// <returns>The maximum number of partitions to plan for.</returns>
+    private static int GetPartitionLimit(int maxDegreeOfParallelism)
+        => maxDegreeOfParallelism == -1 ? Environment.ProcessorCount : maxDegreeOfParallelism;
 }

src/ImageSharp.Drawing/Processing/DrawingCanvasExtensions.cs

@@ -23,13 +23,30 @@ public static DrawingCanvas<TPixel> CreateCanvas<TPixel>(
         DrawingOptions options,
         params IPath[] clipPaths)
         where TPixel : unmanaged, IPixel<TPixel>
+        => CreateCanvas(frame, frame.Configuration, options, clipPaths);
+
+    /// <summary>
+    /// Creates a drawing canvas over an existing frame.
+    /// </summary>
+    /// <typeparam name="TPixel">The pixel format.</typeparam>
+    /// <param name="frame">The frame backing the canvas.</param>
+    /// <param name="configuration">The configuration to use for this canvas instance.</param>
+    /// <param name="options">Initial drawing options for this canvas instance.</param>
+    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
+    /// <returns>A drawing canvas targeting <paramref name="frame"/>.</returns>
+    public static DrawingCanvas<TPixel> CreateCanvas<TPixel>(
+        this ImageFrame<TPixel> frame,
+        Configuration configuration,
+        DrawingOptions options,
+        params IPath[] clipPaths)
+        where TPixel : unmanaged, IPixel<TPixel>
     {
         Guard.NotNull(frame, nameof(frame));
         Guard.NotNull(options, nameof(options));
         Guard.NotNull(clipPaths, nameof(clipPaths));
 
         return new DrawingCanvas<TPixel>(
-            frame.Configuration,
+            configuration,
             new Buffer2DRegion<TPixel>(frame.PixelBuffer, frame.Bounds),
             options,
             clipPaths);
@@ -50,13 +67,32 @@ public static DrawingCanvas<TPixel> CreateCanvas<TPixel>(
         DrawingOptions options,
         params IPath[] clipPaths)
         where TPixel : unmanaged, IPixel<TPixel>
+        => CreateCanvas(image, frameIndex, image.Configuration, options, clipPaths);
+
+    /// <summary>
+    /// Creates a drawing canvas over a specific frame of an image.
+    /// </summary>
+    /// <typeparam name="TPixel">The pixel format.</typeparam>
+    /// <param name="image">The image containing the frame.</param>
+    /// <param name="frameIndex">The zero-based frame index to target.</param>
+    /// <param name="configuration">The configuration to use for this canvas instance.</param>
+    /// <param name="options">Initial drawing options for this canvas instance.</param>
+    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
+    /// <returns>A drawing canvas targeting the selected frame.</returns>
+    public static DrawingCanvas<TPixel> CreateCanvas<TPixel>(
+        this Image<TPixel> image,
+        int frameIndex,
+        Configuration configuration,
+        DrawingOptions options,
+        params IPath[] clipPaths)
+        where TPixel : unmanaged, IPixel<TPixel>
     {
         Guard.NotNull(image, nameof(image));
         Guard.NotNull(options, nameof(options));
         Guard.NotNull(clipPaths, nameof(clipPaths));
         Guard.MustBeBetweenOrEqualTo(frameIndex, 0, image.Frames.Count - 1, nameof(frameIndex));
 
-        return image.Frames[frameIndex].CreateCanvas(options, clipPaths);
+        return image.Frames[frameIndex].CreateCanvas(configuration, options, clipPaths);
     }
 
     /// <summary>
@@ -72,11 +108,28 @@ public static DrawingCanvas<TPixel> CreateCanvas<TPixel>(
         DrawingOptions options,
         params IPath[] clipPaths)
         where TPixel : unmanaged, IPixel<TPixel>
+        => CreateCanvas(image, image.Configuration, options, clipPaths);
+
+    /// <summary>
+    /// Creates a drawing canvas over the root frame of an image.
+    /// </summary>
+    /// <typeparam name="TPixel">The pixel format.</typeparam>
+    /// <param name="image">The image whose root frame should be targeted.</param>
+    /// <param name="configuration">The configuration to use for this canvas instance.</param>
+    /// <param name="options">Initial drawing options for this canvas instance.</param>
+    /// <param name="clipPaths">Initial clip paths for this canvas instance.</param>
+    /// <returns>A drawing canvas targeting the root frame.</returns>
+    public static DrawingCanvas<TPixel> CreateCanvas<TPixel>(
+        this Image<TPixel> image,
+        Configuration configuration,
+        DrawingOptions options,
+        params IPath[] clipPaths)
+        where TPixel : unmanaged, IPixel<TPixel>
     {
         Guard.NotNull(image, nameof(image));
         Guard.NotNull(options, nameof(options));
         Guard.NotNull(clipPaths, nameof(clipPaths));
 
-        return image.Frames.RootFrame.CreateCanvas(options, clipPaths);
+        return image.Frames.RootFrame.CreateCanvas(configuration, options, clipPaths);
     }
 }

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

@@ -36,7 +36,7 @@ public ProcessWithCanvasProcessor(
     /// <inheritdoc />
     protected override void OnFrameApply(ImageFrame<TPixel> source)
     {
-        using DrawingCanvas<TPixel> canvas = source.CreateCanvas(this.definition.Options);
+        using DrawingCanvas<TPixel> canvas = source.CreateCanvas(this.Configuration, this.definition.Options);
         this.action(canvas);
     }
 }

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

@@ -8,23 +8,34 @@ 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));
 
+    [Fact]
+    public void GetPartitionCountSingleLimit_UnboundedSettingIsCappedToProcessorCount()
+        => Assert.Equal(
+            Math.Min(Environment.ProcessorCount, 8),
+            ParallelExecutionHelper.GetPartitionCount(-1, 8));
+
     [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));
 
+    [Fact]
+    public void GetPartitionCountDualLimit_UnboundedSettingIsCappedToProcessorCount()
+        => Assert.Equal(
+            Math.Min(Environment.ProcessorCount, 3),
+            ParallelExecutionHelper.GetPartitionCount(-1, 8, 3));
+
     [Theory]
     [InlineData(-1, 8, -1)]
-    [InlineData(4, 8, 8)]
+    [InlineData(4, 8, 4)]
+    [InlineData(4, 2, 2)]
     [InlineData(2, 2, 2)]
-    public void CreateParallelOptionsPreservesUnboundedSetting(int maxDegreeOfParallelism, int partitionCount, int expected)
+    public void CreateParallelOptions_MatchesParallelOptionsContract(int maxDegreeOfParallelism, int partitionCount, int expected)
         => Assert.Equal(expected, ParallelExecutionHelper.CreateParallelOptions(maxDegreeOfParallelism, partitionCount).MaxDegreeOfParallelism);
 }