liburing, man: make io_uring_sqring_wait() more consistent with API

Make io_uring_sqring_wait() return an amount of free SQ ring entries or -EINVAL if the ring was not setup with IORING_SETUP_SQPOLL, adjust manual page accordingly. Signed-off-by: Dmitry Antipov <[email protected]>
axboe · Dec 5, 2022 · 8d3bb0e · 8d3bb0e
1 parent 5772879
commit 8d3bb0e
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 9 deletions.
diff --git a/man/io_uring_sqring_wait.3 b/man/io_uring_sqring_wait.3
@@ -26,8 +26,10 @@ This feature can only be used when the ring has been setup with
 and hence is using an offloaded approach to request submissions.
 
 .SH RETURN VALUE
-On success it returns the free space. If the kernel does not support the
-feature, -EINVAL is returned.
+On success it returns an amount of free entries in the SQ ring. If the kernel
+does not support the feature, or the ring was not setup with
+.B IORING_SETUP_SQPOLL,
+-EINVAL is returned.
 .SH SEE ALSO
 .BR io_uring_submit (3),
 .BR io_uring_wait_cqe (3),

diff --git a/src/include/liburing.h b/src/include/liburing.h
@@ -1093,18 +1093,23 @@ static inline unsigned io_uring_sq_space_left(const struct io_uring *ring)
 }
 
 /*
- * Only applicable when using SQPOLL - allows the caller to wait for space
- * to free up in the SQ ring, which happens when the kernel side thread has
- * consumed one or more entries. If the SQ ring is currently non-full, no
- * action is taken. Note: may return -EINVAL if the kernel doesn't support
+ * Only applicable when using SQPOLL - allows the caller to wait for an at
+ * least one free entry in the SQ ring, which happens when the kernel side
+ * thread has consumed one or more entries. If the SQ ring is currently
+ * non-full, no waiting occured and an amout of free entries is returned
+ * immediately. Note: may also return -EINVAL if the kernel doesn't support
  * this feature.
  */
 static inline int io_uring_sqring_wait(struct io_uring *ring)
 {
+	int ret;
+
 	if (!(ring->flags & IORING_SETUP_SQPOLL))
-		return 0;
-	if (io_uring_sq_space_left(ring))
-		return 0;
+		return -EINVAL;
+
+	ret = io_uring_sq_space_left(ring);
+	if (ret)
+		return ret;
 
 	return __io_uring_sqring_wait(ring);
 }