Struct I2o2Builder

pub struct I2o2Builder { /* private fields */ }

A set of configuration options for customising the I2o2Scheduler scheduler.

Example

use std::time::Duration;

let (scheduler, handle) = i2o2::I2o2Builder::default()
    .with_io_polling(true)
    .try_create::<()>()?;

// ... do work

Implementations

impl I2o2Builder

pub const fn with_queue_size(self, size: u32) -> Self

Set the queue size of the message queue between clients and the scheduler.

This value will be rounded to the nearest power of two.

By default, this is 128.

pub const fn with_ring_depth(self, size: u32) -> Self

Set the ring depth.

This is the SQ size of the ring itself.

This value must be a power of two.

By default, this is 128.

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

Set the size of the SQ entry to be 128 bytes instead of 64.

This is only required for the opcode::UringCmd80 op, for NVME pass through.

By default, this is false.

pub const fn with_num_registered_buffers(self, size: u32) -> Self

Set the maximum number of registered buffers that might be registered with the ring.

This is value cannot be updated once the ring in created and is used to allocate the necessary structures for the ring.

WARNING: You must have a kernel version 5.19+ in order for this API to not error on creation.

By default, this is 0.

pub const fn with_num_registered_files(self, size: u32) -> Self

Set the maximum number of registered files that might be registered with the ring.

This is value cannot be updated once the ring in created and is used to allocate the necessary structures for the ring.

By default, this is 0.

pub const fn with_io_polling(self, enable: bool) -> Self

Enable/disable IO polling.

Sets IORING_SETUP_IOPOLL

https://www.man7.org/linux/man-pages/man2/io_uring_setup.2.html

Perform busy-waiting for an I/O completion, as opposed to getting notifications via an asynchronous IRQ (Interrupt Request).

WARNING: Enabling this option requires all file IO events to be O_DIRECT

By default, this is disabled.

pub const fn with_coop_task_run(self, enable: bool) -> Self

Enables/disables the coop task run io_uring flag.

Sets IORING_SETUP_COOP_TASKRUN

https://www.man7.org/linux/man-pages/man2/io_uring_setup.2.html

By default, io_uring will interrupt a task running in userspace when a completion event comes in. This is to ensure that completions run in a timely manner. For a lot of use cases, this is overkill and can cause reduced performance from both the inter-processor interrupt used to do this, the kernel/user transition, the needless interruption of the tasks userspace activities, and reduced batching if completions come in at a rapid rate. Most applications don’t need the forceful interruption, as the events are processed at any kernel/user transition. The exception are setups where the application uses multiple threads operating on the same ring, where the application waiting on completions isn’t the one that submitted them. For most other use cases, setting this flag will improve performance.

WARNING: You must have a kernel version 5.19+ in order for this API to not error on creation.

By default, this is disabled.

pub fn try_create<G>(self) -> Result<(I2o2Scheduler<G>, I2o2Handle<G>)>

Attempt to create the scheduler using the current configuration.

pub fn try_spawn<G>(self) -> Result<(JoinHandle<Result<()>>, I2o2Handle<G>)>

where G: Send + 'static,

Attempt to create the scheduler and run it in a background thread using the current configuration.

pub fn try_spawn_and_pin<G>( self, cpu_set: CpuSet, ) -> Result<(JoinHandle<Result<()>>, I2o2Handle<G>)>

where G: Send + 'static,

Attempt to create the scheduler and run it in a background thread using the current configuration and pin the thread to a specific CPU.

Trait Implementations

impl Clone for I2o2Builder

fn clone(&self) -> I2o2Builder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for I2o2Builder

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

Formats the value using the given formatter.

impl Default for I2o2Builder

fn default() -> Self

Returns the “default value” for a type.