How libco Powers WeChat’s Backend with Million‑Scale Coroutines

As Tony said, “WeChat will become the foundation of the digital society; building a good and cool product is no longer enough for the WeChat team.”

The WeChat technical team aims to share its technology spirit and accumulation. Initiatives such as WeMobileDev and tinker (which gained 5,000+ stars in a month) exemplify this effort, and more open‑source projects like the cross‑platform component mars will be released.

Beyond the client, WeChat’s backend has open‑sourced many projects, including phxsql, phxpaxos, and the library discussed here, libco. More projects are under review, and additional repositories can be found at https://github.com/tencent.

libco is a C/C++ coroutine library heavily used in WeChat’s backend, running stably on tens of thousands of machines since 2013. It was first open‑sourced in 2013 as one of Tencent’s six major open‑source projects and has recently received a major update on https://github.com/tencent/libco. libco supports agile synchronous‑style programming while providing high concurrency.

Features Supported by libco

No intrusion into business logic; transform multi‑process or multi‑thread services into coroutine services, achieving hundred‑fold concurrency gains.

Supports CGI framework for easy web service construction (New).

Supports common third‑party libraries such as gethostbyname, mysqlclient, ssl (New).

Optional shared‑stack mode enables millions of connections on a single machine (New).

Complete and concise coroutine programming interface.

Pthread‑like interface using co_create , co_resume , etc.

Coroutine‑private variables and semaphore co_signal (New).

Non‑language‑level lambda implementation for in‑place asynchronous tasks (New).

Lightweight network framework based on epoll/kqueue and high‑performance timer wheel.

Background of libco

Early WeChat backend modules used a hybrid semi‑synchronous, semi‑asynchronous model due to complex business demands and rapid product iteration. The access layer was asynchronous, while business logic ran in synchronous multi‑process or multi‑thread models, limiting concurrency to dozens or hundreds. As business grew, system scale expanded, making modules vulnerable to backend service or network jitter.

Choosing Asynchronous Refactoring

Converting all services to an asynchronous model would require massive engineering effort and pose high risk. Therefore, the team considered using coroutines.

Challenges: 1) Lack of large‑scale C/C++ coroutine experience in the industry; 2) Controlling coroutine scheduling; 3) Handling synchronous‑style API calls such as Socket and mysqlclient; 4) Managing existing global and thread‑local variables.

Using libco, the team solved all these problems, achieving non‑intrusive asynchronous refactoring. Hundreds of modules were converted with minimal changes to business logic, dramatically improving concurrency and making libco a cornerstone of the backend framework.

libco Framework

The framework consists of three layers: the interface layer, the system‑function Hook layer, and the event‑driven layer.

Handling Synchronous‑Style APIs

Synchronous network calls (e.g., connect, write, read) block the thread while waiting for I/O, reducing concurrency. Although synchronous programming offers clear logic and rapid iteration, libco hooks these calls, converting them into asynchronous events. When a coroutine encounters a synchronous network request, libco registers the request as an asynchronous event, yields the coroutine, and resumes it when the event completes or times out.

Most synchronous APIs are intercepted via Hook, allowing libco to schedule coroutine resumption at appropriate moments.

Million‑Scale Coroutine Support

Each coroutine normally owns a private stack, which can limit scalability. libco provides a stackless shared‑stack mode where multiple coroutines share a single stack, copying stack contents only during context switches. This reduces memory copying and enables massive concurrency.

Using the shared‑stack mode, libco created ten million coroutines on a single machine (E5‑2670 v3 @ 2.30GHz ×2, 128 GB RAM), consuming about 66 GB of memory and achieving over 2.1 million QPS.

Coroutine Private Variables

In multi‑process to multi‑thread migrations, thread‑local variables are used. libco introduces coroutine‑private variables (ROUTINE_VAR) to simplify refactoring. These variables act as thread‑local in non‑coroutine environments and as coroutine‑local when running under libco, automatically handling environment detection.

A simple one‑line declaration suffices to define a coroutine‑private variable.

Hook Method for gethostbyname

When a coroutine calls the synchronous DNS function gethostbyname, it blocks the thread, delaying other coroutines. libco examined glibc’s source and found that the internal __poll method prevents the Hook from working. By Hooking __poll and introducing coroutine‑private variables, libco makes gethostbyname asynchronous without modifying glibc.

Other asynchronous solutions require third‑party libraries and callback mechanisms, but libco achieves this solely via Hook.

Coroutine Semaphore

In multi‑threaded code, pthread_signal is used for synchronization. libco provides a coroutine semaphore co_signal and related primitives ( co_cond_signal, co_cond_broadcast) to coordinate coroutine execution.

Conclusion

libco is an efficient C/C++ coroutine library offering a complete programming interface, Socket‑family Hook, and seamless integration of synchronous code into high‑concurrency asynchronous execution, making it a pivotal component of WeChat’s backend architecture.