NativeContainer

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

Types of NativeContainer

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.

NativeContainer and the safety system

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 haven’t freed your memory correctly. 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 doesn’t allow you to schedule a job that has write access to a NativeContainer at the same time as another job that’s writing to it.

If a job doesn’t 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.

NativeContainer Allocator

When creating a NativeContainer, you must specify the memory allocation type that 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 must specify the appropriate one when instantiating a NativeContainer.

• Allocator.Temp has the fastest allocation. Use it for allocations with a lifespan of one frame or fewer. However, you can’t use Temp to pass NativeContainer allocations to jobs.
• Allocator.TempJob is a slower allocation than Temp but is faster than Persistent. Use it for thread-safe allocations within a lifespan of four frames. Important: You must Dispose of this type of allocation within four frames, or the console prints a warning, generated from the native code. Most small jobs use this NativeContainer allocation type.
• Allocator.Persistent is the slowest allocation but can last as long as you need it to, and if necessary, throughout the application’s lifetime. It is a wrapper for a direct call to malloc. Longer jobs can use this NativeContainer allocation type. Don’t 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 because it only stores one piece of data in result.