PhotonLibOS gives C++ servers a coroutine layer over epoll, io_uring and kqueue

A storage team library that became a general C++ concurrency runtime

Photon is described as a C++ library that augments the operating system for high performance concurrent I/O programming. The provenance matters for judging it. The code was collected from the internal code base of the Alibaba Cloud Storage team, where it is described as tested and used in production and as the code the team depends on daily. That origin explains the shape of the project: it is a runtime with file system, network, RPC and storage components rather than a narrow utility.

The intended users are people building I/O intensive applications, particularly ones involving disk or network I/O. The README lists adoption in a set of production systems at Alibaba Group, Ant Group, ByteDance, Xiaomi and XSKY, and points at public projects built on it: overlaybd, a sub project of containerd that is deployed at scale in Alibaba's own infrastructure; OSSFSv2, a POSIX style client for Alibaba Cloud object storage; a connector for AI and ML frameworks such as PyTorch, safetensors and vllm, used for dataset reading, checkpointing and model loading; and a P2P transport component for large scale data serving.

The project description on the repository is blunt about the ambition, calling it probably the fastest coroutine library in the world. The performance claim that the README actually makes is narrower: switching to a thread takes a few nanoseconds, which corresponds to a callback in a typical asynchronous framework, and creating a thread is mainly a simple malloc that can be pooled.

One scheduling layer over epoll, io_uring, kqueue and DPDK

The core mechanism is a user space threading model implemented as coroutines with multi core CPU support. The scheduling work is driven by a set of asynchronous event engines, epoll, io_uring and kqueue among them, and the point of the design is that these engines are hidden behind a single lightweight unified interface. From the program, a coroutine reads or writes a file or a socket and yields when the kernel says it would block; the library then decides which underlying engine is actually doing the waiting.

On top of that foundation, Photon provides higher level abstractions for networking and file I/O, drawing on both ordinary kernel system calls and user space frameworks such as DPDK and SPDK. Since version 0.6, Photon can run with a userspace TCP/IP stack on top of DPDK, which is a different proposition from using the kernel stack: the network path stops passing through the kernel's TCP implementation altogether.

Above the I/O layer sit the distributed system pieces. The README describes new implementations of RPC, an HTTP client and server, and a Redis client, rather than wrapping existing third party ones. The RPC work has a paper, zBuffer zero copy and metadata free serialization for fast RPC with scatter gather, published at PPoPP'26, with the full text in the ACM Digital Library. Repository layout backs this up: separate top level directories for fs, io, net, rpc, thread and common, plus ecosystem, examples, tools, test, doc and third_party.

photon_std is the shortest path in for an existing threaded codebase

Most C++ code in the world is written with threads, so Photon made a deliberate accommodation for that. Starting with version 0.3, a photon_std namespace was added, and the documented workflow is to search a project for std::thread and std::mutex and replace them with the photon_std equivalents. The library presents coroutine friendly versions of the same primitives, so a threaded program can be converted without rewriting its control flow.

There is a companion feature for state that used to live in thread local storage. Version 0.4 added support for coroutine local variables, described in the documentation as similar to the C++11 thread_local keyword, which is what you need once a single OS thread carries many interleaved coroutines and a plain thread local would leak across them.

The clearest demonstration of the intended migration path comes from outside the project. The README links a write up on how RocksDB was transformed from multiple threads to coroutines with only 200 lines of code, which is a small number because the primitives line up one for one. The same version 0.4 release added macOS support on both Intel x86_64 and Apple M1, and added support for the LLVM Clang, Apple Clang and GCC compilers, so the porting surface is no longer Linux only.

Building with CMake and reading the examples tree for the shape of the API

The README does not publish a package manager recipe or a build command line, so the build is a source build through CMake. The repository carries a root CMakeLists.txt, a CMake directory with the toolchain support files, and a third_party directory for vendored dependencies. Continuous integration is set up as separate workflows for Linux x86_64, Linux ARM, macOS x86_64 and macOS ARM, so all four combinations are built on every change.

The fastest way to understand the API is the examples directory, which is organised by topic rather than by feature: c++20coro for the standard library coroutine integration, fstack-dpdk and spdk for the user space network paths, rpc, simple, integration, sync-primitive, perf and vdma-transfer. Each examples folder has its own CMakeLists.txt, so the example programs are the buildable, readable entry points.

The documentation is also split by audience, with the main site at photonlibos.github.io hosting the guides, the performance notes for I/O workloads, and a blog post titled Stackful Coroutine Made Fast that explains the theory behind the coroutine implementation. A Chinese version of the documentation is also published on the site. The repository adds an AGENTS.md file and a tools directory, and the API reference for the library lives in the include directory with the main entry points at photon.h and photon.cpp.

The RPC and storage projects built on Photon are the real argument for it

Judging a coroutine library by its own microbenchmarks is a poor way to decide, so the more useful comparison is with what people built on top of it. The OSSFSv2 client for Alibaba Cloud object storage exposes a POSIX compliant file system interface to users, and the AI and ML connector acts as a storage driver for popular AI frameworks, handling dataset reading, checkpointing and model loading. The P2P transport component exists to address the scalability of large scale data serving, which is the same bottleneck seen in container image services and AI model loading. Caching products such as the OSS Accelerator, a multi tenant distributed cache, and EFC cache are also listed.

The interesting technical point in these is where the I/O actually terminates. Photon does not only wrap kernel system calls; with DPDK and SPDK in the mix, a request can be serviced by a user space network stack, and the RPC layer is designed around zero copy and metadata free serialization, so payloads move without a serialise and copy round trip.

The alternative to this whole approach is not another library so much as a different program shape: one OS thread per connection with blocking sockets, or a callback driven reactor where every completion returns to an event loop. Photon's stated advantage over the callback model is the cost of the handoff, since a coroutine switch takes a few nanoseconds where a callback is the equivalent event. The cost of that advantage is a very large API surface and a runtime that owns the execution model of your program, which is a harder trade than swapping a socket library.

A 0.9 version number and a stated release branch policy

The project is under an Apache 2.0 licence, with the licence text in the LICENSE file at the repository root, which is the permissive grant most commercial teams expect and removes the copyleft question entirely for a library linked into a service.

Version numbers are the thing to watch. The README records version 0.9 as released in April 2025, version 0.8 in August 2024, and version 0.3 on 2 September 2022, with the first tag made on 27 July 2022. The most recent tags are v0.9.6 on 2026-08-21, v0.9.4 on 2026-05-14 and v0.9.3 on 2026-01-04. A library below 1.0 signals that interfaces may still move, and you should expect to absorb those changes rather than treat the version as a stable contract.

Release discipline is spelled out. Since 0.7, Photon uses release branches to improve delivery reliability, and the stated order is that a bug fix is merged into a stable release first, then into higher release versions, and finally into main. That policy gives you an upgrade path that does not force you onto the newest tag.

The project is not archived, and the last push was on 2026-10-19, weeks after the v0.9.6 tag, so work continues on the main branch. A separate pre-1.0 number, a large surface area, and an active commit stream are the three facts to weigh when you decide how much of your I/O layer you want to hand to it.

Editorial conclusion

Photon fits teams writing storage services, proxies or file system clients in C++ where thread or callback overhead matters and the team is willing to own a pre-1.0 dependency. It is the wrong choice for a team that wants a small, stable, portable networking library, because the API surface is large and the latest tag is v0.9.6. Before adopting, check the event engine your target kernel provides, since io_uring support and the DPDK based userspace TCP/IP path are separate features rather than defaults.

Frequently asked questions

Official sources

1. alibaba/PhotonLibOS on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases