Merge pull request #1890 from shimat/docs/asrows-parallel-remarks

Add Parallel.For usage guidance to AsRows<T> XML docs and regression test

Author: shimat

src/OpenCvSharp/Modules/core/Mat/Mat.cs

@@ -4283,6 +4283,19 @@ public unsafe Span<T> RowSpan<T>(int row) where T : unmanaged
     /// <typeparam name="T">Element type. Must match the matrix element type (e.g. <see cref="Vec3b"/> for CV_8UC3).</typeparam>
     /// <returns>A <see cref="MatRowAccessor{T}"/> over this matrix.</returns>
     /// <exception cref="InvalidOperationException">Thrown when the matrix is not 2-dimensional.</exception>
+    /// <remarks>
+    /// <b>Parallel usage:</b> Because <see cref="MatRowAccessor{T}"/> is a <c>ref struct</c> it cannot be
+    /// captured by a lambda closure. Call this method inside each <c>Parallel.For</c> iteration to obtain
+    /// a per-thread local accessor:
+    /// <code>
+    /// Parallel.For(0, mat.Rows, y =&gt;
+    /// {
+    ///     Span&lt;float&gt; row = mat.AsRows&lt;float&gt;()[y];
+    ///     for (int x = 0; x &lt; row.Length; x++)
+    ///         row[x] = ComputeValue(y, x);
+    /// });
+    /// </code>
+    /// </remarks>
     public unsafe MatRowAccessor<T> AsRows<T>() where T : unmanaged
     {
         ThrowIfDisposed();

src/OpenCvSharp/Modules/core/Mat/MatRowAccessor.cs

@@ -25,6 +25,20 @@
 /// This is a <c>ref struct</c> and therefore cannot be stored in fields, boxed, or used as a
 /// generic type argument.
 /// </para>
+/// <para>
+/// <b>Parallel usage:</b> <see cref="MatRowAccessor{T}"/> is safe to use concurrently from multiple threads
+/// as long as each thread writes to a distinct set of rows. Because <see cref="MatRowAccessor{T}"/> is a
+/// <c>ref struct</c> it cannot be captured by a lambda closure; instead, call <see cref="Mat.AsRows{T}"/>
+/// inside each iteration to obtain a per-thread local accessor:
+/// <code>
+/// Parallel.For(0, mat.Rows, y =&gt;
+/// {
+///     Span&lt;float&gt; row = mat.AsRows&lt;float&gt;()[y];
+///     for (int x = 0; x &lt; row.Length; x++)
+///         row[x] = ComputeValue(y, x);
+/// });
+/// </code>
+/// </para>
 /// </remarks>
 public readonly ref struct MatRowAccessor<T> where T : unmanaged
 {

test/OpenCvSharp.Tests/core/MatTest.cs

@@ -1289,4 +1289,41 @@ public void SubmatOfMultiDimensionalMat()
             }
         }
     }
+
+    // Regression test for https://github.com/shimat/opencvsharp/issues/1889
+    [Fact]
+    public void AsRowsParallelFor()
+    {
+        const int rows = 500;
+        const int cols = 1_000;
+
+        using var matX = new Mat(rows, cols, MatType.CV_32FC1);
+        using var matY = new Mat(rows, cols, MatType.CV_32FC1);
+        matX.SetTo(Scalar.All(0f));
+        matY.SetTo(Scalar.All(0f));
+
+        Parallel.For(0, rows, y =>
+        {
+            var rowX = matX.AsRows<float>()[y];
+            var rowY = matY.AsRows<float>()[y];
+            for (var x = 0; x < cols; x++)
+            {
+                rowX[x] = 11f;
+                rowY[x] = 12f;
+            }
+        });
+
+        var resultX = matX.AsRows<float>();
+        var resultY = matY.AsRows<float>();
+        for (var y = 0; y < rows; y++)
+        {
+            var rowX = resultX[y];
+            var rowY = resultY[y];
+            for (var x = 0; x < cols; x++)
+            {
+                Assert.Equal(11f, rowX[x]);
+                Assert.Equal(12f, rowY[x]);
+            }
+        }
+    }
 }