Release 5.20.0

Author: sakno

CHANGELOG.md

@@ -1,6 +1,30 @@
 Release Notes
 ====
 
+# 03-30-2025
+<a href="https://www.nuget.org/packages/dotnext/5.20.0">DotNext 5.20.0</a>
+* Introduced `List.Repeat()` static method to construct read-only lists of repeatable items. Similar to [Enumerable.Repeat](https://learn.microsoft.com/en-us/dotnet/api/system.linq.enumerable.repeat) but returns [IReadOnlyList&lt;T&gt;](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.ireadonlylist-1)
+* Added `Number.RoundUp` and `Number.RoundDown` generic extension methods to round the numbers to the multiple of the specified value
+
+<a href="https://www.nuget.org/packages/dotnext.metaprogramming/5.20.0">DotNext.Metaprogramming 5.20.0</a>
+* Updated dependencies
+
+<a href="https://www.nuget.org/packages/dotnext.unsafe/5.20.0">DotNext.Unsafe 5.20.0</a>
+* Added static methods to `UnmanagedMemory` for page-aligned memory allocation
+
+<a href="https://www.nuget.org/packages/dotnext.threading/5.20.0">DotNext.Threading 5.20.0</a>
+* Improved debugging experience of `RandomAccessCache<TKey, TValue>` class
+* Added `AsyncCounter.TryIncrement` method that allows to specify the upper bound of the counter. As a result, `AsyncCounter` class can be used as a rate limiter
+
+<a href="https://www.nuget.org/packages/dotnext.io/5.20.0">DotNext.IO 5.20.0</a>
+* Introduced `DiskSpacePool` class to assist with building caches when the cached data stored on the disk rather than in memory. The class can be combined with `RandomAccessCache<TKey, TValue>` to organize L1 application-specific caches (while L0 resides in memory and can be organized on top of `RandomAccessCache<TKey, TValue>` as well)
+
+<a href="https://www.nuget.org/packages/dotnext.net.cluster/5.20.0">DotNext.Net.Cluster 5.20.0</a>
+* Updated dependencies
+
+<a href="https://www.nuget.org/packages/dotnext.aspnetcore.cluster/5.20.0">DotNext.AspNetCore.Cluster 5.20.0</a>
+* Updated dependencies
+
 # 03-06-2025
 <a href="https://www.nuget.org/packages/dotnext/5.19.1">DotNext 5.19.1</a>
 * Smallish performance improvements of `SparseBufferWriter<T>`

README.md

@@ -44,27 +44,29 @@ All these things are implemented in 100% managed code on top of existing .NET AP
 * [NuGet Packages](https://www.nuget.org/profiles/rvsakno)
 
 # What's new
-Release Date: 03-06-2025
+Release Date: 03-30-2025
 
-<a href="https://www.nuget.org/packages/dotnext/5.19.1">DotNext 5.19.1</a>
-* Smallish performance improvements of `SparseBufferWriter<T>`
+<a href="https://www.nuget.org/packages/dotnext/5.20.0">DotNext 5.20.0</a>
+* Introduced `List.Repeat()` static method to construct read-only lists of repeatable items. Similar to [Enumerable.Repeat](https://learn.microsoft.com/en-us/dotnet/api/system.linq.enumerable.repeat) but returns [IReadOnlyList&lt;T&gt;](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.ireadonlylist-1)
+* Added `Number.RoundUp` and `Number.RoundDown` generic extension methods to round the numbers to the multiple of the specified value
 
-<a href="https://www.nuget.org/packages/dotnext.metaprogramming/5.19.1">DotNext.Metaprogramming 5.19.1</a>
+<a href="https://www.nuget.org/packages/dotnext.metaprogramming/5.20.0">DotNext.Metaprogramming 5.20.0</a>
 * Updated dependencies
 
-<a href="https://www.nuget.org/packages/dotnext.unsafe/5.19.1">DotNext.Unsafe 5.19.1</a>
-* Updated dependencies
+<a href="https://www.nuget.org/packages/dotnext.unsafe/5.20.0">DotNext.Unsafe 5.20.0</a>
+* Added static methods to `UnmanagedMemory` for page-aligned memory allocation
 
-<a href="https://www.nuget.org/packages/dotnext.threading/5.19.1">DotNext.Threading 5.19.1</a>
-* Fixed weight counting in `RandomAccessCache<TKey, TValue, TWeight>` class
+<a href="https://www.nuget.org/packages/dotnext.threading/5.20.0">DotNext.Threading 5.20.0</a>
+* Improved debugging experience of `RandomAccessCache<TKey, TValue>` class
+* Added `AsyncCounter.TryIncrement` method that allows to specify the upper bound of the counter. As a result, `AsyncCounter` class can be used as a rate limiter
 
-<a href="https://www.nuget.org/packages/dotnext.io/5.19.1">DotNext.IO 5.19.1</a>
-* Updated dependencies
+<a href="https://www.nuget.org/packages/dotnext.io/5.20.0">DotNext.IO 5.20.0</a>
+* Introduced `DiskSpacePool` class to assist with building caches when the cached data stored on the disk rather than in memory. The class can be combined with `RandomAccessCache<TKey, TValue>` to organize L1 application-specific caches (while L0 resides in memory and can be organized on top of `RandomAccessCache<TKey, TValue>` as well)
 
-<a href="https://www.nuget.org/packages/dotnext.net.cluster/5.19.1">DotNext.Net.Cluster 5.19.1</a>
+<a href="https://www.nuget.org/packages/dotnext.net.cluster/5.20.0">DotNext.Net.Cluster 5.20.0</a>
 * Updated dependencies
 
-<a href="https://www.nuget.org/packages/dotnext.aspnetcore.cluster/5.19.1">DotNext.AspNetCore.Cluster 5.19.1</a>
+<a href="https://www.nuget.org/packages/dotnext.aspnetcore.cluster/5.20.0">DotNext.AspNetCore.Cluster 5.20.0</a>
 * Updated dependencies
 
 Changelog for previous versions located [here](./CHANGELOG.md).

src/DotNext.Benchmarks/DotNext.Benchmarks.csproj

@@ -8,7 +8,7 @@
     <RootNamespace>DotNext</RootNamespace>
     <StartupObject>DotNext.Program</StartupObject>
     <IsPackable>false</IsPackable>
-    <Version>5.19.0</Version>
+    <Version>5.20.0</Version>
     <Authors>.NET Foundation and Contributors</Authors>
     <Product>.NEXT Family of Libraries</Product>
     <Description>Various benchmarks demonstrating performance aspects of .NEXT extensions</Description>

src/DotNext.IO/DotNext.IO.csproj

@@ -11,7 +11,7 @@
     <Authors>.NET Foundation and Contributors</Authors>
     <Company />
     <Product>.NEXT Family of Libraries</Product>
-    <VersionPrefix>5.19.1</VersionPrefix>
+    <VersionPrefix>5.20.0</VersionPrefix>
     <VersionSuffix></VersionSuffix>
     <AssemblyName>DotNext.IO</AssemblyName>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>

src/DotNext.IO/IO/MemoryMappedFiles/ReadOnlySequenceAccessor.cs

@@ -31,12 +31,12 @@ internal MemoryManager(IMemorySegmentProvider cursor, in Segment segment)
             Segment = segment;
         }
 
-        public override unsafe Span<byte> GetSpan()
+        public override Span<byte> GetSpan()
             => Cursor.GetSpan(in Segment);
 
         public override Memory<byte> Memory => CreateMemory(Segment.Length);
 
-        public override unsafe MemoryHandle Pin(int index)
+        public override MemoryHandle Pin(int index)
             => Cursor.Pin(in Segment, index);
 
         public override void Unpin()
@@ -201,7 +201,7 @@ private unsafe Span<byte> GetSpan(in Segment window)
         if (current != window)
         {
             segment?.ReleasePointerAndDispose();
-            ptr = default;
+            ptr = null;
             current = window;
             segment = mappedFile.CreateViewAccessor(window.Offset, window.Length, MemoryMappedFileAccess.Read);
             segment.SafeMemoryMappedViewHandle.AcquirePointer(ref ptr);

src/DotNext.IO/Runtime/Caching/DiskSpacePool.FreeList.cs

@@ -0,0 +1,86 @@
+using System.Runtime.CompilerServices;
+
+namespace DotNext.Runtime.Caching;
+
+public partial class DiskSpacePool
+{
+    private volatile SegmentHandle? freeList;
+    private long cursor;
+
+    private long AllocateSegment() => Interlocked.Add(ref cursor, MaxSegmentSize);
+    
+    private SegmentHandle RentOffset()
+    {
+        SegmentHandle? tmp;
+        for (var headCopy = freeList;; headCopy = tmp)
+        {
+            if (headCopy is null)
+            {
+                tmp = new(this);
+                break;
+            }
+
+            tmp = headCopy.TryGetNext(out var next)
+                ? Interlocked.CompareExchange(ref freeList, next, headCopy)
+                : freeList;
+
+            if (ReferenceEquals(tmp, headCopy))
+            {
+                tmp.MoveToCompletedState(this);
+                break;
+            }
+        }
+
+        return tmp;
+    }
+
+    private void ReturnOffset(long offset)
+    {
+        var node = new SegmentHandle(offset);
+        for (SegmentHandle? headCopy = freeList, tmp;; headCopy = tmp)
+        {
+            node.SetNext(headCopy);
+
+            tmp = Interlocked.CompareExchange(ref freeList, node, headCopy);
+            if (ReferenceEquals(tmp, headCopy))
+                break;
+        }
+    }
+    
+    internal sealed class SegmentHandle(long offset)
+    {
+        // Can be null, or Node, or DiskSpacePool, or Sentinel. Null treats as null Node.
+        // Every type represents a state of the node.
+        // Possible transitions:
+        // null or Node => DiskSpacePool - taken from the free list
+        // DiskSpacePool => Sentinel - disposed
+        private object? ownerOrNext;
+
+        internal SegmentHandle(DiskSpacePool pool)
+            : this(pool.AllocateSegment())
+            => ownerOrNext = pool;
+
+        internal bool TryGetNext(out SegmentHandle? next)
+        {
+            var ownerOrNextCopy = ownerOrNext;
+            bool result;
+            next = (result = ownerOrNextCopy is null or SegmentHandle)
+                ? Unsafe.As<SegmentHandle?>(ownerOrNextCopy)
+                : null;
+
+            return result;
+        }
+
+        internal void SetNext(SegmentHandle? next) => ownerOrNext = next;
+
+        internal void MoveToCompletedState(DiskSpacePool pool) => ownerOrNext = pool;
+
+        internal DiskSpacePool? TryGetOwner() => ReferenceEquals(ownerOrNext, Sentinel.Instance) ? null : Unsafe.As<DiskSpacePool?>(ownerOrNext);
+
+        internal void MoveToDisposedState() => ownerOrNext = Sentinel.Instance;
+        
+        internal long Offset => offset;
+
+        public override string ToString() => offset.ToString();
+    }
+}

src/DotNext.IO/Runtime/Caching/DiskSpacePool.IO.cs

@@ -0,0 +1,63 @@
+using Microsoft.Win32.SafeHandles;
+
+namespace DotNext.Runtime.Caching;
+
+using Buffers;
+
+public partial class DiskSpacePool
+{
+    private readonly SafeFileHandle handle;
+    private readonly IReadOnlyList<ReadOnlyMemory<byte>> zeroes;
+
+    private void EraseSegment(long offset)
+    {
+        switch (zeroes)
+        {
+            case []:
+                break;
+            case [var buffer]:
+                RandomAccess.Write(handle, buffer.Span, offset);
+                break;
+            default:
+                RandomAccess.Write(handle, zeroes, offset);
+                break;
+        }
+    }
+
+    private void ReleaseSegment(long offset)
+    {
+        try
+        {
+            EraseSegment(offset);
+        }
+        finally
+        {
+            ReturnOffset(offset);
+        }
+    }
+
+    private ValueTask EraseSegmentAsync(long offset) => zeroes switch
+    {
+        [] => ValueTask.CompletedTask,
+        [var buffer] => RandomAccess.WriteAsync(handle, buffer, offset),
+        _ => RandomAccess.WriteAsync(handle, zeroes, offset),
+    };
+
+    private void Write(long absoluteOffset, ReadOnlySpan<byte> buffer, int segmentOffset)
+        => RandomAccess.Write(handle, buffer, absoluteOffset + segmentOffset);
+    
+    private ValueTask WriteAsync(long absoluteOffset, ReadOnlyMemory<byte> buffer, int segmentOffset, CancellationToken token)
+        => RandomAccess.WriteAsync(handle, buffer, absoluteOffset + segmentOffset, token);
+
+    private int Read(long absoluteOffset, Span<byte> buffer, int segmentOffset)
+        => Read(absoluteOffset, buffer, segmentOffset, MaxSegmentSize - segmentOffset);
+
+    private int Read(long absoluteOffset, Span<byte> buffer, int segmentOffset, int length)
+        => RandomAccess.Read(handle, buffer.TrimLength(length), absoluteOffset + segmentOffset);
+
+    private ValueTask<int> ReadAsync(long absoluteOffset, Memory<byte> buffer, int segmentOffset, CancellationToken token)
+        => ReadAsync(absoluteOffset, buffer, segmentOffset, MaxSegmentSize - segmentOffset, token);
+
+    private ValueTask<int> ReadAsync(long absoluteOffset, Memory<byte> buffer, int segmentOffset, int length, CancellationToken token)
+        => RandomAccess.ReadAsync(handle, buffer.TrimLength(length), absoluteOffset + segmentOffset, token);
+}