Package org.lwjgl.system.linux.liburing

Class IOURingParams

java.lang.Object
org.lwjgl.system.Pointer.Default
org.lwjgl.system.Struct<IOURingParams>
org.lwjgl.system.linux.liburing.IOURingParams
All Implemented Interfaces:
AutoCloseable, org.lwjgl.system.NativeResource, org.lwjgl.system.Pointer
public class IOURingParams extends org.lwjgl.system.Struct<IOURingParams> 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 Details

    • SIZEOF

      public static final int SIZEOF
      The struct size in bytes.

    • ALIGNOF

      public static final int ALIGNOF
      The struct alignment in bytes.

    • SQ_ENTRIES

      public static final int SQ_ENTRIES
      The struct member offsets.

    • CQ_ENTRIES

      public static final int CQ_ENTRIES
      The struct member offsets.

    • FLAGS

      public static final int FLAGS
      The struct member offsets.

    • SQ_THREAD_CPU

      public static final int SQ_THREAD_CPU
      The struct member offsets.

    • SQ_THREAD_IDLE

      public static final int SQ_THREAD_IDLE
      The struct member offsets.

    • FEATURES

      public static final int FEATURES
      The struct member offsets.

    • WQ_FD

      public static final int WQ_FD
      The struct member offsets.

    • RESV

      public static final int RESV
      The struct member offsets.

    • SQ_OFF

      public static final int SQ_OFF
      The struct member offsets.

    • CQ_OFF

      public static final int CQ_OFF
      The struct member offsets.

  • Constructor Details

    • IOURingParams

      public IOURingParams(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 Details

    • sizeof

      public int sizeof()
      Specified by:
      sizeof in class org.lwjgl.system.Struct<IOURingParams>

    • 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.

    • flags

      public int flags()
      one or more of:
      SETUP_IOPOLLSETUP_SQPOLLSETUP_SQ_AFFSETUP_CQSIZESETUP_CLAMP
      SETUP_ATTACH_WQSETUP_R_DISABLEDSETUP_SUBMIT_ALLSETUP_COOP_TASKRUNSETUP_TASKRUN_FLAG
      SETUP_SQE128SETUP_CQE32SETUP_SINGLE_ISSUERSETUP_DEFER_TASKRUN

    • 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.

    • features

      public int features()
      filled in by the kernel, which specifies various features supported by current kernel version. One or more of:
      FEAT_SINGLE_MMAPFEAT_NODROPFEAT_SUBMIT_STABLEFEAT_RW_CUR_POSFEAT_CUR_PERSONALITY
      FEAT_FAST_POLLFEAT_POLL_32BITSFEAT_SQPOLL_NONFIXEDFEAT_EXT_ARGFEAT_NATIVE_WORKERS
      FEAT_RSRC_TAGSFEAT_CQE_SKIPFEAT_LINKED_FILEFEAT_REG_REG_RING

    • wq_fd

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

    • resv

      public 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_off

      public IOCQRingOffsets cq_off()
      Returns:
      a IOCQRingOffsets view of the cq_off field.

    • sq_entries

      public IOURingParams sq_entries(int value)
      Sets the specified value to the sq_entries() field.

    • cq_entries

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

    • flags

      public IOURingParams flags(int value)
      Sets the specified value to the flags() 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.

    • features

      public IOURingParams features(int value)
      Sets the specified value to the features() field.

    • wq_fd

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

    • resv

      public IOURingParams resv(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.

    • sq_off

      public IOURingParams sq_off(IOSQRingOffsets value)
      Copies the specified IOSQRingOffsets to the sq_off() field.

    • sq_off

      public IOURingParams sq_off(Consumer<IOSQRingOffsets> consumer)
      Passes the sq_off() field to the specified Consumer.

    • cq_off

      public IOURingParams cq_off(IOCQRingOffsets value)
      Copies the specified IOCQRingOffsets to the cq_off field.

    • cq_off

      public IOURingParams cq_off(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, 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(int capacity)
      Returns a new IOURingParams.Buffer instance allocated with BufferUtils.
      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:
      capacity - the buffer capacity
      stack - the stack from which to allocate

    • 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:
      capacity - the buffer capacity
      stack - the stack from which to allocate

    • 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 IntBuffer nresv(long struct)
      Unsafe version of resv().

    • nresv

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

    • nsq_off

      public static IOSQRingOffsets nsq_off(long struct)
      Unsafe version of sq_off().

    • ncq_off

      public static IOCQRingOffsets ncq_off(long struct)
      Unsafe version of cq_off().

    • 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, 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.