Auto merge of #23548 - Manishearth:rollup, r=Manishearth

Author: bors

Makefile.in

@@ -97,12 +97,7 @@
 #     make check-stage1-rpass TESTNAME=my-shiny-new-test
 #
 #     // Having trouble figuring out which test is failing? Turn off parallel tests
-#     make check-stage1-std RUST_TEST_TASKS=1
-#
-# This is hardly all there is to know of The Rust Build System's
-# mysteries. The tale continues on the wiki[1].
-#
-# [1]: https://github.com/rust-lang/rust/wiki/Note-testsuite
+#     make check-stage1-std RUST_TEST_THREADS=1
 #
 # If you really feel like getting your hands dirty, then:
 #

man/rustc.1

@@ -242,6 +242,28 @@ full debug info with variable and type information.
 \fBopt\-level\fR=\fIVAL\fR
 Optimize with possible levels 0\[en]3
 
+.SH ENVIRONMENT VARIABLES
+
+Some of these affect the output of the compiler, while others affect programs
+which link to the standard library.
+
+.TP
+\fBRUST_TEST_THREADS\fR
+The test framework Rust provides executes tests in parallel. This variable sets
+the maximum number of threads used for this purpose.
+
+.TP
+\fBRUST_TEST_NOCAPTURE\fR
+A synonym for the --nocapture flag.
+
+.TP
+\fBRUST_MIN_STACK\fR
+Sets the minimum stack size for new threads.
+
+.TP
+\fBRUST_BACKTRACE\fR
+If set, produces a backtrace in the output of a program which panics.
+
 .SH "EXAMPLES"
 To build an executable from a source file with a main function:
     $ rustc \-o hello hello.rs

src/compiletest/compiletest.rs

@@ -224,15 +224,15 @@ pub fn run_tests(config: &Config) {
         // android debug-info test uses remote debugger
         // so, we test 1 task at once.
         // also trying to isolate problems with adb_run_wrapper.sh ilooping
-        env::set_var("RUST_TEST_TASKS","1");
+        env::set_var("RUST_TEST_THREADS","1");
     }
 
     match config.mode {
         DebugInfoLldb => {
             // Some older versions of LLDB seem to have problems with multiple
             // instances running in parallel, so only run one test task at a
             // time.
-            env::set_var("RUST_TEST_TASKS", "1");
+            env::set_var("RUST_TEST_THREADS", "1");
         }
         _ => { /* proceed */ }
     }

src/compiletest/header.rs

@@ -131,7 +131,7 @@ pub fn load_props(testfile: &Path) -> TestProps {
         true
     });
 
