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.
A 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.
Unity ships with a NativeContainer
called NativeArray. You can also manipulate a NativeArray
with NativeSlice to get a subset of the NativeArray
from a particular position to a certain length.
Note: The Entity Component System (ECS) package extends the Unity.Collections
namespace to include other types of NativeContainer
:
NativeList
- a resizable NativeArray
.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 NativeContainer
.
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.
Use the 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 NativeArray
.
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 NativeContainer
.
NativeContainer
allocations using Temp
to jobs. You also need to call the Dispose
method before you return from the method call (such as MonoBehaviour.Update, or any other callback from native to managed code).Temp
but is faster than Persistent
. It is for allocations within a lifespan of four frames and is thread-safe. If you don’t Dispose
of it within four frames, the console prints a warning, generated from the native code. Most small jobs use this NativeContainer
allocation type.NativeContainer
allocation type. You should not use Persistent
where performance is essential.For example:
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 result
).
2018–06–15 Page published
C# Job System exposed in 2018.1 NewIn20181