ACP: Introduce `alloc::io`

[a1phyr]

Proposal

Problem statement

It would be great for OS-independent parts of std::io to be usable in alloc.

Motivating examples or use cases

std::io is a very useful abstraction, but unfortunately it is not available in no_std contexts, even though most of std::io do not depend directly on the underlying OS.

Today, OS-independent crates that use IO traits have the choice between using an alternative but incompatible implementation, such as embedded-io and not supporting no_std.

Solution sketch

The idea of this proposal is to move all OS-independent parts of std::io to alloc: traits, Cursor, Empty, Sink, buffering wrappers, etc. All OS-dependent functions and types will of course stay in std: stdio and pipes.

Unfortunately, some core items in std::io actually depend on the OS under the hood: Error (and unstable RawErrorType), IoSlice, IoSliceMut and copy. This is why this move has not been done earlier. The rest can easily be moved as it doesn't depend on anything else that is not already in alloc.

Here is the proposed plan for these:

• Error and RawErrorType: move them to alloc, while keeping RawErrorType perma-unstable in alloc (for use in std). Creating Error from raw OS errors would only be possible in std, which is possible thanks to incoherent impls. When creating an Error from a raw OS error, std provides alloc with callbacks to decode them (could be replaced with externally implementable items).
• IoSlice and IoSliceMut are even easier, as they only depend on the OS for their exact layout: io_vec on Unix, WSABUF on Windows, etc. We can just have their definition in alloc, with a fallback for platform where the layout doesn't matter.
• copy has specialization paths depending on the OS (eg using sendfile or splice). In alloc, copy would only have the generic path, while std would keep the specialized one. Such difference between standard crate in not new, it already exists with eg panic!.

Note that this proposal makes extra care to not expose anything OS-dependent to alloc users, only keeping that internal or perma-unstable for std; and to avoid linking to anything in alloc, as there are only structure definitions.
I understand that adding OS-dependent code to alloc is quite controversial, but I think that having alloc::io is worth the change.

A PR that successfully moves Error, IoSlice and IoSliceMut to alloc can be found at rust-lang/rust#152918.

Alternatives

• Do nothing, ie keep std::io in std.
• Create new traits with a custom error type, like [ACP] IO traits in core::io #293.
  This proposal has the disadvantage of creating new trait, and therefore is harder to make compatible with the current ecosystem.
• https://rust-lang.zulipchat.com/#narrow/channel/144729-t-types/topic/Lang.20.2B.20Libs-API.20interest.3A.20impl.20subtrait.20via.20supertrait/near/560051418
  This proposition adds language features to try to create new traits while keeping compatibility. This is much more complex and has no concrete path to stabilization.

Possible future work

• Try to move some parts of io to core instead of alloc.
  This will probably be quite difficult as Read directly depends on Vec.

