Back io::stdin with a global singleton BufferedReader

[sfackler]

io::stdin returns a new BufferedReader each time it's called, which
results in some very confusing behavior with disappearing output. It now
returns a StdinReader, which wraps a global singleton
Arc<Mutex<BufferedReader<StdReader>>. Reader is implemented directly
on StdinReader. However, Buffer is not, as the fill_buf method is
fundamentaly un-thread safe. A lock method is defined on StdinReader
which returns a smart pointer wrapping the underlying BufferedReader
while guaranteeing mutual exclusion.

Code that treats the return value of io::stdin as implementing Buffer
will break. Add a call to lock:

io::stdin().read_line();
// =>
io::stdin().lock().read_line();

Closes #14434

[breaking-change]

[rust-highfive]

Warning

• These commits modify unsafe code. Please review it carefully!

[sfackler]

r? @aturon

[aturon]

@sfackler Sorry again for the delay in reviewing this -- it's been very hectic.

@alexcrichton and I talked at length about this PR today, in the context of our in progress std::io reform, and determined that you've basically hit the nail on the head with this. The only request we have is to add inherent methods to StdinReader corresponding to the default methods of Buffer (so not fill_buf or consume), which are implemented by calling the same method on the lock guard. That way the ergonomics are largely the same as today, the breakage is minimized, but we still ensure a clear, thread-safe semantics for the high-level operations.

[sfackler]

Cool, I was considering doing that. read_line, read_until and read_char will be easy. chars and lines don't have a trivial delegation strategy since the lifetimes of the iterators they return won't work out.

I see three possibilities for those.

• We can leave off those methods and force people to call lock() to get at them.
• We can implement our own versions that hold the lock for the lifetime of the iterator object.
• We can implement our own versions that only lock for each individual next call.

I think the first option is probably the best for now, since if we have chars and lines, I imagine it'll be a bit confusing to readers as to which of the options above was used and I'm not sure what the right answer is here, though I'd probably lean towards bullet 2.

[aturon]

I would actually lean more toward bullet 3 (since that's rougly the behavior you'd get by repeatedly calling read_line), but fine to leave these off for now.

[sfackler]

@aturon updated

[sfackler]

I also adjusted lock to take &mut self, which should help prevent people from deadlocking themselves.