From 11c5e25f220a9f52f6cde3b08cf4fd9fe4bcf2a4 Mon Sep 17 00:00:00 2001
From: Benedek Thaler <benedek.thaler@wincent.co>
Date: Fri, 16 Aug 2024 20:37:39 +0200
Subject: [PATCH] Add extra documentation to SendZc

---
 io-uring-test/src/tests/net.rs |  2 ++
 src/opcode.rs                  | 15 +++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/io-uring-test/src/tests/net.rs b/io-uring-test/src/tests/net.rs
index 4502b36..0a50274 100644
--- a/io-uring-test/src/tests/net.rs
+++ b/io-uring-test/src/tests/net.rs
@@ -1662,10 +1662,12 @@ pub fn test_udp_sendzc_with_dest<S: squeue::EntryMarker, C: cqueue::EntryMarker>
                 // First SendZc notification
                 11 => {
                     assert_eq!(cqueue::more(cqe.flags()), true);
+                    assert_eq!(cqueue::notif(cqe.flags()), false);
                 }
                 // Last SendZc notification
                 0 => {
                     assert_eq!(cqueue::more(cqe.flags()), false);
+                    assert_eq!(cqueue::notif(cqe.flags()), true);
                 }
                 _ => panic!("wrong result for notification"),
             },
diff --git a/src/opcode.rs b/src/opcode.rs
index 7a9f3d0..2083872 100644
--- a/src/opcode.rs
+++ b/src/opcode.rs
@@ -1662,6 +1662,21 @@ opcode! {
     ///
     /// A fixed (pre-mapped) buffer can optionally be used from pre-mapped buffers that have been
     /// previously registered with [`Submitter::register_buffers`](crate::Submitter::register_buffers).
+    ///
+    /// This operation might result in two completion queue entries. The flags field of the first
+    /// cqe may likely contain [`IORING_CQE_F_MORE`](crate::cqueue::more), which means that there
+    /// will be a second completion event (notification) for the request, with the `user_data`
+    /// field set to the same value. The user must not modify the data buffer until the
+    /// notification is posted. The first cqe follows the usual rules and so its `res` field will
+    /// contain the number of bytes sent or a negative error code. The notification's `res` field
+    /// will be set to zero and the flags field will contain
+    /// [`IORING_CQE_F_NOTIF`](crate::cqueue::notif). The two step model is needed because the
+    /// kernel may hold on to buffers for a long time, e.g. waiting for a TCP ACK, and having a
+    /// separate cqe for request completions allows userspace to push more data without extra
+    /// delays. Note, notifications are only responsible for controlling the lifetime of the
+    /// buffers, and as such don't mean anything about whether the data has atually been sent out
+    /// or received by the other end. Even errored requests may generate a notification, and the
+    /// user must use [notif](crate::cqueue::notif) rather than relying on the result.
     pub struct SendZc {
         fd: { impl sealed::UseFixed },
         buf: { *const u8 },