comments and docs

Author: antonfirsov

src/ImageSharp/ImageFrame{TPixel}.cs

@@ -170,6 +170,9 @@ internal ImageFrame(Configuration configuration, ImageFrame<TPixel> source)
         /// <summary>
         /// Gets the representation of the pixels as a <see cref="Span{T}"/> of contiguous memory
         /// at row <paramref name="rowIndex"/> beginning from the first pixel on that row.
+        /// <para />
+        /// WARNING: Disposing or leaking the underlying image while still working with it's <see cref="Span{T}"/>
+        /// might lead to memory corruption.
         /// </summary>
         /// <param name="rowIndex">The row.</param>
         /// <returns>The <see cref="Span{TPixel}"/></returns>
@@ -185,6 +188,13 @@ public Span<TPixel> GetPixelRowSpan(int rowIndex)
         /// <summary>
         /// Gets the representation of the pixels as a <see cref="Span{T}"/> in the source image's pixel format
         /// stored in row major order, if the backing buffer is contiguous.
+        /// <para />
+        /// To ensure the memory is contiguous, <see cref="Configuration.MemoryAllocator"/> should be initialized
+        /// with a <see cref="MemoryAllocator"/> that enforces larger contiguous buffers.
+        /// See <see cref="MemoryAllocatorOptions.MinimumContiguousBlockSizeBytes"/>.
+        /// <para />
+        /// WARNING: Disposing or leaking the underlying image while still working with it's <see cref="Span{T}"/>
+        /// might lead to memory corruption.
         /// </summary>
         /// <param name="span">The <see cref="Span{T}"/>.</param>
         /// <returns>The <see cref="bool"/>.</returns>

src/ImageSharp/Image{TPixel}.cs

@@ -206,6 +206,9 @@ internal Image(Configuration configuration, ImageMetadata metadata, IEnumerable<
         /// <summary>
         /// Gets the representation of the pixels as a <see cref="Span{T}"/> of contiguous memory
         /// at row <paramref name="rowIndex"/> beginning from the first pixel on that row.
+        /// <para />
+        /// WARNING: Disposing or leaking the underlying image while still working with it's <see cref="Span{T}"/>
+        /// might lead to memory corruption.
         /// </summary>
         /// <param name="rowIndex">The row.</param>
         /// <returns>The <see cref="Span{TPixel}"/></returns>

src/ImageSharp/IndexedImageFrame{TPixel}.cs

@@ -75,6 +75,9 @@ internal IndexedImageFrame(Configuration configuration, int width, int height, R
         /// <summary>
         /// Gets the representation of the pixels as a <see cref="ReadOnlySpan{T}"/> of contiguous memory
         /// at row <paramref name="rowIndex"/> beginning from the first pixel on that row.
+        /// <para />
+        /// WARNING: Disposing or leaking the underlying <see cref="IndexedImageFrame{TPixel}"/> while still working with it's <see cref="Span{T}"/>
+        /// might lead to memory corruption.
         /// </summary>
         /// <param name="rowIndex">The row index in the pixel buffer.</param>
         /// <returns>The pixel row as a <see cref="ReadOnlySpan{T}"/>.</returns>

src/ImageSharp/Memory/Allocators/Internals/SharedArrayPoolBuffer{T}.cs

@@ -20,6 +20,9 @@ public SharedArrayPoolBuffer(int lengthInElements)
             this.array = ArrayPool<byte>.Shared.Rent(this.lengthInBytes);
         }
 
+        // The worst thing that could happen is that a VERY poorly written user code holding a Span<TPixel> on the stack,
+        // while loosing the reference to Image<TPixel> (or disposing it) may write to an unrelated ArrayPool array.
+        // This is an unlikely scenario we mitigate by a warning in GetPixelRowSpan(i) APIs.
 #pragma warning disable CA2015 // Adding a finalizer to a type derived from MemoryManager<T> may permit memory to be freed while it is still in use by a Span<T>
         ~SharedArrayPoolBuffer() => this.Dispose(false);
 #pragma warning restore

src/ImageSharp/Memory/Allocators/Internals/UniformUnmanagedMemoryPool.Buffer{T}.cs

@@ -71,6 +71,10 @@ public FinalizableBuffer(UniformUnmanagedMemoryPool pool, UnmanagedMemoryHandle
                 bufferHandle.AssignedToNewOwner();
             }
 
+            // A VERY poorly written user code holding a Span<TPixel> on the stack,
+            // while loosing the reference to Image<TPixel> (or disposing it) may write to (now unrelated) pool buffer,
+            // or cause memory corruption if the underlying UmnanagedMemoryHandle has been released.
+            // This is an unlikely scenario we mitigate a warning in GetPixelRowSpan(i) APIs.
 #pragma warning disable CA2015 // Adding a finalizer to a type derived from MemoryManager<T> may permit memory to be freed while it is still in use by a Span<T>
             ~FinalizableBuffer() => this.Dispose(false);
 #pragma warning  restore