Folly Code Review · 16/89

folly::ManualExecutor — 결정적 테스트를 위한 수동 진행

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

한 줄 요약: ManualExecutor는 task를 queue에 쌓아두고 run() 호출 시에만 실행한다. 비동기 Future 체인의 진행을 step-by-step으로 검증하는 테스트 도구다.

#동기 — 비동기 코드의 결정적 테스트

비동기 코드의 테스트는 race로 깨지기 쉽다. CPUThreadPoolExecutor로 schedule하면 언제 실행되는지 테스트가 통제할 수 없다.

1
TEST(Worker, ProcessesQueue) {
2
  folly::CPUThreadPoolExecutor pool(2);
3
  Worker w(&pool);
4
  w.enqueue(1);
5
  w.enqueue(2);
6
  // sleep으로 기다림 — flaky
7
  std::this_thread::sleep_for(std::chrono::milliseconds(100));
8
  EXPECT_EQ(w.processed(), 2);
9
}

위 테스트는 CI 부하에 따라 깨진다. ManualExecutor는 callback이 도는 시점을 테스트가 통제하게 한다.

#API

1
#include <folly/executors/ManualExecutor.h>
2

3
folly::ManualExecutor exec;
4

5
exec.add([] { std::cout << "task 1\n"; });
6
exec.add([] { std::cout << "task 2\n"; });
7

8
// 아직 출력 없음 — queue에만 쌓임
9

10
exec.run();   // 1번 schedule된 만큼 실행
11
// "task 1"
12
// "task 2"

추가 메서드.

1
class ManualExecutor : public DrivableExecutor, public ScheduledExecutor {
2
 public:
3
  void add(Func) override;
4
  void scheduleAt(Func, TimePoint) override;
5

6
  size_t run();           // ready task 모두 실행, 갯수 반환
7
  size_t drain();         // run을 더 이상 task가 없을 때까지
8
  size_t step();          // ready task 1개만 실행
9
  void drive();           // run + nothing to do면 wait
10

11
  bool empty() const;
12
  size_t numPending() const;
13

14
  void advance(Duration);   // 가상 시간 진행 — scheduled task 실행
15
};

#결정적 step-by-step 테스트

1
TEST(FutureChain, RunsInOrder) {
2
  folly::ManualExecutor exec;
3
  std::vector<int> log;
4

5
  folly::makeSemiFuture(1)
6
    .via(&exec)
7
    .thenValue([&](int x) { log.push_back(x); return x + 1; })
8
    .thenValue([&](int x) { log.push_back(x); return x + 1; })
9
    .thenValue([&](int x) { log.push_back(x); });
10

11
  EXPECT_EQ(exec.numPending(), 1);   // 첫 callback만 ready
12

13
  exec.step();
14
  EXPECT_EQ(log, std::vector<int>{1});
15

16
  exec.step();
17
  EXPECT_EQ(log, std::vector<int>{1, 2});
18

19
  exec.run();   // 나머지 모두
20
  EXPECT_EQ(log, (std::vector{1, 2, 3}));
21
}

체인의 각 단계가 언제 실행되는지 명시적으로 통제된다. race가 없으므로 어떤 환경에서도 동일하게 동작한다.

#가상 시간 — advance

1
TEST(Timer, FiresAtCorrectTime) {
2
  folly::ManualExecutor exec;
3
  std::atomic<bool> fired{false};
4

5
  exec.scheduleAt(
6
      [&] { fired = true; },
7
      exec.now() + std::chrono::seconds(5));
8

9
  exec.run();
10
  EXPECT_FALSE(fired);   // 아직 5초 안 지남
11

12
  exec.advance(std::chrono::seconds(4));
13
  EXPECT_FALSE(fired);
14

15
  exec.advance(std::chrono::seconds(1));
16
  EXPECT_TRUE(fired);
17
}

advance(d)는 가상 시간을 d만큼 앞으로 옮기고 그 사이 expire된 schedule을 실행한다. 실제로 5초 wait 하지 않는다.

#drive — Future가 완료될 때까지 진행

1
auto sf = computeAsync();
2
auto f = std::move(sf).via(&exec);
3

