feat: add SQPOLL support for io_uring by SidongYang · Pull Request #7960 · tokio-rs/tokio

SidongYang · 2026-03-08T00:49:09Z

This adds uring_setup_sqpoll to the Runtime Builder, allowing the io_uring driver
to be configured with SQPOLL enabled. This offloads submission queue polling to a
kernel thread, which can significantly reduce syscall overhead.

Added uring_setup_sqpoll to tokio::runtime::Builder.
Updated UringContext to sync the submission queue and check need_wakeup.
Added tests to verify sqpoll in both single-thread and multi-thread runtimes.

martin-g · 2026-03-09T06:07:05Z

tokio/src/runtime/builder.rs

+        ///     .unwrap();
+        /// ```
+        #[cfg_attr(docsrs, doc(cfg(feature = "io-uring")))]
+        pub fn uring_setup_sqpoll(&mut self, idle: u32) -> &mut Self {


Suggested change

pub fn uring_setup_sqpoll(&mut self, idle: u32) -> &mut Self {

pub fn uring_setup_sqpoll(&mut self, idle_timeout: u32) -> &mut Self {

Thanks, Applied.

martin-g · 2026-03-09T06:07:15Z

tokio/src/runtime/builder.rs

+        /// ```
+        #[cfg_attr(docsrs, doc(cfg(feature = "io-uring")))]
+        pub fn uring_setup_sqpoll(&mut self, idle: u32) -> &mut Self {
+            self.uring_setup_sqpoll = Some(idle);


Suggested change

self.uring_setup_sqpoll = Some(idle);

self.uring_setup_sqpoll = Some(idle_timeout);

Thanks, Applied.

martin-g · 2026-03-09T06:08:48Z

tokio/src/runtime/builder.rs

            self
        }
+
+        /// Enables SQPOLL for the io_uring driver and sets the idle timeout.


Suggested change

/// Enables SQPOLL for the io_uring driver and sets the idle timeout.

/// Enables SQPOLL for the io_uring driver and sets the idle timeout (in milliseconds).

if the timeout is in millis. Otherwise, please mention the correct time unit.

Thanks, Applied.

tokio/src/runtime/builder.rs

tokio/src/runtime/io/driver/uring.rs

SidongYang · 2026-03-10T04:42:44Z

I have updated the PR to address the remaining review comments:

Naming: Renamed the idle parameter to idle_timeout in uring_setup_sqpoll and its internal implementation for better clarity.
Documentation:
- Explicitly specified that the idle_timeout unit is in milliseconds.
- Added prerequisites regarding required Linux kernel versions (5.1+) and CAP_SYS_ADMIN privileges (required before Linux 5.11).
- Clarified that the first I/O operation will fail if SQPOLL is enabled but not supported by the system.
Feature Flags: Standardized cfg attributes for io-uring to consistently include rt, fs, and target_os = "linux" to match workspace conventions and prevent compilation failures.
Validation: Verified that the changes compile and that the fs_uring_sqpoll tests pass successfully under tokio_unstable.

martin-g · 2026-03-10T06:20:10Z

Please fix the formatting issues and update to master to fix the FreeBSD build

SidongYang · 2026-03-10T08:56:46Z

@martin-g Thanks, I've fixed formatting and rebased this branch.

martin-g · 2026-03-10T09:04:22Z

Now the spellchecker is complaining.
Please add SQPOLL to https://github.com/tokio-rs/tokio/blob/master/spellcheck.dic and increment the number on the first line in this file.

SidongYang · 2026-03-10T11:57:03Z

Thanks, @martin-g . I've added SQPOLL to the spellcheck file and incremented the number on the first line.

martin-g · 2026-03-10T12:19:39Z

tokio/src/runtime/builder.rs

+        feature = "rt",
+        feature = "fs",
+        target_os = "linux"
+    ))]


Please add some rustdoc here

Sure, I've added a line for rustdoc above. Thanks.

This adds `uring_setup_sqpoll` to the Runtime `Builder`, allowing the io_uring driver to be configured with SQPOLL enabled. This offloads submission queue polling to a kernel thread, which can significantly reduce syscall overhead. - Added `uring_setup_sqpoll` to `tokio::runtime::Builder`. - Updated `UringContext` to sync the submission queue and check `need_wakeup`. - Added tests to verify `sqpoll` in both single-thread and multi-thread runtimes.

martin-g reviewed Mar 9, 2026

View reviewed changes

Darksonn added A-tokio Area: The main tokio crate T-io-uring Topic: Linux io_uring labels Mar 9, 2026

SidongYang force-pushed the uring-sqpoll branch from 69d5df8 to 54468ed Compare March 10, 2026 04:29

SidongYang force-pushed the uring-sqpoll branch from 54468ed to 23df36c Compare March 10, 2026 08:54

SidongYang requested review from Darksonn and martin-g March 10, 2026 08:56

SidongYang force-pushed the uring-sqpoll branch from 23df36c to d300d94 Compare March 10, 2026 11:54

martin-g approved these changes Mar 10, 2026

View reviewed changes

SidongYang force-pushed the uring-sqpoll branch from d300d94 to c56fda6 Compare March 10, 2026 14:15

	pub fn uring_setup_sqpoll(&mut self, idle: u32) -> &mut Self {
	pub fn uring_setup_sqpoll(&mut self, idle_timeout: u32) -> &mut Self {

	self.uring_setup_sqpoll = Some(idle);
	self.uring_setup_sqpoll = Some(idle_timeout);

	/// Enables SQPOLL for the io_uring driver and sets the idle timeout.
	/// Enables SQPOLL for the io_uring driver and sets the idle timeout (in milliseconds).

Uh oh!

Conversation

SidongYang commented Mar 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SidongYang commented Mar 10, 2026

Uh oh!

martin-g commented Mar 10, 2026

Uh oh!

SidongYang commented Mar 10, 2026

Uh oh!

martin-g commented Mar 10, 2026

Uh oh!

SidongYang commented Mar 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants