Folly Code Review · 8/89

folly::SemiFuture vs Future — executor binding의 명시화

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

한 줄 요약: SemiFuture<T>는 executor에 바인딩되지 않은 Future다. 라이브러리 API의 반환 타입으로 SemiFuture를 강제하면 caller가 executor 결정권을 갖는다.

#동기 — executor가 누구의 책임인가

비동기 함수가 Future<T>를 반환하면 어디서 callback이 도는지가 함수 안에 고정된다. caller는 그 executor가 자기 thread context와 맞는지 알 수 없다. 다음 코드는 잘못된 thread에서 GUI를 갱신할 위험이 있다.

1
folly::Future<Image> loadImage(std::string path) {
2
  static folly::CPUThreadPoolExecutor pool(4);
3
  return folly::via(&pool, [path] { return decodeImage(path); });
4
}
5

6
// GUI thread에서
7
loadImage("a.png").thenValue([](Image img) {
8
  ui->display(img);   // BUG: GUI thread가 아닐 수 있음
9
});

loadImage의 caller는 callback이 어디서 도는지 보이지 않는다. Folly의 해법은 executor 결정을 caller에게 떠넘기는 것이다.

1
folly::SemiFuture<Image> loadImage(std::string path) {
2
  return folly::makeSemiFuture()
3
    .deferValue([path](auto) { return decodeImage(path); });
4
}
5

6
// caller
7
loadImage("a.png")
8
  .via(&guiExecutor)         // executor 명시
9
  .thenValue([](Image img) {
10
    ui->display(img);         // 안전
11
  });
12
}

SemiFuture를 반환하면 caller가 .via(executor)를 반드시 호출해야 다음 단계로 갈 수 있다. 컴파일러가 강제하지 않지만 API 관례로 강제된다.

#SemiFuture의 인터페이스

1
// folly/futures/Future.h (요약)
2
template <class T>
3
class SemiFuture {
4
 public:
5
  // executor 바인딩 — Future로 전환
6
  Future<T> via(Executor* e) &&;
7
  Future<T> via(Executor::KeepAlive<> e) &&;
8

9
  // executor 없이 callback 등록 — DrivableExecutor 위에서만 의미
10
  template <class F> SemiFuture<U> deferValue(F&& fn) &&;
11
  template <class F> SemiFuture<U> deferError(F&& fn) &&;
12
  template <class F> SemiFuture<U> defer(F&& fn) &&;
13

14
  // blocking
15
  T get() &&;
16
  T getVia(DrivableExecutor* e) &&;
17

18
  // 그 외
19
  bool isReady() const;
20
  SemiFuture<T> wait() &&;
21
};

deferValue/deferError는 executor가 정해질 때까지 callback을 보류한다. 나중에 .via(e)가 호출되면 모든 deferred callback이 그 executor에서 실행된다.

#Future의 인터페이스 (요약)

1
template <class T>
2
class Future {
3
 public:
4
  Executor* getExecutor() const;
5

6
  template <class F> Future<U> thenValue(F&& fn) &&;
7
  template <class F> Future<U> thenError(folly::tag_t<E>, F&& fn) &&;
8
  template <class F> Future<U> thenTry(F&& fn) &&;
9

10
  Future<T> via(Executor* e) &&;     // executor 재바인딩
11
  Future<T> within(Duration);
12
  Future<T> onTimeout(Duration, F);
13

14
  // SemiFuture로 역변환 — executor 분리
15
  SemiFuture<T> semi() &&;
16
};

Future는 bound executor가 있는 상태이므로 .thenValue를 바로 호출할 수 있다. SemiFuture는 그렇지 않다.

#변환 흐름

SemiFuture .via Executor Future

1
makeSemiFuture(v) ──▶ SemiFuture<T> ──.via(e)──▶ Future<T>
2
                                                    │
3
Promise<T>.getSemiFuture() ──▶ SemiFuture<T>        │
4
                                                    │
5
Promise<T>.getFuture() ──▶ Future<T> (InlineExecutor)
6
                                                    ▼
7
                                            .thenValue / .thenError ...
8
                                                    │
9
                                                    ▼
10
                                            Future<U> 또는 .semi() ──▶ SemiFuture<U>

