Unreal Engine UObject 가비지 컬렉션: 참조 그래프와 안전한 수명 관리

C++ 수명 관리와 UObject GC는 함께 존재한다#

ISO C++에는 UObject 같은 tracing GC가 기본 제공되지 않는다. 대신 stack object, RAII, value type, std::unique_ptr 같은 deterministic ownership을 중심으로 설계한다. Unreal project도 이 원칙을 버리지 않는다.

U나 A prefix는 Unreal naming convention이다. prefix 자체가 GC 대상을 만드는 것이 아니라 실제 UObject inheritance와 reflection 정보가 중요하다.

Reference graph와 collection lifecycle#

GC는 root와 engine-known reference에서 시작해 strong edge를 추적한다. 도달한 object는 이번 collection에서 유지되고, 도달하지 못한 object는 unreachable이 되어 destruction lifecycle로 들어간다.

Reference count와 달리 서로를 가리키는 cycle도 root에서 끊겨 있으면 함께 수거할 수 있다. 반대로 아무 gameplay 가치가 없어도 root나 long-lived owner에서 strong path가 하나 남아 있으면 계속 유지된다. GC가 memory leak을 “항상 막아 준다”는 표현보다 unintended retention도 graph 문제라고 이해하는 편이 정확하다.

일반 collection은 reachability를 계산하는 동안 UObject processing/gameplay를 일시 중단할 수 있지만, mark work 자체는 gc.AllowParallelGC로 collector worker에 나눌 수 있다. Parallel GC와 여러 frame에 걸쳐 mark하는 incremental reachability는 서로 다른 기능이다.

UObject를 올바르게 생성하기#

UObject는 new/delete로 생성·해제하지 않는다.

CreateDefaultSubobject는 constructor-only API다. Runtime에 임의 UObject를 만드는 NewObject의 대체가 아니다.

1
#pragma once
2

3
#include "UObject/Object.h"
4
#include "UObject/ObjectPtr.h"
5
#include "UObject/UObjectGlobals.h"
6
#include "GcOwner.generated.h"
7

8
UCLASS()
9
class MYGAME_API UGcChild final : public UObject
10
{
11
    GENERATED_BODY()
12
};
13

14
UCLASS()
15
class MYGAME_API UGcOwner final : public UObject
16
{
17
    GENERATED_BODY()
18

19
public:
20
    void CreateChild()
21
    {
22
        Child = NewObject<UGcChild>(this);
23
    }
24

25
    void ReleaseChild()
26
    {
27
        Child = nullptr;
28
    }
29

30
private:
31
    UPROPERTY(Transient)
32
    TObjectPtr<UGcChild> Child;
33
};

UObject pointer 결정표#

Persistent reference와 function-local view를 같은 type으로 강제하지 않는다.

Persistent reflected field를 왜 TObjectPtr로 쓰는지는 TObjectPtr 글에서 UFUNCTION, container, serialization과 함께 설명했다.

1
UPROPERTY()
2
TObjectPtr<UObject> Current;
3

4
UPROPERTY()
5
TArray<TObjectPtr<UObject>> History;

Weak, soft, strong pointer의 역할#

1
if (UObject* Object = WeakObject.Get())
2
{
3
    UseObject(Object);
4
}

1
#include "UObject/StrongObjectPtrTemplates.h"
2
#include "UObject/WeakObjectPtrTemplates.h"
3

4
if (TStrongObjectPtr<UObject> Pinned = WeakObject.Pin())
5
{
6
    // Pinned가 살아 있는 동안 GC lifetime은 유지된다.
7
    // UObject API 자체의 thread safety는 별도 계약이다.
8
    UseObject(Pinned.Get());
9
}

Native owner에서 reference를 report하기#

1
#include "UObject/GCObject.h"
2
#include "UObject/Object.h"
3
#include "UObject/ObjectPtr.h"
4
#include "UObject/UObjectGlobals.h"
5

6
class FNativeOwner final : public FGCObject
7
{
8
public:
9
    void SetObject(UObject* InObject)
10
    {
11
        Object = InObject;
12
    }
13

14
    void AddReferencedObjects(FReferenceCollector& Collector) override
15
    {
16
        Collector.AddReferencedObject(Object);
17
    }
18

19
    FString GetReferencerName() const override
20
    {
21
        return TEXT("FNativeOwner");
22
    }
23

24
private:
25
    TObjectPtr<UObject> Object;
26
};

