UnmanagedMemoryBlock`1.cs

using System;
using System.Collections;
using System.Collections.Generic;
using System.ComponentModel;
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.IO;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using System.Threading;
using NumSharp.Backends.Unmanaged.Pooling;
using NumSharp.Unmanaged.Memory;
using NumSharp.Utilities;

namespace NumSharp.Backends.Unmanaged
{
    public unsafe struct UnmanagedMemoryBlock<T> : IUnmanagedMemoryBlock, IMemoryBlock<T>, IEnumerable<T>, IEquatable<UnmanagedMemoryBlock<T>>, ICloneable where T : unmanaged
    {
        private readonly Disposer _disposer;
        public readonly long Count;
        public readonly T* Address;
        public readonly long BytesCount;

        /// <summary>
        ///
        /// </summary>
        /// <param name="count">The length in objects of <typeparamref name="T"/> and not in bytes.</param>
        /// <remarks>
        ///     Does claim ownership since allocation is publicly. Routes through
        ///     <see cref="SizeBucketedBufferPool.Take"/> so recently-freed
        ///     buffers of matching size are reused — eliminates the
        ///     ~500 µs first-touch / kernel-mode page-fault cost for the
        ///     dominant element-wise binary-op output allocation pattern,
        ///     which lets routed binary ops cross from NumPy-parity into
        ///     NumPy-better territory.
        /// </remarks>
        [MethodImpl(Optimize)]
        public UnmanagedMemoryBlock(long count)
        {
            // A wrapped byte count asks the allocator for a small (often zero) block and gets one,
            // so the corruption is silent. See AllocationGuard.
            AllocationGuard.CheckElementCount(count, InfoOf<T>.Size);
            var bytes = BytesCount = count * InfoOf<T>.Size;
            var ptr = SizeBucketedBufferPool.Take(bytes);
            _disposer = new Disposer(ptr, bytes);
            Address = (T*)ptr;
            Count = count;
        }

        /// <summary>
        ///     Construct as a wrapper around pointer and given length without claiming ownership.
        /// </summary>
        /// <param name="ptr"></param>
        /// <param name="count">The length in objects of <typeparamref name="T"/> and not in bytes.</param>
        /// <remarks>
        ///     Does NOT claim ownership: wraps <paramref name="ptr"/> with the non-owning
        ///     <c>Disposer.Null</c> marker (<c>AllocationType.Wrap</c>), so disposing this block
        ///     never frees <paramref name="ptr"/>. The caller remains responsible for the
        ///     lifetime of the underlying memory.
        /// </remarks>
        [MethodImpl(Optimize)]
        public UnmanagedMemoryBlock(T* ptr, long count)
        {
            _disposer = Disposer.Null;
            Address = ptr;
            Count = count;
            BytesCount = count * InfoOf<T>.Size;
        }

        /// <summary>
        ///     Construct with externally allocated memory and a custom <paramref name="dispose"/> function.
        /// </summary>
        /// <param name="start">Pointer to externally allocated unmanaged memory.</param>
        /// <param name="count">The length in objects of <typeparamref name="T"/> and not in bytes.</param>
        /// <param name="dispose">Cleanup action called when memory is released.</param>
        /// <remarks>
        ///     Claims ownership of the memory. Caller is responsible for GC.AddMemoryPressure
        ///     if the memory is unmanaged and large enough to warrant it.
        /// </remarks>
        [MethodImpl(OptimizeAndInline)]
        public UnmanagedMemoryBlock(T* start, long count, Action dispose)
        {
            Count = count;
            BytesCount = InfoOf<T>.Size * count;
            _disposer = new Disposer(dispose); // Caller tracks pressure for their allocation
            Address = start;
        }

        /// <summary>
        ///     Construct with externally allocated memory settings this memory block as owner.
        /// </summary>
        /// <param name="handle"></param>
        /// <param name="count">The length in objects of <typeparamref name="T"/> and not in bytes.</param>
        /// <remarks>Does claim ownership.</remarks>
        [MethodImpl(OptimizeAndInline)]
        public UnmanagedMemoryBlock(GCHandle handle, long count)
        {
            Count = count;
            BytesCount = InfoOf<T>.Size * count;
            Address = (T*)handle.AddrOfPinnedObject();
            _disposer = new Disposer(handle);
        }

        /// <summary>
        ///     Construct with externally allocated memory and a custom <paramref name="dispose"/> function.
        /// </summary>
        /// <param name="handle"></param>
        /// <param name="count">The length in objects of <typeparamref name="T"/> and not in bytes.</param>
        /// <param name="dispose"></param>
        /// <remarks>Does claim ownership.</remarks>
        [MethodImpl(OptimizeAndInline)]
        public UnmanagedMemoryBlock(GCHandle handle, long count, Action dispose)
        {
            Count = count;
            BytesCount = InfoOf<T>.Size * count;
            Address = (T*)handle.AddrOfPinnedObject();
            _disposer = new Disposer(dispose);
        }

        /// <summary>
        ///
        /// </summary>
        /// <param name="count">The length in objects of <typeparamref name="T"/> and not in bytes.</param>
        /// <param name="fill"></param>
        [MethodImpl(OptimizeAndInline)]
        public UnmanagedMemoryBlock(long count, T fill) : this(count)
        {
            Fill(fill, 0, count);
        }

        /// <summary>
        ///     Discriminator tag for the zero-initialized ctor. Keeps it from
        ///     colliding with the <c>(long count, T fill)</c> overload when
        ///     <typeparamref name="T"/> is a 1-byte type (e.g. <see cref="bool"/>),
        ///     where <c>(count, default(T))</c> would otherwise be ambiguous.
        /// </summary>
        private readonly struct Zeroed { }

        /// <summary>
        ///     Allocate a zero-initialized block via
        ///     <see cref="SizeBucketedBufferPool.TakeZeroed"/> (calloc / OS
        ///     demand-zero pages) — no per-element fill loop. This is the
        ///     np.zeros / fill-with-default fast path: a 10M-element block is
        ///     zeroed in ~0.01 ms instead of ~14 ms.
        ///
        ///     Correct for every supported dtype because the all-zero bit
        ///     pattern equals <c>default(T)</c> for all 15 of them — including
        ///     <see cref="System.Half"/>, <see cref="float"/>, <see cref="double"/>,
        ///     <see cref="decimal"/> and <see cref="System.Numerics.Complex"/>
        ///     (each of whose "zero" value is represented by all-zero bytes).
        /// </summary>
        /// <param name="count">The length in objects of <typeparamref name="T"/> and not in bytes.</param>
        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> AllocateZeroed(long count)
            => new UnmanagedMemoryBlock<T>(count, default(Zeroed));

        /// <summary>
        ///     Zero-initialized ctor backing <see cref="AllocateZeroed"/>.
        ///     Claims ownership of a calloc'd buffer (Native disposer), so it
        ///     returns to <see cref="SizeBucketedBufferPool"/> on free just
        ///     like the noisy <see cref="UnmanagedMemoryBlock(long)"/> ctor.
        /// </summary>
        [MethodImpl(Optimize)]
        private UnmanagedMemoryBlock(long count, Zeroed _)
        {
            AllocationGuard.CheckElementCount(count, InfoOf<T>.Size);
            var bytes = BytesCount = count * InfoOf<T>.Size;
            Count = count;

            // Windows large-block fast path: VirtualAlloc returns lazy
            // demand-zero pages, dodging the process heap's eager commit+memset
            // for mid-size calloc. Small sizes and non-Windows fall through to
            // calloc (already lazy via mmap there); so does a VirtualAlloc that
            // unexpectedly fails.
            if (!SizeBucketedBufferPool.GuardPagesEnabled && OsVirtualMemory.IsSupported && bytes >= OsVirtualMemory.ThresholdBytes)
            {
                var vptr = OsVirtualMemory.Alloc(bytes);
                if (vptr != IntPtr.Zero)
                {
                    _disposer = new Disposer(vptr, bytes, virtualAlloc: true);
                    Address = (T*)vptr;
                    return;
                }
            }

            var ptr = SizeBucketedBufferPool.TakeZeroed(bytes);
            _disposer = new Disposer(ptr, bytes);
            Address = (T*)ptr;
        }

        #region Static

        #region FromArray

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }


        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,,,,,] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromArray(T[,,,,,,,,,,,,,,,] arr, bool copy)
        {
            if (!copy)
                return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length);

            var ret = new UnmanagedMemoryBlock<T>(arr.Length);
            fixed (T* arrptr = arr)
            {
                new UnmanagedMemoryBlock<T>(arrptr, arr.Length).CopyTo(ret);
            }

            return ret;
        }

        #endregion

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromBuffer(byte[] arr)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(arr, GCHandleType.Pinned), arr.Length / InfoOf<T>.Size);
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromBuffer(byte[] arr, bool copy)
        {
            return new UnmanagedMemoryBlock<T>(GCHandle.Alloc(copy ? arr.Clone() : arr, GCHandleType.Pinned), arr.Length / InfoOf<T>.Size);
        }

        /// <summary>
        /// Create a memory block from a byte buffer with offset and count support.
        /// </summary>
        /// <param name="arr">The source byte array.</param>
        /// <param name="byteOffset">Byte offset into the array.</param>
        /// <param name="count">Number of elements of type T to include (-1 for all available).</param>
        /// <param name="copy">If true, copies the data; if false, creates a view (pins the array).</param>
        /// <returns>A memory block viewing or copying the specified region.</returns>
        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromBuffer(byte[] arr, long byteOffset, long count, bool copy)
        {
            int itemSize = InfoOf<T>.Size;
            long availableBytes = arr.Length - byteOffset;
            long maxCount = availableBytes / itemSize;
            long actualCount = count < 0 ? maxCount : count;

            if (copy)
            {
                // Allocate new memory and copy
                var ret = new UnmanagedMemoryBlock<T>(actualCount);
                fixed (byte* src = &arr[byteOffset])
                {
                    Buffer.MemoryCopy(src, ret.Address, ret.BytesCount, actualCount * itemSize);
                }
                return ret;
            }
            else
            {
                // Pin the array and return a view with offset
                var handle = GCHandle.Alloc(arr, GCHandleType.Pinned);
                var baseAddr = (byte*)handle.AddrOfPinnedObject();
                return new UnmanagedMemoryBlock<T>((T*)(baseAddr + byteOffset), actualCount, () => handle.Free());
            }
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> FromPool(StackedMemoryPool manager)
        {
            Debug.Assert(manager.SingleSize / InfoOf<T>.Size > 0);
            var buffer = manager.Take();
            return new UnmanagedMemoryBlock<T>((T*)buffer, 1, () => manager.Return(buffer));
        }

        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> Copy(UnmanagedMemoryBlock<T> source)
        {
            var itemCount = source.Count;
            var len = itemCount * InfoOf<T>.Size;
            var ret = new UnmanagedMemoryBlock<T>(itemCount);
            source.CopyTo(ret);
            //source.AsSpan().CopyTo(ret.AsSpan()); //TODO! Benchmark at netcore 3.0, it should be faster than buffer.memorycopy.
            return ret;
        }

        /// <summary>
        ///     
        /// </summary>
        /// <param name="address">The address of the first <typeparamref name="T"/></param>
        /// <param name="count">How many <typeparamref name="T"/> to copy, not how many bytes.</param>
        /// <returns></returns>
        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> Copy(void* address, long count)
        {
            var ret = new UnmanagedMemoryBlock<T>(count);
            new UnmanagedMemoryBlock<T>((T*)address, count).CopyTo(ret);
            //source.AsSpan().CopyTo(ret.AsSpan()); //TODO! Benchmark at netcore 3.0, it should be faster than buffer.memorycopy.
            return ret;
        }

        /// <summary>
        ///
        /// </summary>
        /// <param name="address"></param>
        /// <param name="count">How many <typeparamref name="T"/> to copy, not how many bytes.</param>
        /// <returns></returns>
        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> Copy(IntPtr address, long count)
        {
            return Copy((void*)address, count);
        }

        /// <summary>
        ///
        /// </summary>
        /// <param name="address">The address of the first <typeparamref name="T"/></param>
        /// <param name="count">How many <typeparamref name="T"/> to copy, not how many bytes.</param>
        /// <returns></returns>
        [MethodImpl(OptimizeAndInline)]
        public static UnmanagedMemoryBlock<T> Copy(T* address, long count)
        {
            return Copy((void*)address, count);
        }

        #endregion

        public T this[long index]
        {
            [MethodImpl(OptimizeAndInline)] get => *(Address + index);
            [MethodImpl(OptimizeAndInline)] set => *(Address + index) = value;
        }

        /// <summary>
        /// Backwards-compatible indexer accepting int index.
        /// </summary>
        public T this[int index]
        {
            [MethodImpl(OptimizeAndInline)] get => this[(long)index];
            [MethodImpl(OptimizeAndInline)] set => this[(long)index] = value;
        }

        [MethodImpl(Optimize)]
        public void Reallocate(long length, bool copyOldValues = false)
        {
            if (copyOldValues)
            {
                var @new = new UnmanagedMemoryBlock<T>(length);
                var bytes = Math.Min(Count, length) * InfoOf<T>.Size;
                Buffer.MemoryCopy(Address, @new.Address, bytes, bytes);
                Free();
                this = @new;
            }
            else
            {
                //we do not have to allocate first in we do not copy values.
                Free();
                this = new UnmanagedMemoryBlock<T>(length);
            }
        }

        [MethodImpl(Optimize)]
        public void Reallocate(long length, T fill, bool copyOldValues = false)
        {
            if (copyOldValues)
            {
                var @new = new UnmanagedMemoryBlock<T>(length);
                var bytes = Math.Min(Count, length) * InfoOf<T>.Size;
                Buffer.MemoryCopy(Address, @new.Address, bytes, bytes);

                if (length > Count)
                {
                    @new.Fill(fill, Count, length - Count);
                }

                Free();
                this = @new;
            }
            else
            {
                //we do not have to allocate first in we do not copy values.
                Free();
                this = new UnmanagedMemoryBlock<T>(length, fill);
            }
        }

        /// <summary>
        ///     Fills the contents of this span with the given value.
        /// </summary>
        [MethodImpl(OptimizeAndInline)]
        public void Fill(T value)
        {
            if (Count == 0)
                return;

            if (Unsafe.SizeOf<T>() == 1 && Count < uint.MaxValue)
            {
                T tmp = value; // Avoid taking address of the "value" argument. It would regress performance of the loop below.

                Unsafe.InitBlockUnaligned(Address, Unsafe.As<T, byte>(ref tmp), (uint)Count);
            }
            else
            {
                // Do all math as nuint to avoid unnecessary 64->32->64 bit integer truncations
                UInt64 length = (uint)Count;
                if (length == 0)
                    return;

                T* addr = Address;

                // TODO: Create block fill for value types of power of two sizes e.g. 2,4,8,16

                ulong i = 0;
                for (; i < (length & ~7UL); i += 8)
                {
                    *(addr + (i)) = value;
                    *(addr + (i + 1)) = value;
                    *(addr + (i + 2)) = value;
                    *(addr + (i + 3)) = value;
                    *(addr + (i + 4)) = value;
                    *(addr + (i + 5)) = value;
                    *(addr + (i + 6)) = value;
                    *(addr + (i + 7)) = value;
                }

                if (i < (length & ~3UL))
                {
                    *(addr + (i)) = value;
                    *(addr + (i + 1)) = value;
                    *(addr + (i + 2)) = value;
                    *(addr + (i + 3)) = value;
                    i += 4;
                }

                for (; i < length; i++)
                {
                    addr[i] = value;
                }
            }
        }

        /// <summary>
        ///     Fills the contents of this span with the given value.
        /// </summary>
        [MethodImpl(OptimizeAndInline)]
        public void Fill(T value, long offset, long count)
        {
            if (Count == 0 || count == 0)
                return;

            if (Unsafe.SizeOf<T>() == 1 && Count < uint.MaxValue)
            {
                if (Count - offset <= 0)
                    return;

                T tmp = value; // Avoid taking address of the "value" argument. It would regress performance of the loop below.

                Unsafe.InitBlockUnaligned(Address + offset, Unsafe.As<T, byte>(ref tmp), (uint)count);
            }
            else
            {
                // Do all math as nuint to avoid unnecessary 64->32->64 bit integer truncations
                if (Count - offset <= 0)
                    return;

                ulong length = (ulong)count;
                T* addr = Address + offset;

                // TODO: Create block fill for value types of power of two sizes e.g. 2,4,8,16

                ulong i = 0;
                for (; i < (length & ~7UL); i += 8)
                {
                    *(addr + (i)) = value;
                    *(addr + (i + 1)) = value;
                    *(addr + (i + 2)) = value;
                    *(addr + (i + 3)) = value;
                    *(addr + (i + 4)) = value;
                    *(addr + (i + 5)) = value;
                    *(addr + (i + 6)) = value;
                    *(addr + (i + 7)) = value;
                }

                if (i < (length & ~3UL))
                {
                    *(addr + (i)) = value;
                    *(addr + (i + 1)) = value;
                    *(addr + (i + 2)) = value;
                    *(addr + (i + 3)) = value;
                    i += 4;
                }

                for (; i < length; i++)
                {
                    addr[i] = value;
                }
            }
        }

        /// <summary>
        /// Backwards-compatible overload accepting int index.
        /// </summary>
        [MethodImpl(OptimizeAndInline)]
        public T GetIndex(int index) => GetIndex((long)index);

        /// <summary>
        /// Backwards-compatible overload accepting int index.
        /// </summary>
        [MethodImpl(OptimizeAndInline)]
        public ref T GetRefTo(int index) => ref GetRefTo((long)index);

        /// <summary>
        /// Backwards-compatible overload accepting int index.
        /// </summary>
        [MethodImpl(OptimizeAndInline)]
        public void SetIndex(int index, ref T value) => SetIndex((long)index, ref value);

        /// <summary>
        /// Backwards-compatible overload accepting int index.
        /// </summary>
        [MethodImpl(OptimizeAndInline)]
        public void SetIndex(int index, T value) => SetIndex((long)index, value);


        [MethodImpl(OptimizeAndInline)]
        public T GetIndex(long index)
        {
            return *(Address + index);
        }

        [MethodImpl(OptimizeAndInline)]
        public ref T GetRefTo(long index)
        {
            return ref *(Address + index);
        }

        [MethodImpl(OptimizeAndInline)]
        public void SetIndex(long index, ref T value)
        {
            *(Address + index) = value;
        }

        [MethodImpl(OptimizeAndInline)]
        public void SetIndex(long index, T value)
        {
            *(Address + index) = value;
        }

        [MethodImpl(OptimizeAndInline)]
        public void Free()
        {
            // Backwards-compatible "force free, ignore refcount" — used by
            // legacy callers (ArraySlice.DangerousFree). New ARC-aware code
            // should call Release instead.
            _disposer.Dispose();
        }

        // ---------------------------------------------------------------
        // ARC plumbing — forwards to the inner Disposer.
        // ---------------------------------------------------------------

        [MethodImpl(OptimizeAndInline)]
        public bool TryAddRef() => _disposer.TryAddRef();

        [MethodImpl(OptimizeAndInline)]
        public void Release() => _disposer.Release();

        [MethodImpl(OptimizeAndInline)]
        public void Abandon() => _disposer.Abandon();

        public bool IsReleased => _disposer.IsReleased;

        /// <summary>
        ///     <c>true</c> when this block is held by at most one logical reference.
        ///     Forwards to the inner <see cref="Disposer"/>.
        /// </summary>
        public bool IsUniquelyReferenced => _disposer.IsUniquelyReferenced;

        [MethodImpl(OptimizeAndInline)]
        public IEnumerator<T> GetEnumerator()
        {
            for (long i = 0; i < Count; i++) yield return GetIndex(i);
        }

        [MethodImpl(OptimizeAndInline)]
        IEnumerator IEnumerable.GetEnumerator()
        {
            return GetEnumerator();
        }

        [MethodImpl(OptimizeAndInline)]
        public bool Contains(T item)
        {
            long len = Count;
            for (long i = 0; i < len; i++)
            {
                if ((*(Address + i)).Equals(item)) return true;
            }

            return false;
        }

        [MethodImpl(Optimize)]
        public void CopyTo(T[] array, int arrayIndex)
        {
            long len = Count;
            for (long i = 0; i < len; i++)
            {
                array[i + arrayIndex] = *(Address + i);
            }
        }

        [MethodImpl(Optimize)]
        public void CopyTo(UnmanagedMemoryBlock<T> memoryBlock, long arrayIndex)
        {
            //TODO! at netcore 3, AsSpan.CopyTo might be faster.
            if (memoryBlock == null)
                throw new ArgumentNullException(nameof(memoryBlock));
            if ((ulong)arrayIndex > (ulong)memoryBlock.Count || Count > memoryBlock.Count - arrayIndex)
                throw new ArgumentOutOfRangeException(nameof(arrayIndex));

            Buffer.MemoryCopy(Address, memoryBlock.Address + arrayIndex, InfoOf<T>.Size * (memoryBlock.Count - arrayIndex), InfoOf<T>.Size * Count);
        }

        [MethodImpl(Optimize)]
        public void CopyTo(T* array, long arrayIndex, long lengthToCopy)
        {
            //TODO! at netcore 3, AsSpan.CopyTo might be faster.
            var len = InfoOf<T>.Size * lengthToCopy;
            Buffer.MemoryCopy(Address + arrayIndex, array, len, len);
        }

        /// <summary>Copies the elements of the <see cref="T:System.Collections.ICollection" /> to an <see cref="T:System.Array" />, starting at a particular <see cref="T:System.Array" /> index.</summary>
        /// <param name="array">The one-dimensional <see cref="T:System.Array" /> that is the destination of the elements copied from <see cref="T:System.Collections.ICollection" />. The <see cref="T:System.Array" /> must have zero-based indexing. </param>
        /// <param name="arrayIndex">The zero-based index in <paramref name="array" /> at which copying begins. </param>
        /// <exception cref="T:System.ArgumentNullException">
        /// <paramref name="array" /> is <see langword="null" />. </exception>
        /// <exception cref="T:System.ArgumentOutOfRangeException">
        /// <paramref name="arrayIndex" /> is less than zero. </exception>
        /// <exception cref="T:System.ArgumentException">
        /// <paramref name="array" /> is multidimensional.-or- The number of elements in the source <see cref="T:System.Collections.ICollection" /> is greater than the available space from <paramref name="arrayIndex" /> to the end of the destination <paramref name="array" />.-or-The type of the source <see cref="T:System.Collections.ICollection" /> cannot be cast automatically to the type of the destination <paramref name="array" />.</exception>
        [MethodImpl(Optimize)]
        public void CopyTo(Array array, int arrayIndex)
        {
            if (!(array is T[] arr))
                throw new InvalidCastException("Unable to CopyTo a type that is not " + typeof(T).Name + "[]");

            CopyTo(arr, arrayIndex);
        }

        /// <summary>
        ///     Performs a copy to this memory block.
        /// </summary>
        /// <returns></returns>
        public UnmanagedMemoryBlock<T> Clone()
        {
            var ret = new UnmanagedMemoryBlock<T>(Count);
            this.CopyTo(ret);
            return ret;
        }

        #region Explicit Implementations

        /// <summary>
        ///     The size of a single item stored in <see cref="IMemoryBlock.Address"/>.
        /// </summary>
        int IMemoryBlock.ItemLength => InfoOf<T>.Size;

        /// <summary>
        ///     The start address of this memory block.
        /// </summary>
        unsafe T* IMemoryBlock<T>.Address => Address;

        /// <summary>
        ///     The start address of this memory block.
        /// </summary>
        unsafe void* IMemoryBlock.Address => Address;

        /// <summary>
        ///     How many items are stored in <see cref="IMemoryBlock.Address"/>?
        /// </summary>
        /// <remarks></remarks>
        long IMemoryBlock.Count => Count;

        /// <summary>
        ///     The items with length of <see cref="IMemoryBlock.TypeCode"/> are present in <see cref="IMemoryBlock.Address"/>.
        /// </summary>
        /// <remarks>Calculated by <see cref="IMemoryBlock.Count"/>*<see cref="IMemoryBlock.ItemLength"/></remarks>
        long IMemoryBlock.BytesLength => BytesCount;

        /// <summary>
        ///     The <see cref="NPTypeCode"/> of the type stored inside this memory block.
        /// </summary>
        NPTypeCode IMemoryBlock.TypeCode => InfoOf<T>.NPTypeCode;

        [EditorBrowsable(EditorBrowsableState.Never)]
        public ref T GetPinnableReference()
        {
            return ref *Address;
        }

        /// <summary>Creates a new object that is a copy of the current instance.</summary>
        /// <returns>A new object that is a copy of this instance.</returns>
        object ICloneable.Clone()
        {
            return Clone();
        }

        #endregion

        #region Equality

        /// <summary>Indicates whether the current object is equal to another object of the same type.</summary>
        /// <param name="other">An object to compare with this object.</param>
        /// <returns>
        /// <see langword="true" /> if the current object is equal to the <paramref name="other" /> parameter; otherwise, <see langword="false" />.</returns>
        [MethodImpl(OptimizeAndInline)]
        public bool Equals(UnmanagedMemoryBlock<T> other)
        {
            return Count == other.Count && Address == other.Address;
        }

        /// <summary>Indicates whether this instance and a specified object are equal.</summary>
        /// <param name="obj">The object to compare with the current instance. </param>
        /// <returns>
        /// <see langword="true" /> if <paramref name="obj" /> and this instance are the same type and represent the same value; otherwise, <see langword="false" />. </returns>
        [MethodImpl(OptimizeAndInline)]
        public override bool Equals(object obj)
        {
            return obj is UnmanagedMemoryBlock<T> other && Equals(other);
        }

        /// <summary>Returns the hash code for this instance.</summary>
        /// <returns>A 32-bit signed integer that is the hash code for this instance.</returns>
        [MethodImpl(OptimizeAndInline)]
        public override int GetHashCode()
        {
            unchecked
            {
                return (unchecked((int)Count) * 397) ^ unchecked((int)(long)Address);
            }
        }

        /// <summary>Returns a value that indicates whether the values of two <see cref="T:NumSharp.Backends.Unmanaged.UnmanagedArray`1" /> objects are equal.</summary>
        /// <param name="left">The first value to compare.</param>
        /// <param name="right">The second value to compare.</param>
        /// <returns>true if the <paramref name="left" /> and <paramref name="right" /> parameters have the same value; otherwise, false.</returns>
        [MethodImpl(OptimizeAndInline)]
        public static bool operator ==(UnmanagedMemoryBlock<T> left, UnmanagedMemoryBlock<T> right)
        {
            return left.Equals(right);
        }

        /// <summary>Returns a value that indicates whether two <see cref="T:NumSharp.Backends.Unmanaged.UnmanagedArray`1" /> objects have different values.</summary>
        /// <param name="left">The first value to compare.</param>
        /// <param name="right">The second value to compare.</param>
        /// <returns>true if <paramref name="left" /> and <paramref name="right" /> are not equal; otherwise, false.</returns>
        [MethodImpl(OptimizeAndInline)]
        public static bool operator !=(UnmanagedMemoryBlock<T> left, UnmanagedMemoryBlock<T> right)
        {
            return !left.Equals(right);
        }

        #endregion

        private class Disposer : IDisposable
        {
            public static readonly Disposer Null = new Disposer();

            private enum AllocationType
            {
                Native,
                GCHandle,
                External,
                Wrap,
                Virtual
            }

            // -----------------------------------------------------------------
            // Atomic reference counting (ARC).
            //
            // Encoding:
            //   _refCount >= 0  → live, with N live references
            //   _refCount == -1 → released (NativeMemory.Free called)
            //
            // The state transition from 0 → -1 is the "claim free" step;
            // performed by Release via CompareExchange. Concurrent TryAddRef
            // observing _refCount == 0 may race with that CAS:
            //   - If the AddRef CAS (0 → 1) wins, the Release CAS (0 → -1)
            //     fails and no free happens. The new owner is responsible.
            //   - If the Release CAS wins, the AddRef CAS fails because it
            //     observes -1 (or because its own CAS sees the new value);
            //     TryAddRef returns false.
            // Either ordering preserves the invariant "free happens iff the
            // final transition into 0 references is observed as final".
            //
            // Wrap allocations (Disposer.Null and any AllocationType.Wrap)
            // bypass refcount entirely — they are non-owning markers that
            // never free.
            // -----------------------------------------------------------------
            private long _refCount;

            // Guard against the race where a Release wins the 0→-1 CAS at
            // the same instant the finalizer runs. Both call sites must
            // pass through this exchange to ensure the native free happens
            // exactly once.
            private int _freed;

            private readonly AllocationType _type;

            private readonly IntPtr Address;
            private readonly GCHandle _gcHandle;
            private readonly Action _dispose;
            private readonly long _bytesCount;


            /// <summary>
            ///     Construct a AllocationType.Native (NativeMemory.Alloc)
            /// </summary>
            /// <param name="address">The address of the allocated memory.</param>
            /// <param name="bytesCount">The size in bytes of the allocation (for GC memory pressure tracking).</param>
            public Disposer(IntPtr address, long bytesCount)
            {
                Address = address;
                _bytesCount = bytesCount;
                _type = AllocationType.Native;

                // GC memory pressure for Native allocations is POOL-OWNED
                // (Wave 2.4): SizeBucketedBufferPool.Take registers pressure
                // when it actually calls NativeMemory.Alloc and unregisters
                // when it actually frees — pooled reuse neither adds nor
                // removes. Per-block Add/Remove here double-billed pooled
                // buffers and cost a GC pressure pair on every transient
                // result array (the issue #501 protection is preserved at
                // the pool layer).
            }

            /// <summary>
            ///     Construct a AllocationType.Virtual (VirtualAlloc-backed,
            ///     used by the large zeroed-allocation fast path). Unlike
            ///     <see cref="AllocationType.Native"/> these buffers are NOT
            ///     pooled — they are released straight back to the OS via
            ///     <see cref="OsVirtualMemory.Free"/> (instant for the pages
            ///     never faulted in), so this disposer OWNS its GC pressure
            ///     (registered here, released on free) the same way the
            ///     External path does.
            /// </summary>
            /// <param name="address">Base address from <see cref="OsVirtualMemory.Alloc"/>.</param>
            /// <param name="bytesCount">Allocation size in bytes (GC pressure).</param>
            /// <param name="virtualAlloc">Discriminates this ctor from the Native one; always true.</param>
            public Disposer(IntPtr address, long bytesCount, bool virtualAlloc)
            {
                Address = address;
                _bytesCount = bytesCount;
                _type = AllocationType.Virtual;

                if (bytesCount > 0)
                    GC.AddMemoryPressure(bytesCount);
            }

            /// <summary>
            ///     Construct a AllocationType.GCHandle
            /// </summary>
            /// <param name="gcHandle"></param>
            public Disposer(GCHandle gcHandle)
            {
                _gcHandle = gcHandle;
                _type = AllocationType.GCHandle;
            }

            /// <summary>
            ///     Construct a AllocationType.External
            /// </summary>
            /// <param name="dispose">The cleanup action to invoke on disposal.</param>
            /// <param name="bytesCount">
            ///     Optional: Size in bytes for GC memory pressure tracking.
            ///     Pass 0 for managed memory (GCHandle) or when caller manages pressure.
            ///     Pass actual bytes for unmanaged memory to inform GC.
            /// </param>
            public Disposer(Action dispose, long bytesCount = 0)
            {
                _dispose = dispose;
                _bytesCount = bytesCount;
                _type = AllocationType.External;

                // Track memory pressure for external unmanaged memory
                if (bytesCount > 0)
                    GC.AddMemoryPressure(bytesCount);
            }

            /// <summary>
            ///     Construct a AllocationType.Wrap
            /// </summary>
            private Disposer()
            {
                _type = AllocationType.Wrap;
            }

            [MethodImpl(OptimizeAndInline), SuppressMessage("ReSharper", "PossibleInvalidOperationException")]
            private void ReleaseUnmanagedResources()
            {
                // Single-shot guard: only the first thread through here
                // performs the native free. All other races (concurrent
                // Release + finalizer + explicit Dispose) short-circuit.
                if (Interlocked.Exchange(ref _freed, 1) != 0)
                    return;

                // Once freed, the finalizer would be a guaranteed no-op
                // (_freed == 1) — pull this Disposer out of the finalizer
                // queue so the refcount-driven release path (NDArray Dispose
                // OR the NDArray finalizer's Release) doesn't leave a dead
                // finalizable object churning the finalizer thread. Harmless
                // when called from the finalizer itself or after Dispose's
                // own SuppressFinalize.
                GC.SuppressFinalize(this);

                switch (_type)
                {
                    case AllocationType.Native:
                        // Route back through the size-bucketed pool so the
                        // next same-size allocation can reuse this buffer
                        // warm (matches the NativeMemory.Alloc call the
                        // owning constructor made via SizeBucketedBufferPool.Take).
                        // GC pressure is pool-owned (registered at true alloc,
                        // unregistered at true free) — no per-block Remove.
                        Pooling.SizeBucketedBufferPool.Return(Address, _bytesCount);
                        return;
                    case AllocationType.Wrap:
                        return;
                    case AllocationType.Virtual:
                        // Return the reservation straight to the OS (no pool):
                        // VirtualFree is instant for pages that were never
                        // faulted in — the common np.zeros-then-drop case.
                        Pooling.OsVirtualMemory.Free(Address);
                        if (_bytesCount > 0)
                            GC.RemoveMemoryPressure(_bytesCount);
                        return;
                    case AllocationType.External:
                        _dispose();
                        if (_bytesCount > 0)
                            GC.RemoveMemoryPressure(_bytesCount);
                        return;
                    case AllocationType.GCHandle:
                        _gcHandle.Free();
                        return;
                    default:
                        throw new ArgumentOutOfRangeException();
                }
            }

            // ---------------------------------------------------------------
            // ARC public surface.
            // ---------------------------------------------------------------

            /// <summary>
            /// Add a logical reference. Returns false if the buffer is already released.
            /// </summary>
            [MethodImpl(OptimizeAndInline)]
            public bool TryAddRef()
            {
                // Non-owning wraps are immortal — refcount is meaningless.
                if (_type == AllocationType.Wrap) return true;

                long c;
                do
                {
                    c = Interlocked.Read(ref _refCount);
                    if (c < 0) return false;          // already released
                } while (Interlocked.CompareExchange(ref _refCount, c + 1, c) != c);
                return true;
            }

            /// <summary>
            /// Drop a logical reference. Frees the buffer when the final reference is released.
            /// </summary>
            [MethodImpl(OptimizeAndInline)]
            public void Release()
            {
                if (_type == AllocationType.Wrap) return;

                long n = Interlocked.Decrement(ref _refCount);
                if (n == 0)
                {
                    // Claim the free transition 0 → -1 atomically. If the
                    // CAS fails it means another thread either AddRef'd
                    // (made it 1) or already claimed the free — either way
                    // we step back. ReleaseUnmanagedResources is internally
                    // idempotent via _freed so a lost race is still safe.
                    if (Interlocked.CompareExchange(ref _refCount, -1, 0) == 0)
                        ReleaseUnmanagedResources();
                }
                else if (n < 0)
                {
                    // Stray Release on already-released block. Restore the
                    // sentinel back to -1 so future TryAddRef still rejects.
                    // Each thread's Decrement is paired with this Increment,
                    // so concurrent strays self-balance one-for-one.
                    Interlocked.Increment(ref _refCount);
                }
            }

            /// <summary>
            /// Drop a logical reference WITHOUT claiming the eager free when the count
            /// reaches zero — the finalizer-path counterpart of <see cref="Release"/>.
            ///
            /// An <see cref="NDArray"/> finalizer proves only that THAT wrapper became
            /// unreachable; it proves nothing about other reachable aliases of the same
            /// buffer (a bare <c>UnmanagedStorage</c>/<c>IArraySlice</c> handed out via
            /// <c>GetData()</c> holds no counted reference). Claiming the 0 → -1 free
            /// transition from a finalizer therefore freed memory such an alias still
            /// reads — the <c>SlicingWithNegativeIndex1</c> use-after-free. Leaving the
            /// count at 0 keeps the block alive for exactly as long as it stays
            /// reachable: this Disposer's own finalizer frees (and pools) it in the GC
            /// cycle after the LAST alias dies, and a later <see cref="TryAddRef"/>
            /// (a new NDArray wrapping a live alias) legitimately revives 0 → 1.
            /// Deterministic <see cref="Release"/> (Dispose / NDScope) keeps the eager
            /// free — there the caller asserts no alias outlives.
            /// </summary>
            [MethodImpl(OptimizeAndInline)]
            public void Abandon()
            {
                if (_type == AllocationType.Wrap) return;

                long n = Interlocked.Decrement(ref _refCount);
                if (n < 0)
                {
                    // Stray Abandon on an already-released block (same as Release's
                    // stray handling): restore the -1 sentinel so TryAddRef rejects.
                    Interlocked.Increment(ref _refCount);
                }
            }

            /// <summary>Diagnostic: true once the buffer has been freed.</summary>
            public bool IsReleased
            {
                [MethodImpl(OptimizeAndInline)]
                get => Volatile.Read(ref _freed) != 0;
            }

            /// <summary>
            /// <c>true</c> when at most one logical reference is held (refcount &lt;= 1).
            /// Non-owning wraps are immortal (refcount is meaningless) and report
            /// <c>true</c>. Used by resize's refcheck to detect buffer sharing.
            /// </summary>
            public bool IsUniquelyReferenced
            {
                [MethodImpl(OptimizeAndInline)]
                get => _type == AllocationType.Wrap || Interlocked.Read(ref _refCount) <= 1;
            }

            /// <summary>
            /// Backwards-compatible "force free" entry point. Maps to the
            /// finalizer's behavior: drops any remaining refs and frees.
            /// Prefer <see cref="Release"/> for ARC-aware code paths.
            /// </summary>
            public void Dispose()
            {
                ReleaseUnmanagedResources();
                GC.SuppressFinalize(this);
            }

            /// <summary>Finalizer is the safety net: runs only if the user forgot to Release all refs.</summary>
            ~Disposer()
            {
                // The Disposer is unreachable, so no other thread can call
                // AddRef/Release on it concurrently. If _freed wasn't set,
                // free now — covers the "user forgot" path.
                if (Volatile.Read(ref _freed) == 0)
                    ReleaseUnmanagedResources();
            }
        }
    }
}