mathieu/os-rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Auto merge of #86799 - tlyu:stdio-locked, r=joshtriplett

Browse source 
add owned locked stdio handles

Add stderr_locked, stdin_locked, and stdout_locked free functions
to obtain owned locked stdio handles in a single step. Also add
into_lock methods to consume a stdio handle and return an owned
lock. These methods will make it easier to use locked stdio
handles without having to deal with lifetime problems or keeping
bindings to the unlocked handles around.

Fixes #85383; enables #86412.

r? `@joshtriplett`
`@rustbot` label +A-io +C-enhancement +D-newcomer-roadblock +T-libs-api
This commit is contained in:
bors 2021-07-03 10:40:53 +00:00
commit a8b8558f08
3 changed files with 337 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
library/std/src/io/mod.rs
View file

@ -277,6 +277,8 @@ pub use self::error::{Error, ErrorKind, Result};
pub use self::stdio::set_output_capture;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::stdio::{stderr, stdin, stdout, Stderr, Stdin, Stdout};
#[unstable(feature = "stdio_locked", issue = "none")]
pub use self::stdio::{stderr_locked, stdin_locked, stdout_locked};
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::stdio::{StderrLock, StdinLock, StdoutLock};
#[unstable(feature = "print_internals", issue = "none")]

217
library/std/src/io/stdio.rs
View file

