Error handling: Error type

[dhardy]

This is about design of the error type; see also #8 (should we just panic?) and #9 (error kinds).

(This assumes we do return a Result somewhere and don't do all handling via panics.)

Possible error types:

• simple kind enum
• kind enum + OS code — probably not useful (see below)
• kind + cause (wrapped error) [std only]
• kind + &'static str — also not a good choice; see below

---

Rustdoc: https://dhardy.github.io/rand/rand_core/struct.Error.html

New proposal, which tries to be uniform between std and no_std (aside from missing cause), and allow documentation of both the current error and its cause without creating a new type.

#[derive(Debug)]
pub struct Error {
    pub kind: ErrorKind,
    msg: &'static str,
    #[cfg(feature="std")]
    cause: Option<Box<stdError + Send + Sync>>,
}

impl Error {
    #[cfg(feature="std")]
    pub fn new<E>(kind: ErrorKind, msg: &'static str, cause: Option<E>) -> Self
        where E: Into<Box<stdError + Send + Sync>>
    {
        Self { kind, msg, cause: cause.map(|inner| inner.into()) }
    }

    #[cfg(not(feature="std"))]
    pub fn new<E>(kind: ErrorKind, msg: &'static str, _cause: Option<E>) -> Self {
        Self { kind, msg }
    }
}

Previous proposal:

#[cfg(feature="std")]
// impls: Debug, Display, ::std::error::Error
pub struct Error {
    pub kind: ErrorKind,
    pub cause: Option<Box<std::error::Error>,
}
#[cfg(not(feature="std"))]
// impls: Debug, Display, ::std::error::Error, Clone, PartialEq, Eq
pub struct Error {
    pub kind: ErrorKind,
    pub cause: Option<&'static str>,
}

[pitdicker]

Maybe a third choice:

• kind enum + cause with std feature. Only kind enum for no_std.

They all have advantages and disadvantages. A simple kind enum is easiest to match against. But the other two options would work similar to std::io::error and error-chain, so they should be ergonomic enough to.

'kind enum + cause' can take easy part in error chaining. The disadvantage is that the error type is different in std and no_std mode.

'kind enum + OS code' can take part in error chaining, but only for errors like those of std::io::error. It can work the same in std and no_std mode, and doesn't need to allocate on an error.

'kind enum + OS code' has my preference for now. If we go with this option, I have been toying with the thought that is should maybe be a very small separate crate. It would have to reimplement small parts of std::io::error: we can't wrap ::std::error::Error::description because the function signature does not remember the description is 'static.

[dhardy]

Another thing we considered was &'static str, or perhaps kind + &'static str.

We could manually map OS codes to static strings, or do the dodgy thing I suggested before, potentially leaking memory.

Or we could do kind + cause where cause is the wrapped error in std mode and the OS code in no_std mode.

But how useful is the cause really? In theory kind alone should include enough information most of the time? I guess the answer is that provided the context of the error isn't lost, the kind alone should be enough to localise the error — but extra details might still help.

[pitdicker]

We could manually map OS codes to static strings, or do the dodgy thing I suggested before, potentially leaking memory.

I didn't think this was a serious option. It seems practical. But it is not very clean, and it would set a bad precedent for other crates. I think it would be acceptable for a small crate or a private application, bud not for something as popular as rand.

But how useful is the cause really?

For OsRng the kind NotAvailable can have as a cause that you do not have enough permission to open /dev/random, that there are not enough file descriptors, or someone deleted the device. I think mapping all these causes to NotAvailable makes sense, as that is all users of the library care about.

But for someone trying to figure out why OsRng does not work on his system, it may be useful. (If there are not countless other programs that fail on such a system ;-) ).

OsRng is of course just one thing. ReadRng, something like a USB hardware RNG, or a strange RNG that works over the network can also have OS errors that can help.

The problem is, I don't care very strongly about returning a cause. But with std::error::Error and error-chain it seems to become expected of libraries, and it may just be good to go along.

[dhardy]

Ditto, I feel like we could do without a cause, but it's probably worth including anyway.

I updated the relevant section of the RFC.

[pitdicker]

On the flip side, OsRng implementations may have to handle a std::io::Error, in which case if we don't want to throw away the details, our error type either needs to be able to hold a cause of this type or hold the string version, retrieved with type &str from std::error::Error::description.

A somewhat related question: do we want to provide OsRng with no_std? It is certainly doable, but a bit more complex than the current implementation.

[dhardy]

no_std means no standard OS — either no OS at all or something without all standard functionality. I imagine any replacement for OsRng must be domain specific. I created a no_std issue.

[pitdicker]

Than we do not really have a reason to return an OS error as cause in no_std mode. That would make the option 'kind enum + OS code' not all that interesting.

[pitdicker]

I now like your proposal in the RFC:

#[cfg(feature="std")]
pub struct Error {
    pub kind: ErrorKind,
    pub cause: Option<Box<std::error::Error>,
}
#[cfg(not(feature="std"))]
pub struct Error {
    pub kind: ErrorKind,
    pub cause: Option<&'static str>,
}

I don't like it that the error type changes, but it is practical. And that is wat no_std is about, right :-)?

For no_std the source of the &'static str is not the OS, but under our control. So it can really be a static string. Then we do not have to worry about the leaking trick.

B.t.w. is it common for the fields to be public? It sure is convenient, and I see no disadvantage.

[dhardy]

Common? Not very since it prevents internals from being changed. But I don't think these error types need to change — in fact I think it's quite useful for users to know exactly what the type is.

I'm not 100% convinced on this proposal myself but don't see anything better really.