Remove Closure Allocations when Iterating Rows in Parallel

src/ImageSharp/Advanced/IRowIntervalOperation.cs

@@ -0,0 +1,21 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+using System.Runtime.CompilerServices;
+using SixLabors.ImageSharp.Memory;
+
+namespace SixLabors.ImageSharp.Advanced
+{
+    /// <summary>
+    /// Defines the contract for an action that operates on a row interval.
+    /// </summary>
+    public interface IRowIntervalOperation
+    {
+        /// <summary>
+        /// Invokes the method passing the row interval.
+        /// </summary>
+        /// <param name="rows">The row interval.</param>
+        void Invoke(in RowInterval rows);
+    }
+}

src/ImageSharp/Advanced/IRowIntervalOperation{TBuffer}.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+using System.Buffers;
+using System.Runtime.CompilerServices;
+using SixLabors.ImageSharp.Memory;
+
+namespace SixLabors.ImageSharp.Advanced
+{
+    /// <summary>
+    /// Defines the contract for an action that operates on a row interval with a temporary buffer.
+    /// </summary>
+    /// <typeparam name="TBuffer">The type of buffer elements.</typeparam>
+    public interface IRowIntervalOperation<TBuffer>
+        where TBuffer : unmanaged
+    {
+        /// <summary>
+        /// Invokes the method passing the row interval and a buffer.
+        /// </summary>
+        /// <param name="rows">The row interval.</param>
+        /// <param name="span">The contiguous region of memory.</param>
+        void Invoke(in RowInterval rows, Span<TBuffer> span);
+    }
+}

src/ImageSharp/Advanced/ParallelUtils/ParallelExecutionSettings.cs → src/ImageSharp/Advanced/ParallelExecutionSettings.cs

@@ -1,15 +1,15 @@
-// Copyright (c) Six Labors and contributors.
+// Copyright (c) Six Labors and contributors.
 // Licensed under the Apache License, Version 2.0.
 
 using System;
 using System.Threading.Tasks;
 
 using SixLabors.ImageSharp.Memory;
 
