Struct PushRefused 

#[non_exhaustive]
pub struct PushRefused<T, X> {
    pub error: Error,
    pub payload: Option<T>,
    pub extra: X,
}

A push the ring refused, carrying everything the push was given (M30.1, D-80).

Every owned push returns this on refusal: the io::Error that explains it, the payload the push took (None for one that takes no payload, such as a flush, a cancel or a registered-span push), and the sidecar extra. Batch::register_buffers returns one too, with the whole Vec of buffers as its payload and () as its sidecar. A refused push queued nothing, so nothing will ever complete to hand these back; this is the only way back.

The commonest refusal is IORING_E_SUBMISSION_QUEUE_FULL. No caller can rule it out beforehand, because building the operation is the test, and it is exactly the case where the caller wants the same buffer for a retry:

use windows_ioring_sys::{Batch, IoRing, IoRingErrorExt, PushOptions, SharedHandle};

let mut batch = Batch::new(ring);
if let Err(refused) = batch.read_owned(file, vec![0_u8; 4096], (), 0, PushOptions::new()) {
    if !refused.error.is_submission_queue_full() {
        return Err(refused.into());
    }
    // Backpressure, not a failure: submit what is queued, then retry with
    // the buffer the refusal handed back.
    batch.submit()?;
    let buffer = refused.payload.expect("a read takes a payload");
    let mut batch = Batch::new(ring);
    batch.read_owned(file, buffer, (), 0, PushOptions::new())?;
}

A caller that wants only the error converts with ? or .into(), which keeps the error unchanged (so IoRingErrorExt still finds the HRESULT) and drops the payload and sidecar there, by the caller’s choice rather than the ring’s.

The ring-owned parts of an operation are not returned: a file guard and a registered-buffer use belong to the ring, never to the caller, and are released.

Debug and Display are written by hand so they place no bound on T or X. A consumer’s buffer type need not be Debug for .expect(..) to compile.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

error: Error

Why the push was refused.

payload: Option<T>

The payload the push took, or None if it took none.

extra: X

The sidecar the push took.

Implementations

impl<T, X> PushRefused<T, X>

pub fn into_error(self) -> Error

Discard the payload and sidecar, keeping only the error.

Trait Implementations

impl<T, X> Debug for PushRefused<T, X>

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

Formats the value using the given formatter.

impl<T, X> Display for PushRefused<T, X>

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

Formats the value using the given formatter.

impl<T, X> Error for PushRefused<T, X>

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl<T, X> From<PushRefused<T, X>> for Error

fn from(refused: PushRefused<T, X>) -> Self

Converts to this type from the input type.