[PATCH liburing v1 0/2] Fixes for io_uring_for_each_cqe

[PATCH liburing v1 0/2] Fixes for io_uring_for_each_cqe

[Ammar Faizi]

Hi Jens,

Please consider taking these last-minute fixes for liburing-2.4
release. There are two patches in this series:

## 1. man/io_uring_for_each_cqe: Fix return value, title, and typo

  - Fix the return value. io_uring_for_each_cqe() doesn't return an int.

  - Fix the title, it was io_uring_wait_cqes(), it should be
    io_uring_for_each_cqe().

  - Fix typo: s/io_uring_for_each_cqes/io_uring_for_each_cqe/.

## 2. Explicitly tell it's a macro and add an example

Let the reader directly know that it's not a function, but a macro.
Also, give a simple example of its usage.

Signed-off-by: Alviro Iskandar Setiawan <alviro.iskandar@gnuweeb.org>
Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---

Ammar Faizi (2):
  man/io_uring_for_each_cqe: Fix return value, title, and typo
  man/io_uring_for_each_cqe: Explicitly tell it's a macro and add an example

 man/io_uring_for_each_cqe.3 | 28 +++++++++++++++++++++++-----
 1 file changed, 23 insertions(+), 5 deletions(-)

base-commit: b4ee3108b93f7e4602430246236d14978abad085
-- 
Ammar Faizi

[PATCH liburing v1 1/2] man/io_uring_for_each_cqe: Fix return value, title, and typo

[Ammar Faizi]

1) Fix the return value. io_uring_for_each_cqe() doesn't return an int.

2) Fix the title, it was io_uring_wait_cqes(), it should be
   io_uring_for_each_cqe().

3) Fix typo: s/io_uring_for_each_cqes/io_uring_for_each_cqe/

Fixes: 16d74b1c76043e6 ("man: add man page for io_uring_for_each_cqe()")
Reported-by: Alviro Iskandar Setiawan <alviro.iskandar@gnuweeb.org>
Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 man/io_uring_for_each_cqe.3 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/man/io_uring_for_each_cqe.3 b/man/io_uring_for_each_cqe.3
index 9230d147515c78fb..8445fd605d0b02a6 100644
--- a/man/io_uring_for_each_cqe.3
+++ b/man/io_uring_for_each_cqe.3
@@ -2,16 +2,16 @@
 .\"
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
-.TH io_uring_wait_cqes 3 "June 04, 2023" "liburing-2.4" "liburing Manual"
+.TH io_uring_for_each_cqe 3 "June 04, 2023" "liburing-2.4" "liburing Manual"
 .SH NAME
 io_uring_for_each_cqe \- iterate pending completion events
 .SH SYNOPSIS
 .nf
 .B #include <liburing.h>
 .PP
-.BI "int io_uring_for_each_cqes(struct io_uring *" ring ","
-.BI "                           unsigned " head ","
-.BI "                           struct io_uring_cqe *" cqe ");
+.BI "io_uring_for_each_cqe(struct io_uring *" ring ","
+.BI "                      unsigned " head ","
+.BI "                      struct io_uring_cqe *" cqe ") { }
 .fi
 .SH DESCRIPTION
 .PP
-- 
Ammar Faizi

[PATCH liburing v1 2/2] man/io_uring_for_each_cqe: Explicitly tell it's a macro and add an example

[Ammar Faizi]

Let the reader directly know that it's not a function, but a macro.
Also, give a simple example of its usage.

Co-authored-by: Alviro Iskandar Setiawan <alviro.iskandar@gnuweeb.org>
Signed-off-by: Alviro Iskandar Setiawan <alviro.iskandar@gnuweeb.org>
Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 man/io_uring_for_each_cqe.3 | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/man/io_uring_for_each_cqe.3 b/man/io_uring_for_each_cqe.3
index 8445fd605d0b02a6..78d8f6fc168d12e3 100644
--- a/man/io_uring_for_each_cqe.3
+++ b/man/io_uring_for_each_cqe.3
@@ -17,7 +17,7 @@ io_uring_for_each_cqe \- iterate pending completion events
 .PP
 The
 .BR io_uring_for_each_cqe (3)
-helper iterates completion events belonging to the
+is a macro helper that iterates completion events belonging to the
 .I ring
 using
 .I head
@@ -35,6 +35,24 @@ calling
 .BR io_uring_cqe_seen (3)
 for each of them.
 
+.SH EXAMPLE
+.EX
+void handle_cqes(struct io_uring *ring)
+{
+	struct io_uring_cqe *cqe;
+	unsigned head;
+	unsigned i = 0;
+
+	io_uring_for_each_cqe(ring, head, cqe) {
+		/* handle completion */
+		printf("cqe: %d\\n", cqe->res);
+		i++;
+	}
+
+	io_uring_cq_advance(ring, i);
+}
+.EE
+
 .SH RETURN VALUE
 None
 .SH SEE ALSO
-- 
Ammar Faizi

Re: [PATCH liburing v1 0/2] Fixes for io_uring_for_each_cqe

[Jens Axboe]

On 6/8/23 7:54 PM, Ammar Faizi wrote:
> Hi Jens,
> 
> Please consider taking these last-minute fixes for liburing-2.4
> release. There are two patches in this series:
> 
> ## 1. man/io_uring_for_each_cqe: Fix return value, title, and typo
> 
>   - Fix the return value. io_uring_for_each_cqe() doesn't return an int.
> 
>   - Fix the title, it was io_uring_wait_cqes(), it should be
>     io_uring_for_each_cqe().
> 
>   - Fix typo: s/io_uring_for_each_cqes/io_uring_for_each_cqe/.
> 
> ## 2. Explicitly tell it's a macro and add an example
> 
> Let the reader directly know that it's not a function, but a macro.
> Also, give a simple example of its usage.

Applied, even though not super critical for release. But this should
be it, I'll announce 2.4 tomorrow.

-- 
Jens Axboe

Re: [PATCH liburing v1 0/2] Fixes for io_uring_for_each_cqe

[Jens Axboe]

On Fri, 09 Jun 2023 08:54:01 +0700, Ammar Faizi wrote:
> Please consider taking these last-minute fixes for liburing-2.4
> release. There are two patches in this series:
> 
> ## 1. man/io_uring_for_each_cqe: Fix return value, title, and typo
> 
>   - Fix the return value. io_uring_for_each_cqe() doesn't return an int.
> 
> [...]

Applied, thanks!

[1/2] man/io_uring_for_each_cqe: Fix return value, title, and typo
      commit: c8d06ed9bcbf2ae294242f9caacecfa01bf138b2
[2/2] man/io_uring_for_each_cqe: Explicitly tell it's a macro and add an example
      commit: 298c083d75ecde5a8833366167b3b6abff0c8d39

Best regards,
-- 
Jens Axboe