Folly Code Review · 85/89

folly::AsyncIO — io_uring·Linux AIO

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

한 줄 요약: folly::AsyncIO는 Linux의 io_uring(우선) 또는 libaio(폴백)을 wrap한 async disk I/O 인터페이스다. thread-per-IO 모델 없이 수만 동시 I/O를 다룬다.

#동기

전통적인 disk I/O는 blocking — read/write가 thread를 잠근다. 한 번에 수천 파일을 다루려면 thread를 수천 개 만들거나, 별도 threadpool로 던지거나, epoll+nonblock(disk엔 적용 안 됨)을 흉내내야 한다.

Linux는 두 가지 kernel async I/O를 제공.

libaio (kernel AIO) — 2003년경 도입. O_DIRECT만 지원, 일부 fs에서 fallback to blocking.
io_uring — 2019년 5.1+. unified sqe/cqe ring, O_DIRECT 불필요, regular file 지원, network/disk 모두.

folly::AsyncIO는 두 backend를 같은 인터페이스로 노출한다.

1
folly::IoUringBackend backend(folly::IoUringBackend::Options{}.setCapacity(4096));
2

3
folly::AsyncIO::Op op;
4
op.pread(fd, buffer, length, offset);
5
op.setNotificationCallback([](folly::AsyncIO::Op* o) {
6
  std::cout << "done, bytes: " << o->result() << "\n";
7
});
8
backend.submit(&op);
9

10
backend.pollCompleted();   // 또는 EventBase에서 자동

#API

1
#include <folly/experimental/io/AsyncIO.h>
2

3
class AsyncIO {
4
 public:
5
  struct Op {
6
    void pread(int fd, void* buf, size_t count, off_t offset);
7
    void pwrite(int fd, const void* buf, size_t count, off_t offset);
8
    void preadv(int fd, const iovec* iov, int iovcnt, off_t offset);
9
    void pwritev(int fd, const iovec* iov, int iovcnt, off_t offset);
10
    void fsync(int fd);
11
    void fdatasync(int fd);
12
    ssize_t result() const;   // 완료 후 값
13
  };
14

15
  void submit(Op* op);
16
  void pollCompleted();
17
  Range<Op**> wait(size_t minRequests);
18
};

Op가 한 I/O 요청. submit 후 pollCompleted 또는 wait로 결과 수확.

#Coroutine 통합

1
folly::coro::Task<size_t> ReadAsync(folly::IoUringBackend& backend,
2
                                    int fd, void* buf, size_t len, off_t off) {
3
  folly::AsyncIO::Op op;
4
  op.pread(fd, buf, len, off);
5

6
  folly::coro::Baton done;
7
  op.setNotificationCallback([&](auto*) { done.post(); });
8

9
  backend.submit(&op);
10
  co_await done;
11

12
  if (op.result() < 0) throw std::system_error(-op.result(), std::system_category());
13
  co_return op.result();
14
}

Baton으로 코루틴이 I/O 완료를 await. folly::coro::IoUringExecutor 같은 wrapper가 이 패턴을 자동화.

#내부 — io_uring 동작

io_uring은 링 두 쌍으로 동작한다. SQE(Submission Queue Entry) ring은 user 영역이 채우고 kernel이 poll하며, CQE(Completion Queue Entry) ring은 kernel이 채우고 user가 poll한다.

submit 경로는 다음과 같다.

SQE에 op 정보를 채운다.
io_uring_enter syscall을 호출한다 (SQPOLL mode면 kernel이 자동으로 poll).
kernel이 SQE를 처리하고, 완료되면 CQE에 결과를 기록한다.

poll 경로는 다음과 같다.

user가 CQE ring을 poll한다.
각 CQE의 user_data로 Op*를 복원한다.
callback을 호출한다.

ring 한 쌍이 batch 제출과 batch 수확을 가능하게 한다. syscall 한 번에 수십 op 처리. context switch 비용이 결정적으로 줄어든다.

1
// folly/experimental/io/IoUring.cpp 약식
2
void IoUringBackend::submit(Op* op) {
3
  io_uring_sqe* sqe = io_uring_get_sqe(&ring_);
4
  if (!sqe) {
5
    io_uring_submit(&ring_);   // ring 가득 → flush
6
    sqe = io_uring_get_sqe(&ring_);
7
  }
8
  setupSqe(sqe, op);   // pread / pwrite / fsync 등
9
  io_uring_sqe_set_data(sqe, op);
10
  pending_.insert(op);
11
}
12

