Study of std::io::Error
In this article we’ll dissect the implementation of
std::io::Error type from the Rust’s standard library.
The code in question is here:
You can read this post as either of:
- A study of a specific bit of standard library.
- An advanced error management guide.
- A case of a beautiful API design.
The article requires basic familiarity with Rust error handing.
When designing an
Error type for use with
Result<T, E>, the main question to ask is “how the error will be used?”.
Usually, one of the following is true.
The error is handled programmatically. The consumer inspects the error, so its internal structure needs to be exposed to a reasonable degree.
The error is propagated and displayed to the user. The consumer doesn’t inspect the error beyond the
fmt::Display; so its internal structure can be encapsulated.
Note that there’s a tension between exposing implementation details and encapsulating them. A common anti-pattern for implementing the first case is to define a kitchen-sink enum:
There is a number of problems with this approach.
First, exposing errors from underlying libraries makes them a part of your public API. Major semver bump in your dependency would require you to make a new major version as well.
Second, it sets all the implementation details in stone.
For example, if you notice that the size of
ConnectionDiscovery is huge, boxing this variant would be a breaking change.
Third, it is usually indicative of a larger design issue. Kitchen sink errors pack dissimilar failure modes into one type. But, if failure modes vary widely, it probably isn’t reasonable to handle them! This is an indication that the situation looks more like the case two.
However bad the
enum approach might be, it does achieve maximum inspectability of the first case.
The propagation-centered second case of error management is typically handled by using a boxed trait object.
A type like
Box<dyn std::error::Error> can be constructed from any specific concrete error, can be printed via
Display, and can still optionally expose the underlying error via dynamic downcasting.
anyhow crate is a great example of this style.
The case of
std::io::Error is interesting because it wants to be both of the above and more.
std, so encapsulation and future-proofing are paramount.
IO errors coming from the operating system often can be handled (for example,
- For a systems programming language, it’s important to expose the underlying OS error exactly.
- The set of potential future OS error is unbounded.
io::Erroris also a vocabulary type, and should be able to represent some not-quite-os errors. For example, Rust
Paths can contain internal
opening such path should return an
io::Errorbefore making a syscall.
std::io::Error looks like:
First thing to notice is that it’s an enum internally, but this is a well-hidden implementation detail. To allow inspecting and handing of various error conditions there’s a separate public fieldless kind enum:
Repr are enums, publicly exposing
ErrorKind is much less scary.
Copy fieldless enum’s design space is a point — there are no plausible alternatives or compatibility hazards.
io::Errors are just raw OS error codes:
sys::decode_error_kind function takes care of mapping error codes to
All this together means that code can handle error categories in a cross-platform way by inspecting the
However, if the need arises to handle a very specific error code in an OS-dependent way, that is also possible.
The API carefully provides a convenient abstraction without abstracting away important low-level details.
std::io::Error can also be constructed from an
This provides cross-platform access to error-code style error handling. This is handy if you need the fastest possible errors.
Finally, there’s a third, fully custom variant of the representation:
Things to note:
newfunction delegates to monomorphic
_newfunction. This improves compile time, as less code needs to be duplicated during monomorphization. I think it also improves the runtime a bit: the
_newfunction is not marked as inline, so a function call would be generated at the call-site. This is good, because error construction is the cold-path and saving instruction cache is welcome.
Customvariant is boxed — this is to keep overall
size_ofsmaller. On-the-stack size of errors is important: you pay for it even if there are no errors!
Both these types refer to a
dyn Trait + '_, the
'_is elided to
'static, unless the trait object is behind a reference, in which case it is elided as
&'a dyn Trait + 'a.
into_innerprovide full access to the underlying error. Similarly to
os_errorcase, abstraction blurs details, but also provides hooks to get the underlying data as-is.
Display implementation reveals the most important details about internal representation.
To sum up,
- encapsulates its internal representation and optimizes it by boxing large enum variant,
provides a convenient way to handle error based on category via
- fully exposes underlying OS error, if any.
- can transparently wrap any other error type.
The last point means that
io::Error can be used for ad-hoc errors, as
String are convertible to
It also can be used as a simple replacement for
I think some libraries might simplify their error handing with this:
serde_json provides the following method:
Read can fail with
serde_json::Error needs to be able to represent
I think this is backwards (but I don’t know the whole context, I’d be delighted to be proven wrong!), and the signature should have been this instead:
serde_json::Error wouldn’t have
Io variant and would be stashed into
std::io::Error is a truly marvelous type, which manages to serve many different use-cases without much compromise.
But can we perhaps do better?
The number one problem with
std::io::Error is that, when a file-system operation fails, you don’t know which path it has failed for!
This is understandable — Rust is a systems language, so it shouldn’t add much fat over what OS provides natively.
OS returns an integer return code, and coupling that with a heap-allocated
PathBuf could be an unacceptable overhead!
I don’t know an obviously good solution here.
One option would be to add compile time (once we get std-aware cargo) or runtime (a-la
RUST_BACKTRACE) switch to heap-allocate all path-related IO errors.
A similarly-shaped problem is that
io::Error doesn’t carry a backtrace.
The other problem is that
std::io::Error is not as efficient as it could be:
Its size is pretty big:
For custom case, it incurs double indirection and allocation:
I think we can fix this now!
First, we can get rid of double indirection by using a thin trait object, a-la
GlobalAlloc exist, it’s a relatively straight-forward implementation.
Second, we can make use of the fact that pointers are aligned, and stash both
Simple variants into
usize with the least significant bit set.
I think we can even get creative and use the second least significant bit, leaving the first one as a niche.
That way, even something like
io::Result<i32> can be pointer-sized!
And this concludes the post.
Next time you’ll be designing an error type for your library, take a moment to peer through
std::io::Error, you might find something to steal!
Discussion on /r/rust.