Coercible errors

Zero-cost error handling for generic traits.

Rationale

Assume we want to build a crate that defines a generic trait, meant to be implemented by others. Below is a minimalist example of such a trait:

rust pub trait Producer { fn produce(&self) -> u16; }

Some implementations might work well with this definition, but other implementations may encounter errors in some situations (e.g. IOError for a file-system based implementation). We call the former kind infallible implementations, and the latter kind fallible implementations.

In order to support both kinds of implementations, the methods of our trait should rather return Result<_, _>. This raises the question of the error type that those results should contain.

An option is to define a dedicated error type for our crate, and force implementers to wrap their errors into this type.

rust pub trait Producer { fn produce(&self) -> Result<u16, MyError>; }

This works, but breaks the "zero-cost abstraction" motto for infallible implementations. Indeed, Result<T, MyError> can be significantly bigger than the type T alone. For example, with a simple MyError type defined with the [error_chain] crate,

• <Result<(), MyError> is 56 bytes long (versus 0 bytes for ()),
• <Result<u16, MyError> is 64 bytes long (versus 2 bytes for u16).

A more flexible option is to let implementers specify their own error type:

rust pub trait Producer { type Error: Error + Send + 'static; fn produce(&self) -> Result<u16, Self::Error>; }

For infallible implementations, the Error associated type can be set to [never] or any other value-less type (typically an empty Enum). The compiler will then optimize away this error-type from the Result, effectively returning only the success-type.

We now have a real zero-cost abstraction, where infallible implementations do not pay the toll of error handling. On the other hand, it will be harder to work with several heterogeneous implementations of our trait. Consider for example the following type:

```rust pub struct PMax (P1, P2);

impl<P1: Producer, P2: Producer> Producer for PMax<P1, P2> {
    type Error = ???; // <<<< we have a problem here
    fn produce(&self) -> Result<u16, Self::Error> { 
        Ok(self.0.produce()?.max(self.1.produce()?))
    }

}

```

Since P1 and P2 may use totally unrelated error types, we don't know which error type to use. We could use a "chainable" error type as defined by [error_chain], but then we would go back to using a "fat" result even when P1 and P2 are both infallible.

The solution

This crate provides a solution to the problems described above. The idea is:

• to provide zero-cost error handling for infallible implementations, by allowing them to use [never] as their error type;
• to limit heterogeneity among fallible implementations, by requiring them to use a dedicated error type defined by the trait designer;
• to let the compiler infer the best error type when combining several implementations.

The example above would become:

```rust /// a dedicated error type pub struct MyError { /* ... */ }

// define appropriate types and traits
coercible_errors!(MyError);

pub trait Producer {
    // require that Producer::Error be either MyError or never
    type Error: CoercibleWith<MyError> + CoercibleWith<Never>;
    fn produce(&self) -> Result<u16, Self::Error>;
}

pub struct PMax<P1, P2> (P1, P2);
impl<P1: Producer, P2: Producer> Producer for PMax<P1, P2> 
    // this trait bound is required to be able to use CoercedError below
    where P1::Error: CoercibleWith<P2::Error>
{
    // compute the most appropriate Error type based on P1 and P2;
    // especially, if P1 and P2 are both infallible,
    // PMax will be infallible as well.
    type Error = CoercedError<P1::Error, P2::Error>;
    fn produce(&self) -> Result<u16, Self::Error> {
        Ok(
          // the coerced error always implements From<_>
          // for both P1::Error and P2::Error,
          // so inner errors can simply be lifted with '?'
          self.0.produce()?
          .max(self.1.produce()?)
        )
    }

}

```

The coercible_errors macro takes care of defining the following traits and types:

• CoercibleWith<E> is a trait to let the compiler infer the correct coercing of error types. The macro provides implementations so that [never] and [never] coerce into [never], and that any other combination of [never] and MyError coerce into MyError.
• CoercedError<E1, E2> is a type alias using CoercibleWith to determine the appropriate coerced error type.
• CoercedResult<T, E1, E2> is a shortcut for Result<T, CoercedError<E1, E2>>.

About [never]

Since the [never] type is currently unstable, this crate actually defines its own version called coercible_errors::Never. Once [never] becomes stable, coercible_errors::Never will become a simple alias to [never], avoiding a breaking change.

License

[CECILL-C]

(compatible with GNU LGPL)