@ -310,6 +310,48 @@ pub fn stdin() -> Stdin {
}
}
/// Constructs a new locked handle to the standard input of the current
/// process.
///
/// Each handle returned is a guard granting locked access to a shared
/// global buffer whose access is synchronized via a mutex. If you need
/// more explicit control over locking, for example, in a multi-threaded
/// program, use the [`io::stdin`] function to obtain an unlocked handle,
/// along with the [`Stdin::lock`] method.
///
/// The lock is released when the returned guard goes out of scope. The
/// returned guard also implements the [`Read`] and [`BufRead`] traits for
/// accessing the underlying data.
///
/// **Note**: The mutex locked by this handle is not reentrant. Even in a
/// single-threaded program, calling other code that accesses [`Stdin`]
/// could cause a deadlock or panic, if this locked handle is held across
/// that call.
///
/// ### Note: Windows Portability Consideration
/// When operating in a console, the Windows implementation of this stream does not support
/// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
/// an error.
///
/// # Examples
///
/// ```no_run
/// #![feature(stdio_locked)]
/// use std::io::{self, Read};
///
/// fn main() -> io::Result<()> {
/// let mut buffer = String::new();
/// let mut handle = io::stdin_locked();
///
/// handle.read_to_string(&mut buffer)?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "stdio_locked", issue = "none")]
pub fn stdin_locked() -> StdinLock<'static> {
stdin().into_locked()
}
impl Stdin {
/// Locks this handle to the standard input stream, returning a readable
/// guard.
@ -334,7 +376,7 @@ impl Stdin {
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn lock(&self) -> StdinLock<'_> {
StdinLock { inner: self.inner.lock().unwrap_or_else(|e| e.into_inner()) }
self.lock_any()
}
/// Locks this handle and reads a line of input, appending it to the specified buffer.
@ -367,6 +409,43 @@ impl Stdin {
pub fn read_line(&self, buf: &mut String) -> io::Result<usize> {
self.lock().read_line(buf)
}
// Locks this handle with any lifetime. This depends on the
// implementation detail that the underlying `Mutex` is static.
fn lock_any<'a>(&self) -> StdinLock<'a> {
StdinLock { inner: self.inner.lock().unwrap_or_else(|e| e.into_inner()) }
}
/// Consumes this handle to the standard input stream, locking the
/// shared global buffer associated with the stream and returning a
/// readable guard.
///
/// The lock is released when the returned guard goes out of scope. The
/// returned guard also implements the [`Read`] and [`BufRead`] traits
/// for accessing the underlying data.
///
/// It is often simpler to directly get a locked handle using the
/// [`stdin_locked`] function instead, unless nearby code also needs to
/// use an unlocked handle.
///
/// # Examples
///
/// ```no_run
/// #![feature(stdio_locked)]
/// use std::io::{self, Read};
///
/// fn main() -> io::Result<()> {
/// let mut buffer = String::new();
/// let mut handle = io::stdin().into_locked();
///
/// handle.read_to_string(&mut buffer)?;
/// Ok(())
/// }
/// ```
#[unstable(feature = "stdio_locked", issue = "none")]
pub fn into_locked(self) -> StdinLock<'static> {
self.lock_any()
}
}
#[stable(feature = "std_debug", since = "1.16.0")]
@ -558,6 +637,42 @@ pub fn stdout() -> Stdout {
}
}
/// Constructs a new locked handle to the standard output of the current
/// process.
///
/// Each handle returned is a guard granting locked access to a shared
/// global buffer whose access is synchronized via a mutex. If you need
/// more explicit control over locking, for example, in a multi-threaded
/// program, use the [`io::stdout`] function to obtain an unlocked handle,
/// along with the [`Stdout::lock`] method.
///
/// The lock is released when the returned guard goes out of scope. The
/// returned guard also implements the [`Write`] trait for writing data.
///
/// ### Note: Windows Portability Consideration
/// When operating in a console, the Windows implementation of this stream does not support
/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
/// an error.
///
/// # Examples
///
/// ```no_run
/// #![feature(stdio_locked)]
/// use std::io::{self, Write};
///
/// fn main() -> io::Result<()> {
/// let mut handle = io::stdout_locked();
///
/// handle.write_all(b"hello world")?;
///
/// Ok(())
/// }
/// ```
#[unstable(feature = "stdio_locked", issue = "none")]
pub fn stdout_locked() -> StdoutLock<'static> {
stdout().into_locked()
}
pub fn cleanup() {
if let Some(instance) = STDOUT.get() {
// Flush the data and disable buffering during shutdown
@ -595,8 +710,45 @@ impl Stdout {
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn lock(&self) -> StdoutLock<'_> {
self.lock_any()
}
// Locks this handle with any lifetime. This depends on the
// implementation detail that the underlying `ReentrantMutex` is
// static.
fn lock_any<'a>(&self) -> StdoutLock<'a> {
StdoutLock { inner: self.inner.lock() }
}
/// Consumes this handle to the standard output stream, locking the
/// shared global buffer associated with the stream and returning a
/// writable guard.
///
/// The lock is released when the returned lock goes out of scope. The
/// returned guard also implements the [`Write`] trait for writing data.
///
/// It is often simpler to directly get a locked handle using the
/// [`io::stdout_locked`] function instead, unless nearby code also
/// needs to use an unlocked handle.
///
/// # Examples
///
/// ```no_run
/// #![feature(stdio_locked)]
/// use std::io::{self, Write};
///
/// fn main() -> io::Result<()> {
/// let mut handle = io::stdout().into_locked();
///
/// handle.write_all(b"hello world")?;
///
/// Ok(())
/// }
/// ```
#[unstable(feature = "stdio_locked", issue = "none")]
pub fn into_locked(self) -> StdoutLock<'static> {
self.lock_any()
}
}
#[stable(feature = "std_debug", since = "1.16.0")]
@ -769,6 +921,35 @@ pub fn stderr() -> Stderr {
}
}
/// Constructs a new locked handle to the standard error of the current
/// process.
///
/// This handle is not buffered.
///
/// ### Note: Windows Portability Consideration
/// When operating in a console, the Windows implementation of this stream does not support
/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
/// an error.
///
/// # Example
///
/// ```no_run
/// #![feature(stdio_locked)]
/// use std::io::{self, Write};
///
/// fn main() -> io::Result<()> {
/// let mut handle = io::stderr_locked();
///
/// handle.write_all(b"hello world")?;
///
/// Ok(())
/// }
/// ```
#[unstable(feature = "stdio_locked", issue = "none")]
pub fn stderr_locked() -> StderrLock<'static> {
stderr().into_locked()
}
impl Stderr {
/// Locks this handle to the standard error stream, returning a writable
/// guard.
@ -792,8 +973,42 @@ impl Stderr {
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn lock(&self) -> StderrLock<'_> {
self.lock_any()
}
// Locks this handle with any lifetime. This depends on the
// implementation detail that the underlying `ReentrantMutex` is
// static.
fn lock_any<'a>(&self) -> StderrLock<'a> {
StderrLock { inner: self.inner.lock() }
}
/// Locks and consumes this handle to the standard error stream,
/// returning a writable guard.
///
/// The lock is released when the returned guard goes out of scope. The
/// returned guard also implements the [`Write`] trait for writing
/// data.
///
/// # Examples
///
/// ```
/// #![feature(stdio_locked)]
/// use std::io::{self, Write};
///
/// fn foo() -> io::Result<()> {
/// let stderr = io::stderr();
/// let mut handle = stderr.into_locked();
///
/// handle.write_all(b"hello world")?;
///
/// Ok(())
/// }
/// ```
#[unstable(feature = "stdio_locked", issue = "none")]
pub fn into_locked(self) -> StderrLock<'static> {
self.lock_any()
}
}
#[stable(feature = "std_debug", since = "1.16.0")]

