Reference Pool

Abstract

레퍼런스 풀은 코어에서 게임 코드가 가장 자주 직접 부르는 클래스입니다. new 로 만들고 버리던 작은 객체를 Acquire 로 꺼내고 Release 로 돌려놓게 해서, 플레이 중 가비지가 쌓이지 않게 합니다. 이 페이지는 그 내부 구조를, Unity 쪽 Reference Pooling (레퍼런스 풀링) 페이지는 예제 게임에서의 사용 패턴을 다룹니다.

왜 new 가 문제인가

뱀서라이크에서 적이 초당 5마리 죽고, 그때마다 이벤트 인자 하나와 엔티티 데이터 하나가 만들어진다고 합시다. 1분이면 600개의 객체가 버려집니다. C# 의 가비지 컬렉터는 이것들을 치울 때 게임을 잠깐 멈춥니다. 모바일에서는 이 멈춤이 눈에 보이는 끊김이 됩니다. 풀을 쓰면 같은 객체 몇 개가 계속 돌기 때문에 치울 것이 생기지 않습니다.

내부 구조는 단순하다

graph LR
    A["Acquire&lt;T&gt;()"] --> B{"T 타입 큐에<br>남은 것이 있나"}
    B -- 있다 --> C["꺼내서 반환"]
    B -- 없다 --> D["new T() 로 생성"]
    E["Release(obj)"] --> F["obj.Clear()"] --> G["T 타입 큐에 넣기"]

Mermaid

복사

타입마다 큐가 하나씩 있을 뿐입니다. 크기 제한도, 만료 시간도 없습니다. 그래서 한 번 최대치까지 늘어난 풀은 줄어들지 않습니다 — 줄이려면 Remove<T>(count) 나 RemoveAll<T>() 를 직접 불러야 합니다.

오브젝트 풀과 무엇이 다른가

	레퍼런스 풀	오브젝트 풀
대상	순수 C# 객체	무엇이든 (주로 GameObject, 에셋)
접근	정적 클래스. 어디서든 바로	모듈. 풀을 먼저 만들어야 한다
용량·만료	없음	있음 (Capacity, Expire Time)
초기화 책임	Clear() 한 곳	OnSpawn / OnUnspawn / Release

확장 — 미리 채워 두기

전투가 시작되는 순간 한꺼번에 객체가 만들어져 끊기는 것이 보인다면, 로딩 화면에서 미리 만들어 둘 수 있습니다.

private const int PrewarmEnemyDataCount = 16;

// 로딩 Procedure 에서
ReferencePool.Add<EnemyData>(PrewarmEnemyDataCount);

복사

본문을 읽을 때 주의할 점

•

본문 예제는 GameFrameworkEventArgs 를 상속합니다. 이것은 프레임워크 내부 C# 이벤트의 인자용 기반 클래스입니다. 게임 코드가 EventComponent 로 주고받는 이벤트는 GameEventArgs 를 상속해야 하고, Id 프로퍼티도 구현해야 합니다.

•

ReferencePool.EnableStrictCheck = true; 를 코드에서 직접 쓸 일은 없습니다. Unity 쪽 ReferencePoolComponent 가 인스펙터 설정에 따라 켜 줍니다.

•

이중 반납은 Strict Check 가 켜져 있을 때만 예외로 잡힙니다. 꺼져 있으면 같은 객체가 큐에 두 번 들어가, 이후 서로 다른 두 곳이 같은 객체를 받는 찾기 어려운 버그가 됩니다. 개발 중에는 반드시 켜 두세요.

•

"스레드 안전"은 맞습니다(내부에서 lock 을 겁니다). 다만 풀에서 꺼낸 객체 자체를 여러 스레드가 같이 쓰는 것까지 보호해 주지는 않습니다.

Reference Pool

목적과 개요 (Purpose and Overview)

Reference Pool은 객체를 매번 새로 만들고 파괴하는 대신 재사용해서 가비지 컬렉션(GC) 부하를 줄이는 메모리 관리 시스템입니다. 이벤트 인자 같은 빈번히 생성되는 임시 객체에서 특히 효과적이며, 과도한 GC로 인한 성능 저하를 막아줍니다.

Reference Pool은 GameFramework의 코어 컴포넌트 중 하나이며, Object Pool Manager(오브젝트 풀)와 함께 쓰일 수 있지만 초점이 다릅니다(Reference Pool은 작고 짧게 사는 객체 위주).

핵심 구성요소 (Core Components)

ReferencePool

재사용 가능한 객체 모음을 관리하는 정적 클래스.

•

타입을 키로 하는 ReferenceCollection 사전을 유지

•

객체 획득/반납 및 풀 관리 API 제공

•

올바른 사용을 강제하는 엄격 검사(Strict Check) 모드 제공

IReference

풀에 넣을 수 있는 모든 객체가 구현해야 하는 인터페이스.

•

반납 시 상태를 초기화하기 위한 Clear() 메서드 정의

ReferenceCollection

특정 타입의 참조를 관리하는 내부 클래스.

•

미사용 참조들의 큐 보관

•

획득/반납/추가/제거 등 사용 통계 기록

•

풀이 비면 새 인스턴스 생성 처리

ReferencePoolInfo

특정 참조 풀의 정보를 담는 구조체.

•

모니터링/디버깅에 유용한 사용 통계 제공

GameFrameworkEventArgs

이벤트 인자의 추상 기본 클래스이자 IReference 구현체.

•

