folly::IOBuf shared semantics — clone·unshare·takeOwnership

한 줄 요약: IOBuf의 buffer와 node는 별개다. clone은 buffer를 공유하고 node를 새로 만든다. unshare는 buffer를 분리한다. 이 구분이 zero-copy의 안전성을 결정한다.

#동기 — share의 두 층위

IOBuf의 구조를 다시 본다.

buffer는 실제 byte 영역과 SharedInfo다. node는 그 buffer를 가리키는 IOBuf 객체다.

share할 수 있는 것은 buffer다. 여러 IOBuf node가 같은 buffer를 가리킬 수 있다. 각 node는 독립된 chain link, 독립된 data_/length를 가질 수 있다(같은 buffer의 다른 부분).

#clone — 같은 buffer를 가리키는 새 node

1
auto a = folly::IOBuf::create(1024);
2
a->append(100);
3

4
auto b = a->clone();
5
// b는 새 node, a와 같은 buffer를 가리킴
6
// a->data() == b->data()
7
// SharedInfo.refcount = 2

clone은 얕은 복사다. node는 새로 만들지만 buffer는 공유한다. ref-count가 0이 될 때까지 buffer는 살아 있다.

#unshare — buffer copy로 분리

1
auto b = a->clone();   // ref-count = 2
2
b->unshare();           // b만의 buffer로 복사 — ref-count = 1, 1
3

4
b->writableData()[0] = 'x';   // a는 영향 없음

unshare는 write 전 분리다. 자기만의 buffer로 copy하고 ref-count를 분리한다. copy-on-write의 수동 버전이다.

fbstring이 write를 가로채 자동으로 unshare를 수행한다면, IOBuf는 명시적으로 unshare()를 부르는 모델이다. 같은 원리, 다른 정책 — IOBuf의 buffer는 보통 더 크고 unshare 비용이 더 크기 때문에 의사 결정을 호출자에게 위임한다.

1
// folly/io/IOBuf.cpp (개념)
2
void IOBuf::unshareOne() {
3
  if (isSharedOne()) {
4
    // 새 buffer 할당 + copy
5
    auto newBuf = ...;
6
    std::memcpy(newBuf, data_, length_);
7
    // 기존 SharedInfo decref, 새 SharedInfo
8
    decrementRefcount();
9
    setNewBuffer(newBuf);
10
  }
11
}

#clone vs cloneOne vs cloneAsValue

1
auto chain = ...;   // 3-node chain
2

3
auto a = chain->clone();          // 전체 chain clone, ref-count 모두 share
4
auto b = chain->cloneOne();       // 첫 node만 clone, 나머지 chain은 없음
5
auto c = chain->cloneAsValue();   // unique_ptr 대신 IOBuf 값

• clone() — 전체 chain의 모든 node share
• cloneOne() — 단일 node만 share
• cloneCoalesced() — 새 buffer 하나로 chain 합치기 (zero-copy 아님)

#takeOwnership — 외부 메모리 wrap

1
uint8_t* mem = (uint8_t*)malloc(1024);
2
auto buf = folly::IOBuf::takeOwnership(
3
    mem, 1024,            // 시작, 크기
4
    [mem](void*, void*) { free(mem); });   // free callback
5

6
// buf의 ref-count가 0이 되면 callback 호출

callback의 두 인자는 (data, userData)다. userData는 SharedInfo에 보관할 추가 context다.

1
// mmap 예
2
void* mapped = mmap(nullptr, size, PROT_READ, MAP_PRIVATE, fd, 0);
3
auto buf = folly::IOBuf::takeOwnership(
4
    mapped, size,
5
    [size](void* p, void*) { munmap(p, size); });

#wrapBuffer — read-only, lifetime 미관리

1
const char* msg = "hello";
2
auto buf = folly::IOBuf::wrapBuffer(msg, 5);
3
// buf의 ref-count = 0 (관리 안 함)
4
// msg의 lifetime은 caller가 보장

wrapBuffer는 zero-cost wrap이다. ref-count도 없고, free 콜백도 없다. caller가 lifetime을 보장해야 한다.

좋은 사용:

• string literal
• static buffer
• caller가 lifetime을 확실히 길게 잡은 buffer

위험:

• stack-local buffer
• temporary container의 buffer
• lambda capture로 share되는 buffer

#SharedInfo — 내부

1
// folly/io/IOBuf.h (요약)
2
struct SharedInfo {
3
  FreeFunction freeFn;     // free 콜백
4
  void* userData;          // 콜백에 전달할 context
5
  std::atomic<uint32_t> refcount{1};
6
  uint8_t externallyShared{0};   // 외부 reference 표시
7
};

