|How do you use documentation throughout your workflow? Share your experience with us by taking this survey.|
The drawback to the safety system’s process of copying data is that it also isolates the results of a job within each copy. To overcome this limitation you need to store the results in a type of shared memory called NativeContainer.
NativeContainer is a managed value type that provides a relatively safe C# wrapper for native memory. It contains a pointer to an unmanaged allocation. When used with the Unity C# Job System, a
NativeContainer allows a job to access data shared with the main thread rather than working with a copy.
Note: The Entity Component System (ECS) package extends the
Unity.Collections namespace to include other types of
NativeList- a resizable
NativeHashMap- key and value pairs.
NativeMultiHashMap- multiple values per key.
NativeQueue- a first in, first out (FIFO) queue.
The safety system is built into all
NativeContainer types. It tracks what is reading and writing to any
Note: All safety checks on
NativeContainer types (such as out of bounds checks, deallocation checks, and race condition checks) are only available in the Unity Editor and Play Mode.
Part of this safety system is the DisposeSentinel and AtomicSafetyHandle. The
DisposeSentinel detects memory leaks and gives you an error if you have not correctly freed your memory. Triggering the memory leak error happens long after the leak occurred.
AtomicSafetyHandle to transfer ownership of a
NativeContainer in code. For example, if two scheduled jobs are writing to the same
NativeArray, the safety system throws an exception with a clear error message that explains why and how to solve the problem. The safety system throws this exception when you schedule the offending job.
In this case, you can schedule a job with a dependency
See in Glossary. The first job can write to the
NativeContainer, and once it has finished executing, the next job can then safely read and write to that same
NativeContainer. The read and write restrictions also apply when accessing data from the main thread. The safety system does allow multiple jobs to read from the same data in parallel.
By default, when a job has access to a
NativeContainer, it has both read and write access. This configuration can slow performance. The C# Job System does not allow you to schedule a job that has write access to a
NativeContainer at the same time as another job that is writing to it.
If a job does not need to write to a
NativeContainer, mark the
NativeContainer with the
[ReadOnly] attribute, like so:
[ReadOnly] public NativeArray<int> input;
In the above example, you can execute the job at the same time as other jobs that also have read-only access to the first
Note: There is no protection against accessing static data from within a job. Accessing static data circumvents all safety systems and can crash Unity. For more information, see C# Job System tips and troubleshooting.
When creating a
NativeContainer, you must specify the type of memory allocation you need. The allocation type depends on the length of time the job runs. This way you can tailor the allocation to get the best performance possible in each situation.
There are three Allocator types for
NativeContainer memory allocation and release. You need to specify the appropriate one when instantiating your
Tempto jobs. You also need to call the
Disposemethod before you return from the method call (such as MonoBehaviour.Update, or any other callback from native to managed code).
Tempbut is faster than
Persistent. It is for allocations within a lifespan of four frames and is thread-safe. If you don’t
Disposeof it within four frames, the console prints a warning, generated from the native code. Most small jobs use this
NativeContainerallocation type. You should not use
Persistentwhere performance is essential.
NativeArray<float> result = new NativeArray<float>(1, Allocator.TempJob);
Note: The number 1 in the example above indicates the size of the
NativeArray. In this case, it has only one array element (as it only stores one piece of data in
2018–06–15 Page published
C# Job System exposed in 2018.1 NewIn20181