DoxigAlpha

enter

Tell the kernel we have submitted SQEs and/or want to wait for CQEs. Returns the number of SQEs submitted.

Function parameters

Parameters

#
self:*IoUring
to_submit:u32
min_complete:u32
flags:u32

Used to select how the read should be handled.

Types

#
ReadBuffer
Used to select how the read should be handled.
RecvBuffer
Used to select how the recv call should be handled.
BufferGroup
Group of application provided buffers.

A friendly way to setup an io_uring, with default linux.io_uring_params.

Functions

#
init
A friendly way to setup an io_uring, with default linux.io_uring_params.
init_params
A powerful way to setup an io_uring, if you want to tweak linux.io_uring_params such as submission
get_sqe
Returns a pointer to a vacant SQE, or an error if the submission queue is full.
submit
Submits the SQEs acquired via get_sqe() to the kernel.
submit_and_wait
Like submit(), but allows waiting for events as well.
enter
Tell the kernel we have submitted SQEs and/or want to wait for CQEs.
flush_sq
Sync internal state with kernel ring state on the SQ side.
sq_ring_needs_enter
Returns true if we are not using an SQ thread (thus nobody submits but us),
sq_ready
Returns the number of flushed and unflushed SQEs pending in the submission queue.
cq_ready
Returns the number of CQEs in the completion queue, i.e.
copy_cqes
Copies as many CQEs as are ready, and that can fit into the destination `cqes` slice.
copy_cqe
Returns a copy of an I/O completion, waiting for it if necessary, and advancing the CQ ring.
cq_ring_needs_flush
Matches the implementation of cq_ring_needs_flush() in liburing.
cqe_seen
For advanced use cases only that implement custom completion queue methods.
cq_advance
For advanced use cases only that implement custom completion queue methods.
fsync
Queues (but does not submit) an SQE to perform an `fsync(2)`.
nop
Queues (but does not submit) an SQE to perform a no-op.
read
Queues (but does not submit) an SQE to perform a `read(2)` or `preadv(2)` depending on the buffer type.
write
Queues (but does not submit) an SQE to perform a `write(2)`.
splice
Queues (but does not submit) an SQE to perform a `splice(2)`
read_fixed
Queues (but does not submit) an SQE to perform a IORING_OP_READ_FIXED.
writev
Queues (but does not submit) an SQE to perform a `pwritev()`.
write_fixed
Queues (but does not submit) an SQE to perform a IORING_OP_WRITE_FIXED.
accept
Queues (but does not submit) an SQE to perform an `accept4(2)` on a socket.
accept_multishot
Queues an multishot accept on a socket.
accept_direct
Queues an accept using direct (registered) file descriptors.
accept_multishot_direct
Queues an multishot accept using direct (registered) file descriptors.
connect
Queue (but does not submit) an SQE to perform a `connect(2)` on a socket.
epoll_ctl
Queues (but does not submit) an SQE to perform a `epoll_ctl(2)`.
recv
Queues (but does not submit) an SQE to perform a `recv(2)`.
send
Queues (but does not submit) an SQE to perform a `send(2)`.
send_zc
Queues (but does not submit) an SQE to perform an async zerocopy `send(2)`.
send_zc_fixed
Queues (but does not submit) an SQE to perform an async zerocopy `send(2)`.
recvmsg
Queues (but does not submit) an SQE to perform a `recvmsg(2)`.
sendmsg
Queues (but does not submit) an SQE to perform a `sendmsg(2)`.
sendmsg_zc
Queues (but does not submit) an SQE to perform an async zerocopy `sendmsg(2)`.
openat
Queues (but does not submit) an SQE to perform an `openat(2)`.
openat_direct
Queues an openat using direct (registered) file descriptors.
close
Queues (but does not submit) an SQE to perform a `close(2)`.
close_direct
Queues close of registered file descriptor.
timeout
Queues (but does not submit) an SQE to register a timeout operation.
timeout_remove
Queues (but does not submit) an SQE to remove an existing timeout operation.
link_timeout
Queues (but does not submit) an SQE to add a link timeout operation.
poll_add
Queues (but does not submit) an SQE to perform a `poll(2)`.
poll_remove
Queues (but does not submit) an SQE to remove an existing poll operation.
poll_update
Queues (but does not submit) an SQE to update the user data of an existing poll
fallocate
Queues (but does not submit) an SQE to perform an `fallocate(2)`.
statx
Queues (but does not submit) an SQE to perform an `statx(2)`.
cancel
Queues (but does not submit) an SQE to remove an existing operation.
shutdown
Queues (but does not submit) an SQE to perform a `shutdown(2)`.
renameat
Queues (but does not submit) an SQE to perform a `renameat2(2)`.
unlinkat
Queues (but does not submit) an SQE to perform a `unlinkat(2)`.
mkdirat
Queues (but does not submit) an SQE to perform a `mkdirat(2)`.
symlinkat
Queues (but does not submit) an SQE to perform a `symlinkat(2)`.
linkat
Queues (but does not submit) an SQE to perform a `linkat(2)`.
provide_buffers
Queues (but does not submit) an SQE to provide a group of buffers used for commands that read/receive data.
remove_buffers
Queues (but does not submit) an SQE to remove a group of provided buffers.
waitid
Queues (but does not submit) an SQE to perform a `waitid(2)`.
register_files
Registers an array of file descriptors.
register_files_update
Updates registered file descriptors.
register_files_sparse
Registers an empty (-1) file table of `nr_files` number of file descriptors.
register_eventfd
Registers the file descriptor for an eventfd that will be notified of completion events on
register_eventfd_async
Registers the file descriptor for an eventfd that will be notified of completion events on
unregister_eventfd
Unregister the registered eventfd file descriptor.
register_buffers
Registers an array of buffers for use with `read_fixed` and `write_fixed`.
unregister_buffers
Unregister the registered buffers.
get_probe
Returns a io_uring_probe which is used to probe the capabilities of the
unregister_files
Unregisters all registered file descriptors previously associated with the ring.
socket
Prepares a socket creation request.
socket_direct
Prepares a socket creation request for registered file at index `file_index`.
socket_direct_alloc
Prepares a socket creation request for registered file, index chosen by kernel (file index alloc).
bind
Queues (but does not submit) an SQE to perform an `bind(2)` on a socket.
listen
Queues (but does not submit) an SQE to perform an `listen(2)` on a socket.
cmd_sock
Prepares an cmd request for a socket.
setsockopt
Prepares set socket option for the optname argument, at the protocol
getsockopt
Prepares get socket option to retrieve the value for the option specified by
setup_buf_ring
Registers a shared buffer ring to be used with provided buffers.
buf_ring_init
Initialises `br` so that it is ready to be used.
buf_ring_mask
Calculates the appropriate size mask for a buffer ring.
buf_ring_add
Assigns `buffer` with the `br` buffer ring.
buf_ring_advance
Make `count` new buffers visible to the kernel.