refcount는 atomic이다. 모든 clone/unshare/destroy는 atomic operation을 거친다. 비용은 uncontended 시 ~5ns, contended 시 훨씬 더.

#externallyShared — 외부 참조 추적

1
auto a = folly::IOBuf::create(1024);
2
auto b = a->clone();
3

4
a->markExternallySharedOne();   // 외부 코드가 a의 buffer를 본다고 표시
5

6
b->isShared();   // true — refcount > 1
7
b->isExternallyShared();   // true — externallyShared 비트

externallyShared는 코드 외부에서 buffer를 보고 있을 때 사용한다. 예를 들어 raw pointer를 다른 thread에 넘긴 경우. refcount로는 안 잡힌다.

#chain의 ref-count

chain은 node별로 buffer가 다를 수 있다. clone은 각 node를 개별 clone해 각 buffer의 refcount를 늘린다.

1
auto chain = makeThreeNodeChain();
2
auto cloned = chain->clone();
3
// 3개 node 모두 새로 만들고, 각각 자기 buffer의 refcount 증가

unshareChain()은 chain의 모든 node를 unshare한다.

1
chain->unshareChain();   // 모든 node 자기 buffer로 분리

#안전 규칙

1. shared buffer에 write 금지. isShared() 또는 unshare() 후 write.
2. wrapBuffer는 lifetime을 caller가 보장. heap/stack 구분.
3. takeOwnership의 free callback이 thread-safe 한지 확인. ref-count가 어느 thread에서 0이 될지 모름.
4. clone 후 chain pointer를 caller에 노출하면 안 됨. clone은 새 chain이지만 같은 buffer다.

#코드 리뷰 포인트

• writableData() 호출 전 isShared() 체크? shared면 silent corruption.
• takeOwnership의 free callback이 다른 destructor와 race하지 않는가? atomic decrement 후 호출됨.
• wrapBuffer의 lifetime이 명확한가? 같은 함수 안에서 사용/소멸이 보이는가.
• chain 전체를 clone하는데 외부에서는 node 하나만 본다고 가정하지 않는가? clone vs cloneOne 구분.

#자주 보는 안티패턴

1
// 1. clone 후 mutation
2
auto b = a->clone();
3
b->writableData()[0] = 'x';   // a도 바뀜
4
// 옳음:
5
b->unshare();
6
b->writableData()[0] = 'x';
7

8
// 2. wrapBuffer + temporary
9
auto buf = folly::IOBuf::wrapBuffer(makeTempString().data(), 5);
10
// makeTempString() 소멸 — buf dangling
11

12
// 3. takeOwnership에서 다른 IOBuf와 share된 메모리
13
auto buf1 = folly::IOBuf::create(1024);
14
auto buf2 = folly::IOBuf::takeOwnership(
15
    buf1->writableData(), 100,   // buf1과 same buffer
16
    [](void*, void*) { /* nothing */ });
17
// buf1 또는 buf2 destroy 시 double free 또는 use-after-free
18

19
// 4. 다른 thread에서 unshare 도중 read
20
// thread 1: buf->unshareOne();    // 새 buffer 할당 중
21
// thread 2: read(buf->data());    // race
22
// IOBuf의 unshare는 thread-safe 아니다 — node 단위 sync 필요

#std::shared_ptr와 비교

std::shared_ptr<T>는 T 전체를 ref-count 관리한다. IOBuf의 clone은 buffer를 share하지만 node는 독립이다.

shared_ptr<T> + aliasing constructor로 비슷한 모양을 만들 수 있지만 IOBuf는 chain까지 표현해 더 풍부하다.

#정리

• IOBuf의 node와 buffer는 별개다. node는 chain의 link, buffer는 byte 영역.
• clone은 buffer를 share하고 새 node를 만든다(얕은 복사).
• unshare는 buffer를 자기만의 copy로 분리한다(write 전 안전).
• takeOwnership은 외부 메모리를 ref-count로 관리한다.
• wrapBuffer는 zero-cost wrap이지만 lifetime은 caller 책임.
• SharedInfo.refcount는 atomic. 외부 참조는 externallyShared 비트로 표시.
• shared buffer에 write 금지. 항상 isShared/unshare 후 write.

#다음 편

Part 5부터 String/Format을 본다. 이 시리즈의 Part 1-4가 Folly의 async + I/O 핵심을 다뤘다.

#관련 항목

• Folly Part 4-01 — IOBuf
• Folly Part 4-04 — Zero-copy 패턴
• Effective Modern C++ Item 19 — shared_ptr 비교