Folly Code Review · 84/89

folly::io::Compression — zstd·lz4·snappy wrapper

2026년 6월 8일 · Hawk · 4분 읽기

한 줄 요약: folly::io::Codec은 IOBuf를 입력/출력으로 받는 통합 compression 인터페이스다. zstd/lz4/snappy/zlib을 algorithm enum 한 번 바꿔 교체할 수 있다.

#동기

production code는 다양한 compression을 쓴다. RPC payload는 lz4(빠름), 영구 저장은 zstd(고압축), 호환성이 필요한 자리는 zlib. 각 알고리즘의 API가 미묘하게 다르고 IOBuf chain 처리도 직접 짜야 한다.

folly::io::Codec은 단일 추상화.

1
auto codec = folly::io::getCodec(folly::io::CodecType::ZSTD);
2
auto compressed = codec->compress(input);
3
auto decompressed = codec->uncompress(compressed.get());

CodecType만 바꾸면 알고리즘 교체. benchmark/A-B test에 유리.

#지원 알고리즘

1
enum class CodecType : int {
2
  NO_COMPRESSION = 0,
3
  LZ4            = 1,
4
  SNAPPY         = 2,
5
  ZLIB           = 3,
6
  LZ4_VARINT_SIZE = 4,
7
  LZMA2          = 5,
8
  LZMA2_VARINT_SIZE = 6,
9
  ZSTD           = 7,
10
  GZIP           = 8,
11
  LZ4_FRAME      = 9,
12
  BZIP2          = 10,
13
  ZSTD_FAST      = 11,
14
};

build option에 따라 일부는 disabled. 사용 가능한지 folly::io::hasCodec(type)로 확인.

Algorithm	Throughput (compress)	Throughput (decompress)	Compression ratio
snappy	~500 MB/s	~1500 MB/s	낮음
lz4	~500 MB/s	~3000 MB/s	낮음
zstd (lvl 3)	~400 MB/s	~1500 MB/s	중-고
zstd (lvl 19)	~10 MB/s	~1500 MB/s	매우 높음
zlib	~100 MB/s	~400 MB/s	중
lzma	~5 MB/s	~50 MB/s	최고

낮은 latency RPC는 lz4/snappy, archival storage는 zstd-19, balance는 zstd-3.

#API

1
#include <folly/io/Compression.h>
2

3
auto codec = folly::io::getCodec(
4
  folly::io::CodecType::ZSTD,
5
  /*level=*/3);
6

7
// 1. compress
8
auto src = folly::IOBuf::copyBuffer("hello world");
9
auto compressed = codec->compress(src.get());
10

11
// 2. uncompress
12
auto decompressed = codec->uncompress(
13
  compressed.get(),
14
  /*uncompressedLength=*/src->computeChainDataLength());
15

16
// 3. uncompress with prefix size (codec이 size를 포함하면 nullopt)
17
auto out = codec->uncompress(compressed.get());

핵심 메서드 둘 — compress(IOBuf*), uncompress(IOBuf*, optional<size_t>). 입력/출력 모두 unique_ptr<IOBuf>라 chain 데이터 그대로.

#Streaming

1
auto stream = folly::io::getStreamCodec(folly::io::CodecType::ZSTD);
2

3
folly::IOBufQueue inputQ, outputQ;
4
// ... feed inputQ from network ...
5

6
while (auto chunk = inputQ.pop_front()) {
7
  auto out = stream->compress(chunk.get());
8
  outputQ.append(std::move(out));
9
}
10
auto tail = stream->compress(nullptr);   // flush
11
outputQ.append(std::move(tail));

streaming codec은 partial input/output을 처리. fixed-size chunk가 network에서 들어올 때.

#내부 구현 — codec factory

1
// folly/io/Compression.cpp 약식
2
std::unique_ptr<Codec> getCodec(CodecType type, int level) {
3
  switch (type) {
4
    case CodecType::LZ4:    return std::make_unique<LZ4Codec>(level);
5
    case CodecType::SNAPPY: return std::make_unique<SnappyCodec>();
6
    case CodecType::ZSTD:   return std::make_unique<ZstdCodec>(level);
7
    // ...
8
    default: throw std::runtime_error("unsupported codec");
9
  }
10
}
11

