Unity DOTS ECS 대규모 엔티티 연산 시 NativeArray 메모리 누수와 Job System 동기화 병목 트러블슈팅

🌐 English Abstract

This article provides an in-depth troubleshooting guide for handling NativeArray memory leaks and C# Job System synchronization bottlenecks in Unity DOTS (Data-Oriented Technology Stack) ECS environments. It explores allocator lifecycles, memory safety checks, Structural Changes, and EntityCommandBuffer optimization strategies when dealing with large-scale entity calculations. Developers will gain actionable insights on resolving main-thread stalls and optimizing memory performance for enterprise-level Unity projects.

유니티의 DOTS(Data-Oriented Technology Stack)와 ECS(Entity Component System)는 수만 개 이상의 대규모 엔티티(Entity)를 고성능으로 처리하기 위한 강력한 프레임워크입니다. 캐시 지역성(Cache Locality)을 극대화하고 Burst 컴파일러(Burst Compiler)와 C# Job System을 활용하여 가비지 컬렉션(Garbage Collection) 없는 극한의 연산 속도를 제공합니다.

하지만 실제 실무 프로젝트에서 대규모 연산을 구현하다 보면 예기치 못한 두 가지 거대한 장벽에 직면하게 됩니다. 바로 NativeArray 메모리 누수(Memory Leak)와 Job System 동기화 병목(Synchronization Bottleneck / Sync Point) 현상입니다. 관리되는 메모리(Managed Memory)에 익숙한 C# 개발자가 비관리 메모리(Unmanaged Memory)를 제어할 때 발생하는 문제점들을 파악하고, 이를 시스템적으로 해결할 수 있는 깊이 있는 트러블슈팅 가이드를 공유합니다.

1. NativeArray 메모리 모델 및 누수(Memory Leak) 원인 분석

DOTS ECS 환경에서는 C#의 GC 관리를 받는 배열 대신, C++ 힙(Heap) 영역에 직접 메모리를 할당하는 네이티브 컨테이너(Native Container)인 NativeArray<T>, NativeList<T>, NativeHashMap<K,V> 등을 사용합니다. 이 컨테이너들은 가비지 컬렉터의 추적을 받지 않기 때문에 개발자가 직접 생명주기(Lifecycle)를 관리해야 합니다.

1.1 메모리 할당자(Allocator)의 이해와 오용 케이스

NativeArray를 할당할 때는 연산의 목적과 수명에 맞는 할당자(Allocator) 유형을 선택해야 합니다. 선택이 잘못될 경우 메모리 누수나 크래시(Crash)가 발생합니다.

• Allocator.Temp: 가장 빠른 할당 속도를 자랑하며, 단일 프레임(Single Frame) 내에서 할당 및 해제(Dispose)가 완료되어야 합니다. 1프레임을 초과하여 유지되거나 멀티스레드 Job 내부로 직접 전달되면 에러가 발생합니다.
• Allocator.TempJob: 멀티스레드 Job에 전달할 때 사용되며, 최대 4프레임 이내에 해제되어야 합니다. 해제하지 않을 경우 유니티 에디터에서 경고 메세지(Leak Warning)를 출력합니다.
• Allocator.Persistent: 수명이 길거나 애플리케이션 전체에 걸쳐 유지되어야 하는 데이터에 사용됩니다. C++의 malloc과 동일하므로 명시적으로 Dispose()를 호출하지 않으면 앱이 종료될 때까지 메모리 누수가 발생합니다.

1.2 실무에서 자주 발생하는 메모리 누수 패턴 (Edge Cases)

대규모 ECS 시스템에서 가장 많이 발생하는 메모리 누수 패턴은 "Job이 완료되기 전에 스레드가 예외(Exception)를 일으켜 Dispose()에 도달하지 못하는 케이스"와 "동적으로 생성된 NativeArray를 수신하는 JobHandle 체인의 유실"입니다.

아래는 잘못 작성된 메모리 할당 코드의 전형적인 예시입니다:

// ❌ 메모리 누수가 발생하는 잘못된 코드 예시
public partial struct MovementSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        // 매 프레임 Persistent 할당
        NativeArray<float3> positions = new NativeArray<float3>(100000, Allocator.Persistent);

        var job = new ProcessPositionJob { Positions = positions };
        JobHandle jobHandle = job.Schedule(state.Dependency);

        // state.Dependency를 업데이트하지 않고 Dispose도 생략함!
        // 메모리가 매 프레임 100,000 * 12 Bytes 씩 누수됨
    }
}

1.3 올바른 Dispose 처리 기법: [DeallocateOnJobCompletion]과 DisposeJob

메모리 누수를 방지하기 위해서는 작업 완료 후 자동으로 메모리를 해제하는 속성(Attribute)을 사용하거나, 안전한 의존성 관리 기법을 도입해야 합니다.

// ⭕ 메모리 누수를 완전히 방지하는 올바른 코드
[BurstCompile]
public struct ProcessPositionJob : IJobParallelFor
{
    // Job 완료 시 자동으로 NativeArray를 해제함
    [DeallocateOnJobCompletion]
    [ReadOnly] public NativeArray<float3> Positions;

    public void Execute(int index)
    {
        // 연산 로직 수행
    }
}

public partial struct MovementSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        NativeArray<float3> positions = new NativeArray<float3>(100000, Allocator.TempJob);

        var job = new ProcessPositionJob { Positions = positions };
        
        // JobHandle 체인 명시적 연결
        state.Dependency = job.Schedule(positions.Length, 64, state.Dependency);
        
        // 또는 명시적으로 DisposeJob 사용 가능:
        // state.Dependency = positions.Dispose(state.Dependency);
    }
}

