🧱 Lesson 3.3: NativeContainers & the Safety System

Why Not Just Use List<T>?

A regular List<T> or T[] is a managed object: it lives on the garbage-collected heap, it can be moved by the GC, and its memory layout isn't guaranteed. None of that is safe to hand to another thread, and all of it generates the GC pressure you learned to avoid in Lesson 2.3.

NativeContainers solve both problems. They wrap a block of unmanaged memory (allocated outside the GC heap), so they generate zero garbage and never move. They store only blittable value types, so their bytes can be shared across threads directly. And they carry safety handles that let Unity track who is allowed to read or write them at any moment. The trade-off: because they're outside the GC, you are responsible for freeing them.

The Container Family

NativeArray<T> is the workhorse, but the Unity.Collections package ships a whole family for different shapes of data:

They behave like their managed cousins but with the native rules. For example, a growable list you fill from a job:

using Unity.Collections;

var results = new NativeList<int>(Allocator.TempJob);   // starts empty, grows
results.Add(42);
results.Add(7);
int first = results[0];
results.Dispose();

// A single value out of a reduction job:
var total = new NativeReference<float>(Allocator.TempJob);
// ... job writes total.Value ...
float sum = total.Value;
total.Dispose();

💡 Fixed strings. Since string isn't blittable, jobs use FixedString32Bytes, FixedString128Bytes, etc. — inline, stack-sized strings you can store in a NativeContainer. Handy for names or tags inside ECS components.

Allocators & Lifetimes

Every NativeContainer is created with an allocator, and choosing the right one is about how long the container needs to live. There are three you'll use constantly:

The rule of thumb: scratch data inside one method → Temp; buffers you fill and hand to this frame's jobs → TempJob; long-lived buffers you allocate once and keep → Persistent. A frequent beginner mistake is allocating a big Persistent array every frame instead of once — that's just slow malloc/free churn dressed up as native code.

Disposal & Leak Detection

Because NativeContainers live outside the GC, forgetting to Dispose() one is a genuine memory leak — the native block is never reclaimed. Unity ships a leak detection system that catches this: allocate a TempJob container and fail to free it in time, and the console prints a warning that even points back to the allocation site.

var buffer = new NativeArray<float3>(1000, Allocator.Persistent);
try
{
    // ... use buffer across frames ...
}
finally
{
    if (buffer.IsCreated) buffer.Dispose();   // always free it
}

For long-lived Persistent containers on a MonoBehaviour or system, the natural place to dispose is OnDestroy() (or a system's OnDestroy). Guard with IsCreated so you never double-dispose. Think of every new NativeArray(...) as opening a resource that you are on the hook to close.

The Safety System

In the editor and development builds, every NativeContainer carries an AtomicSafetyHandle that tracks who may touch it right now. This is what threw the exception in Lesson 3.2 when we broke the golden rule, and it's what makes parallel jobs trustworthy. It enforces three things:

• No use-after-dispose — touching a freed container throws immediately, instead of reading garbage.
• No unsynchronised sharing — if a job is writing a container, nothing else (another job or the main thread) may read or write it until that job completes, unless you declared a dependency.
• Read/write intent — the [ReadOnly] and [WriteOnly] attributes tell the system your access pattern.

Those attributes aren't just documentation — they unlock parallelism. Mark an input [ReadOnly] and the safety system knows many jobs can read that array at the same time (readers don't conflict). Leave it read-write and it must assume you might write, so it serialises access:

struct FlockJob : IJobParallelFor
{
    [ReadOnly] public NativeArray<float3> allPositions;  // shared read — many jobs OK
    public NativeArray<float3> velocities;               // this job's output
    public void Execute(int i) { /* read allPositions, write velocities[i] */ }
}

Disposing Alongside a Job

There's a subtlety with the "schedule early, complete late" pattern: if a container is still being used by an in-flight job, you can't dispose it on the main thread yet — the safety system won't let you. Two clean options:

// Option A: dispose AFTER the job that uses it, without blocking now.
// Dispose(handle) schedules the free to happen once the job finishes.
JobHandle handle = job.Schedule();
positions.Dispose(handle);
velocities.Dispose(handle);
// (no Complete() needed here if you don't need results this line)

// Option B: let the job own the deallocation.
struct SumJob : IJob
{
    [ReadOnly] [DeallocateOnJobCompletion] public NativeArray<float> input;
    public NativeReference<float> result;
    public void Execute() { /* ... */ }   // 'input' is freed automatically after
}

container.Dispose(jobHandle) queues the free to run when that job completes — no main-thread stall. [DeallocateOnJobCompletion] hands the responsibility to the job itself for inputs you won't need afterward. Both keep the free correctly ordered after the work that reads the data.

Hands-on Challenge

var data = new NativeArray<float>(1000, Allocator.TempJob);
var handle = new MyJob { data = data }.Schedule();
float x = data[0];   // (1)
// ...no Dispose anywhere... (2)

Summary

🚀 What's Next?

You have safe, packed, thread-shareable data. In Lesson 3.4: Parallel Jobs & Burst Compilation we split work across every core with IJobParallelFor and switch on the Burst compiler to turn that C# into vectorised native code — the payoff the whole module has been building toward.