Project Parcel

Parcel은 자바 환경에서 GC 오버헤드와 런타임 리플렉션 비용을 최소화하여, 극도의 처리량(Throughput)과 낮은 지연 시간(Latency)을 달성하는 것을 목표로 하는 컴파일 타임 스키마 기반 이진 직렬화 라이브러리이다.

라이브러리는 다음 자바 기본 및 핵심 타입을 지원한다.

• 기본 타입(Primitive Types) 및 래퍼 클래스:
  • byte, short, int, long, float, double, boolean, char
  • java.lang.String, java.lang.Enum, java.util.Optional, java.util.UUID
  • java.time.Instant, java.time.LocalDateTime, java.time.LocalDate, java.time.LocalTime, java.time.ZonedDateTime, java.time.OffsetDateTime, java.time.OffsetTime
• 컬렉션 인터페이스 (제한적 지원): java.util.List, java.util.Set, java.util.Map (단, 제네릭 타입이 기본 타입 또는 @Parcelable 객체인 경우에 한함)

1. 사용 예시

repositories {
    maven {
        name = "Elex Repository"
        url = "https://artifacts.elex-project.com/repository/maven/"
    }
}
dependencies {
    implementation("com.elex-project:parcel-annotations:1.0.0")
    implementation("com.elex-project:parcel:1.0.0")
    annotationProcessor("com.elex-project:parcel-preprocessor:1.0.0")
}

@Parcelable
public class MyPojo {
	@Sequence(0)
    public int id;
	@Sequence(1)
    public String name;
	@Sequence(2)
    public int age;
	
	public MyPojo(){} // requires no-args constructor
}

// 사용 예시
byte[] bytes = Parcel.pack(myPojo);
MyPojo myPojo = Parcel.unpack(bytes, MyPojo.class);

2. 워크 플로우

[ 개발자 소스 코드 ] 
    │ (POJO 객체에 @Parcelable, @Sequence 작성)
    ▼
[ 1. 컴파일 단계 (APT) ]
    │ · 자바 컴파일러(javac)가 ParcelProcessor 실행
    │ · POJO의 구조와 인덱스를 분석하여 'XxxSerializer.java' 소스 코드 자동 생성
    ▼
[ 2. 빌드 산출물 ]
    │ · 원본 클래스 파일 + 컴파일된 XxxSerializer.class가 패키징됨
    ▼
[ 3. 런타임 단계 (실행) ]
    │ · Parcel.serialize(pojo) 호출
    │ · 내부 BufferPool에서 재사용 버퍼 획득 (Zero-Allocation)
    │ · 리플렉션 없이 생성된 Serializer가 가변 길이(Varint) 이진 데이터로 직렬화
    ▼
[ 최종 바이너리 데이터 (byte[]) ]

2.1 컴파일 타임 워크플로우 상세

1. 개발자가 프로젝트를 빌드(gradle build 등)하면 자바 컴파일러(javac)가 실행됩니다.
2. annotation-processor 모듈의 META-INF에 등록된 ParcelProcessor가 호출됩니다.
3. 소스 코드 내의 @Parcelable 어노테이션이 붙은 클래스를 탐색합니다.
4. @Sequence 값을 기준으로 필드 정렬 및 유효성 검증(인덱스 중복 여부 등)을 수행합니다.
5. Filer API를 사용하여 하드코딩된 바이트 쓰기 코드가 담긴 인간이 읽을 수 있는 자바 소스 파일(*Serializer.java)을 생성하고, 컴파일러가 이 파일까지 함께 클래스 파일로 빌드합니다.

2.2 런타임 워크플로우 상세

1. 애플리케이션 실행 중 Parcel.serialize(userPojo)를 호출합니다.
2. Parcel 핵심 API는 ThreadLocal에서 현재 스레드 전용으로 할당된 내부 바이트 버퍼를 꺼냅니다. (새로운 배열 할당 최소화)
3. 미리 규칙(Naming Convention)에 따라 매핑된 UserPojoSerializer.serialize(userPojo, buffer)를 직접 호출합니다.
4. 생성된 직렬화 코드는 리플렉션을 전혀 쓰지 않고 객체의 getter를 호출하거나 VarHandle을 통해 값을 읽어와 버퍼에 가변 정수(Varint) 인코딩 방식으로 밀어 넣습니다.
5. 최종적으로 채워진 버퍼의 데이터 영역만큼만 byte[]로 반환하거나 스트림으로 출력합니다.

---

Copyright © 2026 Elex. All rights reserved.