Source

Implementation

#
pub fn enter(self: *IoUring, to_submit: u32, min_complete: u32, flags: u32) !u32 {
    assert(self.fd >= 0);
    const res = linux.io_uring_enter(self.fd, to_submit, min_complete, flags, null);
    switch (linux.E.init(res)) {
        .SUCCESS => {},
        // The kernel was unable to allocate memory or ran out of resources for the request.
        // The application should wait for some completions and try again:
        .AGAIN => return error.SystemResources,
        // The SQE `fd` is invalid, or IOSQE_FIXED_FILE was set but no files were registered:
        .BADF => return error.FileDescriptorInvalid,
        // The file descriptor is valid, but the ring is not in the right state.
        // See io_uring_register(2) for how to enable the ring.
        .BADFD => return error.FileDescriptorInBadState,
        // The application attempted to overcommit the number of requests it can have pending.
        // The application should wait for some completions and try again:
        .BUSY => return error.CompletionQueueOvercommitted,
        // The SQE is invalid, or valid but the ring was setup with IORING_SETUP_IOPOLL:
        .INVAL => return error.SubmissionQueueEntryInvalid,
        // The buffer is outside the process' accessible address space, or IORING_OP_READ_FIXED
        // or IORING_OP_WRITE_FIXED was specified but no buffers were registered, or the range
        // described by `addr` and `len` is not within the buffer registered at `buf_index`:
        .FAULT => return error.BufferInvalid,
        .NXIO => return error.RingShuttingDown,
        // The kernel believes our `self.fd` does not refer to an io_uring instance,
        // or the opcode is valid but not supported by this kernel (more likely):
        .OPNOTSUPP => return error.OpcodeNotSupported,
        // The operation was interrupted by a delivery of a signal before it could complete.
        // This can happen while waiting for events with IORING_ENTER_GETEVENTS:
        .INTR => return error.SignalInterrupt,
        else => |errno| return posix.unexpectedErrno(errno),
    }
    return @as(u32, @intCast(res));
}