NativeContainerAttribute

Description

Allows you to create your own custom native container.

Native containers let you create new container types, which do not allocate any GC memory and give explicit control over allocations. They data contained must be blittable. Native Containers can also be used on jobs, the job system understand NativeContainers and the job debugger ensures that all access to the containers is safe and throws exceptions if any usage code contains race conditions or contains non-deterministic behaviour.

Native containers must embed an AtomicSafetyHandle in order to ensure that the job debugging system can detect any possible race conditions. A Dispose Sentinel is used to detect any leaks immediately.

Note that creating your own custom container has to be done by carefully following the code example below. It is strongly recommended to add test coverage for all scenarios when creating a custom container, particularly for the integration into jobs, ensuring that all race conditions are prevented. When implemented incorrectly, a custom container can easily crash Unity without throwing any useful exception.

using System.Diagnostics;
using System;
using Unity.Collections.LowLevel.Unsafe;
using Unity.Collections;

// Marks our struct as a NativeContainer.
// If ENABLE_UNITY_COLLECTIONS_CHECKS is enabled,
// it is required that m_Safety & m_DisposeSentinel are declared, with exactly these names.
[NativeContainer]
// The [NativeContainerSupportsMinMaxWriteRestriction] enables
// a common jobification pattern where an IJobParallelFor is split into ranges
// And the job is only allowed to access the index range being Executed by that worker thread.
// Effectively limiting access of the array to the specific index passed into the Execute(int index) method
// This attribute requires m_MinIndex & m_MaxIndex to exist.
// and the container is expected to perform out of bounds checks against it.
// m_MinIndex & m_MaxIndex will be set by the job scheduler before Execute is called on the worker thread.
[NativeContainerSupportsMinMaxWriteRestriction]
// It is recommended to always implement a Debugger proxy
// to visualize the contents of the array in VisualStudio and other tools.
[DebuggerDisplay("Length = {Length}")]
[DebuggerTypeProxy(typeof(NativeCustomArrayDebugView<>))]
public struct NativeCustomArray<T> : IDisposable where T : struct
{
    internal IntPtr                   m_Buffer;
    internal int                      m_Length;

#if ENABLE_UNITY_COLLECTIONS_CHECKS
    internal int                      m_MinIndex;
    internal int                      m_MaxIndex;
    internal AtomicSafetyHandle       m_Safety;
    internal DisposeSentinel          m_DisposeSentinel;
    static int                        s_staticSafetyId;

    [BurstDiscard]
    static void AssignStaticSafetyId(ref AtomicSafetyHandle safetyHandle)
    {
        // static safety IDs are unique per-type, and should only be initialized the first time an instance of
        // the type is created.
        if (s_staticSafetyId == 0)
        {
            s_staticSafetyId = AtomicSafetyHandle.NewStaticSafetyId<NativeCustomArray<T>>();

            // Each static safety ID can optionally provide custom error messages for each AtomicSafetyErrorType.
            // This is rarely necessary, but can be useful if higher-level code can provide more helpful error guidance
            // than the default error message.
            // See the documentation for AtomicSafetyHandle.SetCustomErrorMessage() for details on the message format.
            AtomicSafetyHandle.SetCustomErrorMessage(s_staticSafetyId, AtomicSafetyErrorType.DeallocatedFromJob,
                "The {5} has been deallocated before being passed into a job. For NativeCustomArrays, this usually means <type-specific guidance here>");
        }
        AtomicSafetyHandle.SetStaticSafetyId(ref safetyHandle, s_staticSafetyId);
    }

#endif

    internal Allocator                m_AllocatorLabel;