4
// Future 완료까지 진행
5
while (!f.isReady()) {
6
  exec.drive();
7
}
8
auto v = std::move(f).get();

drive()는 ready task를 실행하고 없으면 short wait 후 다시 본다. loopOnce()와 비슷한 의미다.

#내부 구현

1
// folly/executors/ManualExecutor.h (요약)
2
class ManualExecutor : public DrivableExecutor, public ScheduledExecutor {
3
 public:
4
  void add(Func f) override {
5
    std::lock_guard<std::mutex> lock(lock_);
6
    funcs_.push(std::move(f));
7
    sem_.post();
8
  }
9

10
  size_t run() {
11
    size_t count = 0;
12
    std::vector<Func> funcs;
13
    {
14
      std::lock_guard<std::mutex> lock(lock_);
15
      funcs_.swap_to_vec(funcs);   // 현재 시점의 ready만
16
    }
17
    for (auto& f : funcs) {
18
      f();
19
      ++count;
20
    }
21
    return count;
22
  }
23

24
 private:
25
  std::mutex lock_;
26
  std::queue<Func> funcs_;
27
  std::priority_queue<ScheduledFunc> scheduledFuncs_;
28
  TimePoint now_;
29
  folly::LifoSem sem_;
30
};

queue + scheduled queue + virtual clock의 단순한 조합이다.

#InlineExecutor와의 차이

항목	InlineExecutor	ManualExecutor
실행 시점	add() 즉시	run()/drive() 호출 시
결정성	있음 (즉시)	있음 (수동)
가상 시간	없음	advance() 지원
사용 사례	단순 동기 테스트	비동기 시퀀스 테스트

InlineExecutor는 비동기성을 제거하지만 ManualExecutor는 비동기성을 시각화한다. 후자가 비동기 시나리오의 테스트에 더 적합하다.

#실전 — RPC 테스트

1
TEST(RpcClient, RetriesOnTimeout) {
2
  folly::ManualExecutor exec;
3
  MockServer server;
4
  RpcClient client(&exec, &server);
5

6
  auto sf = client.call("foo");
7
  auto f = std::move(sf).via(&exec);
8

9
  // 첫 시도
10
  exec.run();
11
  EXPECT_EQ(server.callCount(), 1);
12

13
  // 5초 후 timeout
14
  exec.advance(std::chrono::seconds(5));
15
  exec.run();
16
  EXPECT_EQ(server.callCount(), 2);   // 재시도
17

18
  // 응답 도착
19
  server.respond(2, "ok");
20
  exec.run();
21
  EXPECT_TRUE(f.isReady());
22
  EXPECT_EQ(std::move(f).get(), "ok");
23
}

advance로 타이머 발화 시점을 직접 제어한다. 5초를 실제로 기다리지 않고 타임아웃 시나리오를 검증한다.

#코드 리뷰 포인트

테스트에서 sleep_for를 쓰고 있는가? ManualExecutor + advance로 대체한다.
production code에 ManualExecutor가 들어가지 않았는가? 테스트 전용이다.
run() vs drain() 사용 의도? 부분 진행이면 step/run, 끝까지면 drain.
drive() 무한 루프? Future가 영원히 ready가 안 되는 버그를 가린다. timeout을 둔다.

#자주 보는 안티패턴

1
// 1. ManualExecutor + 실제 sleep
2
exec.add([] { ... });
3
std::this_thread::sleep_for(std::chrono::seconds(1));
4
exec.run();   // sleep은 의미 없음 — ManualExecutor가 시간 통제
5

6
// 2. production에서 ManualExecutor
7
folly::ManualExecutor exec;
8
server.setExecutor(&exec);   // 누군가 run()을 안 부르면 영원히 진행 안 함
9

10
// 3. step()을 부르지 않고 .get()
11
auto f = compute().via(&exec);
12
f.get();   // ManualExecutor는 자동 실행 안 함 — deadlock
13

14
// 4. advance 없이 timer 테스트
15
exec.scheduleAt([&] { fired = true; }, exec.now() + std::chrono::seconds(5));
16
exec.run();   // 가상 시간 안 옮김 — 아무 일도 안 일어남