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
`UnsafeHashSet`	Set of values, without any thread safety check features.	Documentation
`NativeParallelHashMap`	Unordered associative array, a collection of keys and values.	Documentation
`UnsafeParallelHashMap`	Unordered associative array, a collection of keys and values, without any thread safety check features.	Documentation
`NativeParallelHashSet`	Set of values.	Documentation
`UnsafeParallelHashSet`	Set of values, without any thread safety check features.	Documentation
`NativeParallelMultiHashMap`	Unordered associative array, a collection of keys and values. This container can store multiple values for every key.	Documentation
`UnsafeParallelMultiHashMap`	Unordered associative array, a collection of keys and values, without any thread safety check features. This container can store multiple values for every key.	Documentation
`NativeStream`	A deterministic data streaming supporting parallel reading and parallel writing. Allows you to write different types or arrays into a single stream.	Documentation
`UnsafeStream`	A deterministic data streaming supporting parallel reading and parallel writings, without any thread safety check features. Allows you to write different types or arrays into a single stream.	Documentation
`NativeReference`	An unmanaged, reference container.	Documentation
`UnsafeAppendBuffer`	An unmanaged, untyped, buffer, without any thread safety check features.	Documentation
`UnsafeRingQueue`	Fixed-size circular buffer, without any thread safety check features.	Documentation
`UnsafeAtomicCounter32`	32-bit atomic counter.	Documentation
`UnsafeAtomicCounter64`	64-bit atomic counter.	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

For licensing details see LICENSE.md

9.2 KiB Raw Blame History