diff --git a/src/doc/unstable-book/src/SUMMARY.md b/src/doc/unstable-book/src/SUMMARY.md index 3d9e7c7fd860d..8f26e4d36cda2 100644 --- a/src/doc/unstable-book/src/SUMMARY.md +++ b/src/doc/unstable-book/src/SUMMARY.md @@ -178,7 +178,7 @@ - [peek](library-features/peek.md) - [placement_in](library-features/placement-in.md) - [placement_new_protocol](library-features/placement-new-protocol.md) - - [print](library-features/print.md) + - [print_internals](library-features/print-internals.md) - [proc_macro_internals](library-features/proc-macro-internals.md) - [process_try_wait](library-features/process-try-wait.md) - [question_mark_carrier](library-features/question-mark-carrier.md) diff --git a/src/doc/unstable-book/src/library-features/print.md b/src/doc/unstable-book/src/library-features/print-internals.md similarity index 84% rename from src/doc/unstable-book/src/library-features/print.md rename to src/doc/unstable-book/src/library-features/print-internals.md index dc25cb237e3b5..a68557872af55 100644 --- a/src/doc/unstable-book/src/library-features/print.md +++ b/src/doc/unstable-book/src/library-features/print-internals.md @@ -1,4 +1,4 @@ -# `print` +# `print_internals` This feature is internal to the Rust compiler and is not intended for general use. diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index e2832873e2e67..c872a8e526114 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -287,9 +287,11 @@ pub use self::error::{Result, Error, ErrorKind}; #[stable(feature = "rust1", since = "1.0.0")] pub use self::util::{copy, sink, Sink, empty, Empty, repeat, Repeat}; #[stable(feature = "rust1", since = "1.0.0")] -pub use self::stdio::{stdin, stdout, stderr, _print, Stdin, Stdout, Stderr}; +pub use self::stdio::{stdin, stdout, stderr, Stdin, Stdout, Stderr}; #[stable(feature = "rust1", since = "1.0.0")] pub use self::stdio::{StdoutLock, StderrLock, StdinLock}; +#[unstable(feature = "print_internals", issue = "0")] +pub use self::stdio::{_print, _eprint}; #[unstable(feature = "libstd_io_internals", issue = "0")] #[doc(no_inline, hidden)] pub use self::stdio::{set_panic, set_print}; diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs index 38ad23e14b3eb..a8b0bf0071a22 100644 --- a/src/libstd/io/stdio.rs +++ b/src/libstd/io/stdio.rs @@ -17,7 +17,7 @@ use io::{self, BufReader, LineWriter}; use sync::{Arc, Mutex, MutexGuard}; use sys::stdio; use sys_common::remutex::{ReentrantMutex, ReentrantMutexGuard}; -use thread::LocalKeyState; +use thread::{LocalKey, LocalKeyState}; /// Stdout used by print! and println! macros thread_local! { @@ -659,41 +659,56 @@ pub fn set_print(sink: Option>) -> Option> { }) } -#[unstable(feature = "print", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "0")] -#[doc(hidden)] -pub fn _print(args: fmt::Arguments) { - // As an implementation of the `println!` macro, we want to try our best to - // not panic wherever possible and get the output somewhere. There are - // currently two possible vectors for panics we take care of here: - // - // 1. If the TLS key for the local stdout has been destroyed, accessing it - // would cause a panic. Note that we just lump in the uninitialized case - // here for convenience, we're not trying to avoid a panic. - // 2. If the local stdout is currently in use (e.g. we're in the middle of - // already printing) then accessing again would cause a panic. - // - // If, however, the actual I/O causes an error, we do indeed panic. - let result = match LOCAL_STDOUT.state() { +/// Write `args` to output stream `local_s` if possible, `global_s` +/// otherwise. `label` identifies the stream in a panic message. +/// +/// This function is used to print error messages, so it takes extra +/// care to avoid causing a panic when `local_stream` is unusable. +/// For instance, if the TLS key for the local stream is uninitialized +/// or already destroyed, or if the local stream is locked by another +/// thread, it will just fall back to the global stream. +/// +/// However, if the actual I/O causes an error, this function does panic. +fn print_to(args: fmt::Arguments, + local_s: &'static LocalKey>>>, + global_s: fn() -> T, + label: &str) where T: Write { + let result = match local_s.state() { LocalKeyState::Uninitialized | - LocalKeyState::Destroyed => stdout().write_fmt(args), + LocalKeyState::Destroyed => global_s().write_fmt(args), LocalKeyState::Valid => { - LOCAL_STDOUT.with(|s| { + local_s.with(|s| { if let Ok(mut borrowed) = s.try_borrow_mut() { if let Some(w) = borrowed.as_mut() { return w.write_fmt(args); } } - stdout().write_fmt(args) + global_s().write_fmt(args) }) } }; if let Err(e) = result { - panic!("failed printing to stdout: {}", e); + panic!("failed printing to {}: {}", label, e); } } +#[unstable(feature = "print_internals", + reason = "implementation detail which may disappear or be replaced at any time", + issue = "0")] +#[doc(hidden)] +pub fn _print(args: fmt::Arguments) { + print_to(args, &LOCAL_STDOUT, stdout, "stdout"); +} + +#[unstable(feature = "print_internals", + reason = "implementation detail which may disappear or be replaced at any time", + issue = "0")] +#[doc(hidden)] +pub fn _eprint(args: fmt::Arguments) { + use panicking::LOCAL_STDERR; + print_to(args, &LOCAL_STDERR, stderr, "stderr"); +} + #[cfg(test)] mod tests { use thread; diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index a1f092621cb44..ef78ea6dfe8ee 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -68,6 +68,9 @@ macro_rules! panic { /// necessary to use `io::stdout().flush()` to ensure the output is emitted /// immediately. /// +/// Use `print!` only for the primary output of your program. Use +/// `eprint!` instead to print error and progress messages. +/// /// # Panics /// /// Panics if writing to `io::stdout()` fails. @@ -105,9 +108,12 @@ macro_rules! print { /// Use the `format!` syntax to write data to the standard output. /// See `std::fmt` for more information. /// +/// Use `println!` only for the primary output of your program. Use +/// `eprintln!` instead to print error and progress messages. +/// /// # Panics /// -/// Panics if writing to `io::stdout()` fails. +/// Panics if writing to `io::stdout` fails. /// /// # Examples /// @@ -124,6 +130,45 @@ macro_rules! println { ($fmt:expr, $($arg:tt)*) => (print!(concat!($fmt, "\n"), $($arg)*)); } +/// Macro for printing to the standard error. +/// +/// Equivalent to the `print!` macro, except that output goes to +/// `io::stderr` instead of `io::stdout`. See `print!` for +/// example usage. +/// +/// Use `eprint!` only for error and progress messages. Use `print!` +/// instead for the primary output of your program. +/// +/// # Panics +/// +/// Panics if writing to `io::stderr` fails. +#[macro_export] +#[stable(feature = "eprint", since="1.18.0")] +#[allow_internal_unstable] +macro_rules! eprint { + ($($arg:tt)*) => ($crate::io::_eprint(format_args!($($arg)*))); +} + +/// Macro for printing to the standard error, with a newline. +/// +/// Equivalent to the `println!` macro, except that output goes to +/// `io::stderr` instead of `io::stdout`. See `println!` for +/// example usage. +/// +/// Use `eprintln!` only for error and progress messages. Use `println!` +/// instead for the primary output of your program. +/// +/// # Panics +/// +/// Panics if writing to `io::stderr` fails. +#[macro_export] +#[stable(feature = "eprint", since="1.18.0")] +macro_rules! eprintln { + () => (eprint!("\n")); + ($fmt:expr) => (eprint!(concat!($fmt, "\n"))); + ($fmt:expr, $($arg:tt)*) => (eprint!(concat!($fmt, "\n"), $($arg)*)); +} + /// A macro to select an event from a number of receivers. /// /// This macro is used to wait for the first event to occur on a number of diff --git a/src/test/run-pass/print-stdout-eprint-stderr.rs b/src/test/run-pass/print-stdout-eprint-stderr.rs new file mode 100644 index 0000000000000..0a0f30aba72c2 --- /dev/null +++ b/src/test/run-pass/print-stdout-eprint-stderr.rs @@ -0,0 +1,40 @@ +// Copyright 2017 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +// ignore-emscripten spawning processes is not supported + +use std::{env, process}; + +fn child() { + print!("[stdout 0]"); + print!("[stdout {}]", 1); + println!("[stdout {}]", 2); + println!(); + eprint!("[stderr 0]"); + eprint!("[stderr {}]", 1); + eprintln!("[stderr {}]", 2); + eprintln!(); +} + +fn parent() { + let this = env::args().next().unwrap(); + let output = process::Command::new(this).arg("-").output().unwrap(); + assert!(output.status.success()); + + let stdout = String::from_utf8(output.stdout).unwrap(); + let stderr = String::from_utf8(output.stderr).unwrap(); + + assert_eq!(stdout, "[stdout 0][stdout 1][stdout 2]\n\n"); + assert_eq!(stderr, "[stderr 0][stderr 1][stderr 2]\n\n"); +} + +fn main() { + if env::args().count() == 2 { child() } else { parent() } +}