-namespace SixLabors.ImageSharp.Advanced.ParallelUtils
+namespace SixLabors.ImageSharp.Advanced
 {
     /// <summary>
-    /// Defines execution settings for methods in <see cref="ParallelHelper"/>.
+    /// Defines execution settings for methods in <see cref="ParallelRowIterator"/>.
     /// </summary>
     public readonly struct ParallelExecutionSettings
     {
@@ -89,7 +89,7 @@ public ParallelExecutionSettings MultiplyMinimumPixelsPerTask(int multiplier)
         }
 
         /// <summary>
-        /// Get the default <see cref="SixLabors.ImageSharp.Advanced.ParallelUtils.ParallelExecutionSettings"/> for a <see cref="SixLabors.ImageSharp.Configuration"/>
+        /// Get the default <see cref="SixLabors.ImageSharp.Advanced.ParallelExecutionSettings"/> for a <see cref="SixLabors.ImageSharp.Configuration"/>
         /// </summary>
         /// <param name="configuration">The <see cref="Configuration"/>.</param>
         /// <returns>The <see cref="ParallelExecutionSettings"/>.</returns>

src/ImageSharp/Advanced/ParallelRowIterator.Wrappers.cs

@@ -0,0 +1,110 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+using System.Buffers;
+using System.Runtime.CompilerServices;
+using System.Threading.Tasks;
+using SixLabors.ImageSharp.Memory;
+
+namespace SixLabors.ImageSharp.Advanced
+{
+    /// <content>
+    /// Utility methods for batched processing of pixel row intervals.
+    /// Parallel execution is optimized for image processing based on values defined
+    /// <see cref="ParallelExecutionSettings"/> or <see cref="Configuration"/>.
+    /// Using this class is preferred over direct usage of <see cref="Parallel"/> utility methods.
+    /// </content>
+    public static partial class ParallelRowIterator
+    {
+        private readonly struct WrappingRowIntervalInfo
+        {
+            public readonly int MinY;
+            public readonly int MaxY;
+            public readonly int StepY;
+            public readonly int MaxX;
+
+            public WrappingRowIntervalInfo(int minY, int maxY, int stepY)
+                : this(minY, maxY, stepY, 0)
+            {
+            }
+
+            public WrappingRowIntervalInfo(int minY, int maxY, int stepY, int maxX)
+            {
+                this.MinY = minY;
+                this.MaxY = maxY;
+                this.StepY = stepY;
+                this.MaxX = maxX;
+            }
+        }
+
+        private readonly struct WrappingRowIntervalOperation<T>
+            where T : struct, IRowIntervalOperation
+        {
+            private readonly WrappingRowIntervalInfo info;
+            private readonly T operation;
+
+            [MethodImpl(InliningOptions.ShortMethod)]
+            public WrappingRowIntervalOperation(in WrappingRowIntervalInfo info, in T operation)
+            {
+                this.info = info;
+                this.operation = operation;
+            }
+
+            [MethodImpl(InliningOptions.ShortMethod)]
+            public void Invoke(int i)
+            {
+                int yMin = this.info.MinY + (i * this.info.StepY);
+
+                if (yMin >= this.info.MaxY)
+                {
+                    return;
+                }
+
+                int yMax = Math.Min(yMin + this.info.StepY, this.info.MaxY);
+                var rows = new RowInterval(yMin, yMax);
+
+                // Skip the safety copy when invoking a potentially impure method on a readonly field
+                Unsafe.AsRef(this.operation).Invoke(in rows);
+            }
+        }
+
+        private readonly struct WrappingRowIntervalBufferOperation<T, TBuffer>
+            where T : struct, IRowIntervalOperation<TBuffer>
+            where TBuffer : unmanaged
+        {
+            private readonly WrappingRowIntervalInfo info;
+            private readonly MemoryAllocator allocator;
+            private readonly T operation;
+
+            [MethodImpl(InliningOptions.ShortMethod)]
+            public WrappingRowIntervalBufferOperation(
+                in WrappingRowIntervalInfo info,
+                MemoryAllocator allocator,
+                in T operation)
+            {
+                this.info = info;
+                this.allocator = allocator;
+                this.operation = operation;
+            }
+
+            [MethodImpl(InliningOptions.ShortMethod)]
+            public void Invoke(int i)
+            {
+                int yMin = this.info.MinY + (i * this.info.StepY);
+
+                if (yMin >= this.info.MaxY)
+                {
+                    return;
+                }
+
+                int yMax = Math.Min(yMin + this.info.StepY, this.info.MaxY);
+                var rows = new RowInterval(yMin, yMax);
+
+                using IMemoryOwner<TBuffer> buffer = this.allocator.Allocate<TBuffer>(this.info.MaxX);
+
+                Unsafe.AsRef(this.operation).Invoke(in rows, buffer.Memory.Span);
+            }
+        }
+    }
+}

src/ImageSharp/Advanced/ParallelRowIterator.cs

@@ -0,0 +1,162 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+using System.Buffers;
+using System.Runtime.CompilerServices;
+using System.Threading.Tasks;
+using SixLabors.ImageSharp.Memory;
+
+namespace SixLabors.ImageSharp.Advanced
+{
+    /// <summary>
+    /// Utility methods for batched processing of pixel row intervals.
+    /// Parallel execution is optimized for image processing based on values defined
+    /// <see cref="ParallelExecutionSettings"/> or <see cref="Configuration"/>.
+    /// Using this class is preferred over direct usage of <see cref="Parallel"/> utility methods.
+    /// </summary>
+    public static partial class ParallelRowIterator
+    {
+        /// <summary>
+        /// Iterate through the rows of a rectangle in optimized batches defined by <see cref="RowInterval"/>-s.
+        /// </summary>
+        /// <typeparam name="T">The type of row operation to perform.</typeparam>
+        /// <param name="configuration">The <see cref="Configuration"/> to get the parallel settings from.</param>
+        /// <param name="rectangle">The <see cref="Rectangle"/>.</param>
+        /// <param name="operation">The operation defining the iteration logic on a single <see cref="RowInterval"/>.</param>
+        [MethodImpl(InliningOptions.ShortMethod)]
+        public static void IterateRows<T>(Configuration configuration, Rectangle rectangle, in T operation)
+            where T : struct, IRowIntervalOperation
+        {
+            var parallelSettings = ParallelExecutionSettings.FromConfiguration(configuration);
+            IterateRows(rectangle, in parallelSettings, in operation);
+        }
+
+        /// <summary>
+        /// Iterate through the rows of a rectangle in optimized batches defined by <see cref="RowInterval"/>-s.
+        /// </summary>
+        /// <typeparam name="T">The type of row operation to perform.</typeparam>
+        /// <param name="rectangle">The <see cref="Rectangle"/>.</param>
+        /// <param name="parallelSettings">The <see cref="ParallelExecutionSettings"/>.</param>
+        /// <param name="operation">The operation defining the iteration logic on a single <see cref="RowInterval"/>.</param>
+        public static void IterateRows<T>(
+            Rectangle rectangle,
+            in ParallelExecutionSettings parallelSettings,
+            in T operation)
+            where T : struct, IRowIntervalOperation
+        {
+            ValidateRectangle(rectangle);
+
+            int top = rectangle.Top;
+            int bottom = rectangle.Bottom;
+            int width = rectangle.Width;
+            int height = rectangle.Height;
+
+            int maxSteps = DivideCeil(width * height, parallelSettings.MinimumPixelsProcessedPerTask);
+            int numOfSteps = Math.Min(parallelSettings.MaxDegreeOfParallelism, maxSteps);
+
+            // Avoid TPL overhead in this trivial case:
+            if (numOfSteps == 1)
+            {
+                var rows = new RowInterval(top, bottom);
+                Unsafe.AsRef(operation).Invoke(in rows);
+                return;
+            }
+
+            int verticalStep = DivideCeil(rectangle.Height, numOfSteps);
+            var parallelOptions = new ParallelOptions { MaxDegreeOfParallelism = numOfSteps };
+            var info = new WrappingRowIntervalInfo(top, bottom, verticalStep);
+            var wrappingOperation = new WrappingRowIntervalOperation<T>(in info, in operation);
+
+            Parallel.For(
+                0,
+                numOfSteps,
+                parallelOptions,
+                wrappingOperation.Invoke);
+        }
+
+        /// <summary>
+        /// Iterate through the rows of a rectangle in optimized batches defined by <see cref="RowInterval"/>-s
+        /// instantiating a temporary buffer for each <paramref name="operation"/> invocation.
+        /// </summary>
+        /// <typeparam name="T">The type of row operation to perform.</typeparam>
+        /// <typeparam name="TBuffer">The type of buffer elements.</typeparam>
+        /// <param name="configuration">The <see cref="Configuration"/> to get the parallel settings from.</param>
+        /// <param name="rectangle">The <see cref="Rectangle"/>.</param>
+        /// <param name="operation">The operation defining the iteration logic on a single <see cref="RowInterval"/>.</param>
+        public static void IterateRows<T, TBuffer>(Configuration configuration, Rectangle rectangle, in T operation)
+            where T : struct, IRowIntervalOperation<TBuffer>
+            where TBuffer : unmanaged
+        {
+            var parallelSettings = ParallelExecutionSettings.FromConfiguration(configuration);
+            IterateRows<T, TBuffer>(rectangle, in parallelSettings, in operation);
+        }
+
+        /// <summary>
+        /// Iterate through the rows of a rectangle in optimized batches defined by <see cref="RowInterval"/>-s
+        /// instantiating a temporary buffer for each <paramref name="operation"/> invocation.
+        /// </summary>
+        /// <typeparam name="T">The type of row operation to perform.</typeparam>
+        /// <typeparam name="TBuffer">The type of buffer elements.</typeparam>
+        /// <param name="rectangle">The <see cref="Rectangle"/>.</param>
+        /// <param name="parallelSettings">The <see cref="ParallelExecutionSettings"/>.</param>
+        /// <param name="operation">The operation defining the iteration logic on a single <see cref="RowInterval"/>.</param>
+        public static void IterateRows<T, TBuffer>(
+            Rectangle rectangle,
+            in ParallelExecutionSettings parallelSettings,
+            in T operation)
+            where T : struct, IRowIntervalOperation<TBuffer>
+            where TBuffer : unmanaged
+        {
+            ValidateRectangle(rectangle);
+
+            int top = rectangle.Top;
+            int bottom = rectangle.Bottom;
+            int width = rectangle.Width;
+            int height = rectangle.Height;
+
+            int maxSteps = DivideCeil(width * height, parallelSettings.MinimumPixelsProcessedPerTask);
+            int numOfSteps = Math.Min(parallelSettings.MaxDegreeOfParallelism, maxSteps);
+            MemoryAllocator allocator = parallelSettings.MemoryAllocator;
+
+            // Avoid TPL overhead in this trivial case:
+            if (numOfSteps == 1)
+            {
+                var rows = new RowInterval(top, bottom);
+                using (IMemoryOwner<TBuffer> buffer = allocator.Allocate<TBuffer>(width))
+                {
+                    Unsafe.AsRef(operation).Invoke(rows, buffer.Memory.Span);
+                }
+
+                return;
+            }
+
+            int verticalStep = DivideCeil(height, numOfSteps);
+            var parallelOptions = new ParallelOptions { MaxDegreeOfParallelism = numOfSteps };
+            var info = new WrappingRowIntervalInfo(top, bottom, verticalStep, width);
+            var wrappingOperation = new WrappingRowIntervalBufferOperation<T, TBuffer>(in info, allocator, in operation);
+
+            Parallel.For(
+                0,
+                numOfSteps,
+                parallelOptions,
+                wrappingOperation.Invoke);
+        }
+
+        [MethodImpl(InliningOptions.ShortMethod)]
+        private static int DivideCeil(int dividend, int divisor) => 1 + ((dividend - 1) / divisor);
+
+        private static void ValidateRectangle(Rectangle rectangle)
+        {
+            Guard.MustBeGreaterThan(
+                rectangle.Width,
+                0,
+                $"{nameof(rectangle)}.{nameof(rectangle.Width)}");
+
+            Guard.MustBeGreaterThan(
+                rectangle.Height,
+                0,
+                $"{nameof(rectangle)}.{nameof(rectangle.Height)}");
+        }
+    }
+}