1
#pragma once
2

3
#include "UObject/Object.h"
4
#include "UObject/ObjectPtr.h"
5
#include "ManualReferenceOwner.generated.h"
6

7
UCLASS()
8
class MYGAME_API UManualReferenceOwner final : public UObject
9
{
10
    GENERATED_BODY()
11

12
public:
13
    static void AddReferencedObjects(
14
        UObject* InThis,
15
        FReferenceCollector& Collector);
16

17
    void SetReference(UObject* InObject)
18
    {
19
        NativeReference = InObject;
20
    }
21

22
private:
23
    TObjectPtr<UObject> NativeReference; // intentionally unreflected
24
};

1
#include "ManualReferenceOwner.h"
2

3
#include "UObject/UObjectGlobals.h"
4

5
void UManualReferenceOwner::AddReferencedObjects(
6
    UObject* InThis,
7
    FReferenceCollector& Collector)
8
{
9
    UManualReferenceOwner* This =
10
        CastChecked<UManualReferenceOwner>(InThis);
11

12
    Collector.AddReferencedObject(This->NativeReference, This);
13
    Super::AddReferencedObjects(InThis, Collector);
14
}

파괴를 요청하는 API와 GC destruction을 구분한다#

일반 UObject를 더 이상 쓰지 않는다면 strong reference를 해제하고 GC에 맡긴다. ConditionalBeginDestroy()를 gameplay destruction이나 “GC 힌트”로 직접 호출하지 않는다. 이 함수는 GC가 이미 파괴하기로 결정한 object의 destruction lifecycle을 진행하는 내부 경계다.

AActor::Destroy()는 latent이며 보통 tick 끝에 처리된다. Gameplay 연결 해제는 EndPlay, native resource release는 BeginDestroy/FinishDestroy override의 contract에 맞춘다. 모든 override에서 필요한 Super 호출을 보존한다.

Null test와 UObject validity도 구분한다.

1
if (IsValid(Object))
2
{
3
    UseObject(Object);
4
}

IsValid는 null과 garbage/pending-destruction 상태를 함께 확인할 때 유용하다. 그러나 이미 수명이 끝난 untracked raw address를 safe handle로 바꾸지는 않는다. Long-lived non-owning field에는 TWeakObjectPtr를 사용해야 한다.

GC cluster는 root가 아니다#

Cluster는 여러 object를 reachability unit으로 묶어 per-object scanning 비용을 줄이는 고급 최적화다. Cluster root가 global Root Set이라는 뜻은 아니다.

• Cluster root 자격은 CanBeClusterRoot, member 자격은 CanBeInCluster, 실제 구성은 CreateCluster와 project setting에 달려 있다.
• Cluster member 하나가 외부 strong reference로 reachable하면 cluster 전체가 유지될 수 있다.
• 큰 cluster나 merged cluster는 over-retention과 일괄 unhash/destruction hitch를 만들 수 있다.
• “같은 level”이나 “subobject”라는 사실만으로 무조건 자동 cluster가 된다고 가정하지 않는다.

먼저 Unreal Insights와 GC analytics로 root traversal, cluster, destruction 비용을 측정하고, 실제 object graph와 lifetime이 함께 움직이는 대상을 묶는다.

Parallel, incremental, destruction 설정을 분리한다#

이 설정들은 모두 pause와 관련 있어 보이지만 서로 다른 단계를 제어한다.

하나를 켰다고 나머지가 자동으로 켜지거나 thread-safe해지는 것은 아니다.

점진적 도달 가능성 분석은 Experimental 기능이다#

UE 5.4는 incremental reachability와 incremental gather를 Experimental로 도입했다. mark와 unreachable object gather를 여러 frame으로 나눠 긴 pause를 줄이는 대신, write barrier와 target별 검증이 필요하다.

공식 예제는 아래처럼 설정한다.

1
[ConsoleVariables]
2
gc.AllowIncrementalReachability=1
3
gc.AllowIncrementalGather=1
4
gc.IncrementalReachabilityTimeLimit=0.002

0.002는 2 ms의 예시 budget일 뿐 보편적인 권장값이나 보장된 hard limit가 아니다. 실제 frame 비용을 측정해 project와 target에 맞게 조정한다.

활성화하려면 아래 조건부터 만족해야 한다.