    public NativeCustomArray(int length, Allocator allocator)
    {
        ulong totalSize = (ulong)UnsafeUtility.SizeOf<T>() * (ulong)length;

#if ENABLE_UNITY_COLLECTIONS_CHECKS
        // Native allocation is only valid for Temp, Job and Persistent
        if (allocator <= Allocator.None)
            throw new ArgumentException("Allocator must be Temp, TempJob or Persistent", "allocator");
        if (length < 0)
            throw new ArgumentOutOfRangeException("length", "Length must be >= 0");
        if (!UnsafeUtility.IsBlittable<T>())
            throw new ArgumentException(string.Format("{0} used in NativeCustomArray<{0}> must be blittable", typeof(T)));
#endif

        m_Buffer = UnsafeUtility.Malloc(totalSize, UnsafeUtility.AlignOf<T>(), allocator);
        UnsafeUtility.MemClear(m_Buffer , totalSize);

        m_Length = length;
        m_AllocatorLabel = allocator;

#if ENABLE_UNITY_COLLECTIONS_CHECKS
        m_MinIndex = 0;
        m_MaxIndex = length - 1;
        DisposeSentinel.Create(m_Buffer, allocator, out m_Safety, out m_DisposeSentinel, 0);
        AssignStaticSafetyId(ref array.m_Safety);
#endif
    }

    public int Length { get { return m_Length; } }

    public unsafe T this[int index]
    {
        get
        {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
            // If the container is currently not allowed to read from the buffer
            // then this will throw an exception.
            // This handles all cases, from already disposed containers
            // to safe multithreaded access.
            AtomicSafetyHandle.CheckReadAndThrow(m_Safety);

            // Perform out of range checks based on
            // the NativeContainerSupportsMinMaxWriteRestriction policy
            if (index < m_MinIndex || index > m_MaxIndex)
                FailOutOfRangeError(index);
#endif
            // Read the element from the allocated native memory
            return UnsafeUtility.ReadArrayElement<T>(m_Buffer, index);
        }

        set
        {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
            // If the container is currently not allowed to write to the buffer
            // then this will throw an exception.
            // This handles all cases, from already disposed containers
            // to safe multithreaded access.
            AtomicSafetyHandle.CheckWriteAndThrow(m_Safety);

            // Perform out of range checks based on
            // the NativeContainerSupportsMinMaxWriteRestriction policy
            if (index < m_MinIndex || index > m_MaxIndex)
                FailOutOfRangeError(index);
#endif
            // Writes value to the allocated native memory
            UnsafeUtility.WriteArrayElement(m_Buffer, index, value);
        }
    }

    public T[] ToArray()
    {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
        AtomicSafetyHandle.CheckReadAndThrow(m_Safety);
#endif

        var array = new T[Length];
        for (var i = 0; i < Length; i++)
            array[i] = UnsafeUtility.ReadArrayElement<T>(m_Buffer, i);
        return array;
    }

    public bool IsCreated
    {
        get { return m_Buffer != IntPtr.Zero; }
    }

    public void Dispose()
    {
#if ENABLE_UNITY_COLLECTIONS_CHECKS
        DisposeSentinel.Dispose(m_Safety, ref m_DisposeSentinel);
#endif

        UnsafeUtility.Free(m_Buffer, m_AllocatorLabel);
        m_Buffer = IntPtr.Zero;
        m_Length = 0;
    }

#if ENABLE_UNITY_COLLECTIONS_CHECKS
    private void FailOutOfRangeError(int index)
    {
        if (index < Length && (m_MinIndex != 0 || m_MaxIndex != Length - 1))
            throw new IndexOutOfRangeException(string.Format(
                "Index {0} is out of restricted IJobParallelFor range [{1}...{2}] in ReadWriteBuffer.\n" +
                "ReadWriteBuffers are restricted to only read & write the element at the job index. " +
                "You can use double buffering strategies to avoid race conditions due to " +
                "reading & writing in parallel to the same elements from a job.",
                index, m_MinIndex, m_MaxIndex));

        throw new IndexOutOfRangeException(string.Format("Index {0} is out of range of '{1}' Length.", index, Length));
    }

#endif
}

// Visualizes the custom array in the C# debugger
internal sealed class NativeCustomArrayDebugView<T> where T : struct
{
    private NativeCustomArray<T> m_Array;

    public NativeCustomArrayDebugView(NativeCustomArray<T> array)
    {
        m_Array = array;
    }

    public T[] Items
    {
        get { return m_Array.ToArray(); }
    }
}