이벤트 인자는 자주 만들어졌다가 버려지므로 풀링의 대표적인 대상

동작 방식 (How Reference Pooling Works)

획득(Acquisition)

클라이언트가 참조가 필요하면 ReferencePool.Acquire<T>() 호출:

•

풀이 비어 있지 않으면 하나 꺼내 반환

•

비어 있으면 새 인스턴스 생성

•

통계 카운터 업데이트

사용(Usage)

반환받은 객체를 필요한 동안 사용.

반납(Release)

사용을 끝내면 ReferencePool.Release(reference) 호출:

•

객체의 Clear()를 호출하여 상태 초기화

•

해당 타입의 컬렉션 큐에 재등록

•

통계 카운터 업데이트

엄격 검사(Strict Checking)

개발 중 오남용을 잡기 위한 검사를 활성화할 수 있음:

•

유효한 타입인지(추상 X, IReference 구현) 확인

•

중복 반납 같은 오류 검사

GameFramework와의 연동 (Integration)

이벤트 시스템

•

대부분의 이벤트 인자 클래스는 GameFrameworkEventArgs를 상속(IReference 구현)

•

자주 생성·소멸되는 이벤트 인자가 풀링의 최적 대상

•

예: ResetSoundAgentEventArgs.Create() 내부에서 ReferencePool.Acquire<ResetSoundAgentEventArgs>() 사용

프레임워크 컴포넌트

•

Entity/UI/Sound/Network 등 여러 매니저가 이벤트 시스템을 광범위하게 사용

•

이로 인해 Reference Pool의 GC 절감 효과를 간접적으로 크게 얻음

코어 인프라

•

Reference Pool은 GameFrameworkEntry와 나란히 위치한 코어 인프라로,

모든 모듈과 게임 코드에서 공용으로 사용할 수 있음

사용 패턴 (Usage Patterns)

풀링 가능한 클래스 만들기

IReference를 구현(보통 GameFrameworkEventArgs 상속)하고 Clear()로 초기화:

public class MyCustomEventArgs : GameFrameworkEventArgs
{
    private int m_Value;

    public int Value => m_Value;

    public static MyCustomEventArgs Create(int value)
    {
        MyCustomEventArgs eventArgs = ReferencePool.Acquire<MyCustomEventArgs>();
        eventArgs.m_Value = value;
        return eventArgs;
    }

    public override void Clear()
    {
        m_Value = 0;
    }
}

복사

전형적인 흐름

// 1) 획득
MyCustomEventArgs args = ReferencePool.Acquire<MyCustomEventArgs>();
// 또는 팩토리 메서드
MyCustomEventArgs args2 = MyCustomEventArgs.Create(42);

// 2) 사용
// ... args 사용 ...

// 3) 반납
ReferencePool.Release(args);

복사

풀 관리 API (예시)

•

Add<T>(count) : 지정 개수만큼 미리 생성해 풀에 추가

•

Remove<T>(count) : 지정 개수만큼 제거

•

RemoveAll<T>() : 해당 타입 전부 제거

•

ClearAll() : 모든 참조 풀 초기화

•

GetAllReferencePoolInfos() : 모든 풀의 통계 정보 조회

성능 관점 (Performance Considerations)

이점

•

GC 감소: 재사용으로 GC 빈도/정지 시간을 줄임

•

메모리 효율: 자주 쓰는 임시 객체를 메모리에 유지하여 반복 할당 회피

•

성능 향상: 이벤트가 많거나 임시 객체가 많은 시스템에서 특히 효과적

베스트 프랙티스

•

완전 초기화: Clear()에서 모든 필드를 꼼꼼히 초기화

•

반납 철저: 사용 후 반드시 Release() 호출

•

엄격 검사 활성화(개발 중):

ReferencePool.EnableStrictCheck = true;

복사

•

적합한 대상만 풀링: 짧게 자주 생성되는 객체에 적합(오래 사는/거의 안 만드는 객체는 X)

•

통계 모니터링: GetAllReferencePoolInfos()로 과다/누락 확인

◦

미사용 수가 비정상적으로 크면 과도한 사전 생성 의심

◦

획득/반납 불균형은 메모리 누수 신호

결론 (Conclusion)

Reference Pool은 GameFramework의 핵심 메모리 관리 시스템으로, 객체 재사용을 통해 GC 오버헤드를 줄이고 게임처럼 메모리에 민감한 환경에서 안정적인 성능을 유지하게 도와줍니다.

특히 이벤트 인자처럼 짧은 생명주기를 가진 객체에 효과가 크며, 올바르게 사용하면 GC 정지 시간을 눈에 띄게 줄여 전체 반응성을 높일 수 있습니다.

Reference Pool

Abstract

Reference Pool

관련 소스 파일 (Relevant source files)

목적과 개요 (Purpose and Overview)

핵심 구성요소 (Core Components)

ReferencePool

IReference

ReferenceCollection

ReferencePoolInfo

GameFrameworkEventArgs

동작 방식 (How Reference Pooling Works)

획득(Acquisition)

사용(Usage)

반납(Release)

엄격 검사(Strict Checking)

GameFramework와의 연동 (Integration)

이벤트 시스템

프레임워크 컴포넌트

코어 인프라

사용 패턴 (Usage Patterns)

풀링 가능한 클래스 만들기

전형적인 흐름

풀 관리 API (예시)

성능 관점 (Performance Considerations)

이점

베스트 프랙티스

결론 (Conclusion)