Jobs, Burst and performance attributes

Unity 6 reference

At a glance

Burst and the Job System can improve performance by moving eligible work into optimized jobs. Their attributes also describe access patterns and memory lifetimes. Safety-related escape hatches require particular care.

Quick reference

Attribute	What it does	Applies to and requires
[BurstCompile]	Ask Burst to compile eligible jobs or methods for optimized native execution.	Job or method · Unity.Burst · Burst package
[BurstDiscard]	Exclude a compatible method body from Burst compilation.	Method · Unity.Burst · Burst package
[WriteOnly]	Declare a native container job field as write-only to the safety system.	Job field · Unity.Collections
[ReadOnly]	Declare a native container job field as read-only.	Job field · Unity.Collections
[DeallocateOnJobCompletion]	Automatically dispose of supported native containers when a job completes.	Job field · Unity.Collections
[NativeDisableParallelForRestriction]	Disable a parallel-for write restriction for a native container.	Job field · Unity.Collections
[NativeDisableUnsafePtrRestriction]	Disable safety restrictions on an unsafe pointer in a job.	Job field · Unity.Collections.LowLevel.Unsafe
[Preserve]	Keep an annotated type or member from being removed by managed stripping.	Type or member · UnityEngine.Scripting

How to choose

[BurstCompile]

Ask Burst to compile eligible jobs or methods for optimized native execution.

Use it when: Optimize eligible large-scale numeric or data-oriented job workloads.

Be aware: Burst is a separate package and only supports a subset of managed C# features.

Reference: Unity documentation

[BurstDiscard]

Exclude a compatible method body from Burst compilation.

Use it when: Separate a diagnostic helper that should not execute in Burst code.

Be aware: Do not assume managed code runs inside a Burst job just because a method is marked.

Reference: Unity documentation

[WriteOnly]

Declare a native container job field as write-only to the safety system.

Use it when: Mark a job output buffer that is only written during execution.

Be aware: The attribute affects job safety access checks; it does not make unrelated code thread-safe.

Reference: Unity documentation

[ReadOnly]

Declare a native container job field as read-only.

Use it when: Expose an input collection to a job without allowing writes.

Be aware: Often enables safe concurrent readers, but does not replace lifetime management.

Reference: Unity documentation

[DeallocateOnJobCompletion]

Automatically dispose of supported native containers when a job completes.

Use it when: Give a short-lived native buffer ownership tied to the job lifecycle.

Be aware: Only supported containers and allocation patterns qualify. Do not access the container afterward.

Reference: Unity documentation

[NativeDisableParallelForRestriction]

Disable a parallel-for write restriction for a native container.

Use it when: Support a proven custom parallel indexing scheme that cannot be represented by the default restriction.

Be aware: You must independently guarantee that writes do not race. This removes a safety guard.

Reference: Unity documentation

[NativeDisableUnsafePtrRestriction]

Disable safety restrictions on an unsafe pointer in a job.

Use it when: Integrate carefully reviewed unsafe pointer code in a performance-critical job.

Be aware: High-risk escape hatch: pointer lifetime and concurrent access become your responsibility.

Reference: Unity documentation

[Preserve]

Keep an annotated type or member from being removed by managed stripping.

Use it when: Keep reflected or indirectly referenced code available in a player build.

Be aware: Useful with reflection and code discovered indirectly; verify actual linker behavior.

Reference: Unity documentation

A read-only Burst job

Unity C# | SumJob.cs

using Unity.Burst;
using Unity.Collections;
using Unity.Jobs;

[BurstCompile]
public struct SumJob : IJob
{
    [ReadOnly] public NativeArray<int> Input;
    public NativeArray<int> Output;

    public void Execute()
    {
        int sum = 0;
        for (int i = 0; i < Input.Length; i++)
            sum += Input[i];
        Output[0] = sum;
    }
}

The job defines its data-access contract. The code that allocates NativeArray values and schedules the job must still complete the job dependency and dispose allocated memory correctly. A job declaration by itself does not manage those lifetimes.

Safety restrictions are important

Do not use NativeDisableParallelForRestriction or NativeDisableUnsafePtrRestriction merely to silence a safety error. First prove that concurrent accesses and memory lifetimes are correct.

Related lessons

• Unity scripting lifecycle
• Assembly definitions
• Namespaces