Skip to contentSkip to conversation

improve sendzc man pages

PATCH In review Pavel Begunkov 2 participants 5 messages Oct 21, 2022 io_uring

lore
Share & tools
lore
#0 lore raw

cover improve sendzc man pages

Add a note about failing zc requests with -EOPNOTSUPP and add a paragraph about IORING_RECVSEND_FIXED_BUF.

Pavel Begunkov (3):
io_uring_enter.2: add sendzc -EOPNOTSUPP note io_uring_enter.2: document IORING_RECVSEND_POLL_FIRST io_uring_enter.2: document IORING_RECVSEND_FIXED_BUF

 man/io_uring_enter.2 | 98 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 2 deletions(-)
Signature · 1 line
2.38.0
#1 lore raw

PATCH 1/3 io_uring_enter.2: add sendzc -EOPNOTSUPP note

---
 man/io_uring_enter.2 | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)
man/io_uring_enter.2 +5 -2
index 2ebc6e3..25fdc1e 100644
@@ -1098,8 +1098,11 @@ Available since 5.19.
 Issue the zerocopy equivalent of a
 .BR send(2)
 system call. Similar to IORING_OP_SEND, but tries to avoid making intermediate
-copies of data. Zerocopy execution is not guaranteed and it may fall back to
-copying.
+copies of data. Zerocopy execution is not guaranteed and may fall back to
+copying. The request may also fail with
+.B -EOPNOTSUPP,
+for instance when a protocol doesn't support zerocopy in the first place, in
+which case users are recommended to use copying sends instead.
 
 The
 .I flags
Signature · 1 line
2.38.0
#2 lore raw

PATCH 2/3 io_uring_enter.2: document IORING_RECVSEND_POLL_FIRST

In reply to Pavel Begunkov
---
 man/io_uring_enter.2 | 85 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
man/io_uring_enter.2 +85 -0
index 25fdc1e..d98ae59 100644
@@ -394,12 +394,46 @@ holds the flags associated with the system call. See also
 .BR sendmsg (2)
 for the general description of the related system call. Available since 5.3.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently full and attempting to
+send data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a send of the data when there is enough space available.
+This initial send attempt can be wasteful for the case where the socket
+is expected to be full, setting this flag will bypass the initial send
+attempt and go straight to arming poll. If poll does indicate that data can
+be sent, the operation will proceed.
+.EE
+.in
+.PP
+
 .TP
 .B IORING_OP_RECVMSG
 Works just like IORING_OP_SENDMSG, except for
 .BR recvmsg(2)
 instead. See the description of IORING_OP_SENDMSG. Available since 5.3.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently empty and attempting to
+receive data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a receive of the data when the socket has data to be read.
+This initial receive attempt can be wasteful for the case where the socket
+is expected to be empty, setting this flag will bypass the initial receive
+attempt and go straight to arming poll. If poll does indicate that data is
+ready to be received, the operation will proceed.
+.EE
+.in
+.PP
+
 .TP
 .B IORING_OP_SEND
 Issue the equivalent of a
@@ -416,12 +450,46 @@ holds the flags associated with the system call. See also
 .BR send(2)
 for the general description of the related system call. Available since 5.6.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently full and attempting to
+send data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a send of the data when there is enough space available.
+This initial send attempt can be wasteful for the case where the socket
+is expected to be full, setting this flag will bypass the initial send
+attempt and go straight to arming poll. If poll does indicate that data can
+be sent, the operation will proceed.
+.EE
+.in
+.PP
+
 .TP
 .B IORING_OP_RECV
 Works just like IORING_OP_SEND, except for
 .BR recv(2)
 instead. See the description of IORING_OP_SEND. Available since 5.6.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently empty and attempting to
+receive data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a receive of the data when the socket has data to be read.
+This initial receive attempt can be wasteful for the case where the socket
+is expected to be empty, setting this flag will bypass the initial receive
+attempt and go straight to arming poll. If poll does indicate that data is
+ready to be received, the operation will proceed.
+.EE
+.in
+.PP
+
 .TP
 .B IORING_OP_TIMEOUT
 This command will register a timeout operation. The
@@ -1150,6 +1218,23 @@ system call equivalent.
 
 Available since 6.0.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently full and attempting to
+send data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a send of the data when there is enough space available.
+This initial send attempt can be wasteful for the case where the socket
+is expected to be full, setting this flag will bypass the initial send
+attempt and go straight to arming poll. If poll does indicate that data can
+be sent, the operation will proceed.
+.EE
+.in
+.PP
+
 .PP
 The
 .I flags
Signature · 1 line
2.38.0
#3 lore raw

PATCH 3/3 io_uring_enter.2: document IORING_RECVSEND_FIXED_BUF

In reply to Pavel Begunkov
---
 man/io_uring_enter.2 | 6 ++++++
 1 file changed, 6 insertions(+)
man/io_uring_enter.2 +6 -0
index d98ae59..2a8705f 100644
@@ -1231,6 +1231,12 @@ This initial send attempt can be wasteful for the case where the socket
 is expected to be full, setting this flag will bypass the initial send
 attempt and go straight to arming poll. If poll does indicate that data can
 be sent, the operation will proceed.
+
+.B IORING_RECVSEND_FIXED_BUF
+instructs to use a pre-mapped buffer. If set, the
+.I buf_index
+field should contain an index into an array of fixed buffers. See
+io_uring_register(2) for details on how to setup a context for fixed buffer I/O.
 .EE
 .in
 .PP
Signature · 1 line
2.38.0
maintainer
#4 lore raw
In reply to Pavel Begunkov
Quoted 10 lines · Pavel Begunkov

Add a note about failing zc requests with -EOPNOTSUPP and add a paragraph about IORING_RECVSEND_FIXED_BUF.

Pavel Begunkov (3):
io_uring_enter.2: add sendzc -EOPNOTSUPP note io_uring_enter.2: document IORING_RECVSEND_POLL_FIRST io_uring_enter.2: document IORING_RECVSEND_FIXED_BUF

 man/io_uring_enter.2 | 98 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 2 deletions(-)

Applied with minor edits, thanks!

Signature · 1 line
Jens Axboe