Docs and null check on Configuration.MemoryAllocator.

src/ImageSharp/Configuration.cs

@@ -26,10 +26,11 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// A lazily initialized configuration default instance.
         /// </summary>
-        private static readonly Lazy<Configuration> Lazy = new Lazy<Configuration>(CreateDefaultInstance);
+        private static readonly Lazy<Configuration> Lazy = new(CreateDefaultInstance);
         private const int DefaultStreamProcessingBufferSize = 8096;
         private int streamProcessingBufferSize = DefaultStreamProcessingBufferSize;
         private int maxDegreeOfParallelism = Environment.ProcessorCount;
+        private MemoryAllocator memoryAllocator = MemoryAllocator.Default;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="Configuration" /> class.
@@ -125,9 +126,31 @@ namespace SixLabors.ImageSharp
         public ImageFormatManager ImageFormatsManager { get; set; } = new ImageFormatManager();
 
         /// <summary>
-        /// Gets or sets the <see cref="MemoryAllocator"/> that is currently in use.
+        /// Gets or sets the <see cref="ImageSharp.Memory.MemoryAllocator"/> that is currently in use.
+        /// Defaults to <see cref="ImageSharp.Memory.MemoryAllocator.Default"/>.
+        /// <para />
+        /// Allocators are expensive, so it is strongly recommended to use only one busy instance per process.
+        /// In case you need to customize it, you can ensure this by changing
         /// </summary>
-        public MemoryAllocator MemoryAllocator { get; set; } = MemoryAllocator.Default;
+        /// <remarks>
+        /// It's possible to reduce allocator footprint by assigning a custom instance created with
+        /// <see cref="Memory.MemoryAllocator.Create(MemoryAllocatorSettings)"/>, but note that since the default pooling
+        /// allocators are expensive, it is strictly recommended to use a single process-wide allocator.
+        /// You can ensure this by altering the allocator of <see cref="Default"/>, or by implementing custom application logic that
+        /// manages allocator lifetime.
+        /// <para />
+        /// If an allocator has to be dropped for some reason, <see cref="Memory.MemoryAllocator.ReleaseRetainedResources"/>
+        /// shall be invoked after disposing all associated <see cref="Image"/> instances.
+        /// </remarks>
+        public MemoryAllocator MemoryAllocator
+        {
+            get => this.memoryAllocator;
+            set
+            {
+                Guard.NotNull(value, nameof(this.MemoryAllocator));
+                this.memoryAllocator = value;
+            }
+        }
 
         /// <summary>
         /// Gets the maximum header size of all the formats.
@@ -173,7 +196,7 @@ namespace SixLabors.ImageSharp
             MaxDegreeOfParallelism = this.MaxDegreeOfParallelism,
             StreamProcessingBufferSize = this.StreamProcessingBufferSize,
             ImageFormatsManager = this.ImageFormatsManager,
-            MemoryAllocator = this.MemoryAllocator,
+            memoryAllocator = this.memoryAllocator,
             ImageOperationsProvider = this.ImageOperationsProvider,
             ReadOrigin = this.ReadOrigin,
             FileSystem = this.FileSystem,

tests/ImageSharp.Tests/ConfigurationTests.cs

@@ -149,6 +149,21 @@ namespace SixLabors.ImageSharp.Tests
                     () => config.StreamProcessingBufferSize = 0);
         }
 
+        [Fact]
+        public void MemoryAllocator_Setter_Roundtrips()
+        {
+            MemoryAllocator customAllocator = new SimpleGcMemoryAllocator();
+            var config = new Configuration() { MemoryAllocator = customAllocator };
+            Assert.Same(customAllocator, config.MemoryAllocator);
+        }
+
+        [Fact]
+        public void MemoryAllocator_SetNull_ThrowsArgumentNullException()
+        {
+            var config = new Configuration();
+            Assert.Throws<ArgumentNullException>(() => config.MemoryAllocator = null);
+        }
+
         [Fact]
         public void InheritsDefaultMemoryAllocatorInstance()
         {