13
void IoUringBackend::pollCompleted() {
14
  io_uring_cqe* cqe;
15
  while (io_uring_peek_cqe(&ring_, &cqe) == 0) {
16
    auto* op = static_cast<Op*>(io_uring_cqe_get_data(cqe));
17
    op->result_ = cqe->res;
18
    io_uring_cqe_seen(&ring_, cqe);
19
    op->complete();   // callback
20
  }
21
}

#libaio fallback

io_uring이 없는 (5.1 미만) kernel에서는 libaio.

1
// folly/experimental/io/Aio.cpp 약식
2
class AioBackend {
3
  void submit(Op* op) {
4
    io_event ev;
5
    iocb* cb = &op->cb_;
6
    io_prep_pread(cb, op->fd_, op->buf_, op->len_, op->offset_);
7
    io_submit(ctx_, 1, &cb);
8
  }
9

10
  void pollCompleted() {
11
    io_event events[64];
12
    int n = io_getevents(ctx_, 0, 64, events, nullptr);
13
    for (int i = 0; i < n; ++i) {
14
      auto* op = static_cast<Op*>(events[i].data);
15
      op->result_ = events[i].res;
16
      op->complete();
17
    }
18
  }
19
};

libaio는 O_DIRECT 강제, regular fs에서 fallback to blocking이 있어 모든 I/O가 진짜 async 아닐 수 있음. io_uring이 압도적 우위.

#사용 패턴 — high-throughput read

1
folly::IoUringBackend backend(folly::IoUringBackend::Options{}
2
  .setCapacity(8192));
3

4
std::vector<folly::AsyncIO::Op> ops(1000);
5
std::vector<std::vector<char>> bufs(1000, std::vector<char>(4096));
6

7
for (size_t i = 0; i < 1000; ++i) {
8
  ops[i].pread(fd, bufs[i].data(), 4096, i * 4096);
9
  backend.submit(&ops[i]);
10
}
11

12
size_t completed = 0;
13
while (completed < 1000) {
14
  auto done = backend.wait(/*min=*/1);
15
  for (auto* op : done) {
16
    ++completed;
17
    // process result
18
  }
19
}

1000개 4KB read를 한 번에 제출. io_uring이라면 4-5 syscall로 완료. thread-per-IO 모델은 1000 thread 필요.

#std와의 비교

항목	표준 (없음)	folly::AsyncIO	std::async	Boost.Asio
disk async	N/A	io_uring/libaio	thread per call	같음 (asio도 io_uring backend 추가)
network async	N/A	folly::AsyncSocket	N/A	yes
throughput	N/A	매우 높음 (kernel polling)	낮음	높음
coroutine	N/A	folly::coro	N/A	asio::awaitable

std::async는 disk I/O 해법이 아니다. thread를 spawn해 blocking read하는 정도. folly::AsyncIO는 진짜 kernel async.

io_uring backend는 Boost.Asio도 추가했다 — 같은 kernel feature를 다른 wrapper가 채택.

#코드 리뷰 포인트

io_uring 사용 여부가 kernel version에 좌우 → runtime check 후 fallback.
ring capacity가 부족하면 submit이 spin/block. capacity tuning.
buffer가 op 수명보다 짧으면 UAF — buffer 보장.
syscall mode (io_uring_enter 직접 vs SQPOLL) — SQPOLL은 kernel thread를 점유. high-throughput 환경에서만.
coroutine wrap이 없으면 callback boilerplate. folly::coro::IoUringExecutor 또는 직접 Baton wrap.

#자주 보는 안티패턴

1
// 1. op buffer가 stack에 있는데 callback이 늦게
2
{
3
  folly::AsyncIO::Op op;
4
  char buf[4096];
5
  op.pread(fd, buf, 4096, 0);
6
  backend.submit(&op);
7
}   // op과 buf 모두 destroy — kernel은 아직 작업 중
8
// → heap에 두거나 callback이 완료될 때까지 살아있어야
9

10
// 2. fsync를 매 write마다
11
for (auto& blk : blocks) {
12
  op.pwrite(fd, blk.data(), blk.size(), off);
13
  backend.submit(&op);
14
  op.fsync(fd);   // 매 write마다 fsync — throughput 박살
15
}
16
// → batch 후 한 번 fsync
17

18
// 3. O_DIRECT 없는 fd에 libaio
19
fd = open(path, O_RDONLY);   // O_DIRECT 아님
20
AioBackend backend;
21
// → libaio가 blocking으로 fallback. io_uring 사용 또는 O_DIRECT.
22

23
// 4. pollCompleted를 한 thread에서, submit을 다른 thread에서
24
// → io_uring ring은 multi-threaded SQ submit 위험. SQ lock 또는 single submitter.