-    for key in vec!["RUST_TEST_NOCAPTURE", "RUST_TEST_TASKS"] {
+    for key in vec!["RUST_TEST_NOCAPTURE", "RUST_TEST_THREADS"] {
         match env::var(key) {
             Ok(val) =>
                 if exec_env.iter().find(|&&(ref x, _)| *x == key.to_string()).is_none() {

src/doc/trpl/ffi.md

@@ -170,6 +170,8 @@ Foreign libraries often hand off ownership of resources to the calling code.
 When this occurs, we must use Rust's destructors to provide safety and guarantee
 the release of these resources (especially in the case of panic).
 
+For more about destructors, see the [Drop trait](../std/ops/trait.Drop.html).
+
 # Callbacks from C code to Rust functions
 
 Some external libraries require the usage of callbacks to report back their

src/doc/trpl/pointers.md

@@ -561,38 +561,40 @@ fn main() {
 In this case, Rust knows that `x` is being *borrowed* by the `add_one()`
 function, and since it's only reading the value, allows it.
 
-We can borrow `x` multiple times, as long as it's not simultaneous:
+We can borrow `x` as read-only multiple times, even simultaneously:
 
 ```{rust}
-fn add_one(x: &i32) -> i32 {
-    *x + 1
+fn add(x: &i32, y: &i32) -> i32 {
+    *x + *y
 }
 
 fn main() {
     let x = Box::new(5);
 
-    println!("{}", add_one(&*x));
-    println!("{}", add_one(&*x));
-    println!("{}", add_one(&*x));
+    println!("{}", add(&x, &x));
+    println!("{}", add(&x, &x));
 }
 ```
 
-Or as long as it's not a mutable borrow. This will error:
+We can mutably borrow `x` multiple times, but only if x itself is mutable, and
+it may not be *simultaneously* borrowed: 
 
 ```{rust,ignore}
-fn add_one(x: &mut i32) -> i32 {
-    *x + 1
+fn increment(x: &mut i32) {
+    *x += 1;
 }
 
 fn main() {
-    let x = Box::new(5);
+    // If variable x is not "mut", this will not compile
+    let mut x = Box::new(5);
 
-    println!("{}", add_one(&*x)); // error: cannot borrow immutable dereference
-                                  // of `&`-pointer as mutable
+    increment(&mut x);
+    increment(&mut x);
+    println!("{}", x);
 }
 ```
 
-Notice we changed the signature of `add_one()` to request a mutable reference.
+Notice the signature of `increment()` requests a mutable reference.
 
 ## Best practices
 

src/doc/trpl/unsafe.md

@@ -93,10 +93,6 @@ offered by the Rust language and libraries. For example, they
 - are plain-old-data, that is, they don't move ownership, again unlike
   `Box`, hence the Rust compiler cannot protect against bugs like
   use-after-free;
-- are considered sendable (if their contents is considered sendable),
-  so the compiler offers no assistance with ensuring their use is
-  thread-safe; for example, one can concurrently access a `*mut i32`
-  from two threads without synchronization.
 - lack any form of lifetimes, unlike `&`, and so the compiler cannot
   reason about dangling pointers; and
 - have no guarantees about aliasing or mutability other than mutation

src/libstd/fs/mod.rs

@@ -73,6 +73,11 @@ pub struct Metadata(fs_imp::FileAttr);
 /// will yield instances of `io::Result<DirEntry>`. Through a `DirEntry`
 /// information like the entry's path and possibly other metadata can be
 /// learned.
+///
+/// # Failure
+///
+/// This `io::Result` will be an `Err` if there's some sort of intermittent
+/// IO error during iteration.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct ReadDir(fs_imp::ReadDir);
 

src/libstd/io/mod.rs

@@ -584,7 +584,8 @@ pub trait BufRead: Read {
         read_until(self, byte, buf)
     }
 
-    /// Read all bytes until a newline byte (the 0xA byte) is reached.
+    /// Read all bytes until a newline byte (the 0xA byte) is reached, and
+    /// append them to the provided buffer.
     ///
     /// This function will continue to read (and buffer) bytes from the
     /// underlying stream until the newline delimiter (the 0xA byte) or EOF is

src/libstd/num/f32.rs

@@ -191,8 +191,8 @@ impl Float for f32 {
     /// Constructs a floating point number by multiplying `x` by 2 raised to the
     /// power of `exp`
     #[inline]
-    fn ldexp(x: f32, exp: int) -> f32 {
-        unsafe { cmath::ldexpf(x, exp as c_int) }
+    fn ldexp(self, exp: isize) -> f32 {
+        unsafe { cmath::ldexpf(self, exp as c_int) }
     }
 
     /// Breaks the number into a normalized fraction and a base-2 exponent,
@@ -2207,8 +2207,8 @@ mod tests {
         let f1: f32 = FromStrRadix::from_str_radix("1p-123", 16).unwrap();
         let f2: f32 = FromStrRadix::from_str_radix("1p-111", 16).unwrap();
         let f3: f32 = FromStrRadix::from_str_radix("1.Cp-12", 16).unwrap();
-        assert_eq!(Float::ldexp(1f32, -123), f1);
-        assert_eq!(Float::ldexp(1f32, -111), f2);
+        assert_eq!(1f32.ldexp(-123), f1);
+        assert_eq!(1f32.ldexp(-111), f2);
         assert_eq!(Float::ldexp(1.75f32, -12), f3);
 
         assert_eq!(Float::ldexp(0f32, -123), 0f32);