2. Job System 동기화 병목(Sync Point)과 성능 저하 요소

DOTS ECS의 두 번째 주요 난관은 **동기화 병목(Synchronization Bottleneck)**입니다. 아무리 많은 CPU 코어를 활용하더라도, 메인 스레드(Main Thread)와 워커 스레드(Worker Thread)가 서로를 기다리는 **스톨(Stall)** 현상이 발생하면 병렬 처리의 이점이 상쇄됩니다.

2.1 조기 JobHandle.Complete() 호출로 인한 메인 스레드 대기

가장 흔한 병목의 원인은 JobHandle.Complete()를 필요 이상으로 빨리 호출하는 것입니다. 이 메서드는 백그라운드 스레드에서 작동 중인 연산이 끝날 때까지 메인 스레드를 강제로 블로킹(Blocking)합니다.

해결 전략: Complete() 호출을 최대한 늦추거나, 다음 프레임까지 연동되도록 프레임 간 딜레이를 허용하는 의존성 구조(Dependency Graph)로 설계해야 합니다.

2.2 구조적 변경(Structural Change)이 야기하는 글로벌 동기화 지점

ECS 프레임워크에서 구조적 변경(Structural Change)이란 청크(Chunk)의 메모리 레이아웃을 변형하는 모든 작업을 의미합니다:

• 엔티티 생성(CreateEntity) 또는 파괴(DestroyEntity)
• 컴포넌트 추가(AddComponent) 또는 제거(RemoveComponent)
• Shared Component 값의 변경

구조적 변경이 일어나는 순간, 유니티는 내부 청크 메모리를 재배치(Reallocation)해야 하므로 실행 중인 모든 Job이 끝날 때까지 모든 스레드를 정지시킵니다. 이를 **동기화 지점(Sync Point)**이라 부르며, 렌더링 프레임이 심각하게 튀는 원인이 됩니다.

2.3 EntityCommandBuffer(ECB)를 활용한 구조적 변경 지연 처리

동기화 지점 폭탄을 피하는 표준 해법은 EntityCommandBuffer(ECB)를 사용하는 것입니다. Job 내부에서는 구조적 변경 명령을 버퍼에 기록(Record)만 해두고, 프레임의 특정 시점(예: EndSimulationEntityCommandBufferSystem)에 일괄(Batch) 처리하는 구조입니다.

// ⭕ ParallelWriter와 ECB를 이용한 병목 없는 구조적 변경 예시
[BurstCompile]
public struct DestroyExpiredEntitiesJob : IJobEntity
{
    public EntityCommandBuffer.ParallelWriter Sticker;

    // EntityAndIndexInQuery를 이용하여 안전한 멀티스레드 병렬 기록
    public void Execute(Entity entity, [EntityIndexInQuery] int sortIndex, in Lifetime lifetime)
    {
        if (lifetime.Value <= 0)
        {
            // 직접 파괴하지 않고 버퍼에 예약
            Sticker.DestroyEntity(sortIndex, entity);
        }
    }
}

public partial struct LifetimeSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        var ecbSingleton = SystemAPI.GetSingleton<EndSimulationEntityCommandBufferSystem.Singleton>();
        var ecb = ecbSingleton.CreateCommandBuffer(state.WorldUnmanaged);

        var job = new DestroyExpiredEntitiesJob
        {
            Sticker = ecb.AsParallelWriter()
        };

        state.Dependency = job.ScheduleParallel(state.Dependency);
    }
}

3. 실무 트러블슈팅 체크리스트 및 프로파일링 기법

메모리 누수와 병목 현상을 정확하게 진단하기 위해서는 유니티에서 제공하는 정교한 프로파일링 도구를 연동하여 관찰해야 합니다.

1. Native Memory Leak Detector 활성화: 프로젝트 빌드 옵션 또는 에디터 설정에서 Jobs -> Burst -> Safety Checks를 활성화하여 leak 경고 메시지의 스택 트레이스(Stack Trace)를 확보합니다.
2. Unity Profiler의 Timeline View 활용: Profiler 하단의 Timeline 뷰를 통해 메인 스레드에 WaitForJob 또는 DOTS Sync Point로 인한 거대한 갭(Gap)이 존재하는지 모니터링합니다.
3. Memory Profiler 패키지 사용: 스냅샷(Snapshot)을 두 번 촬영하여 비교(Diff)함으로써 어떤 NativeArray나 NativeUnsafePtr가 정리되지 않고 누적되는지 확인합니다.

4. 결론 (Conclusion)

Unity DOTS ECS 환경에서 수만 개 이상의 엔티티를 부드럽게 연산하기 위해서는 C# 연산 효율화뿐만 아니라 하드웨어 레이어에 근접한 비관리 메모리 및 스레드 관리가 필수적입니다.

NativeArray의 수명을 Allocator 및 [DeallocateOnJobCompletion]을 이용해 명확히 제어하고, 구조적 변경을 EntityCommandBufferSystem으로 지연시켜 동기화 병목(Sync Point)을 지워나가는 것이 대규모 아키텍처 구축의 핵심입니다. 시스템 설계 단계부터 선제적인 프로파일링과 완벽한 의존성 관리 패턴을 도입하여 최고 수준의 프레임 유지력을 확보하시길 바랍니다.