polyphony 0.94 → 0.96
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/test.yml +3 -3
- data/.github/workflows/test_io_uring.yml +4 -4
- data/.gitignore +3 -3
- data/CHANGELOG.md +19 -0
- data/docs/api-reference/fiber.md +2 -2
- data/docs/api-reference/object.md +3 -3
- data/docs/main-concepts/exception-handling.md +2 -2
- data/examples/adapters/redis_blpop.rb +4 -3
- data/examples/adapters/redis_channels.rb +16 -7
- data/examples/core/await.rb +1 -1
- data/examples/io/readline.rb +19 -0
- data/ext/polyphony/backend_common.c +25 -3
- data/ext/polyphony/backend_io_uring.c +18 -16
- data/ext/polyphony/backend_libev.c +2 -2
- data/ext/polyphony/event.c +1 -1
- data/ext/polyphony/extconf.rb +5 -3
- data/ext/polyphony/fiber.c +5 -13
- data/ext/polyphony/io_extensions.c +1 -1
- data/ext/polyphony/pipe.c +1 -1
- data/ext/polyphony/polyphony.c +1 -1
- data/ext/polyphony/polyphony_ext.c +1 -1
- data/ext/polyphony/queue.c +1 -1
- data/ext/polyphony/ring_buffer.c +1 -0
- data/ext/polyphony/socket_extensions.c +1 -1
- data/ext/polyphony/thread.c +1 -1
- data/lib/polyphony/adapters/readline.rb +6 -4
- data/lib/polyphony/adapters/redis.rb +28 -87
- data/lib/polyphony/core/channel.rb +15 -0
- data/lib/polyphony/core/sync.rb +4 -0
- data/lib/polyphony/debugger.rb +2 -2
- data/lib/polyphony/extensions/socket.rb +2 -0
- data/lib/polyphony/version.rb +1 -1
- data/lib/polyphony.rb +4 -0
- data/polyphony.gemspec +10 -10
- data/test/helper.rb +0 -5
- data/test/test_backend.rb +5 -1
- data/test/test_enumerator.rb +46 -0
- data/test/test_ext.rb +63 -0
- data/test/test_io.rb +241 -216
- data/test/test_socket.rb +1 -1
- data/test/test_thread_pool.rb +5 -5
- data/vendor/liburing/.github/workflows/build.yml +51 -5
- data/vendor/liburing/.github/workflows/shellcheck.yml +1 -1
- data/vendor/liburing/.gitignore +6 -123
- data/vendor/liburing/CHANGELOG +35 -0
- data/vendor/liburing/CITATION.cff +11 -0
- data/vendor/liburing/LICENSE +16 -3
- data/vendor/liburing/Makefile +3 -1
- data/vendor/liburing/Makefile.common +1 -0
- data/vendor/liburing/README +14 -2
- data/vendor/liburing/SECURITY.md +6 -0
- data/vendor/liburing/configure +16 -15
- data/vendor/liburing/examples/Makefile +4 -1
- data/vendor/liburing/examples/io_uring-udp.c +395 -0
- data/vendor/liburing/examples/poll-bench.c +101 -0
- data/vendor/liburing/examples/send-zerocopy.c +339 -0
- data/vendor/liburing/liburing.spec +1 -1
- data/vendor/liburing/man/io_uring.7 +38 -11
- data/vendor/liburing/man/io_uring_buf_ring_add.3 +53 -0
- data/vendor/liburing/man/io_uring_buf_ring_advance.3 +31 -0
- data/vendor/liburing/man/io_uring_buf_ring_cq_advance.3 +41 -0
- data/vendor/liburing/man/io_uring_buf_ring_init.3 +30 -0
- data/vendor/liburing/man/io_uring_buf_ring_mask.3 +27 -0
- data/vendor/liburing/man/io_uring_cq_advance.3 +29 -15
- data/vendor/liburing/man/io_uring_cq_has_overflow.3 +25 -0
- data/vendor/liburing/man/io_uring_cq_ready.3 +9 -8
- data/vendor/liburing/man/io_uring_cqe_get_data.3 +32 -13
- data/vendor/liburing/man/io_uring_cqe_get_data64.3 +1 -0
- data/vendor/liburing/man/io_uring_cqe_seen.3 +22 -12
- data/vendor/liburing/man/io_uring_enter.2 +249 -32
- data/vendor/liburing/man/io_uring_enter2.2 +1 -0
- data/vendor/liburing/man/io_uring_free_probe.3 +11 -8
- data/vendor/liburing/man/io_uring_get_events.3 +33 -0
- data/vendor/liburing/man/io_uring_get_probe.3 +9 -8
- data/vendor/liburing/man/io_uring_get_sqe.3 +29 -10
- data/vendor/liburing/man/io_uring_opcode_supported.3 +11 -10
- data/vendor/liburing/man/io_uring_peek_cqe.3 +38 -0
- data/vendor/liburing/man/io_uring_prep_accept.3 +197 -0
- data/vendor/liburing/man/io_uring_prep_accept_direct.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_cancel.3 +118 -0
- data/vendor/liburing/man/io_uring_prep_cancel64.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_close.3 +59 -0
- data/vendor/liburing/man/io_uring_prep_close_direct.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_connect.3 +66 -0
- data/vendor/liburing/man/io_uring_prep_fadvise.3 +59 -0
- data/vendor/liburing/man/io_uring_prep_fallocate.3 +59 -0
- data/vendor/liburing/man/io_uring_prep_files_update.3 +92 -0
- data/vendor/liburing/man/io_uring_prep_fsync.3 +70 -0
- data/vendor/liburing/man/io_uring_prep_link.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_linkat.3 +91 -0
- data/vendor/liburing/man/io_uring_prep_madvise.3 +56 -0
- data/vendor/liburing/man/io_uring_prep_mkdir.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_mkdirat.3 +83 -0
- data/vendor/liburing/man/io_uring_prep_msg_ring.3 +39 -25
- data/vendor/liburing/man/io_uring_prep_multishot_accept.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_multishot_accept_direct.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_nop.3 +28 -0
- data/vendor/liburing/man/io_uring_prep_openat.3 +117 -0
- data/vendor/liburing/man/io_uring_prep_openat2.3 +117 -0
- data/vendor/liburing/man/io_uring_prep_openat2_direct.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_openat_direct.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_poll_add.3 +72 -0
- data/vendor/liburing/man/io_uring_prep_poll_multishot.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_poll_remove.3 +55 -0
- data/vendor/liburing/man/io_uring_prep_poll_update.3 +89 -0
- data/vendor/liburing/man/io_uring_prep_provide_buffers.3 +131 -0
- data/vendor/liburing/man/io_uring_prep_read.3 +33 -14
- data/vendor/liburing/man/io_uring_prep_read_fixed.3 +39 -21
- data/vendor/liburing/man/io_uring_prep_readv.3 +49 -15
- data/vendor/liburing/man/io_uring_prep_readv2.3 +49 -17
- data/vendor/liburing/man/io_uring_prep_recv.3 +105 -0
- data/vendor/liburing/man/io_uring_prep_recv_multishot.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_recvmsg.3 +124 -0
- data/vendor/liburing/man/io_uring_prep_recvmsg_multishot.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_remove_buffers.3 +52 -0
- data/vendor/liburing/man/io_uring_prep_rename.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_renameat.3 +96 -0
- data/vendor/liburing/man/io_uring_prep_send.3 +57 -0
- data/vendor/liburing/man/io_uring_prep_send_zc.3 +64 -0
- data/vendor/liburing/man/io_uring_prep_sendmsg.3 +69 -0
- data/vendor/liburing/man/io_uring_prep_shutdown.3 +53 -0
- data/vendor/liburing/man/io_uring_prep_socket.3 +118 -0
- data/vendor/liburing/man/io_uring_prep_socket_direct.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_socket_direct_alloc.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_splice.3 +80 -0
- data/vendor/liburing/man/io_uring_prep_statx.3 +74 -0
- data/vendor/liburing/man/io_uring_prep_symlink.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_symlinkat.3 +85 -0
- data/vendor/liburing/man/io_uring_prep_sync_file_range.3 +59 -0
- data/vendor/liburing/man/io_uring_prep_tee.3 +74 -0
- data/vendor/liburing/man/io_uring_prep_timeout.3 +95 -0
- data/vendor/liburing/man/io_uring_prep_timeout_remove.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_timeout_update.3 +98 -0
- data/vendor/liburing/man/io_uring_prep_unlink.3 +1 -0
- data/vendor/liburing/man/io_uring_prep_unlinkat.3 +82 -0
- data/vendor/liburing/man/io_uring_prep_write.3 +32 -15
- data/vendor/liburing/man/io_uring_prep_write_fixed.3 +39 -21
- data/vendor/liburing/man/io_uring_prep_writev.3 +50 -16
- data/vendor/liburing/man/io_uring_prep_writev2.3 +50 -17
- data/vendor/liburing/man/io_uring_queue_exit.3 +3 -4
- data/vendor/liburing/man/io_uring_queue_init.3 +58 -13
- data/vendor/liburing/man/io_uring_queue_init_params.3 +1 -0
- data/vendor/liburing/man/io_uring_recvmsg_cmsg_firsthdr.3 +1 -0
- data/vendor/liburing/man/io_uring_recvmsg_cmsg_nexthdr.3 +1 -0
- data/vendor/liburing/man/io_uring_recvmsg_name.3 +1 -0
- data/vendor/liburing/man/io_uring_recvmsg_out.3 +78 -0
- data/vendor/liburing/man/io_uring_recvmsg_payload.3 +1 -0
- data/vendor/liburing/man/io_uring_recvmsg_payload_length.3 +1 -0
- data/vendor/liburing/man/io_uring_recvmsg_validate.3 +1 -0
- data/vendor/liburing/man/io_uring_register.2 +153 -13
- data/vendor/liburing/man/io_uring_register_buf_ring.3 +140 -0
- data/vendor/liburing/man/io_uring_register_buffers.3 +32 -12
- data/vendor/liburing/man/io_uring_register_eventfd.3 +51 -0
- data/vendor/liburing/man/io_uring_register_eventfd_async.3 +1 -0
- data/vendor/liburing/man/io_uring_register_file_alloc_range.3 +52 -0
- data/vendor/liburing/man/io_uring_register_files.3 +33 -11
- data/vendor/liburing/man/io_uring_register_files_sparse.3 +1 -0
- data/vendor/liburing/man/io_uring_register_iowq_aff.3 +61 -0
- data/vendor/liburing/man/io_uring_register_iowq_max_workers.3 +71 -0
- data/vendor/liburing/man/io_uring_register_ring_fd.3 +49 -0
- data/vendor/liburing/man/io_uring_register_sync_cancel.3 +71 -0
- data/vendor/liburing/man/io_uring_setup.2 +119 -13
- data/vendor/liburing/man/io_uring_sq_ready.3 +14 -8
- data/vendor/liburing/man/io_uring_sq_space_left.3 +9 -9
- data/vendor/liburing/man/io_uring_sqe_set_data.3 +29 -11
- data/vendor/liburing/man/io_uring_sqe_set_data64.3 +1 -0
- data/vendor/liburing/man/io_uring_sqe_set_flags.3 +38 -11
- data/vendor/liburing/man/io_uring_sqring_wait.3 +13 -9
- data/vendor/liburing/man/io_uring_submit.3 +29 -12
- data/vendor/liburing/man/io_uring_submit_and_get_events.3 +31 -0
- data/vendor/liburing/man/io_uring_submit_and_wait.3 +16 -12
- data/vendor/liburing/man/io_uring_submit_and_wait_timeout.3 +30 -23
- data/vendor/liburing/man/io_uring_unregister_buf_ring.3 +30 -0
- data/vendor/liburing/man/io_uring_unregister_buffers.3 +11 -10
- data/vendor/liburing/man/io_uring_unregister_eventfd.3 +1 -0
- data/vendor/liburing/man/io_uring_unregister_files.3 +11 -10
- data/vendor/liburing/man/io_uring_unregister_iowq_aff.3 +1 -0
- data/vendor/liburing/man/io_uring_unregister_ring_fd.3 +32 -0
- data/vendor/liburing/man/io_uring_wait_cqe.3 +19 -12
- data/vendor/liburing/man/io_uring_wait_cqe_nr.3 +21 -14
- data/vendor/liburing/man/io_uring_wait_cqe_timeout.3 +27 -13
- data/vendor/liburing/man/io_uring_wait_cqes.3 +24 -14
- data/vendor/liburing/src/Makefile +8 -7
- data/vendor/liburing/src/arch/aarch64/lib.h +48 -0
- data/vendor/liburing/src/arch/aarch64/syscall.h +0 -4
- data/vendor/liburing/src/arch/generic/lib.h +0 -4
- data/vendor/liburing/src/arch/generic/syscall.h +29 -16
- data/vendor/liburing/src/arch/syscall-defs.h +41 -14
- data/vendor/liburing/src/arch/x86/lib.h +0 -21
- data/vendor/liburing/src/arch/x86/syscall.h +146 -10
- data/vendor/liburing/src/include/liburing/io_uring.h +245 -5
- data/vendor/liburing/src/include/liburing.h +468 -35
- data/vendor/liburing/src/int_flags.h +1 -0
- data/vendor/liburing/src/lib.h +20 -16
- data/vendor/liburing/src/liburing.map +16 -0
- data/vendor/liburing/src/nolibc.c +1 -1
- data/vendor/liburing/src/queue.c +87 -55
- data/vendor/liburing/src/register.c +129 -53
- data/vendor/liburing/src/setup.c +65 -28
- data/vendor/liburing/src/syscall.c +14 -32
- data/vendor/liburing/src/syscall.h +12 -64
- data/vendor/liburing/test/{232c93d07b74-test.c → 232c93d07b74.c} +8 -9
- data/vendor/liburing/test/{35fa71a030ca-test.c → 35fa71a030ca.c} +4 -4
- data/vendor/liburing/test/{500f9fbadef8-test.c → 500f9fbadef8.c} +7 -7
- data/vendor/liburing/test/{7ad0e4b2f83c-test.c → 7ad0e4b2f83c.c} +8 -7
- data/vendor/liburing/test/{8a9973408177-test.c → 8a9973408177.c} +4 -3
- data/vendor/liburing/test/{917257daa0fe-test.c → 917257daa0fe.c} +3 -2
- data/vendor/liburing/test/Makefile +60 -62
- data/vendor/liburing/test/{a0908ae19763-test.c → a0908ae19763.c} +3 -2
- data/vendor/liburing/test/{a4c0b3decb33-test.c → a4c0b3decb33.c} +3 -2
- data/vendor/liburing/test/accept-link.c +5 -4
- data/vendor/liburing/test/accept-reuse.c +17 -16
- data/vendor/liburing/test/accept-test.c +14 -10
- data/vendor/liburing/test/accept.c +529 -107
- data/vendor/liburing/test/across-fork.c +7 -6
- data/vendor/liburing/test/{b19062a56726-test.c → b19062a56726.c} +3 -2
- data/vendor/liburing/test/{b5837bd5311d-test.c → b5837bd5311d.c} +10 -9
- data/vendor/liburing/test/buf-ring.c +420 -0
- data/vendor/liburing/test/{ce593a6c480a-test.c → ce593a6c480a.c} +15 -12
- data/vendor/liburing/test/connect.c +8 -7
- data/vendor/liburing/test/cq-full.c +5 -4
- data/vendor/liburing/test/cq-overflow.c +242 -12
- data/vendor/liburing/test/cq-peek-batch.c +5 -4
- data/vendor/liburing/test/cq-ready.c +5 -4
- data/vendor/liburing/test/cq-size.c +5 -4
- data/vendor/liburing/test/{d4ae271dfaae-test.c → d4ae271dfaae.c} +2 -2
- data/vendor/liburing/test/{d77a67ed5f27-test.c → d77a67ed5f27.c} +6 -6
- data/vendor/liburing/test/defer-taskrun.c +336 -0
- data/vendor/liburing/test/defer.c +26 -14
- data/vendor/liburing/test/double-poll-crash.c +15 -5
- data/vendor/liburing/test/drop-submit.c +5 -3
- data/vendor/liburing/test/{eeed8b54e0df-test.c → eeed8b54e0df.c} +7 -6
- data/vendor/liburing/test/empty-eownerdead.c +4 -4
- data/vendor/liburing/test/eventfd-disable.c +48 -20
- data/vendor/liburing/test/eventfd-reg.c +10 -9
- data/vendor/liburing/test/eventfd-ring.c +13 -12
- data/vendor/liburing/test/eventfd.c +13 -12
- data/vendor/liburing/test/exit-no-cleanup.c +1 -1
- data/vendor/liburing/test/fadvise.c +3 -3
- data/vendor/liburing/test/fallocate.c +16 -9
- data/vendor/liburing/test/{fc2a85cb02ef-test.c → fc2a85cb02ef.c} +4 -3
- data/vendor/liburing/test/fd-pass.c +187 -0
- data/vendor/liburing/test/file-register.c +302 -36
- data/vendor/liburing/test/file-update.c +62 -4
- data/vendor/liburing/test/file-verify.c +6 -2
- data/vendor/liburing/test/files-exit-hang-poll.c +11 -25
- data/vendor/liburing/test/files-exit-hang-timeout.c +13 -10
- data/vendor/liburing/test/fixed-buf-iter.c +115 -0
- data/vendor/liburing/test/fixed-link.c +10 -10
- data/vendor/liburing/test/fixed-reuse.c +160 -0
- data/vendor/liburing/test/fpos.c +6 -3
- data/vendor/liburing/test/fsync.c +3 -3
- data/vendor/liburing/test/hardlink.c +10 -6
- data/vendor/liburing/test/helpers.c +137 -4
- data/vendor/liburing/test/helpers.h +27 -0
- data/vendor/liburing/test/io-cancel.c +16 -11
- data/vendor/liburing/test/io_uring_enter.c +46 -81
- data/vendor/liburing/test/io_uring_passthrough.c +451 -0
- data/vendor/liburing/test/io_uring_register.c +59 -229
- data/vendor/liburing/test/io_uring_setup.c +24 -29
- data/vendor/liburing/test/iopoll-leak.c +85 -0
- data/vendor/liburing/test/iopoll.c +16 -9
- data/vendor/liburing/test/lfs-openat-write.c +3 -1
- data/vendor/liburing/test/link-timeout.c +4 -3
- data/vendor/liburing/test/link.c +8 -7
- data/vendor/liburing/test/madvise.c +2 -2
- data/vendor/liburing/test/mkdir.c +9 -5
- data/vendor/liburing/test/msg-ring.c +46 -20
- data/vendor/liburing/test/multicqes_drain.c +51 -12
- data/vendor/liburing/test/nolibc.c +60 -0
- data/vendor/liburing/test/nop.c +78 -16
- data/vendor/liburing/test/nvme.h +168 -0
- data/vendor/liburing/test/open-direct-link.c +188 -0
- data/vendor/liburing/test/open-direct-pick.c +180 -0
- data/vendor/liburing/test/openat2.c +3 -3
- data/vendor/liburing/test/poll-cancel-all.c +472 -0
- data/vendor/liburing/test/poll-link.c +9 -18
- data/vendor/liburing/test/poll-mshot-overflow.c +162 -0
- data/vendor/liburing/test/poll-mshot-update.c +83 -33
- data/vendor/liburing/test/pollfree.c +2 -2
- data/vendor/liburing/test/read-before-exit.c +112 -0
- data/vendor/liburing/test/read-write.c +83 -1
- data/vendor/liburing/test/recv-msgall-stream.c +398 -0
- data/vendor/liburing/test/recv-msgall.c +265 -0
- data/vendor/liburing/test/recv-multishot.c +505 -0
- data/vendor/liburing/test/rename.c +2 -5
- data/vendor/liburing/test/ring-leak.c +97 -0
- data/vendor/liburing/test/ringbuf-read.c +200 -0
- data/vendor/liburing/test/rsrc_tags.c +25 -13
- data/vendor/liburing/test/runtests-quiet.sh +11 -0
- data/vendor/liburing/test/runtests.sh +18 -20
- data/vendor/liburing/test/rw_merge_test.c +3 -2
- data/vendor/liburing/test/send-zerocopy.c +684 -0
- data/vendor/liburing/test/send_recv.c +49 -2
- data/vendor/liburing/test/send_recvmsg.c +165 -55
- data/vendor/liburing/test/shutdown.c +3 -4
- data/vendor/liburing/test/sigfd-deadlock.c +22 -8
- data/vendor/liburing/test/single-issuer.c +171 -0
- data/vendor/liburing/test/socket-rw-eagain.c +2 -12
- data/vendor/liburing/test/socket-rw-offset.c +2 -11
- data/vendor/liburing/test/socket-rw.c +2 -11
- data/vendor/liburing/test/socket.c +409 -0
- data/vendor/liburing/test/sq-poll-dup.c +1 -1
- data/vendor/liburing/test/sq-poll-share.c +1 -1
- data/vendor/liburing/test/statx.c +2 -2
- data/vendor/liburing/test/submit-and-wait.c +108 -0
- data/vendor/liburing/test/submit-link-fail.c +5 -3
- data/vendor/liburing/test/submit-reuse.c +0 -2
- data/vendor/liburing/test/sync-cancel.c +235 -0
- data/vendor/liburing/test/test.h +35 -0
- data/vendor/liburing/test/timeout-overflow.c +11 -11
- data/vendor/liburing/test/timeout.c +7 -7
- data/vendor/liburing/test/tty-write-dpoll.c +60 -0
- data/vendor/liburing/test/unlink.c +1 -1
- data/vendor/liburing/test/xattr.c +425 -0
- metadata +160 -52
- data/Gemfile.lock +0 -78
@@ -4,24 +4,24 @@
|
|
4
4
|
.\"
|
5
5
|
.TH io_uring_prep_writev2 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
|
6
6
|
.SH NAME
|
7
|
-
io_uring_prep_writev2
|
8
|
-
|
7
|
+
io_uring_prep_writev2 \- prepare vector I/O write request with flags
|
9
8
|
.SH SYNOPSIS
|
10
9
|
.nf
|
11
|
-
.
|
10
|
+
.B #include <sys/uio.h>
|
11
|
+
.B #include <liburing.h>
|
12
12
|
.PP
|
13
|
-
.BI "void io_uring_prep_writev2(struct io_uring_sqe *sqe,"
|
14
|
-
.BI " int fd,"
|
15
|
-
.BI " const struct iovec *iovecs,"
|
16
|
-
.BI " unsigned nr_vecs,"
|
17
|
-
.BI " __u64 offset,"
|
18
|
-
.BI " int flags)"
|
13
|
+
.BI "void io_uring_prep_writev2(struct io_uring_sqe *" sqe ","
|
14
|
+
.BI " int " fd ","
|
15
|
+
.BI " const struct iovec *" iovecs ","
|
16
|
+
.BI " unsigned " nr_vecs ","
|
17
|
+
.BI " __u64 " offset ","
|
18
|
+
.BI " int " flags ");"
|
19
19
|
.fi
|
20
|
-
.PP
|
21
20
|
.SH DESCRIPTION
|
22
21
|
.PP
|
23
|
-
The
|
24
|
-
|
22
|
+
The
|
23
|
+
.BR io_uring_prep_writev2 (3)
|
24
|
+
prepares a vectored IO write request. The submission queue entry
|
25
25
|
.I sqe
|
26
26
|
is setup to use the file descriptor
|
27
27
|
.I fd
|
@@ -30,7 +30,7 @@ to start writing
|
|
30
30
|
from the
|
31
31
|
.I iovecs
|
32
32
|
array at the specified
|
33
|
-
.
|
33
|
+
.IR offset .
|
34
34
|
The behavior of the function can be controlled with the
|
35
35
|
.I flags
|
36
36
|
parameter.
|
@@ -58,21 +58,54 @@ per-IO O_APPEND
|
|
58
58
|
|
59
59
|
.P
|
60
60
|
On files that support seeking, if the offset is set to
|
61
|
-
.
|
61
|
+
.BR -1 ,
|
62
62
|
the write operation commences at the file offset, and the file offset is
|
63
63
|
incremented by the number of bytes written. See
|
64
64
|
.BR write (2)
|
65
65
|
for more details. Note that for an async API, reading and updating the
|
66
66
|
current file offset may result in unpredictable behavior, unless access
|
67
|
-
to the file is serialized. It is not encouraged to use this feature
|
67
|
+
to the file is serialized. It is not encouraged to use this feature if it's
|
68
68
|
possible to provide the desired IO offset from the application or library.
|
69
69
|
|
70
|
-
On files that are not capable of seeking, the offset
|
70
|
+
On files that are not capable of seeking, the offset must be 0 or -1.
|
71
71
|
|
72
72
|
After the write has been prepared, it can be submitted with one of the submit
|
73
73
|
functions.
|
74
74
|
|
75
75
|
.SH RETURN VALUE
|
76
76
|
None
|
77
|
+
.SH ERRORS
|
78
|
+
The CQE
|
79
|
+
.I res
|
80
|
+
field will contain the result of the operation. See the related man page for
|
81
|
+
details on possible values. Note that where synchronous system calls will return
|
82
|
+
.B -1
|
83
|
+
on failure and set
|
84
|
+
.I errno
|
85
|
+
to the actual error value, io_uring never uses
|
86
|
+
.IR errno .
|
87
|
+
Instead it returns the negated
|
88
|
+
.I errno
|
89
|
+
directly in the CQE
|
90
|
+
.I res
|
91
|
+
field.
|
92
|
+
.SH NOTES
|
93
|
+
Unless an application explicitly needs to pass in more than iovec, it is more
|
94
|
+
efficient to use
|
95
|
+
.BR io_uring_prep_write (3)
|
96
|
+
rather than this function, as no state has to be maintained for a
|
97
|
+
non-vectored IO request.
|
98
|
+
As with any request that passes in data in a struct, that data must remain
|
99
|
+
valid until the request has been successfully submitted. It need not remain
|
100
|
+
valid until completion. Once a request has been submitted, the in-kernel
|
101
|
+
state is stable. Very early kernels (5.4 and earlier) required state to be
|
102
|
+
stable until the completion occurred. Applications can test for this
|
103
|
+
behavior by inspecting the
|
104
|
+
.B IORING_FEAT_SUBMIT_STABLE
|
105
|
+
flag passed back from
|
106
|
+
.BR io_uring_queue_init_params (3).
|
77
107
|
.SH SEE ALSO
|
78
|
-
.BR io_uring_get_sqe (3),
|
108
|
+
.BR io_uring_get_sqe (3),
|
109
|
+
.BR io_uring_prep_write (3),
|
110
|
+
.BR io_uring_prep_writev (3),
|
111
|
+
.BR io_uring_submit (3)
|
@@ -5,14 +5,13 @@
|
|
5
5
|
.\"
|
6
6
|
.TH io_uring_queue_exit 3 "July 10, 2020" "liburing-0.7" "liburing Manual"
|
7
7
|
.SH NAME
|
8
|
-
io_uring_queue_exit
|
8
|
+
io_uring_queue_exit \- tear down io_uring submission and completion queues
|
9
9
|
.SH SYNOPSIS
|
10
10
|
.nf
|
11
|
-
.
|
11
|
+
.B #include <liburing.h>
|
12
12
|
.PP
|
13
|
-
.BI "void io_uring_queue_exit(struct io_uring * ring );"
|
13
|
+
.BI "void io_uring_queue_exit(struct io_uring *" ring ");"
|
14
14
|
.fi
|
15
|
-
.PP
|
16
15
|
.SH DESCRIPTION
|
17
16
|
.PP
|
18
17
|
.BR io_uring_queue_exit (3)
|
@@ -5,40 +5,85 @@
|
|
5
5
|
.\"
|
6
6
|
.TH io_uring_queue_init 3 "July 10, 2020" "liburing-0.7" "liburing Manual"
|
7
7
|
.SH NAME
|
8
|
-
io_uring_queue_init
|
8
|
+
io_uring_queue_init \- setup io_uring submission and completion queues
|
9
9
|
.SH SYNOPSIS
|
10
10
|
.nf
|
11
|
-
.
|
11
|
+
.B #include <liburing.h>
|
12
12
|
.PP
|
13
|
-
.BI "int io_uring_queue_init(unsigned " entries ",
|
14
|
-
.BI "
|
15
|
-
.
|
13
|
+
.BI "int io_uring_queue_init(unsigned " entries ","
|
14
|
+
.BI " struct io_uring *" ring ","
|
15
|
+
.BI " unsigned " flags ");"
|
16
16
|
.PP
|
17
|
+
.BI "int io_uring_queue_init_params(unsigned " entries ","
|
18
|
+
.BI " struct io_uring *" ring ","
|
19
|
+
.BI " struct io_uring_params *" params ");"
|
20
|
+
.fi
|
17
21
|
.SH DESCRIPTION
|
18
22
|
.PP
|
19
|
-
The
|
20
|
-
|
23
|
+
The
|
24
|
+
.BR io_uring_queue_init (3)
|
25
|
+
function executes the
|
26
|
+
.BR io_uring_setup (2)
|
27
|
+
system call to initialize the submission and completion queues in the kernel
|
28
|
+
with at least
|
21
29
|
.I entries
|
22
|
-
entries and then maps the resulting file descriptor to
|
23
|
-
application and the kernel.
|
30
|
+
entries in the submission queue and then maps the resulting file descriptor to
|
31
|
+
memory shared between the application and the kernel.
|
24
32
|
|
25
|
-
|
33
|
+
By default, the CQ ring will have twice the number of entries as specified by
|
34
|
+
.I entries
|
35
|
+
for the SQ ring. This is adequate for regular file or storage workloads, but
|
36
|
+
may be too small networked workloads. The SQ ring entries do not impose a limit
|
37
|
+
on the number of in-flight requests that the ring can support, it merely limits
|
38
|
+
the number that can be submitted to the kernel in one go (batch). if the CQ
|
39
|
+
ring overflows, e.g. more entries are generated than fits in the ring before the
|
40
|
+
application can reap them, then the ring enters a CQ ring overflow state. This
|
41
|
+
is indicated by
|
42
|
+
.B IORING_SQ_CQ_OVERFLOW
|
43
|
+
being set in the SQ ring flags. Unless the kernel runs out of available memory,
|
44
|
+
entries are not dropped, but it is a much slower completion path and will slow
|
45
|
+
down request processing. For that reason it should be avoided and the CQ
|
46
|
+
ring sized appropriately for the workload. Setting
|
47
|
+
.I cq_entries
|
48
|
+
in
|
49
|
+
.I struct io_uring_params
|
50
|
+
will tell the kernel to allocate this many entries for the CQ ring, independent
|
51
|
+
of the SQ ring size in given in
|
52
|
+
.IR entries .
|
53
|
+
If the value isn't a power of 2, it will be rounded up to the nearest power of
|
54
|
+
2.
|
55
|
+
|
56
|
+
On success,
|
57
|
+
.BR io_uring_queue_init (3)
|
58
|
+
returns 0 and
|
26
59
|
.I ring
|
27
60
|
will point to the shared memory containing the io_uring queues. On failure
|
28
|
-
-errno
|
61
|
+
.BR -errno
|
62
|
+
is returned.
|
29
63
|
|
30
64
|
.I flags
|
31
|
-
will be passed through to the io_uring_setup syscall (see
|
65
|
+
will be passed through to the io_uring_setup syscall (see
|
32
66
|
.BR io_uring_setup (2)).
|
33
67
|
|
68
|
+
If the
|
69
|
+
.BR io_uring_queue_init_params (3)
|
70
|
+
variant is used, then the parameters indicated by
|
71
|
+
.I params
|
72
|
+
will be passed straight through to the
|
73
|
+
.BR io_uring_setup (2)
|
74
|
+
system call.
|
75
|
+
|
34
76
|
On success, the resources held by
|
35
77
|
.I ring
|
36
78
|
should be released via a corresponding call to
|
37
79
|
.BR io_uring_queue_exit (3).
|
38
80
|
.SH RETURN VALUE
|
39
81
|
.BR io_uring_queue_init (3)
|
40
|
-
returns 0 on success and
|
82
|
+
returns 0 on success and
|
83
|
+
.BR -errno
|
84
|
+
on failure.
|
41
85
|
.SH SEE ALSO
|
42
86
|
.BR io_uring_setup (2),
|
87
|
+
.BR io_uring_register_ring_fd (3),
|
43
88
|
.BR mmap (2),
|
44
89
|
.BR io_uring_queue_exit (3)
|
@@ -0,0 +1 @@
|
|
1
|
+
io_uring_queue_init.3
|
@@ -0,0 +1 @@
|
|
1
|
+
io_uring_recvmsg_out.3
|
@@ -0,0 +1 @@
|
|
1
|
+
io_uring_recvmsg_out.3
|
@@ -0,0 +1 @@
|
|
1
|
+
io_uring_recvmsg_out.3
|
@@ -0,0 +1,78 @@
|
|
1
|
+
.\" Copyright (C), 2022 Dylan Yudaken <dylany@fb.com>
|
2
|
+
.\"
|
3
|
+
.\" SPDX-License-Identifier: LGPL-2.0-or-later
|
4
|
+
.\"
|
5
|
+
.TH io_uring_recvmsg_out 3 "Julyu 26, 2022" "liburing-2.2" "liburing Manual"
|
6
|
+
.SH NAME
|
7
|
+
io_uring_recvmsg_out - access data from multishot recvmsg
|
8
|
+
.SH SYNOPSIS
|
9
|
+
.nf
|
10
|
+
.B #include <liburing.h>
|
11
|
+
.PP
|
12
|
+
.BI "struct io_uring_recvmsg_out *io_uring_recvmsg_validate(void *" buf ","
|
13
|
+
.BI " int " buf_len ","
|
14
|
+
.BI " struct msghdr *" msgh ");"
|
15
|
+
.PP
|
16
|
+
.BI "void *io_uring_recvmsg_name(struct io_uring_recvmsg_out *" o ");"
|
17
|
+
.PP
|
18
|
+
.BI "struct cmsghdr *io_uring_recvmsg_cmsg_firsthdr(struct io_uring_recvmsg_out * " o ","
|
19
|
+
.BI " struct msghdr *" msgh ");"
|
20
|
+
.BI "struct cmsghdr *io_uring_recvmsg_cmsg_nexthdr(struct io_uring_recvmsg_out * " o ","
|
21
|
+
.BI " struct msghdr *" msgh ","
|
22
|
+
.BI " struct cmsghdr *" cmsg ");"
|
23
|
+
.PP
|
24
|
+
.BI "void *io_uring_recvmsg_payload(struct io_uring_recvmsg_out * " o ","
|
25
|
+
.BI " struct msghdr *" msgh ");"
|
26
|
+
.BI "unsigned int io_uring_recvmsg_payload_length(struct io_uring_recvmsg_out *" o ","
|
27
|
+
.BI " int " buf_len ","
|
28
|
+
.BI " struct msghdr *" msgh ");"
|
29
|
+
.PP
|
30
|
+
.fi
|
31
|
+
|
32
|
+
.SH DESCRIPTION
|
33
|
+
|
34
|
+
These functions are used to access data in the payload delivered by
|
35
|
+
.BR io_uring_prep_recv_multishot (3)
|
36
|
+
.
|
37
|
+
.PP
|
38
|
+
.BR io_uring_recvmsg_validate (3)
|
39
|
+
will validate a buffer delivered by
|
40
|
+
.BR io_uring_prep_recv_multishot (3)
|
41
|
+
and extract the
|
42
|
+
.I io_uring_recvmsg_out
|
43
|
+
if it is valid, returning a pointer to it or else NULL.
|
44
|
+
.PP
|
45
|
+
The structure is defined as follows:
|
46
|
+
.PP
|
47
|
+
.in +4n
|
48
|
+
.EX
|
49
|
+
|
50
|
+
struct io_uring_recvmsg_out {
|
51
|
+
__u32 namelen; /* Name byte count as would have been populated
|
52
|
+
* by recvmsg(2) */
|
53
|
+
__u32 controllen; /* Control byte count */
|
54
|
+
__u32 payloadlen; /* Payload byte count as would have been returned
|
55
|
+
* by recvmsg(2) */
|
56
|
+
__u32 flags; /* Flags result as would have been populated
|
57
|
+
* by recvmsg(2) */
|
58
|
+
};
|
59
|
+
|
60
|
+
.IP * 3
|
61
|
+
.BR io_uring_recvmsg_name (3)
|
62
|
+
returns a pointer to the name in the buffer.
|
63
|
+
.IP *
|
64
|
+
.BR io_uring_recvmsg_cmsg_firsthdr (3)
|
65
|
+
returns a pointer to the first cmsg in the buffer, or NULL.
|
66
|
+
.IP *
|
67
|
+
.BR io_uring_recvmsg_cmsg_nexthdr (3)
|
68
|
+
returns a pointer to the next cmsg in the buffer, or NULL.
|
69
|
+
.IP *
|
70
|
+
.BR io_uring_recvmsg_payload (3)
|
71
|
+
returns a pointer to the payload in the buffer.
|
72
|
+
.IP *
|
73
|
+
.BR io_uring_recvmsg_payload_length (3)
|
74
|
+
Calculates the usable payload length in bytes.
|
75
|
+
|
76
|
+
|
77
|
+
.SH "SEE ALSO"
|
78
|
+
.BR io_uring_prep_recv_multishot (3)
|
@@ -0,0 +1 @@
|
|
1
|
+
io_uring_recvmsg_out.3
|
@@ -0,0 +1 @@
|
|
1
|
+
io_uring_recvmsg_out.3
|
@@ -0,0 +1 @@
|
|
1
|
+
io_uring_recvmsg_out.3
|
@@ -3,12 +3,12 @@
|
|
3
3
|
.\"
|
4
4
|
.\" SPDX-License-Identifier: LGPL-2.0-or-later
|
5
5
|
.\"
|
6
|
-
.TH
|
6
|
+
.TH io_uring_register 2 2019-01-17 "Linux" "Linux Programmer's Manual"
|
7
7
|
.SH NAME
|
8
8
|
io_uring_register \- register files or user buffers for asynchronous I/O
|
9
9
|
.SH SYNOPSIS
|
10
10
|
.nf
|
11
|
-
.BR "#include <
|
11
|
+
.BR "#include <liburing.h>"
|
12
12
|
.PP
|
13
13
|
.BI "int io_uring_register(unsigned int " fd ", unsigned int " opcode ,
|
14
14
|
.BI " void *" arg ", unsigned int " nr_args );
|
@@ -18,7 +18,7 @@ io_uring_register \- register files or user buffers for asynchronous I/O
|
|
18
18
|
.PP
|
19
19
|
|
20
20
|
The
|
21
|
-
.BR io_uring_register ()
|
21
|
+
.BR io_uring_register (2)
|
22
22
|
system call registers resources (e.g. user buffers, files, eventfd,
|
23
23
|
personality, restrictions) for use in an
|
24
24
|
.BR io_uring (7)
|
@@ -85,7 +85,7 @@ region.
|
|
85
85
|
An application can increase or decrease the size or number of
|
86
86
|
registered buffers by first unregistering the existing buffers, and
|
87
87
|
then issuing a new call to
|
88
|
-
.BR io_uring_register ()
|
88
|
+
.BR io_uring_register (2)
|
89
89
|
with the new buffers.
|
90
90
|
|
91
91
|
Note that before 5.13 registering buffers would wait for the ring to idle.
|
@@ -328,7 +328,13 @@ registered through this operation.
|
|
328
328
|
.I arg
|
329
329
|
must contain a pointer to the eventfd file descriptor, and
|
330
330
|
.I nr_args
|
331
|
-
must be 1.
|
331
|
+
must be 1. Note that while io_uring generally takes care to avoid spurious
|
332
|
+
events, they can occur. Similarly, batched completions of CQEs may only trigger
|
333
|
+
a single eventfd notification even if multiple CQEs are posted. The application
|
334
|
+
should make no assumptions on number of events being available having a direct
|
335
|
+
correlation to eventfd notifications posted. An eventfd notification must thus
|
336
|
+
only be treated as a hint to check the CQ ring for completions. Available since
|
337
|
+
5.2.
|
332
338
|
|
333
339
|
An application can temporarily disable notifications, coming through the
|
334
340
|
registered eventfd, by setting the
|
@@ -422,7 +428,7 @@ array of
|
|
422
428
|
entries.
|
423
429
|
|
424
430
|
With an entry it is possible to allow an
|
425
|
-
.BR io_uring_register ()
|
431
|
+
.BR io_uring_register (2)
|
426
432
|
.I opcode,
|
427
433
|
or specify which
|
428
434
|
.I opcode
|
@@ -434,7 +440,7 @@ or require certain
|
|
434
440
|
to be specified (these flags must be set on each submission queue entry).
|
435
441
|
|
436
442
|
All the restrictions must be submitted with a single
|
437
|
-
.BR io_uring_register ()
|
443
|
+
.BR io_uring_register (2)
|
438
444
|
call and they are handled as an allowlist (opcodes and flags not registered,
|
439
445
|
are not allowed).
|
440
446
|
|
@@ -540,7 +546,7 @@ for the system call. This flag tells the kernel that a registered descriptor
|
|
540
546
|
is used rather than a real file descriptor.
|
541
547
|
|
542
548
|
Each thread or process using a ring must register the file descriptor directly
|
543
|
-
by issuing this request.
|
549
|
+
by issuing this request.
|
544
550
|
|
545
551
|
The maximum number of supported registered ring descriptors is currently
|
546
552
|
limited to
|
@@ -573,15 +579,149 @@ slot, making it available for future use.
|
|
573
579
|
|
574
580
|
Available since 5.18.
|
575
581
|
|
582
|
+
.TP
|
583
|
+
.B IORING_REGISTER_PBUF_RING
|
584
|
+
Registers a shared buffer ring to be used with provided buffers. This is a
|
585
|
+
newer alternative to using
|
586
|
+
.B IORING_OP_PROVIDE_BUFFERS
|
587
|
+
which is more efficient, to be used with request types that support the
|
588
|
+
.B IOSQE_BUFFER_SELECT
|
589
|
+
flag.
|
590
|
+
|
591
|
+
The
|
592
|
+
.I arg
|
593
|
+
argument must be filled in with the appropriate information. It looks as
|
594
|
+
follows:
|
595
|
+
.PP
|
596
|
+
.in +12n
|
597
|
+
.EX
|
598
|
+
struct io_uring_buf_reg {
|
599
|
+
__u64 ring_addr;
|
600
|
+
__u32 ring_entries;
|
601
|
+
__u16 bgid;
|
602
|
+
__u16 pad;
|
603
|
+
__u64 resv[3];
|
604
|
+
};
|
605
|
+
.EE
|
606
|
+
.in
|
607
|
+
.PP
|
608
|
+
.in +8n
|
609
|
+
The
|
610
|
+
.I ring_addr
|
611
|
+
field must contain the address to the memory allocated to fit this ring.
|
612
|
+
The memory must be page aligned and hence allocated appropriately using eg
|
613
|
+
.BR posix_memalign (3)
|
614
|
+
or similar. The size of the ring is the product of
|
615
|
+
.I ring_entries
|
616
|
+
and the size of
|
617
|
+
.IR "struct io_uring_buf" .
|
618
|
+
.I ring_entries
|
619
|
+
is the desired size of the ring, and must be a power-of-2 in size. The maximum
|
620
|
+
size allowed is 2^15 (32768).
|
621
|
+
.I bgid
|
622
|
+
is the buffer group ID associated with this ring. SQEs that select a buffer
|
623
|
+
has a buffer group associated with them in their
|
624
|
+
.I buf_group
|
625
|
+
field, and the associated CQE will have
|
626
|
+
.B IORING_CQE_F_BUFFER
|
627
|
+
set in their
|
628
|
+
.I flags
|
629
|
+
member, which will also contain the specific ID of the buffer selected. The rest
|
630
|
+
of the fields are reserved and must be cleared to zero.
|
631
|
+
|
632
|
+
The
|
633
|
+
.I flags
|
634
|
+
argument is currently unused and must be set to zero.
|
635
|
+
|
636
|
+
.i nr_args
|
637
|
+
must be set to 1.
|
638
|
+
|
639
|
+
Also see
|
640
|
+
.BR io_uring_register_buf_ring (3)
|
641
|
+
for more details. Available since 5.19.
|
642
|
+
|
643
|
+
.TP
|
644
|
+
.B IORING_UNREGISTER_PBUF_RING
|
645
|
+
Unregister a previously registered provided buffer ring.
|
646
|
+
.I arg
|
647
|
+
must be set to the address of a struct io_uring_buf_reg, with just the
|
648
|
+
.I bgid
|
649
|
+
field set to the buffer group ID of the previously registered provided buffer
|
650
|
+
group.
|
651
|
+
.I nr_args
|
652
|
+
must be set to 1. Also see
|
653
|
+
.B IORING_REGISTER_PBUF_RING .
|
654
|
+
|
655
|
+
Available since 5.19.
|
656
|
+
|
657
|
+
.TP
|
658
|
+
.B IORING_REGISTER_SYNC_CANCEL
|
659
|
+
Performs a synchronous cancelation request, which works in a similar fashion to
|
660
|
+
.B IORING_OP_ASYNC_CANCEL
|
661
|
+
except it completes inline. This can be useful for scenarios where cancelations
|
662
|
+
should happen synchronously, rather than needing to issue an SQE and wait for
|
663
|
+
completion of that specific CQE.
|
664
|
+
|
665
|
+
.I arg
|
666
|
+
must be set to a pointer to a struct io_uring_sync_cancel_reg structure, with
|
667
|
+
the details filled in for what request(s) to target for cancelation. See
|
668
|
+
.BR io_uring_register_sync_cancel (3)
|
669
|
+
for details on that. The return values are the same, except they are passed
|
670
|
+
back synchronously rather than through the CQE
|
671
|
+
.I res
|
672
|
+
field.
|
673
|
+
.I nr_args
|
674
|
+
must be set to 1.
|
675
|
+
|
676
|
+
Available since 6.0.
|
677
|
+
|
678
|
+
.TP
|
679
|
+
.B IORING_REGISTER_FILE_ALLOC_RANGE
|
680
|
+
sets the allowable range for fixed file index allocations within the
|
681
|
+
kernel. When requests that can instantiate a new fixed file are used with
|
682
|
+
.B IORING_FILE_INDEX_ALLOC ,
|
683
|
+
the application is asking the kernel to allocate a new fixed file descriptor
|
684
|
+
rather than pass in a specific value for one. By default, the kernel will
|
685
|
+
pick any available fixed file descriptor within the range available.
|
686
|
+
This effectively allows the application to set aside a range just for dynamic
|
687
|
+
allocations, with the remainder being used for specific values.
|
688
|
+
|
689
|
+
.I nr_args
|
690
|
+
must be set to 1 and
|
691
|
+
.I arg
|
692
|
+
must be set to a pointer to a struct io_uring_file_index_range:
|
693
|
+
.PP
|
694
|
+
.in +12n
|
695
|
+
.EX
|
696
|
+
struct io_uring_file_index_range {
|
697
|
+
__u32 off;
|
698
|
+
__u32 len;
|
699
|
+
__u64 resv;
|
700
|
+
};
|
701
|
+
.EE
|
702
|
+
.in
|
703
|
+
.PP
|
704
|
+
.in +8n
|
705
|
+
with
|
706
|
+
.I off
|
707
|
+
being set to the starting value for the range, and
|
708
|
+
.I len
|
709
|
+
being set to the number of descriptors. The reserved
|
710
|
+
.I resv
|
711
|
+
field must be cleared to zero.
|
712
|
+
|
713
|
+
The application must have registered a file table first.
|
714
|
+
|
715
|
+
Available since 6.0.
|
716
|
+
|
576
717
|
.SH RETURN VALUE
|
577
718
|
|
578
719
|
On success,
|
579
|
-
.BR io_uring_register ()
|
580
|
-
returns 0. On error,
|
581
|
-
|
582
|
-
is returned, and
|
720
|
+
.BR io_uring_register (2)
|
721
|
+
returns 0. On error, a negative error code is returned. The caller should not
|
722
|
+
rely on
|
583
723
|
.I errno
|
584
|
-
|
724
|
+
variable.
|
585
725
|
|
586
726
|
.SH ERRORS
|
587
727
|
.TP
|
@@ -0,0 +1,140 @@
|
|
1
|
+
.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
|
2
|
+
.\"
|
3
|
+
.\" SPDX-License-Identifier: LGPL-2.0-or-later
|
4
|
+
.\"
|
5
|
+
.TH io_uring_register_buf_ring 3 "May 18, 2022" "liburing-2.2" "liburing Manual"
|
6
|
+
.SH NAME
|
7
|
+
io_uring_register_buf_ring \- register buffer ring for provided buffers
|
8
|
+
.SH SYNOPSIS
|
9
|
+
.nf
|
10
|
+
.B #include <liburing.h>
|
11
|
+
.PP
|
12
|
+
.BI "int io_uring_register_buf_ring(struct io_uring *" ring ",
|
13
|
+
.BI " struct io_uring_buf_reg *" reg ",
|
14
|
+
.BI " unsigned int " flags ");"
|
15
|
+
.BI "
|
16
|
+
.fi
|
17
|
+
.SH DESCRIPTION
|
18
|
+
.PP
|
19
|
+
The
|
20
|
+
.BR io_uring_register_buf_ring (3)
|
21
|
+
function registers a shared buffer ring to be used with provided buffers. For
|
22
|
+
the request types that support it, provided buffers are given to the ring and
|
23
|
+
one is selected by a request if it has
|
24
|
+
.B IOSQE_BUFFER_SELECT
|
25
|
+
set in the SQE
|
26
|
+
.IR flags ,
|
27
|
+
when the request is ready to receive data. This allows both clear ownership
|
28
|
+
of the buffer lifetime, and a way to have more read/receive type of operations
|
29
|
+
in flight than buffers available.
|
30
|
+
|
31
|
+
The
|
32
|
+
.I reg
|
33
|
+
argument must be filled in with the appropriate information. It looks as
|
34
|
+
follows:
|
35
|
+
.PP
|
36
|
+
.in +4n
|
37
|
+
.EX
|
38
|
+
struct io_uring_buf_reg {
|
39
|
+
__u64 ring_addr;
|
40
|
+
__u32 ring_entries;
|
41
|
+
__u16 bgid;
|
42
|
+
__u16 pad;
|
43
|
+
__u64 resv[3];
|
44
|
+
};
|
45
|
+
.EE
|
46
|
+
.in
|
47
|
+
.PP
|
48
|
+
The
|
49
|
+
.I ring_addr
|
50
|
+
field must contain the address to the memory allocated to fit this ring.
|
51
|
+
The memory must be page aligned and hence allocated appropriately using eg
|
52
|
+
.BR posix_memalign (3)
|
53
|
+
or similar. The size of the ring is the product of
|
54
|
+
.I ring_entries
|
55
|
+
and the size of
|
56
|
+
.IR "struct io_uring_buf" .
|
57
|
+
.I ring_entries
|
58
|
+
is the desired size of the ring, and must be a power-of-2 in size. The maximum
|
59
|
+
size allowed is 2^15 (32768).
|
60
|
+
.I bgid
|
61
|
+
is the buffer group ID associated with this ring. SQEs that select a buffer
|
62
|
+
has a buffer group associated with them in their
|
63
|
+
.I buf_group
|
64
|
+
field, and the associated CQE will have
|
65
|
+
.B IORING_CQE_F_BUFFER
|
66
|
+
set in their
|
67
|
+
.I flags
|
68
|
+
member, which will also contain the specific ID of the buffer selected. The rest
|
69
|
+
of the fields are reserved and must be cleared to zero.
|
70
|
+
|
71
|
+
The
|
72
|
+
.I flags
|
73
|
+
argument is currently unused and must be set to zero.
|
74
|
+
|
75
|
+
A shared buffer ring looks as follows:
|
76
|
+
.PP
|
77
|
+
.in +4n
|
78
|
+
.EX
|
79
|
+
struct io_uring_buf_ring {
|
80
|
+
union {
|
81
|
+
struct {
|
82
|
+
__u64 resv1;
|
83
|
+
__u32 resv2;
|
84
|
+
__u16 resv3;
|
85
|
+
__u16 tail;
|
86
|
+
};
|
87
|
+
struct io_uring_buf bufs[0];
|
88
|
+
};
|
89
|
+
};
|
90
|
+
.EE
|
91
|
+
.in
|
92
|
+
.PP
|
93
|
+
where
|
94
|
+
.I tail
|
95
|
+
is the index at which the application can insert new buffers for consumption
|
96
|
+
by requests, and
|
97
|
+
.I struct io_uring_buf
|
98
|
+
is buffer definition:
|
99
|
+
.PP
|
100
|
+
.in +4n
|
101
|
+
.EX
|
102
|
+
struct io_uring_buf {
|
103
|
+
__u64 addr;
|
104
|
+
__u32 len;
|
105
|
+
__u16 bid;
|
106
|
+
__u16 resv;
|
107
|
+
};
|
108
|
+
.EE
|
109
|
+
.in
|
110
|
+
.PP
|
111
|
+
where
|
112
|
+
.I addr
|
113
|
+
is the address for the buffer,
|
114
|
+
.I len
|
115
|
+
is the length of the buffer in bytes, and
|
116
|
+
.I bid
|
117
|
+
is the buffer ID that will be returned in the CQE once consumed.
|
118
|
+
|
119
|
+
Reserved fields must not be touched. Applications must use
|
120
|
+
.BR io_uring_buf_ring_init (3)
|
121
|
+
to initialise the buffer ring. Applications may use
|
122
|
+
.BR io_uring_buf_ring_add (3)
|
123
|
+
and
|
124
|
+
.BR io_uring_buf_ring_advance (3)
|
125
|
+
or
|
126
|
+
.BR io_uring_buf_ring_advance (3)
|
127
|
+
to provide buffers, which will set these fields and update the tail.
|
128
|
+
|
129
|
+
Available since 5.19.
|
130
|
+
|
131
|
+
.SH RETURN VALUE
|
132
|
+
On success
|
133
|
+
.BR io_uring_register_buf_ring (3)
|
134
|
+
returns 0. On failure it returns
|
135
|
+
.BR -errno .
|
136
|
+
.SH SEE ALSO
|
137
|
+
.BR io_uring_buf_ring_init (3),
|
138
|
+
.BR io_uring_buf_ring_add (3),
|
139
|
+
.BR io_uring_buf_ring_advance (3),
|
140
|
+
.BR io_uring_buf_ring_cq_advance (3)
|