Struct a10::Config

pub struct Config<'r> { /* private fields */ }

Configuration of a Ring.

Created by calling Ring::config.

Implementations

impl<'r> Config<'r>

pub const fn disable(self) -> Config<'r>

Start the ring in a disabled state.

While the ring is disabled submissions are not allowed. To enable the ring use Ring::enable.

pub const fn single_issuer(self) -> Config<'r>

Enable single issuer.

This hints to the kernel that only a single thread will submit requests, which is used for optimisations within the kernel. This means that only the thread that build the ring or enabled it (after starting in disable mode) may register resources with the ring, resources such as the ReadBufPool.

This optimisation is enforces by the kernel, which will return EEXIST or AlreadyExists if another thread attempt to register resource or otherwise use the Ring in a way that is not allowed.

pub const fn defer_task_run(self) -> Config<'r>

Defer task running.

By default, kernel will process all outstanding work at the end of any system call or thread interrupt. This can delay the application from making other progress.

Enabling this option will hint to kernel that it should defer work until Ring::poll is called. This way the work is done in the Ring::poll.

This options required Config::single_issuer to be set. This option does not work with Config::with_kernel_thread set.

pub const fn with_completion_queue_size(self, entries: u32) -> Self

Set the size of the completion queue.

By default the kernel will use a completion queue twice as large as the submission queue (entries in the call to Ring::config).

Uses IORING_SETUP_CQSIZE, added in Linux kernel 5.5.

pub const fn clamp_queue_sizes(self) -> Self

Clamp queue sizes to the maximum.

The maximum queue sizes aren’t exposed by the kernel, making this the only way (currently) to get the largest possible queues.

Uses IORING_SETUP_CLAMP, added in Linux kernel 5.6.

pub const fn with_kernel_thread(self, enabled: bool) -> Self

Start a kernel thread polling the Ring.

When this option is enabled a kernel thread is created to perform submission queue polling. This allows issuing I/O without ever context switching into the kernel.

Notes

When setting this to false it significantly changes the way A10 works. With this disabled you need to call Ring::poll to submit I/O work, with this enables this is done by the kernel thread. That means that if multiple threads use the same SubmissionQueue their submissions might not actually be submitted until Ring::poll is called.

pub const fn with_cpu_affinity(self, cpu: u32) -> Self

Set the CPU affinity of kernel thread polling the Ring.

Only works in combination with Config::with_kernel_thread.

pub const fn with_idle_timeout(self, timeout: Duration) -> Self

Set the idle timeout of the kernel thread polling the submission queue. After timeout time has passed after the last I/O submission the kernel thread will go to sleep. If the I/O is kept busy the kernel thread will never sleep. Note that A10 will ensure the kernel thread is woken up when more submissions are added.

The accuracy of timeout is only in milliseconds, anything more precise will be discarded.

pub const fn attach(self, other_ring: &'r Ring) -> Self

Attach the new (to be created) ring to other_ring.

This will cause the Ring being created to share the asynchronous worker thread backend of the specified other_ring, rather than create a new separate thread pool.

Uses IORING_SETUP_ATTACH_WQ, added in Linux kernel 5.6.

pub const fn attach_queue(self, other_ring: &'r SubmissionQueue) -> Self

Same as Config::attach, but accepts a SubmissionQueue.

pub fn build(self) -> Result<Ring>

Build a new Ring.

Trait Implementations

impl<'r> Clone for Config<'r>

fn clone(&self) -> Config<'r>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'r> Debug for Config<'r>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.