Design Principles and Practical Implementation of Network Coroutines in iQIYI's libfiber

The article uses iQIYI's open‑source network coroutine library libfiber as an example to illustrate the design principles, programming practices, and performance optimizations of network coroutines.

1. Overview Early server applications used a multi‑process model, then moved to multi‑threading to reduce resource consumption, but both suffered from blocking I/O. Non‑blocking network programming (e.g., Nginx, Netty) improves concurrency but increases development complexity.

2. Network Coroutine Basics Network coroutines transform blocking I/O into non‑blocking I/O at the kernel level while preserving a sequential programming style. The article first reviews non‑blocking network programming (select/poll/epoll/kqueue, event registration, callbacks, data buffering) and then introduces coroutine concepts, including the smallest scheduling unit, context switching, and the distinction between network concurrency and CPU concurrency.

2.1 Non‑blocking Network Programming Typical design involves registering socket events with an event engine, receiving ready events, and invoking callbacks. The article lists the steps and shows diagrams of asynchronous read/write flows.

2.2 Network Coroutine Programming Coroutines simplify high‑concurrency network code by allowing developers to write sequential logic while the library handles underlying non‑blocking operations. The article discusses the historical background of coroutines and highlights Russ Cox’s libtask as an early example.

2.3 Coroutine Scheduling libfiber adopts a single‑threaded scheduler to avoid the overhead of multi‑thread synchronization and to keep CPU cache affinity. It explains why multi‑threaded scheduling would introduce cache invalidation and lock contention, and how single‑threaded scheduling can still exploit multi‑core CPUs by running multiple processes or threads, each with its own scheduler.

2.4 Event‑Engine Design libfiber supports Linux (epoll), BSD/macOS (kqueue), and Windows (iocp, message loop). It describes how the event engine is abstracted and how Windows UI message loops can be used for network coroutines.

2.5 Synchronization Mechanisms The library provides coroutine mutexes, event‑based locks, condition variables, and semaphores. It details the lock acquisition flow, lock waiting queues, and how event‑based locks avoid deadlocks in multi‑threaded scenarios. Condition variables enable producer‑consumer patterns, and semaphores protect backend resources from overload.

2.6 DNS Integration libfiber integrates a third‑party DNS resolver to make hostname resolution coroutine‑friendly, avoiding the thread‑pool approach used by many other libraries.

2.7 System API Hooking To coroutine‑ify existing blocking libraries, libfiber hooks a wide range of I/O‑related system calls (read, write, send, recv, socket, accept, connect, select, poll, epoll, etc.) and DNS functions, allowing MySQL, HTTP, and Redis clients to operate in a coroutine context without source‑level changes.

3. Real‑World Practices at iQIYI The article presents two case studies:

CDN core module “Qixun” uses libfiber for high‑concurrency client handling, request merging, breakpoint resume, and bandwidth reduction, achieving < 2% video stutter and < 1% CDN back‑origin bandwidth.

High‑Performance DNS (HPDNS) leverages libfiber for the TCP path, achieving >2 million queries per second on a single machine and sub‑minute propagation of DNS updates.

Both systems benefit from libfiber’s lightweight coroutine model, single‑threaded scheduler, and efficient event handling.

4. Conclusion The article summarizes the design rationale of libfiber, its core components, and the lessons learned from deploying network coroutines in large‑scale production services, providing readers with a comprehensive understanding of both theory and practice.