1. GC-exposed UPROPERTY raw UObject pointer를 TObjectPtr로 전환한다.
2. UObject static AddReferencedObjects와 FGCObject storage도 TObjectPtr로 바꾼다.
3. Async/task code의 object lifetime과 API thread safety를 별도로 검사한다.
4. PIE뿐 아니라 target server/client build에서 stress test한다.
5. GC verification과 reference tracking으로 barrier 누락을 찾는다.

Manual GC는 마지막 수단이다#

Automatic GC를 기본으로 둔다.

• gc.CollectGarbageEveryFrame N은 매 N frame마다 collection/full-purge request를 넣는 debug stress command다. Production optimization이 아니다.
• GEngine->ForceGarbageCollection(true)는 그 line에서 즉시 memory를 비우지 않는다. 다음 가능한 시점에 full purge를 요청한다.
• CollectGarbage(...) 직접 호출은 다른 thread의 UObject lock을 기다리고 큰 hitch를 만들 수 있다.

Manual collection이 정당한 경우는 loading screen처럼 hitch를 숨길 수 있거나, 측정 결과 page swapping/OOM 위험 직전에 collection하는 편이 낫다는 증거가 있을 때다. Routine gameplay tick에서 강제하지 않는다.

성능 개선 순서는 다음이 안전하다.

1. Unreal Insights와 gc.DumpAnalyticsToLog로 mark, gather, purge, cluster 비용을 구분한다.
2. 불필요한 persistent strong edge와 root를 제거한다.
3. 짧게 쏟아지는 transient UObject 생성 churn을 줄이거나 적절히 pool한다.
4. UObject가 제공하는 reflection, serialization, replication, editor 기능이 필요 없는 data만 value/plain C++ type으로 옮긴다.
5. Cluster와 incremental setting은 target별 측정 뒤 적용한다.

“Blueprint macro가 function보다 runtime UObject를 항상 더 많이 만든다”거나 “C++로 옮기면 GC object가 자동으로 줄어든다”는 식의 일반화는 editor graph node와 cooked runtime object를 혼동한다. 실제 runtime allocation을 profile한다.

최종 점검표#

• 대상이 UObject인지 plain C++ value인지 먼저 구분했는가?
• Root에서 target까지 의도한 strong path를 그릴 수 있는가?
• Persistent strong field는 UPROPERTY() TObjectPtr<T>인가?
• Outer를 owner-to-child keepalive로 오해하지 않는가?
• Long-lived non-owning field는 TWeakObjectPtr인가?
• Soft load 완료 뒤 필요한 strong ownership을 넘겼는가?
• TStrongObjectPtr의 hidden retention과 cycle을 검토했는가?
• Custom AddReferencedObjects가 모든 edge와 Super를 처리하는가?
• 일반 UObject에 ConditionalBeginDestroy()를 직접 호출하지 않는가?
• Actor와 Component는 각각 public Destroy API를 쓰는가?
• Cluster를 root나 자동 subobject group으로 오해하지 않는가?
• Disregard pool을 gameplay opt-in으로 사용하지 않는가?
• Parallel mark, incremental mark, BeginDestroy slicing, memory free를 구분했는가?
• Incremental mode 전 모든 GC-reported pointer를 TObjectPtr로 전환했는가?
• Forced GC는 측정된 loading/memory boundary에만 있는가?

참고 자료#

• Epic Games: Object Pointers
• Epic Games: Incremental Garbage Collection
• Epic Games: Unreal Object Handling
• Epic Games: Objects
• Epic Games: Creating Objects
• Epic Games: Garbage Collection Settings
• Epic Games: Console Variables Reference
• Epic Games: Memory and CPU Performance Considerations
• Epic Games: FGCObject
• Epic Games: FReferenceCollector::AddReferencedObject
• Epic Games: AddToRoot
• Epic Games: AActor::Destroy
• Epic Games: Actor Lifecycle
• Epic Games: CollectGarbage
• Epic Games: UEngine::ForceGarbageCollection
• Epic Games: Async Asset Loading
• Epic Games: Smart Pointers for plain C++ objects
• Epic Games: UE 5.4 Release Notes
• Epic Games: UE 5.5 Release Notes
• Garbage collection in Unity and Unreal Engine
• 언리얼 가비지 컬렉터(GC) 심화 정리
• How to register disregard for GC objects
• [UE5] Garbage Collection