v0.2.1Linux 6.0+Rust 1.80+MIT OR Apache-2.0
giong is a thread-per-core async runtime for Rust on Linux, built directly on io_uring. Every read, write, accept and close that one turn of the event loop produces enters the kernel in a single io_uring_enter.
cargo add giong/json at 50 connections: 0.03 system calls per request for giong, 2.05 for raw Tokio. bench/syscalls.shNamed after Thánh Gióng, the child of Vietnamese legend who lay silent for three years and then rose a giant. giong costs next to nothing while idle and uses every core the moment load arrives.
unsafe blockio-uring, libc, socket2why
giong commits to io_uring and to one thread per core, and to nothing else. These are the six things that buys.
io_uring_enter · DEFER_TASKRUN · SINGLE_ISSUER
Every read, write, accept, close and cancellation a turn of the loop produces enters the kernel together, and every ready completion comes back in the same call. A request costs about 0.03 system calls; an epoll-based server needs 2.
multishot accept · multishot recv · provided buffers
One submission lasts the life of a listener or connection. The kernel picks a buffer only when data arrives, so it is still warm in cache. At 5,000 connections giong spends the least CPU per request of the runtimes measured.
tests/cancel.rs
Drop an I/O future mid-flight and its buffer moves to the driver until the kernel confirms the cancel. A timeout around recv, recv_from or accept loses no data, datagram or connection.
Builder::spin_before_park
Let a worker watch its ring for a while before it sleeps. On a single connection that is 19 µs median instead of 28 and 48% more requests. It costs CPU, so it is off by default.
giong::fs
Open, read, write, fsync, statx, rename and remove are entries in the worker's ring, next to the network. No pool of blocking threads. A file has no cursor: every read and write names its offset.
!Send · Rc · RefCell
One thread per core, and a task never changes thread. Futures need not be Send; Rc and RefCell just work. No locks on the hot path.
numbers
One core per server, loopback, medians of five interleaved rounds on a 4-vCPU virtual machine. giong is not faster than everything at everything. The charts say where the design pays off and where it does not.
/json, 50 connections · lower is better
The structural difference, and the most robust result here. On the small response it buys little, because a request costs about 4 µs of kernel time whichever way it is delivered. On 8 KB responses, where a whole batch leaves in one call, it is worth almost half the CPU: 16.0 µs per request against 27.9 for raw Tokio.
/json, microseconds · lower is better
With one connection every request finds a sleeping server. spin_before_park(200 µs) keeps the worker watching its ring: 47.9k requests/s instead of 32.4k. It costs CPU, 20.5 instead of 13.6 µs per request, and the worker keeps its core busy between requests. Without it giong is the same as the others.
/json, microseconds of user plus kernel time · lower is better
giong is 11% below hand-written epoll and 16% below tuned Monoio, with the lowest p99 (26 ms; epoll 32, Monoio 44, raw Tokio 54). The likely reason is the provided buffer ring: receive buffers are reused while still warm in cache. At 50 and 1,000 connections giong, tuned Monoio and epoll are level.
requests per second, TLS 1.3, the same rustls on both sides, thin line from lowest to highest round · higher is better
TLS costs giong 4% on /json and 14% on 8 KB responses. Handshakes are level: a handshake is almost all cryptography, and both sides use the same library for it. Most of the /users factor is there without TLS.
4 KiB at a random offset, one task, operations per second, thin line from lowest to highest round · higher is better
5.5 times Tokio, where every read is a hand-off to another thread and back; on giong it is one entry in a batch. A blocking std call is 28% faster for cached data. What giong buys is a worker that never waits when the data is not cached, which this benchmark does not measure.
/json, requests per second, thin line from lowest to highest round
giong, tuned Monoio, raw Tokio and epoll are within noise: the kernel's TCP stack, not the runtime, is most of the cost, and wrk is the limit. giong-http reads higher and we do not know why. It costs 7% more CPU per request, as checking every header should, and keeps its core busier. Treat that row as a measurement of the setup.
/compute is the same for everyone, as it should be: the time goes into the function, not the runtime.wrk threads are as likely to be the limit as the server.DEFER_TASKRUN passed in. Its default ring is about 20% slower on the small response; comparing against that would flatter giong.Full tables, method and raw output: README · bench/results/
compare
The other io_uring runtimes for Rust, as they stood when the benchmarks ran. Monoio and Glommio are mature projects with wider ecosystems; this table is about how each one is built, not a ranking.
| giong 0.2 | Monoio 0.2.4 | Glommio 0.9.0 | |
|---|---|---|---|
| Platforms | Linux ≥ 6.0 | Linux ≥ 5.6, with an epoll/kqueue fallback (runs on macOS) | Linux ≥ 5.8, needs a raised memlock limit |
| Receiving | multishot, kernel-provided buffers | one submission per read, caller's buffer | direct recv, io_uring to wait |
| Accepting | multishot | one submission per accept | one submission per accept |
| Buffer API | ownership passing | ownership passing | borrowed (AsyncRead / AsyncWrite) |
| Timeout around a read | loses no data | needs the separate cancelable_* API | — |
| Ring defaults | DEFER_TASKRUN on | no flags; pass your own builder | — |
| Busy-poll option | yes | no | yes |
| Multi-core | built-in builder with graceful draining and signals | #[monoio::main(threads = N)] | executor pools placed by CPU topology |
| Scheduling | FIFO | FIFO | weighted queues with latency classes |
| I/O | TCP, UDP, Unix sockets, files | TCP, UDP, Unix sockets, files | TCP, UDP, Unix sockets, Direct I/O files |
| Ecosystem | its own HTTP/1.1 server and server-side TLS; nothing else | TLS, HTTP, codecs, Tokio compatibility layer | channels, semaphores, rate control |
| Size | ~5,400 lines, plus ~2,250 for HTTP and TLS | ~25,000 lines | ~40,500 lines |
code
Every worker binds its own SO_REUSEPORT listener on the same port and the kernel spreads connections across cores. Buffers go to the kernel by value and come back with the result.
HTTP on every core · giong-http
use std::time::Duration;
use giong::net::TcpListener;
use giong_http::{Request, Response, Server};
async fn handler(req: Request) -> Response {
match (req.method(), req.path()) {
("GET", "/health") => Response::text("ok"),
("POST", "/echo") => Response::new(200).body(req.body().to_vec()),
_ => Response::new(404),
}
}
fn main() -> std::io::Result<()> {
giong::Builder::new()
.shutdown_on_signals(true) // Ctrl-C / SIGTERM stop it gracefully
.shutdown_grace(Duration::from_secs(10)) // requests in progress are answered
.build()?
.run(|_worker| async {
// Every worker binds its own SO_REUSEPORT listener on the same port;
// the kernel spreads connections across cores.
let listener = TcpListener::bind("0.0.0.0:8080").expect("bind");
Server::new().serve(listener, handler).await;
})
}One listener per worker; requests in progress are answered before a worker stops.
HTTPS · giong-http + giong-tls
let acceptor = giong_tls::TlsAcceptor::from_pem(
&std::fs::read("cert.pem")?,
&std::fs::read("key.pem")?,
)?;
// ... in each worker:
let listener = TcpListener::bind("0.0.0.0:8443").expect("bind");
Server::new().serve_tls(listener, acceptor.clone(), handler).await;Turn on the tls feature of giong-http. Handlers, limits, timeouts and graceful shutdown are the same as for plain HTTP.
The bare runtime · giong
use giong::net::TcpListener;
fn main() -> std::io::Result<()> {
giong::Builder::new()
.shutdown_on_signals(true)
.build()?
.run(|_worker| async {
let listener = TcpListener::bind("0.0.0.0:8080").expect("bind");
while let Some(Ok(stream)) = giong::until_shutdown(listener.accept()).await {
giong::spawn(async move {
loop {
let Ok(data) = stream.recv().await else { return };
if data.is_empty() { return } // peer closed
let reply = data.to_vec();
drop(data); // buffer back to the pool
if stream.write_all(reply).await.0.is_err() { return }
}
});
}
})
}recv() lends a buffer from the worker's pool. An empty buffer means the peer closed the connection.
UDP and files · giong::net · giong::fs
use giong::{fs, fs::File, net::UdpSocket};
async fn demo() -> std::io::Result<()> {
let socket = UdpSocket::bind("127.0.0.1:9000")?;
let (datagram, peer) = socket.recv_from().await?; // multishot, cancel safe
let reply = datagram.to_vec();
drop(datagram); // buffer back to the pool
socket.send_to(reply, peer).await.0?;
let file = File::create("log.txt").await?;
file.write_all_at(b"hello\n".to_vec(), 0).await.0?;
file.sync_all().await?;
let text = fs::read("log.txt").await?;
assert_eq!(text, b"hello\n");
fs::rename("log.txt", "log.old").await
}Receiving borrows a buffer from the pool; whatever you hand to the kernel goes in by value and comes back with the result.
design
A worker is a thread pinned to one core, with its own tasks, run queue, timer wheel, receive buffers and ring. Other threads reach it only through an injector and an eventfd.
↺ repeat
eventfd + injector, only when another thread wakes a task
Send + Sync although tasks are not, without unsafe.write_all(buf) returns (result, buf). The kernel keeps a pointer to the buffer until it is done, and this API makes that sound in Rust.JoinHandle. One bad connection does not take down the worker.recvmsg on the same buffer pool as TCP. Every worker binds its own SO_REUSEPORT socket and recv_from is cancel safe.DEFER_TASKRUN (6.1+), COOP_TASKRUN (6.0), no flags. The fallbacks are tested on every change by forcing them.crates
The runtime, and the layers a service needs on top of it. Together they serve HTTPS at 144.8k requests/s on one core, against 81.0k for Axum on the same rustls.
The runtime: TCP, UDP, Unix sockets, files, timers, a cross-thread channel and graceful shutdown.
Builder::new().workers(n), one worker per coreTcpListener, TcpStream, UdpSocket, UnixListener, UnixStreamfs::File with read_at and write_at, fs::read, rename, remove_filetime::sleep, timeout, spawn, Handle::spawn_on, sync::mpscabout 5,400 lines · 115 tests
A small, strict HTTP/1.1 server with one async handler.
Content-Length or chunked400 to any request a proxy in front could read differentlyServer::serve, serve_unix, serve_tlsabout 1,850 lines · 46 tests, among them 500,000 random inputs for the parser
Server-side TLS 1.2 and 1.3 on rustls with ring. No OpenSSL.
TlsAcceptor::from_pem(cert, key), or bring your own rustls::ServerConfigrecv() is cancel safeabout 390 lines · 8 tests · TLS costs 4% on /json
A PostgreSQL client and pool. The statements of every task pipeline over a few connections.
Client::connect, query, execute, transaction, cancel_tokenPool per worker: shared, pipelined statements; get() for a transactionabout 5,300 lines · 73 tests · 2.6× deadpool's statements per core
verified
A runtime that hands buffers to the kernel has to earn trust. This is the evidence so far, and the gaps in it.
tests/cancel.rs.giong-tls has had no independent security audit. The cryptography and the protocol are rustls's; giong's part is connecting rustls to the socket.limits
0.2 is complete enough to write real servers. It is also young, narrow on purpose, and Linux only.
Kernel 6.0 or newer. There is no epoll, kqueue or IOCP fallback, and there will not be one.
Crates that need the Tokio runtime (hyper, sqlx, reqwest) do not run on giong. Crates that only use std::future do.
giong-http speaks HTTP/1.1 and receives a body in full before it calls the handler. A body over the limit is refused, not streamed.
No TLS client, no kTLS, no certificate reload built in.
An overloaded core is not helped by an idle one. Spread work yourself with spawn_on or a channel.
bind and connect resolve names with a blocking call. Also missing: Unix datagram sockets, multicast, reading directories.
Monoio is the mature choice and runs in production at ByteDance. If you need an HTTP client, HTTP/2 or Tokio-compatible crates today, use it.
Glommio is built for storage engines: Direct I/O and priority scheduling are its strengths.
Tokio is the general-purpose runtime. giong is not trying to replace it for every workload.
roadmap
Milestones in order, with no dates: a milestone is done when its exit criteria are met. 0.3 is about measuring, not features.
0.1done
0.2current
giong-http and giong-tls, HTTPS in giong-http0.3next
loom model check of the cross-thread wake-up; cargo fuzz of the parsergiong-tlsDone when: published multi-core results with their method, and no open memory- or thread-safety finding
0.4next
connect by name, the RFC 8305 wayspawn_on; writevAGENTS.md and llms.txtDone when: every item with tests, including cancellation tests
cratesplanned
giong-postgres: SCRAM, TLS, pipelining, a pool per coregiong-http; giong-redis with automatic pipelininggiong-web: router, middleware, JSON, compression; streaming bodiesgiong-mcp: a read-only MCP server for coding agentsDone when: each one passing against the real service in CI and benchmarked against its Tokio counterpart
0.5planned
Done when: the whole suite passing on both drivers, and the difference measured
0.6planned
giong-http, over TLS with ALPNfutures-io / Tokio I/O traitsDone when: real browsers served over HTTP/2, and h2spec passing
0.7planned
SQPOLL and NAPI busy polling; kTLSDone when: a documented, reproducible gain for every option that is merged
1.0planned
cargo-semver-checks in CI; every public item documentedSend futures as a requirement: the API stays usable with Rc and RefCell.Source: ROADMAP.md
get started
Two commands and a handler. The crates are on crates.io.
--security-opt seccomp=unconfined.cargo add giong
cargo add giong-httpgiong-http is optional. For HTTPS, add it with --features tls.
Paste the HTTP example from What the code looks like into src/main.rs, then:
cargo run --release # listens on port 8080
curl localhost:8080/health # okgit clone https://github.com/giong-run/Giong.git && cd Giong
cargo test --workspace --all-features # the whole suite, every crateEach one runs from a clone of the repository. examples/
A TCP echo server on every core.
cargo run --release --example echo
nc 127.0.0.1 7000A small HTTP/1.1 server: keep-alive, pipelining, idle timeouts, a header size limit and graceful shutdown on SIGINT and SIGTERM. The same routes the benchmarks use.
cargo run --release --example http
curl localhost:3006/jsonA UDP echo server, receiving with multishot recvmsg.
cargo run --release --example udp_echo
echo hello | nc -u -w1 127.0.0.1 7001Prints files to standard output, reading them through io_uring with positional reads.
cargo run --release --example cat -- Cargo.tomldocs & community
giong is open source and developed in the open on GitHub. Open an issue before starting on anything larger than a small fix.
unsafe and cancellationIssuesBugs and proposals. For a bug, include uname -r, the Rust version and a small programSecurityReport a vulnerability privatelyfaq
Short answers. The README has the long ones.
Not yet. 0.2 is complete enough to write real servers and is tested hard (see what has been checked), but it has not run in production. 1.0 waits for, among other things, at least one production user reporting back.
No. io_uring is a Linux interface and there is no fallback. On Windows use WSL2 with a 6.x kernel (uname -r; wsl --update if it is older); on macOS a Linux virtual machine. In Docker, start the container with --security-opt seccomp=unconfined: the default profile blocks io_uring.
6.0 or newer, 6.1 or newer recommended. giong tries three ring setups in order: DEFER_TASKRUN (6.1+), COOP_TASKRUN (6.0), then no flags.
Not crates that need the Tokio runtime. Crates that only use std::future work. Adapters for the futures-io and Tokio I/O traits are planned for 0.6.
Sometimes, and the page says where. Small responses at 50 connections are a tie. giong makes about 0.03 system calls per request against 2.05, spends the least CPU per request at 5,000 connections, and reads files 5.5 times faster than Tokio on one core. On 14 cores it had the most requests per second at 1, 2 and 8 workers and was level with or behind tuned Monoio at 4 and 6. Every number is over loopback on one machine.
Privately, through GitHub's vulnerability reporting, not in a public issue.
After Thánh Gióng, the child of Vietnamese legend who lay silent for three years and then rose a giant: next to nothing while idle, every core the moment load arrives.