119
library/std/src/io/stdio/tests.rs
View file

@ -1,5 +1,6 @@
use super::*;
use crate::panic::{RefUnwindSafe, UnwindSafe};
use crate::sync::mpsc::sync_channel;
use crate::thread;
#[test]
@ -45,3 +46,121 @@ fn panic_doesnt_poison() {
let _a = stderr();
let _a = _a.lock();
}
#[test]
#[cfg_attr(target_os = "emscripten", ignore)]
fn test_lock_stderr() {
test_lock(stderr, stderr_locked);
}
#[test]
#[cfg_attr(target_os = "emscripten", ignore)]
fn test_lock_stdin() {
test_lock(stdin, stdin_locked);
}
#[test]
#[cfg_attr(target_os = "emscripten", ignore)]
fn test_lock_stdout() {
test_lock(stdout, stdout_locked);
}
// Helper trait to make lock testing function generic.
trait Stdio<'a>: 'static
where
Self::Lock: 'a,
{
type Lock;
fn lock(&'a self) -> Self::Lock;
}
impl<'a> Stdio<'a> for Stderr {
type Lock = StderrLock<'a>;
fn lock(&'a self) -> StderrLock<'a> {
self.lock()
}
}
impl<'a> Stdio<'a> for Stdin {
type Lock = StdinLock<'a>;
fn lock(&'a self) -> StdinLock<'a> {
self.lock()
}
}
impl<'a> Stdio<'a> for Stdout {
type Lock = StdoutLock<'a>;
fn lock(&'a self) -> StdoutLock<'a> {
self.lock()
}
}
// Helper trait to make lock testing function generic.
trait StdioOwnedLock: 'static {}
impl StdioOwnedLock for StderrLock<'static> {}
impl StdioOwnedLock for StdinLock<'static> {}
impl StdioOwnedLock for StdoutLock<'static> {}
// Tests locking on stdio handles by starting two threads and checking that
// they block each other appropriately.
fn test_lock<T, U>(get_handle: fn() -> T, get_locked: fn() -> U)
where
T: for<'a> Stdio<'a>,
U: StdioOwnedLock,
{
// State enum to track different phases of the test, primarily when
// each lock is acquired and released.
#[derive(Debug, PartialEq)]
enum State {
Start1,
Acquire1,
Start2,
Release1,
Acquire2,
Release2,
}
use State::*;
// Logging vector to be checked to make sure lock acquisitions and
// releases happened in the correct order.
let log = Arc::new(Mutex::new(Vec::new()));
let ((tx1, rx1), (tx2, rx2)) = (sync_channel(0), sync_channel(0));
let th1 = {
let (log, tx) = (Arc::clone(&log), tx1);
thread::spawn(move || {
log.lock().unwrap().push(Start1);
let handle = get_handle();
{
let locked = handle.lock();
log.lock().unwrap().push(Acquire1);
tx.send(Acquire1).unwrap(); // notify of acquisition
tx.send(Release1).unwrap(); // wait for release command
log.lock().unwrap().push(Release1);
}
tx.send(Acquire1).unwrap(); // wait for th2 acquire
{
let locked = handle.lock();
log.lock().unwrap().push(Acquire1);
}
log.lock().unwrap().push(Release1);
})
};
let th2 = {
let (log, tx) = (Arc::clone(&log), tx2);
thread::spawn(move || {
tx.send(Start2).unwrap(); // wait for start command
let locked = get_locked();
log.lock().unwrap().push(Acquire2);
tx.send(Acquire2).unwrap(); // notify of acquisition
tx.send(Release2).unwrap(); // wait for release command
log.lock().unwrap().push(Release2);
})
};
assert_eq!(rx1.recv().unwrap(), Acquire1); // wait for th1 acquire
log.lock().unwrap().push(Start2);
assert_eq!(rx2.recv().unwrap(), Start2); // block th2
assert_eq!(rx1.recv().unwrap(), Release1); // release th1
assert_eq!(rx2.recv().unwrap(), Acquire2); // wait for th2 acquire
assert_eq!(rx1.recv().unwrap(), Acquire1); // block th1
assert_eq!(rx2.recv().unwrap(), Release2); // release th2
th2.join().unwrap();
th1.join().unwrap();
assert_eq!(
*log.lock().unwrap(),
[Start1, Acquire1, Start2, Release1, Acquire2, Release2, Acquire1, Release1]
);
}