wave8-handle-complete-sync-point-antipattern

handle.Complete() Sync Point Anti-Pattern

Intent

Identify and eliminate inline handle.Complete() calls in production systems that create unintended main-thread stalls, and replace them with WorldUpdateAllocator + dependency chain patterns.

Use When

• Profiling reveals unexpected main-thread "WaitForJobGroupID" stalls
• Code review finds handle.Complete() outside of test/editor contexts
• A system uses Allocator.Persistent NativeArrays read in the same OnUpdate that schedules work on them

Avoid When

• Explicit sync is genuinely required (disposing a NativeArray at end of frame after a one-shot operation) — in that case, document why Complete() is necessary

Senior Pattern

// ANTI-PATTERN — inline Complete() stalls main thread:
public partial struct BrokenSystem : ISystem
{
    NativeArray<int> _results;

    public void OnCreate(ref SystemState state)
    {
        _results = new NativeArray<int>(100, Allocator.Persistent);
    }

    public void OnUpdate(ref SystemState state)
    {
        var job = new ComputeJob { Results = _results };
        var handle = job.Schedule();  // does not extend state.Dependency
        handle.Complete();            // SYNC POINT — stalls main thread every frame
        // Read _results here — destroys frame parallelism
    }

    public void OnDestroy(ref SystemState state) => _results.Dispose();
}

// CORRECT — WorldUpdateAllocator + dependency chain:
[BurstCompile]
public partial struct FixedSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        // Auto-freed after world update — no Dispose, no Complete():
        var results = CollectionHelper.CreateNativeArray<int>(100, state.WorldUpdateAllocator);
        state.Dependency = new ComputeJob { Results = results }
            .Schedule(state.Dependency);

        // Downstream system that reads results — chains via state.Dependency:
        state.Dependency = new ConsumeJob { Results = results }
            .Schedule(state.Dependency);
        // No Complete() — ECS propagates the handle to subsequent systems
    }
}

// CORRECT — when output must be passed to a managed system:
// Write result into a singleton component, read it in a non-Burst system next frame
public struct ComputeResult : IComponentData { public int Value; }