Struct ConversionError

pub struct ConversionError<S, E = NoDetails> {
    pub details: E,
    pub cause: Option<Error>,
    pub source: Option<S>,
}

General error type for fallible constructors.

In Interprocess, many types feature conversions to and from handles/file descriptors and types from the standard library. Many of those conversions are fallible because the semantic mapping between the source and destination types is not always 1:1, with various invariants that need to be upheld and which are always queried for. With async types, this is further complicated: runtimes typically need to register OS objects in their polling/completion infrastructure to use them asynchronously.

All those conversion have one thing in common: they consume ownership of one object and return ownership of its new form. If the conversion fails, it would be invaluably useful in some cases to return ownership of the original object back to the caller, so that it could use it in some other way. The source field allows for that, but also reserves the callee’s freedom not to do so. (Hey, it’s not like I wanted it to be like this, Tokio just doesn’t have .try_clone() and returns io::Error. Oh well, unwrapping’s always an option.)

Many (but not all) of those conversions also have an OS error they can attribute the failure to.

Additionally, some conversions have an additional “details” error field that contains extra infromation about the error. That is typically an enumeration that specifies which stage of the conversion the OS error happened on.

Fields

details: E

Extra information about the error.

cause: Option<Error>

The underlying OS error, if any.

source: Option<S>

Ownership of the input of the conversion.

Implementations

impl<S, E: Default> ConversionError<S, E>

pub fn from_source(source: S) -> Self

Constructs an error value without an OS cause and with default contents for the “details” field.

pub fn from_cause(cause: Error) -> Self

Constructs an error value that doesn’t return input ownership, with default contents for the “details” field and an OS cause.

pub fn from_source_and_cause(source: S, cause: Error) -> Self

Constructs an error value from a given OS cause, filling the “details” field with its default value.

impl<S, E> ConversionError<S, E>

pub fn from_source_and_details(source: S, details: E) -> Self

Constructs an error value without an OS cause.

pub fn from_cause_and_details(cause: Error, details: E) -> Self

Constructs an error value that doesn’t return input ownership.

pub fn map_source<Sb>(self, f: impl FnOnce(S) -> Sb) -> ConversionError<Sb, E>

Maps the type with which ownership over the input is returned using the given closure.

This utility is mostly used in the crate’s internals.

pub fn try_map_source<Sb>( self, f: impl FnOnce(S) -> Option<Sb>, ) -> ConversionError<Sb, E>

Maps the type with which ownership over the input is returned using the given closure, also allowing it to drop the ownership.

This utility is mostly used in the crate’s internals.

impl<S, E: Display> ConversionError<S, E>

pub fn to_io_error(&self) -> Error

Boxes the error into an io::Error.

Trait Implementations

impl<S: Debug, E: Debug> Debug for ConversionError<S, E>

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

Formats the value using the given formatter.

impl<S, E: Default> Default for ConversionError<S, E>

fn default() -> Self

Returns the “default value” for a type.

impl<S, E: Display> Display for ConversionError<S, E>

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

Formats the value using the given formatter.

impl<S: Debug, E: Error + 'static> Error for ConversionError<S, E>

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<S, E: Display> From<ConversionError<S, E>> for Error

Boxes the error into an io::Error, dropping the retained file descriptor in the process.

fn from(e: ConversionError<S, E>) -> Self

Converts to this type from the input type.