io-uring

Name: io-uring
Author: mohitmishra786

62installs19forks

How to install io-uring?

mohitmishra786/low-level-dev-skills/io-uring

$npx -y skills add mohitmishra786/low-level-dev-skills --skill io-uring

Installs into the current project.

Summary

io_uring skill for Linux async I/O. Use when building high-performance servers with liburing, multi-shot operations, provided buffers, fixed files, zero-copy send, or tokio-uring. Activates on queries about io_uring, SQE/CQE, liburing, IORING_OP_PROVIDE_BUFFERS, or io_uring vs ep

Files · 1

View on GitHub

SKILL.md

1	# io_uring
2
3	## Purpose
4
5	Guide agents through Linux io_uring: the submission/completion queue model (SQE/CQE), liburing API, multi-shot accept/recv, provided buffer rings, fixed files and registered buffers, zero-copy send, Rust integration with tokio-uring, performance comparison with epoll, and security considerations.
6
7	## When to Use
8
9	- Building a high-throughput network or disk server on Linux 5.1+
10	- Replacing epoll + thread pool with fewer syscalls
11	- Implementing multi-shot accept/recv for connection-heavy services
12	- Using zero-copy networking with `IORING_OP_SEND_ZC`
13	- Integrating async I/O in Rust via `tokio-uring`
14	- Evaluating io_uring vs epoll for your workload
15
16	## Workflow
17
18	### 1. SQ/CQ model
19
20	```
21	Application Kernel
22	│ │
23	├── mmap SQ ring ───────────►│ submission queue (SQE)
24	├── mmap CQ ring ◄──────────│ completion queue (CQE)
25	├── io_uring_submit() ──────►│ processes SQEs
26	└── io_uring_wait_cqe() ◄──│ posts CQEs
27	```
28
29	Each SQE describes one operation; each CQE reports result and user_data cookie.
30
31	### 2. Minimal liburing example
32
33	```c
34	#include <liburing.h>
35	#include <fcntl.h>
36	#include <unistd.h>
37	#include <stdio.h>
38
39	int main(void) {
40	struct io_uring ring;
41	io_uring_queue_init(32, &ring, 0);
42
43	int fd = open("test.txt", O_RDONLY);
44	char buf[4096];
45
46	struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
47	io_uring_prep_read(sqe, fd, buf, sizeof(buf), 0);
48	io_uring_sqe_set_data(sqe, (void *)1);
49
50	io_uring_submit(&ring);
51
52	struct io_uring_cqe *cqe;
53	io_uring_wait_cqe(&ring, &cqe);
54	if (cqe->res >= 0)
55	printf("read %d bytes\n", cqe->res);
56	else
57	perror("read");
58
59	io_uring_cqe_seen(&ring, cqe);
60	io_uring_queue_exit(&ring);
61	close(fd);
62	return 0;
63	}
64	```
65
66	```bash
67	gcc -o uring_read uring_read.c -luring
68	./uring_read
69	```
70
71	### 3. Common prep operations
72
73	\| Function \| Operation \|
74	\|----------\|-----------\|
75	\| `io_uring_prep_read` \| File read \|
76	\| `io_uring_prep_write` \| File write \|
77	\| `io_uring_prep_recv` \| Socket recv \|
78	\| `io_uring_prep_send` \| Socket send \|
79	\| `io_uring_prep_accept` \| Accept connection \|
80	\| `io_uring_prep_connect` \| Outbound connect \|
81	\| `io_uring_prep_poll_add` \| Poll fd \|
82	\| `io_uring_prep_timeout` \| Timeout/link timeout \|
83
84	```c
85	// Batch multiple SQEs before single submit
86	for (int i = 0; i < n; i++) {
87	sqe = io_uring_get_sqe(&ring);
88	io_uring_prep_read(sqe, fds[i], bufs[i], sizes[i], 0);
89	io_uring_sqe_set_data(sqe, (void *)(intptr_t)i);
90	}
91	io_uring_submit(&ring);
92	```
93
94	### 4. Multi-shot operations
95
96	```c
97	// Multi-shot accept — one SQE handles many connections
98	sqe = io_uring_get_sqe(&ring);
99	io_uring_prep_multishot_accept(sqe, listen_fd, NULL, NULL, 0);
100	io_uring_sqe_set_data(sqe, (void *)ACCEPT_COOKIE);
101
102	// Loop on CQEs until CQE_FLAG_MORE is clear
103	while (1) {
104	io_uring_wait_cqe(&ring, &cqe);
105	if (cqe->user_data == ACCEPT_COOKIE) {
106	int client_fd = cqe->res;
107	if (client_fd >= 0)
108	handle_client(client_fd);
109	if (!(cqe->flags & IORING_CQE_F_MORE))
110	break; // re-arm accept SQE
111	}
112	io_uring_cqe_seen(&ring, cqe);
113	}
114	```
115
116	### 5. Provided buffer rings
117
118	```c
119	#include <liburing.h>
120
121	#define BUF_GROUP 0
122	#define BUF_SIZE 4096
123	#define BUF_COUNT 64
124
125	struct io_uring_buf_ring *buf_ring;
126	char bufs[BUF_COUNT][BUF_SIZE];
127
128	// Setup buffer ring
129	buf_ring = io_uring_setup_buf_ring(&ring, BUF_COUNT, BUF_GROUP, 0, &ret);
130	for (int i = 0; i < BUF_COUNT; i++)
131	io_uring_buf_ring_add(buf_ring, bufs[i], BUF_SIZE, i, BUF_COUNT - 1 - i, 0);
132	io_uring_buf_ring_advance(buf_ring, BUF_COUNT);
133
134	// Recv with provided buffers
135	sqe = io_uring_get_sqe(&ring);
136	io_uring_prep_recv_multishot(sqe, sock_fd, NULL, 0, 0);
137	sqe->buf_group = BUF_GROUP;
138	```
139
140	Kernel selects buffer from ring — eliminates per-recv buffer allocation.
141
142	### 6. Fixed files and registered buffers
143
144	```c
145	// Register files — avoids per-op fd table lookup
146	int fds[64];
147	io_uring_register_files(&ring, fds, 64);
148	io_uring_prep_read(sqe, 0, buf, size, offset); // index 0, not fd
149
150	// Registered buffers — pinned, DMA-friendly
151	struct iovec iov = { .iov_base = buf, .iov_len = size };
152	io_uring_register_buffers(&ring, &iov, 1);
153	io_uring_prep_read_fixed(sqe, fd, buf, size, offset, 0);
154	```
155
156	### 7. Zero-copy send
157
158	```c
159	sqe = io_uring_get_sqe(&ring);
160	io_uring_prep_send_zc(sqe, sock_fd, data, len, 0, 0);
161	// May complete with IORING_CQE_F_MORE — wait for notification CQE
162	```
163
164	Requires kernel 6.0+, NIC/driver support. Falls back to copy mode if unavailable.
165
166	### 8. tokio-uring (Rust)
167
168	```rust
169	use tokio_uring::fs::File;
170
171	#[tokio_uring::main]
172	async fn main() -> std::io::Result<()> {
173	let file = File::open("t

People who liked this also viewed

6 picks

Type

io-uring

62installs19forks

View on GitHub

How to install io-uring?

mohitmishra786/low-level-dev-skills/io-uring

$npx -y skills add mohitmishra786/low-level-dev-skills --skill io-uring

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# io_uring
2
3	## Purpose
4
5	Guide agents through Linux io_uring: the submission/completion queue model (SQE/CQE), liburing API, multi-shot accept/recv, provided buffer rings, fixed files and registered buffers, zero-copy send, Rust integration with tokio-uring, performance comparison with epoll, and security considerations.
6
7	## When to Use
8
9	- Building a high-throughput network or disk server on Linux 5.1+
10	- Replacing epoll + thread pool with fewer syscalls
11	- Implementing multi-shot accept/recv for connection-heavy services
12	- Using zero-copy networking with `IORING_OP_SEND_ZC`
13	- Integrating async I/O in Rust via `tokio-uring`
14	- Evaluating io_uring vs epoll for your workload
15
16	## Workflow
17
18	### 1. SQ/CQ model
19
20	```
21	Application Kernel
22	│ │
23	├── mmap SQ ring ───────────►│ submission queue (SQE)
24	├── mmap CQ ring ◄──────────│ completion queue (CQE)
25	├── io_uring_submit() ──────►│ processes SQEs
26	└── io_uring_wait_cqe() ◄──│ posts CQEs
27	```
28
29	Each SQE describes one operation; each CQE reports result and user_data cookie.
30
31	### 2. Minimal liburing example
32
33	```c
34	#include <liburing.h>
35	#include <fcntl.h>
36	#include <unistd.h>
37	#include <stdio.h>
38
39	int main(void) {
40	struct io_uring ring;
41	io_uring_queue_init(32, &ring, 0);
42
43	int fd = open("test.txt", O_RDONLY);
44	char buf[4096];
45
46	struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
47	io_uring_prep_read(sqe, fd, buf, sizeof(buf), 0);
48	io_uring_sqe_set_data(sqe, (void *)1);
49
50	io_uring_submit(&ring);
51
52	struct io_uring_cqe *cqe;
53	io_uring_wait_cqe(&ring, &cqe);
54	if (cqe->res >= 0)
55	printf("read %d bytes\n", cqe->res);
56	else
57	perror("read");
58
59	io_uring_cqe_seen(&ring, cqe);
60	io_uring_queue_exit(&ring);
61	close(fd);
62	return 0;
63	}
64	```
65
66	```bash
67	gcc -o uring_read uring_read.c -luring
68	./uring_read
69	```
70
71	### 3. Common prep operations
72
73	\| Function \| Operation \|
74	\|----------\|-----------\|
75	\| `io_uring_prep_read` \| File read \|
76	\| `io_uring_prep_write` \| File write \|
77	\| `io_uring_prep_recv` \| Socket recv \|
78	\| `io_uring_prep_send` \| Socket send \|
79	\| `io_uring_prep_accept` \| Accept connection \|
80	\| `io_uring_prep_connect` \| Outbound connect \|
81	\| `io_uring_prep_poll_add` \| Poll fd \|
82	\| `io_uring_prep_timeout` \| Timeout/link timeout \|
83
84	```c
85	// Batch multiple SQEs before single submit
86	for (int i = 0; i < n; i++) {
87	sqe = io_uring_get_sqe(&ring);
88	io_uring_prep_read(sqe, fds[i], bufs[i], sizes[i], 0);
89	io_uring_sqe_set_data(sqe, (void *)(intptr_t)i);
90	}
91	io_uring_submit(&ring);
92	```
93
94	### 4. Multi-shot operations
95
96	```c
97	// Multi-shot accept — one SQE handles many connections
98	sqe = io_uring_get_sqe(&ring);
99	io_uring_prep_multishot_accept(sqe, listen_fd, NULL, NULL, 0);
100	io_uring_sqe_set_data(sqe, (void *)ACCEPT_COOKIE);
101
102	// Loop on CQEs until CQE_FLAG_MORE is clear
103	while (1) {
104	io_uring_wait_cqe(&ring, &cqe);
105	if (cqe->user_data == ACCEPT_COOKIE) {
106	int client_fd = cqe->res;
107	if (client_fd >= 0)
108	handle_client(client_fd);
109	if (!(cqe->flags & IORING_CQE_F_MORE))
110	break; // re-arm accept SQE
111	}
112	io_uring_cqe_seen(&ring, cqe);
113	}
114	```
115
116	### 5. Provided buffer rings
117
118	```c
119	#include <liburing.h>
120
121	#define BUF_GROUP 0
122	#define BUF_SIZE 4096
123	#define BUF_COUNT 64
124
125	struct io_uring_buf_ring *buf_ring;
126	char bufs[BUF_COUNT][BUF_SIZE];
127
128	// Setup buffer ring
129	buf_ring = io_uring_setup_buf_ring(&ring, BUF_COUNT, BUF_GROUP, 0, &ret);
130	for (int i = 0; i < BUF_COUNT; i++)
131	io_uring_buf_ring_add(buf_ring, bufs[i], BUF_SIZE, i, BUF_COUNT - 1 - i, 0);
132	io_uring_buf_ring_advance(buf_ring, BUF_COUNT);
133
134	// Recv with provided buffers
135	sqe = io_uring_get_sqe(&ring);
136	io_uring_prep_recv_multishot(sqe, sock_fd, NULL, 0, 0);
137	sqe->buf_group = BUF_GROUP;
138	```
139
140	Kernel selects buffer from ring — eliminates per-recv buffer allocation.
141
142	### 6. Fixed files and registered buffers
143
144	```c
145	// Register files — avoids per-op fd table lookup
146	int fds[64];
147	io_uring_register_files(&ring, fds, 64);
148	io_uring_prep_read(sqe, 0, buf, size, offset); // index 0, not fd
149
150	// Registered buffers — pinned, DMA-friendly
151	struct iovec iov = { .iov_base = buf, .iov_len = size };
152	io_uring_register_buffers(&ring, &iov, 1);
153	io_uring_prep_read_fixed(sqe, fd, buf, size, offset, 0);
154	```
155
156	### 7. Zero-copy send
157
158	```c
159	sqe = io_uring_get_sqe(&ring);
160	io_uring_prep_send_zc(sqe, sock_fd, data, len, 0, 0);
161	// May complete with IORING_CQE_F_MORE — wait for notification CQE
162	```
163
164	Requires kernel 6.0+, NIC/driver support. Falls back to copy mode if unavailable.
165
166	### 8. tokio-uring (Rust)
167
168	```rust
169	use tokio_uring::fs::File;
170
171	#[tokio_uring::main]
172	async fn main() -> std::io::Result<()> {
173	let file = File::open("t

People who liked this also viewed

6 picks

Type