Class IOURingParams

  • All Implemented Interfaces:
    java.lang.AutoCloseable, org.lwjgl.system.NativeResource, org.lwjgl.system.Pointer

    public class IOURingParams
    extends org.lwjgl.system.Struct
    implements org.lwjgl.system.NativeResource
    Passed in for setup. Copied back with updated info on success.

    The flags, sq_thread_cpu, and sq_thread_idle fields are used to configure the io_uring instance. If no flags are specified, the io_uring instance is setup for interrupt driven I/O. I/O may be submitted using enter and can be reaped by polling the completion queue.

    The rest of the fields are filled in by the kernel, and provide the information necessary to memory map the submission queue, completion queue, and the array of submission queue entries.

    sq_off describes the offsets of various ring buffer fields. Taken together, sq_entries and sq_off provide all of the information necessary for accessing the submission queue ring buffer and the submission queue entry array. The submission queue can be mapped with a call like:

    
     ptr = mmap(0, sq_off.array + sq_entries * sizeof(__u32),
                PROT_READ|PROT_WRITE, MAP_SHARED|MAP_POPULATE,
                ring_fd, IORING_OFF_SQ_RING);

    where sq_off is the io_sqring_offsets structure, and ring_fd is the file descriptor returned from setup. The addition of sq_off.array to the length of the region accounts for the fact that the ring located at the end of the data structure. As an example, the ring buffer head pointer can be accessed by adding sq_off.head to the address returned from mmap(2):

    
     head = ptr + sq_off.head;

    The array of submission queue entries is mapped with:

    
     sqentries = mmap(0, sq_entries * sizeof(struct io_uring_sqe),
                      PROT_READ|PROT_WRITE, MAP_SHARED|MAP_POPULATE,
                      ring_fd, IORING_OFF_SQES);

    The completion queue is described by cq_entries and cq_off. The completion queue is simpler, since the entries are not separated from the queue itself, and can be mapped with:

    
     ptr = mmap(0, cq_off.cqes + cq_entries * sizeof(struct io_uring_cqe),        
                PROT_READ|PROT_WRITE, MAP_SHARED|MAP_POPULATE, ring_fd,
                IORING_OFF_CQ_RING);

    Layout

    
     struct io_uring_params {
         __u32 sq_entries();
         __u32 cq_entries;
         __u32 flags();
         __u32 sq_thread_cpu;
         __u32 sq_thread_idle;
         __u32 features();
         __u32 wq_fd;
         __u32 resv[3];
         struct io_sqring_offsets sq_off();
         struct io_cqring_offsets cq_off;
     }
    • Field Detail

      • SIZEOF

        The struct size in bytes.
      • ALIGNOF

        The struct alignment in bytes.
      • SQ_ENTRIES, CQ_ENTRIES, FLAGS, SQ_THREAD_CPU, SQ_THREAD_IDLE, FEATURES, WQ_FD, RESV, SQ_OFF, CQ_OFF

        The struct member offsets.
    • Constructor Detail

      • IOURingParams

        public IOURingParams​(java.nio.ByteBuffer container)
        Creates a IOURingParams instance at the current position of the specified ByteBuffer container. Changes to the buffer's content will be visible to the struct instance and vice versa.

        The created instance holds a strong reference to the container object.

    • Method Detail

      • sizeof

        public int sizeof()
        Specified by:
        sizeof in class org.lwjgl.system.Struct
      • sq_entries

        public int sq_entries()
        the number of submission queue entries allocated
      • cq_entries

        public int cq_entries()
        Returns:
        the value of the cq_entries field.
      • sq_thread_cpu

        public int sq_thread_cpu()
        Returns:
        the value of the sq_thread_cpu field.
      • sq_thread_idle

        public int sq_thread_idle()
        Returns:
        the value of the sq_thread_idle field.
      • wq_fd

        public int wq_fd()
        Returns:
        the value of the wq_fd field.
      • resv

        public java.nio.IntBuffer resv()
        Returns:
        a IntBuffer view of the resv field.
      • resv

        public int resv​(int index)
        Returns:
        the value at the specified index of the resv field.
      • sq_off

        public IOSQRingOffsets sq_off()
        The flags field is used by the kernel to communicate state information to the application. Currently, it is used to inform the application when a call to enter is necessary.

        The dropped member is incremented for each invalid submission queue entry encountered in the ring buffer.

        The head and tail track the ring buffer state. The tail is incremented by the application when submitting new I/O, and the head is incremented by the kernel when the I/O has been successfully submitted. Determining the index of the head or tail into the ring is accomplished by applying a mask:

        
         index = tail & ring_mask;
      • cq_entries

        public IOURingParams cq_entries​(int value)
        Sets the specified value to the cq_entries field.
      • sq_thread_cpu

        public IOURingParams sq_thread_cpu​(int value)
        Sets the specified value to the sq_thread_cpu field.
      • sq_thread_idle

        public IOURingParams sq_thread_idle​(int value)
        Sets the specified value to the sq_thread_idle field.
      • wq_fd

        public IOURingParams wq_fd​(int value)
        Sets the specified value to the wq_fd field.
      • resv

        public IOURingParams resv​(java.nio.IntBuffer value)
        Copies the specified IntBuffer to the resv field.
      • resv

        public IOURingParams resv​(int index,
                                  int value)
        Sets the specified value at the specified index of the resv field.
      • cq_off

        public IOURingParams cq_off​(java.util.function.Consumer<IOCQRingOffsets> consumer)
        Passes the cq_off field to the specified Consumer.
      • set

        public IOURingParams set​(int sq_entries,
                                 int cq_entries,
                                 int flags,
                                 int sq_thread_cpu,
                                 int sq_thread_idle,
                                 int features,
                                 int wq_fd,
                                 java.nio.IntBuffer resv,
                                 IOSQRingOffsets sq_off,
                                 IOCQRingOffsets cq_off)
        Initializes this struct with the specified values.
      • set

        public IOURingParams set​(IOURingParams src)
        Copies the specified struct data to this struct.
        Parameters:
        src - the source struct
        Returns:
        this struct
      • malloc

        public static IOURingParams malloc()
        Returns a new IOURingParams instance allocated with memAlloc. The instance must be explicitly freed.
      • calloc

        public static IOURingParams calloc()
        Returns a new IOURingParams instance allocated with memCalloc. The instance must be explicitly freed.
      • create

        public static IOURingParams create()
        Returns a new IOURingParams instance allocated with BufferUtils.
      • create

        public static IOURingParams create​(long address)
        Returns a new IOURingParams instance for the specified memory address.
      • createSafe

        @Nullable
        public static IOURingParams createSafe​(long address)
        Like create, but returns null if address is NULL.
      • malloc

        public static IOURingParams.Buffer malloc​(int capacity)
        Returns a new IOURingParams.Buffer instance allocated with memAlloc. The instance must be explicitly freed.
        Parameters:
        capacity - the buffer capacity
      • calloc

        public static IOURingParams.Buffer calloc​(int capacity)
        Returns a new IOURingParams.Buffer instance allocated with memCalloc. The instance must be explicitly freed.
        Parameters:
        capacity - the buffer capacity
      • create

        public static IOURingParams.Buffer create​(long address,
                                                  int capacity)
        Create a IOURingParams.Buffer instance at the specified memory.
        Parameters:
        address - the memory address
        capacity - the buffer capacity
      • createSafe

        @Nullable
        public static IOURingParams.Buffer createSafe​(long address,
                                                      int capacity)
        Like create, but returns null if address is NULL.
      • malloc

        public static IOURingParams malloc​(org.lwjgl.system.MemoryStack stack)
        Returns a new IOURingParams instance allocated on the specified MemoryStack.
        Parameters:
        stack - the stack from which to allocate
      • calloc

        public static IOURingParams calloc​(org.lwjgl.system.MemoryStack stack)
        Returns a new IOURingParams instance allocated on the specified MemoryStack and initializes all its bits to zero.
        Parameters:
        stack - the stack from which to allocate
      • malloc

        public static IOURingParams.Buffer malloc​(int capacity,
                                                  org.lwjgl.system.MemoryStack stack)
        Returns a new IOURingParams.Buffer instance allocated on the specified MemoryStack.
        Parameters:
        stack - the stack from which to allocate
        capacity - the buffer capacity
      • calloc

        public static IOURingParams.Buffer calloc​(int capacity,
                                                  org.lwjgl.system.MemoryStack stack)
        Returns a new IOURingParams.Buffer instance allocated on the specified MemoryStack and initializes all its bits to zero.
        Parameters:
        stack - the stack from which to allocate
        capacity - the buffer capacity
      • nsq_entries

        public static int nsq_entries​(long struct)
        Unsafe version of sq_entries().
      • ncq_entries

        public static int ncq_entries​(long struct)
        Unsafe version of cq_entries().
      • nflags

        public static int nflags​(long struct)
        Unsafe version of flags().
      • nsq_thread_cpu

        public static int nsq_thread_cpu​(long struct)
        Unsafe version of sq_thread_cpu().
      • nsq_thread_idle

        public static int nsq_thread_idle​(long struct)
        Unsafe version of sq_thread_idle().
      • nfeatures

        public static int nfeatures​(long struct)
        Unsafe version of features().
      • nwq_fd

        public static int nwq_fd​(long struct)
        Unsafe version of wq_fd().
      • nresv

        public static java.nio.IntBuffer nresv​(long struct)
        Unsafe version of resv().
      • nresv

        public static int nresv​(long struct,
                                int index)
        Unsafe version of resv.
      • nsq_entries

        public static void nsq_entries​(long struct,
                                       int value)
        Unsafe version of sq_entries.
      • ncq_entries

        public static void ncq_entries​(long struct,
                                       int value)
        Unsafe version of cq_entries.
      • nflags

        public static void nflags​(long struct,
                                  int value)
        Unsafe version of flags.
      • nsq_thread_cpu

        public static void nsq_thread_cpu​(long struct,
                                          int value)
        Unsafe version of sq_thread_cpu.
      • nsq_thread_idle

        public static void nsq_thread_idle​(long struct,
                                           int value)
        Unsafe version of sq_thread_idle.
      • nfeatures

        public static void nfeatures​(long struct,
                                     int value)
        Unsafe version of features.
      • nwq_fd

        public static void nwq_fd​(long struct,
                                  int value)
        Unsafe version of wq_fd.
      • nresv

        public static void nresv​(long struct,
                                 java.nio.IntBuffer value)
        Unsafe version of resv.
      • nresv

        public static void nresv​(long struct,
                                 int index,
                                 int value)
        Unsafe version of resv.
      • nsq_off

        public static void nsq_off​(long struct,
                                   IOSQRingOffsets value)
        Unsafe version of sq_off.
      • ncq_off

        public static void ncq_off​(long struct,
                                   IOCQRingOffsets value)
        Unsafe version of cq_off.