getFuture()는 InlineExecutor에 자동 바인딩된다. 이는 어디서 callback이 도는지가 caller의 thread에 의존한다는 뜻이고, 거의 항상 명확한 표현이 아니다. OSS 코드 리뷰에서는 getSemiFuture() 사용을 권장한다.

#라이브러리 API 권장 패턴

1
// 잘못된 패턴 — executor가 함수에 고정
2
folly::Future<Result> doWork();          // 어디서 callback이 도는지 불명
3

4
// 권장 패턴 — caller가 결정
5
folly::SemiFuture<Result> doWork();      // .via(e)를 caller가 호출
6

7
// 모듈 boundary에서의 강제
8
namespace mylib {
9
  folly::SemiFuture<Response> Handle(Request);   // SemiFuture로 export
10
}

내부 구현은 자유롭게 Future를 쓰지만 공개 API는 SemiFuture로 통일한다. Folly 자체의 모든 public API가 이 규칙을 따른다.

#defer vs via — 두 가지 callback 등록

1
folly::SemiFuture<int> sf = computeAsync();
2

3
// 방법 A — defer: executor 결정 전 등록, 나중에 via로 일괄 실행
4
sf
5
  .deferValue([](int x) { return x + 1; })
6
  .deferValue([](int x) { return x * 2; })
7
  .via(&pool)
8
  .thenValue([](int x) { return std::to_string(x); })
9
  .get();
10

11
// 방법 B — 즉시 via, 이후 then 사용
12
sf
13
  .via(&pool)
14
  .thenValue([](int x) { return x + 1; })
15
  .thenValue([](int x) { return x * 2; })
16
  .get();

A는 SemiFuture가 라이브러리 boundary를 넘어 caller까지 흘러갈 때 유용하다. B는 같은 스코프 안에서 명확하다.

#내부 구현 — Executor 보관

1
// folly/futures/detail/Core.h (개념)
2
template <class T>
3
class Core {
4
  Executor::KeepAlive<> executor_;   // SemiFuture는 nullptr, Future는 bound
5
  // ...
6
};
7

8
// .via 호출 시
9
template <class T>
10
Future<T> SemiFuture<T>::via(Executor::KeepAlive<> e) && {
11
  this->getCore().setExecutor(std::move(e));
12
  return Future<T>(detail::EmptyConstruct{}, this->getCore());
13
}

Executor::KeepAlive<>는 executor에 대한 참조 카운트 증가를 보장한다. callback이 실행될 때까지 executor가 destroyed되지 않는다.

#std::executor 제안과의 관계

C++26 후보의 std::execution::scheduler/sender/receiver는 같은 문제를 푼다.

1
Folly                    std::execution (P2300)
2
─────────────────────    ─────────────────────
3
SemiFuture<T>            sender (unbound)
4
Future<T>                connected sender
5
Executor                 scheduler
6
.via(e)                  on(scheduler, sender)
7
.thenValue(f)            then(sender, f)
8
.get()                   sync_wait(sender)

개념적으로 거의 1

대응이다. P2300이 표준에 도착하면 Folly 사용자는 점진적으로 이전할 수 있다.

#코드 리뷰 포인트

public API가 Future를 반환하는가? SemiFuture로 바꾼다.
getFuture() 사용? getSemiFuture()로 바꾸고 caller가 .via(e)를 호출하게 한다.
체인 중간에 .via()가 없이 .then을 부르는가? SemiFuture는 컴파일 에러가 난다. Future라면 어디서 도는지 명확해야 한다.
.semi()로 다시 SemiFuture를 만드는 이유가 있는가? 라이브러리 경계를 넘기는 경우에만 의미 있다.

#자주 보는 안티패턴

1
// 1. public API가 Future
2
folly::Future<Result> handleRequest(Request);   // 잘못
3

4
// 2. SemiFuture에 InlineExecutor를 강제
5
auto v = computeSemi().via(&folly::InlineExecutor::instance()).get();
6
// continuation이 호출자 thread에서 도는 게 의도였는가?
7

8
// 3. .via 누락 후 .get
9
auto v = computeSemi().get();   // 내부적으로 InlineExecutor 사용 — 의도 불명
10

11
// 4. 매 호출마다 .via를 잊는다
12
mylib::Handle(req)
13
  .thenValue([](auto r) { ... });   // SemiFuture라 컴파일 에러