Struct ringbahn::Ring

pub struct Ring<D: Drive> { /* fields omitted */ }

A low-level primitive for building an IO object on io-uring

Ring is a state machine similar to Submission, but it is designed to cycle through multiple IO events submitted to io-uring, rather than representing a single submission. Because of this, it is more low level, but it is suitable fro building an IO object like a File on top of io-uring.

Users writing code on top of Ring are responsible for making sure that it is correct. For example, when calling poll, users must ensure that they are in the proper state to submit whatever type of IO they would be attempting to submit. Additionally, users should note that Ring does not implement Drop. In order to cancel any ongoing IO, users are responsible for implementing drop to call cancel properly.

Implementations

impl<D: Drive> Ring<D>

pub fn new(driver: D) -> Ring<D>

Construct a new Ring on top of a driver.

pub fn driver(&self) -> &D

pub fn poll(
    self: Pin<&mut Self>,
    ctx: &mut Context,
    is_eager: bool,
    prepare: impl FnOnce(&mut SubmissionQueueEvent)
) -> Poll<Result<usize>>

Poll the ring state machine.

This accepts a callback, prepare, which prepares an event to be submitted to io-uring. This callback will only be called once during an iteration of ring's state machine: once an event has been prepared, until it is completed or cancelled, a single ring instance will not prepare any additional events.

pub fn cancel(&mut self, cancellation: Cancellation)

Cancel any ongoing IO with this cancellation.

Users are responsible for ensuring that the cancellation passed would be appropriate to clean up the resources of the running event.

pub fn cancel_pinned(self: Pin<&mut Self>, cancellation: Cancellation)

Cancel any ongoing IO, but from a pinned reference.

This has the same behavior of as Ring::cancel.

Trait Implementations

impl<D: Drive + Clone> Clone for Ring<D>

fn clone(&self) -> Ring<D>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<D: Default + Drive> Default for Ring<D>

fn default() -> Ring<D>

Returns the "default value" for a type.