• Compatibility with #[cfg(no_global_oom_handling)]
  This should be possible for most of alloc::io to handle OOM errors through io::Error, though some PR in this direction has already been rejected (Handle OOM when writing to Vec rust#148024).

Links and related work

Tracking issue: rust-lang/rust#48331
Prior try to move Error to core (not alloc): rust-lang/rust#116685
Current PR for OS-specific parts: rust-lang/rust#152918
https://internals.rust-lang.org/t/a-plan-to-move-most-of-std-io-to-alloc/23678

Many #![no_std] crates reimplementing std::io:

• embedded-io
• core2 and its forks
• ciborium-io, created by ciborium to support no_std.

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[tgross35]

I'm not sure if this adds anything to the other proposals other than being easier to do. Which is valid, but it's more useful if we can get Read and Write into core.

Maybe the team could give an update on their preferred approach at this point? A lot of ideas have centered around moving the current io::Error to core, but it is worth noting that #293 was closed by the author (possibly due to lack of time) rather than being rejected by the team. If there is still interest in moving Error, I think it would be good to start by refreshing rust-lang/rust#116685 (with its own tracking issue) as a first step to unblock easy experimentation.

[programmerjake]

I think that we should move io::Error to core even if we decide we want I/O traits to have their errors be associated types, since io::Error makes a good enough default type. Also because you can write things like
io::Read<Error: Into<io::Error>>

[kayabaNerve]

While there should be long-term progress on Read, Write in core IMO, that doesn't change how this proposal makes io more accessible and moves the needle towards that. While I'd love if this refreshed interest could move those down to core, and most of the current discussion items to alloc, I won't complain about anything which gets us closer to that goal even if itself argued incremental.

[max-heller]

I think it would be good to start by refreshing rust-lang/rust#116685

I'm going to give this a shot: rust-lang/rust#153915

[joshtriplett]

We talked about this in today's @rust-lang/libs-api meeting.

We're happy to approve this as an incremental step. We'd also love to see future work for a core::io, once there's a solution for core::io::Error to enable the many things that depend on that, but that shouldn't be a blocker for doing this incremental step.

[a1phyr]

This is great to hear!

As it seems to be very requested, I would like to add my 2 cents on core::io (apart from the fact that I would really like it too).

First, Error is not the real blocker here. Granted, it uses the heap, but we could imagine to have a CoreBox created from alloc with a callback for rustc_dealloc. (A bit like what I do for raw OS errors in rust-lang/rust#152918, but for allocations). It is a bit hacky, but, well, it works.
The real issue here are the traits Read and BufRead whose methods use Vec directly. In the current situation, having them in core would probably require a mechanism to split trait definitions between crates (if we keep the current traits ofc).

However, I there is another way: merge core and alloc in a single crate with a feature "alloc". In this case, we can simply #[cfg(feature = "alloc")] the annoying items. This is probably complex to do, but from a pure library point-of-view, I think that is is quite nice.

[max-heller]

First, Error is not the real blocker here. Granted, it uses the heap, but we could imagine to have a CoreBox created from alloc with a callback for rustc_dealloc. (A bit like what I do for raw OS errors in rust-lang/rust#152918, but for allocations). It is a bit hacky, but, well, it works.

This approach was demoed by programmerjake and I've brought it up-to-date in rust-lang/rust#153915. It works, on most platforms, but in core we can't necessarily assume atomics are available on all platforms to implement the vtables (see #t-libs > Targets that don't support all atomic orderings). So it's not the only blocker, but it does seem to be a blocker at least for now (until we get externally-implementable-items with default implementations or a resolution on platform support for atomics).

Edit: How does this work in rust-lang/rust#152918, do we assume that all platforms that support alloc support pointer-sized atomics? The docs for e.g. alloc::sync seem to contradict that:

Note: This module is only available on platforms that support atomic loads and stores of pointers. This may be detected at compile time using #[cfg(target_has_atomic = "ptr")].

---

The real issue here are the traits Read and BufRead whose methods use Vec directly. In the current situation, having them in core would probably require a mechanism to split trait definitions between crates (if we keep the current traits ofc).

I wonder how breaking it would be to change the &mut Vec<u8> parameters to something like &mut impl/dyn Extend<u8> (over an edition?). From the perspective of callers, I'd expect that to work (mostly?) the same, and it doesn't look like there are a ton of implementations of read_to_end() that actually depend on the Vec. Probably too breaking to ever do, but just a thought.

[fintelia]

From the perspective of callers, I'd expect that to work (mostly?) the same, and it doesn't look like there are a ton of implementations of read_to_end() that actually depend on the Vec. Probably too breaking to ever do, but just a thought.

Some of the standard library's implementations of read_to_end read into the unfilled portion of the Vec.

[a1phyr]

Edit: How does this work in rust-lang/rust#152918, do we assume that all platforms that support alloc support pointer-sized atomics? The docs for e.g. alloc::sync seem to contradict that

Hmm, I though that not using CAS made me safe about this, but I it looks like old ARM architectures are full of surprises! Time for some cfg I guess. Thanks!