12
class ZstdCodec : public Codec {
13
 public:
14
  ZstdCodec(int level) : level_(level) {}
15

16
  std::unique_ptr<IOBuf> doCompress(const IOBuf* data) override {
17
    size_t bound = ZSTD_compressBound(data->computeChainDataLength());
18
    auto out = IOBuf::create(bound);
19
    auto coalesced = data->coalesce();
20
    size_t actual = ZSTD_compress(
21
      out->writableData(), bound,
22
      coalesced.data(), coalesced.size(),
23
      level_);
24
    if (ZSTD_isError(actual)) throw CompressionException(...);
25
    out->append(actual);
26
    return out;
27
  }
28
};

각 codec class가 base Codec 인터페이스 구현. dispatch는 factory에서 enum→class.

#IOBuf coalesce overhead

1
auto coalesced = data->coalesce();  // chain → contiguous (alloc 가능)

대부분 codec library가 contiguous buffer를 받는다. IOBuf chain이면 coalesce()로 합치는 비용이 생긴다. zstd/lz4는 streaming API도 있어 chain을 chunk별로 feed 가능.

#std와의 비교

항목	std (없음)	folly::io::Codec	Abseil (없음)	Arrow Compression
표준	N/A	통합 wrapper	직접 호출	통합 wrapper
algorithm 교체	N/A	enum	코드 변경	enum
streaming	N/A	streamCodec	직접	있음
IOBuf 통합	N/A	O	N/A	Arrow Buffer

C++ 표준에는 compression이 없다. zip/gzip/zstd 모두 외부. folly가 한 추상화 안에 묶어 RPC layer 같은 알고리즘 dynamic 선택이 필요한 곳에 적합.

#코드 리뷰 포인트

매 compress 호출마다 getCodec을 부르면 factory dispatch overhead. codec 객체를 보관.
coalesce()가 큰 IOBuf chain에 호출되면 alloc + copy. streaming codec 검토.
level 선택 — RPC payload에 zstd-19는 과함. lz4 또는 zstd-1~3 권장.
uncompressed size를 모르고 decompress → zstd는 frame header에서 size 추출 가능하나 일부는 호출자가 알아야.
의도하지 않은 알고리즘 mismatch — magic byte로 자동 감지하는 wrapper(예: zlib magic 0x78)가 적절.

#자주 보는 안티패턴

1
// 1. compress한 buffer를 다시 decompress해 비교 (debug)
2
auto c = codec->compress(orig.get());
3
auto d = codec->uncompress(c.get());
4
CHECK(equals(orig, d));   // hot path에 두지 말 것
5

6
// 2. 매번 getCodec
7
for (auto& msg : msgs) {
8
  auto codec = folly::io::getCodec(CodecType::ZSTD);  // factory
9
  auto out = codec->compress(msg);
10
}
11
// → codec를 한 번 만들어 재사용
12

13
// 3. zstd level 22로 RPC hot path
14
auto codec = folly::io::getCodec(CodecType::ZSTD, 22);
15
// → 10 MB/s compression — RPC 처리량 한계
16

17
// 4. 압축 후 length prefix 없이 그대로 저장
18
// → uncompress 시 결과 길이 모름
19
// → length-prefixed framing 또는 algorithm이 자체 frame을 가진 variant 사용 (LZ4_FRAME)

#실전 — RPC payload

1
class RpcServer {
2
  std::unique_ptr<folly::io::Codec> codec_;
3

4
 public:
5
  RpcServer()
6
    : codec_(folly::io::getCodec(folly::io::CodecType::ZSTD, /*level=*/3)) {}
7

8
  std::unique_ptr<folly::IOBuf> EncodeResponse(const Response& r) {
9
    auto serialized = Serialize(r);   // IOBuf
10
    if (serialized->computeChainDataLength() > kCompressThreshold) {
11
      return codec_->compress(serialized.get());
12
    }
13
    return serialized;
14
  }
15
};