Unity.Collections

A C# collections library providing data structures that can be used in jobs, and optimized by Burst compiler.

Package CI Summary

Documentation

https://docs.unity3d.com/Packages/com.unity.collections@0.14/manual/index.html

Data structures

The Unity.Collections package includes the following data structures:

Data structure	Description	Documentation
BitField32	Fixed size 32-bit array of bits.	Documentation
BitField64	Fixed size 64-bit array of bits.	Documentation
NativeBitArray	Arbitrary sized array of bits.	Documentation
UnsafeBitArray	Arbitrary sized array of bits, without any thread safety check features.	Documentation
NativeList	An unmanaged, resizable list.	Documentation
UnsafeList	An unmanaged, resizable list, without any thread safety check features.	Documentation
NativeHashMap	Unordered associative array, a collection of keys and values.	Documentation
UnsafeHashMap	Unordered associative array, a collection of keys and values, without any thread safety check features.	Documentation
NativeHashSet	Set of values.	Documentation

The items in this package build upon the NativeArray, NativeSlice, and other members of the Unity.Collections namespace, which Unity includes in the core module.

Notation

Native* container prefix signifies that containers have debug safety mechanisms which will warn users when a container is used incorrectly in regard with thread-safety, or memory management. Unsafe* containers do not provide those safety warnings, and the user is fully responsible to guarantee that code will execute correctly. Almost all Native* containers are implemented by using Unsafe* container of the same kind internally. In the release build, since debug safety mechanism is disabled, there should not be any significant performance difference between Unsafe* and Native* containers. Unsafe* containers are in Unity.Collections.LowLevel.Unsafe namespace, while Native* containers are in Unity.Collections namespace.

Determinism

Populating containers from parallel jobs is never deterministic, except when using NativeStream or UnsafeStream. If determinism is required, consider sorting the container as a separate step or post-process it on a single thread.

Known Issues

All containers allocated with Allocator.Temp on the same thread use a shared AtomicSafetyHandle instance. This is problematic when using NativeParallelHashMap, NativeParallelMultiHashMap, NativeParallelHashSet and NativeList together in situations where their secondary safety handle is used. This means that operations that invalidate an enumerator for either of these collections (or the NativeArray returned by NativeList.AsArray) will also invalidate all other previously acquired enumerators. For example, this will throw when safety checks are enabled:

var list = new NativeList<int>(Allocator.Temp);
list.Add(1);

// This array uses the secondary safety handle of the list, which is
// shared between all Allocator.Temp allocations.
var array = list.AsArray();

var list2 = new NativeParallelHashSet<int>(Allocator.Temp);

// This invalidates the secondary safety handle, which is also used
// by the list above.
list2.TryAdd(1);

// This throws an InvalidOperationException because the shared safety
// handle was invalidated.
var x = array[0];

This defect will be addressed in a future release.

Licensing

Unity Companion License (“License”) Software Copyright © 2017-2020 Unity Technologies ApS

For licensing details see LICENSE.md