diff options
Diffstat (limited to 'man/io_uring_queue_init.3')
| -rw-r--r-- | man/io_uring_queue_init.3 | 71 |
1 files changed, 58 insertions, 13 deletions
diff --git a/man/io_uring_queue_init.3 b/man/io_uring_queue_init.3 index 1980fa4..086b70f 100644 --- a/man/io_uring_queue_init.3 +++ b/man/io_uring_queue_init.3 @@ -5,40 +5,85 @@ .\" .TH io_uring_queue_init 3 "July 10, 2020" "liburing-0.7" "liburing Manual" .SH NAME -io_uring_queue_init - setup io_uring submission and completion queues +io_uring_queue_init \- setup io_uring submission and completion queues .SH SYNOPSIS .nf -.BR "#include <liburing.h>" +.B #include <liburing.h> .PP -.BI "int io_uring_queue_init(unsigned " entries ", struct io_uring *" ring , -.BI " unsigned " flags ); -.fi +.BI "int io_uring_queue_init(unsigned " entries "," +.BI " struct io_uring *" ring "," +.BI " unsigned " flags ");" .PP +.BI "int io_uring_queue_init_params(unsigned " entries "," +.BI " struct io_uring *" ring "," +.BI " struct io_uring_params *" params ");" +.fi .SH DESCRIPTION .PP -The io_uring_queue_init() function executes the io_uring_setup syscall to -initialize the submission and completion queues in the kernel with at least +The +.BR io_uring_queue_init (3) +function executes the +.BR io_uring_setup (2) +system call to initialize the submission and completion queues in the kernel +with at least .I entries -entries and then maps the resulting file descriptor to memory shared between the -application and the kernel. +entries in the submission queue and then maps the resulting file descriptor to +memory shared between the application and the kernel. -On success io_uring_queue_init() returns 0 and +By default, the CQ ring will have twice the number of entries as specified by +.I entries +for the SQ ring. This is adequate for regular file or storage workloads, but +may be too small networked workloads. The SQ ring entries do not impose a limit +on the number of in-flight requests that the ring can support, it merely limits +the number that can be submitted to the kernel in one go (batch). if the CQ +ring overflows, e.g. more entries are generated than fits in the ring before the +application can reap them, then the ring enters a CQ ring overflow state. This +is indicated by +.B IORING_SQ_CQ_OVERFLOW +being set in the SQ ring flags. Unless the kernel runs out of available memory, +entries are not dropped, but it is a much slower completion path and will slow +down request processing. For that reason it should be avoided and the CQ +ring sized appropriately for the workload. Setting +.I cq_entries +in +.I struct io_uring_params +will tell the kernel to allocate this many entries for the CQ ring, independent +of the SQ ring size in given in +.IR entries . +If the value isn't a power of 2, it will be rounded up to the nearest power of +2. + +On success, +.BR io_uring_queue_init (3) +returns 0 and .I ring will point to the shared memory containing the io_uring queues. On failure --errno is returned. +.BR -errno +is returned. .I flags -will be passed through to the io_uring_setup syscall (see +will be passed through to the io_uring_setup syscall (see .BR io_uring_setup (2)). +If the +.BR io_uring_queue_init_params (3) +variant is used, then the parameters indicated by +.I params +will be passed straight through to the +.BR io_uring_setup (2) +system call. + On success, the resources held by .I ring should be released via a corresponding call to .BR io_uring_queue_exit (3). .SH RETURN VALUE .BR io_uring_queue_init (3) -returns 0 on success and -errno on failure. +returns 0 on success and +.BR -errno +on failure. .SH SEE ALSO .BR io_uring_setup (2), +.BR io_uring_register_ring_fd (3), .BR mmap (2), .BR io_uring_queue_exit (3) |