⚙️ Lesson 3.2: Your First Job — IJob & Scheduling

The Idle Cores Problem

Unity's core loop is single-threaded by design: your Update(), physics step, and animation all run in sequence on the main thread. That's simple to reason about, but it means a heavy per-frame computation — 50,000 particles, a flow field, thousands of spatial-audio distance checks — blocks everything else while a modern CPU's other cores do nothing.

The C# Job System lets you package a chunk of work as a job and hand it to Unity's worker thread pool — a set of background threads Unity keeps warm, roughly one per CPU core. The scheduler spreads jobs across those threads, so eight cores can chew through the work in a fraction of the wall-clock time. Crucially, it does this safely: the system's job is to make multithreading approachable without the classic nightmares of race conditions and locks.

Anatomy of an IJob

A job is a struct that implements a job interface. The simplest is IJob: it runs once, on one worker thread. Its fields are its input and output, and its Execute() method is the work:

using Unity.Collections;
using Unity.Jobs;
using Unity.Mathematics;

// A job is a struct. Its fields are the ONLY data it may touch.
struct MoveJob : IJob
{
    public float deltaTime;                 // plain value, copied in
    public NativeArray<float3> positions;   // shared buffer it reads + writes
    [ReadOnly] public NativeArray<float3> velocities;  // read-only input

    public void Execute()
    {
        for (int i = 0; i < positions.Length; i++)
            positions[i] += velocities[i] * deltaTime;
    }
}

Notice what's not here: no MonoBehaviour, no references to scene objects, no calls into the Unity API. A job is a self-contained bundle of blittable data and pure logic. That restriction is exactly what lets Unity run it on another thread safely — there's nothing shared to trip over except the containers you explicitly hand it.

Data Lives in NativeArrays

A job can't take an ordinary C# float3[] — managed arrays live on the garbage-collected heap and can't be safely shared across threads. Instead the Job System uses NativeContainers, the most common being NativeArray<T>: a fixed-size, unmanaged (GC-free) buffer of blittable values that Unity can track across threads. You allocate one, fill it, hand it to the job, and (critically) dispose it when done:

int count = 50000;
// Allocator.TempJob = short-lived, for data handed to a job this frame.
var positions  = new NativeArray<float3>(count, Allocator.TempJob);
var velocities = new NativeArray<float3>(count, Allocator.TempJob);
// ... fill them from your data ...

var job = new MoveJob {
    deltaTime  = Time.deltaTime,
    positions  = positions,
    velocities = velocities
};

NativeContainers are their own topic — allocators, the safety system, and leak detection — and they get the full treatment in Lesson 3.3. For now, the mental model is: a NativeArray is a T[] you're allowed to share with a job, and that you are responsible for freeing.

Schedule & Complete

You don't call Execute() yourself. You schedule the job, which queues it on the worker pool and immediately returns a JobHandle — a receipt you use to wait for it. Calling Complete() on that handle blocks the main thread until the job has finished, after which its results are safe to read:

// Queue the job onto a worker thread — returns instantly.
JobHandle handle = job.Schedule();

// ... the main thread is free here to do other work ...

// Block until the job is done; now the data is safe to touch.
handle.Complete();

// Read results back out, then release the native memory.
for (int i = 0; i < positions.Length; i++)
    myTransforms[i].position = positions[i];

positions.Dispose();
velocities.Dispose();

Between Schedule() and Complete(), the job may be running on another thread — so the data it owns is off-limits to you. Complete() is the synchronisation point that hands ownership back.

Figure 2: The lifecycle. Schedule hands work to a worker; the main thread is free until Complete synchronises and returns the data.

The Golden Rule

There is one rule that prevents the entire category of multithreading bugs:

While the job is in flight, its NativeArrays belong to the worker thread. If the main thread also pokes at them, you have a data race — the exact bug the Job System exists to prevent. And it does prevent it: Unity's safety system tracks who owns each container and throws a clear InvalidOperationException the moment you break the rule, instead of letting you ship a heisenbug. You get told off immediately, in the editor, with a message that names the container.

The takeaway: schedule your work, leave its data alone, and only touch it again after Complete(). The safety system has your back while you learn the discipline.

Chaining with Dependencies

Real frames have jobs that depend on each other — compute forces, then integrate velocities, then move positions. You express "B must wait for A" by passing A's handle into B's Schedule():

JobHandle forcesHandle = forcesJob.Schedule();

// integrateJob won't start until forcesJob is done — pass the dependency.
JobHandle integrateHandle = integrateJob.Schedule(forcesHandle);

// moveJob waits for integrate.
JobHandle moveHandle = moveJob.Schedule(integrateHandle);

// Completing the last handle completes the whole chain.
moveHandle.Complete();

The scheduler now knows the ordering and guarantees each job sees the previous one's finished output — while still running independent chains in parallel on other workers. Dependencies are also how the safety system reasons about who may touch a container when: if two jobs write the same array, you must make one depend on the other, or Unity refuses to schedule them.

Schedule Early, Complete Late

The Job System only buys you time if the workers actually run while the main thread does something else. Scheduling a job and completing it on the very next line gives you the overhead of threading with none of the benefit — the main thread just waits.

The idiomatic pattern is schedule as early as possible, complete as late as possible. A common shape: schedule heavy jobs at the start of the frame (e.g. in Update), let the rest of your game logic run, then complete them at the end (e.g. in LateUpdate) when you finally need the results. The wider that gap, the more free parallelism you get.

Hands-on Challenge

struct DistanceJob : IJob {
    [ReadOnly] public NativeArray<float3> points;
    public float3 target;
    public NativeArray<float> results;
    public void Execute() {
        for (int i = 0; i < points.Length; i++)
            results[i] = math.distance(points[i], target);
    }
}
// caller:
var pts = new NativeArray<float3>(n, Allocator.TempJob);
var res = new NativeArray<float>(n, Allocator.TempJob);
/* fill pts */
var h = new DistanceJob { points = pts, target = t, results = res }.Schedule();
h.Complete();
/* use res */
pts.Dispose(); res.Dispose();

Summary

🚀 What's Next?

You leaned on NativeArray and Allocator.TempJob without really meeting them. In Lesson 3.3: NativeContainers & the Safety System we go deep on native memory — allocators, [ReadOnly]/[WriteOnly], leak detection, and the rules that keep parallel jobs honest.