plucky (3) io_uring_queue_init_params.3.gz

NAME

       io_uring_queue_init - setup io_uring submission and completion queues

SYNOPSIS

       #include <liburing.h>

       int io_uring_queue_init(unsigned entries,
                               struct io_uring *ring,
                               unsigned flags);

       int io_uring_queue_init_params(unsigned entries,
                                      struct io_uring *ring,
                                      struct io_uring_params *params);

       int io_uring_queue_init_mem(unsigned entries,
                                   struct io_uring *ring,
                                   struct io_uring_params *params,
                                   void *buf, size_t buf_size);

DESCRIPTION

       The  io_uring_queue_init(3)  function  executes  the  io_uring_setup(2)  system  call  to  initialize the
       submission and completion queues in the kernel with at least entries entries in the submission queue  and
       then maps the resulting file descriptor to memory shared between the application and the kernel.

       By  default,  the  CQ ring will have twice the number of entries as specified by entries for the SQ ring.
       This is adequate for regular file or storage workloads, but may be too small for 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 if the
       kernel supports IORING_FEAT_NODROP the ring enters a CQ ring overflow state. Otherwise it drops the  CQEs
       and  increments  cq.koverflow  in  struct io_uring with the number of CQEs dropped. The overflow state is
       indicated by 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 cq_entries in 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 entries.  If the value isn't a power  of  2,
       it will be rounded up to the nearest power of 2.

       On  success,  io_uring_queue_init(3)  returns  0  and ring will point to the shared memory containing the
       io_uring queues. On failure -errno is returned.

       flags will be passed through to the io_uring_setup syscall (see io_uring_setup(2)).

       The io_uring_queue_init_params(3)  and  io_uring_queue_init_mem(3)  variants  will  pass  the  parameters
       indicated by params straight through to the io_uring_setup(2) system call.

       The  io_uring_queue_init_mem(3) variant uses the provided buf with associated size buf_size as the memory
       for  the  ring,  using  the  IORING_SETUP_NO_MMAP  flag  to  io_uring_setup(2).   The  buffer  passed  to
       io_uring_queue_init_mem(3) must already be zeroed.  Typically, the caller should allocate a huge page and
       pass  that  in  to  io_uring_queue_init_mem(3).   Pages   allocated   by   mmap   are   already   zeroed.
       io_uring_queue_init_mem(3) returns the number of bytes used from the provided buffer, so that the app can
       reuse the buffer with the returned offset to put more rings in the same huge page.

       On  success,  the  resources  held  by  ring  should  be   released   via   a   corresponding   call   to
       io_uring_queue_exit(3).

RETURN VALUE

       io_uring_queue_init(3) and io_uring_queue_init_params(3) return 0 on success and -errno on failure.

       io_uring_queue_init_mem(3)  returns  the  number  of  bytes used from the provided buffer on success, and
       -errno on failure.

SEE ALSO

       io_uring_setup(2), io_uring_register_ring_fd(3), mmap(2), io_uring_queue_exit(3)