Firstborn/Library/PackageCache/com.unity.collections@1.4.0/README.md
Schaken-Mods b486678290 Library -Artifacts
Library -Artifacts
2023-03-28 12:24:16 -05:00

8.3 KiB

Unity.Collections

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

Package CI Summary

ReleaseBadge ReleaseBadge

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
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

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

For licensing details see LICENSE.md