---

yaml
---
r: 195546
b: refs/heads/master
c: abd747c
h: refs/heads/master
v: v3

Author: Manishearth

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 240734c31e529557583a0dc8e97abf858b4a375d
+refs/heads/master: abd747cd153c1ef3648831916017fb692200387d
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: b3317d68910900f135f9f38e43a7a699bc736b4a
 refs/heads/try: 961e0358e1a5c0faaef606e31e9965742c1643bf

trunk/configure

@@ -404,7 +404,7 @@ case $CFG_OSTYPE in
         CFG_OSTYPE=pc-windows-gnu
         ;;
 
-# Thad's Cygwin identifers below
+# Thad's Cygwin identifiers below
 
 #   Vista 32 bit
     CYGWIN_NT-6.0)
@@ -526,7 +526,8 @@ VAL_OPTIONS=""
 opt valgrind 0 "run tests with valgrind (memcheck by default)"
 opt helgrind 0 "run tests with helgrind instead of memcheck"
 opt valgrind-rpass 1 "run rpass-valgrind tests with valgrind"
-opt docs     1 "build documentation"
+opt docs     1 "build standard library documentation"
+opt compiler-docs     0 "build compiler documentation"
 opt optimize 1 "build optimized rust code"
 opt optimize-cxx 1 "build optimized C++ code"
 opt optimize-llvm 1 "build optimized LLVM"

trunk/mk/crates.mk

@@ -122,17 +122,34 @@ ONLY_RLIB_rustc_bitflags := 1
 # You should not need to edit below this line
 ################################################################################
 
+# On channels where the only usable crate is std, only build documentation for
+# std. This keeps distributions small and doesn't clutter up the API docs with
+# confusing internal details from the crates behind the facade.
+#
+# (Disabled while cmr figures out how to change rustdoc to make reexports work
+# slightly nicer. Otherwise, all cross-crate links to Vec will go to
+# libcollections, breaking them, and [src] links for anything reexported will
+# not work.)
+
+#ifeq ($(CFG_RELEASE_CHANNEL),stable)
+#DOC_CRATES := std
+#else
+#ifeq ($(CFG_RELEASE_CHANNEL),beta)
+#DOC_CRATES := std
+#else
 DOC_CRATES := $(filter-out rustc, \
-              $(filter-out rustc_trans, \
-              $(filter-out rustc_typeck, \
-              $(filter-out rustc_borrowck, \
-              $(filter-out rustc_resolve, \
-              $(filter-out rustc_driver, \
-              $(filter-out rustc_privacy, \
-              $(filter-out rustc_lint, \
-              $(filter-out log, \
-              $(filter-out getopts, \
-              $(filter-out syntax, $(CRATES))))))))))))
+	   $(filter-out rustc_trans, \
+	   $(filter-out rustc_typeck, \
+	   $(filter-out rustc_borrowck, \
+	   $(filter-out rustc_resolve, \
+	   $(filter-out rustc_driver, \
+	   $(filter-out rustc_privacy, \
+	   $(filter-out rustc_lint, \
+	   $(filter-out log, \
+	   $(filter-out getopts, \
+	   $(filter-out syntax, $(CRATES))))))))))))
+#endif
+#endif
 COMPILER_DOC_CRATES := rustc rustc_trans rustc_borrowck rustc_resolve \
                        rustc_typeck rustc_driver syntax rustc_privacy \
                        rustc_lint

trunk/mk/docs.mk

@@ -259,7 +259,10 @@ doc/$(1)/index.html: $$(LIB_DOC_DEP_$(1)) doc/$(1)/
 endef
 
 $(foreach crate,$(DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),DOC_TARGETS)))
-$(foreach crate,$(COMPILER_DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),COMPILER_DOC_TARGETS)))
+
+ifdef CFG_COMPILER_DOCS
+  $(foreach crate,$(COMPILER_DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),COMPILER_DOC_TARGETS)))
+endif
 
 ifdef CFG_DISABLE_DOCS
   $(info cfg: disabling doc build (CFG_DISABLE_DOCS))

trunk/mk/platform.mk

@@ -179,7 +179,7 @@ define CFG_MAKE_TOOLCHAIN
 
   ifeq ($$(findstring $(HOST_$(1)),arm aarch64 mips mipsel powerpc),)
 
-  # On Bitrig, we need the relocation model to be PIC for everthing
+  # On Bitrig, we need the relocation model to be PIC for everything
   ifeq (,$(filter $(OSTYPE_$(1)),bitrig))
     LLVM_MC_RELOCATION_MODEL="pic"
   else

trunk/mk/target.mk

@@ -132,7 +132,7 @@ endef
 # on $$(TSREQ$(1)_T_$(2)_H_$(3)), to ensure that no products will be
 # put into the target area until after the get-snapshot.py script has
 # had its chance to clean it out; otherwise the other products will be
-# inadvertantly included in the clean out.
+# inadvertently included in the clean out.
 SNAPSHOT_RUSTC_POST_CLEANUP=$(HBIN0_H_$(CFG_BUILD))/rustc$(X_$(CFG_BUILD))
 
 define TARGET_HOST_RULES

trunk/mk/tests.mk

@@ -166,7 +166,7 @@ $(foreach file,$(wildcard $(S)src/doc/trpl/*.md), \
 ######################################################################
 
 # The main testing target. Tests lots of stuff.
-check: cleantmptestlogs cleantestlibs all check-stage2 tidy
+check: check-sanitycheck cleantmptestlogs cleantestlibs all check-stage2 tidy
 	$(Q)$(CFG_PYTHON) $(S)src/etc/check-summary.py tmp/*.log
 
 # As above but don't bother running tidy.
@@ -193,6 +193,11 @@ check-docs: cleantestlibs cleantmptestlogs check-stage2-docs
 # Not run as part of the normal test suite, but tested by bors on checkin.
 check-secondary: check-build-compiletest check-build-lexer-verifier check-lexer check-pretty
 
+.PHONY: check-sanitycheck
+
+check-sanitycheck:
+	$(Q)$(CFG_PYTHON) $(S)src/etc/check-sanitycheck.py
+
 # check + check-secondary.
 #
 # Issue #17883: build check-secondary first so hidden dependencies in

trunk/src/compiletest/compiletest.rs

@@ -18,7 +18,6 @@
 #![feature(std_misc)]
 #![feature(test)]
 #![feature(path_ext)]
-#![feature(convert)]
 #![feature(str_char)]
 
 #![deny(warnings)]

trunk/src/doc/reference.md

@@ -977,17 +977,13 @@ An example of `use` declarations:
 
 ```
 # #![feature(core)]
-use std::iter::range_step;
 use std::option::Option::{Some, None};
 use std::collections::hash_map::{self, HashMap};
 
 fn foo<T>(_: T){}
 fn bar(map1: HashMap<String, usize>, map2: hash_map::HashMap<String, usize>){}
 
 fn main() {
-    // Equivalent to 'std::iter::range_step(0, 10, 2);'
-    range_step(0, 10, 2);
-
     // Equivalent to 'foo(vec![std::option::Option::Some(1.0f64),
     // std::option::Option::None]);'
     foo(vec![Some(1.0f64), None]);
@@ -1188,12 +1184,15 @@ the guarantee that these issues are never caused by safe code.
 
 * Data races
 * Dereferencing a null/dangling raw pointer
-* Mutating an immutable value/reference without `UnsafeCell`
 * Reads of [undef](http://llvm.org/docs/LangRef.html#undefined-values)
   (uninitialized) memory
 * Breaking the [pointer aliasing
   rules](http://llvm.org/docs/LangRef.html#pointer-aliasing-rules)
   with raw pointers (a subset of the rules used by C)
+* `&mut` and `&` follow LLVM’s scoped [noalias] model, except if the `&T`
+  contains an `UnsafeCell<U>`. Unsafe code must not violate these aliasing
+  guarantees.
+* Mutating an immutable value/reference without `UnsafeCell<U>`
 * Invoking undefined behavior via compiler intrinsics:
   * Indexing outside of the bounds of an object with `std::ptr::offset`
     (`offset` intrinsic), with
@@ -1210,6 +1209,8 @@ the guarantee that these issues are never caused by safe code.
   code. Rust's failure system is not compatible with exception handling in
   other languages. Unwinding must be caught and handled at FFI boundaries.
 
+[noalias]: http://llvm.org/docs/LangRef.html#noalias
+
 ##### Behaviour not considered unsafe
 
 This is a list of behaviour not considered *unsafe* in Rust terms, but that may

trunk/src/doc/trpl/SUMMARY.md

@@ -42,5 +42,6 @@
     * [Intrinsics](intrinsics.md)
     * [Lang items](lang-items.md)
     * [Link args](link-args.md)
+    * [Benchmark Tests](benchmark-tests.md)
 * [Conclusion](conclusion.md)
 * [Glossary](glossary.md)

trunk/src/doc/trpl/arrays-vectors-and-slices.md

@@ -99,5 +99,4 @@ You can also take a slice of a vector, `String`, or `&str`, because they are
 backed by arrays. Slices have type `&[T]`, which we'll talk about when we cover
 generics.
 
-We have now learned all of the most basic Rust concepts. Next, we learn how to
-get input from the keyboard.
+We have now learned all of the most basic Rust concepts.

trunk/src/doc/trpl/associated-types.md

@@ -170,7 +170,7 @@ let obj = Box::new(graph) as Box<Graph>;
           ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ```
 
-We can’t create a trait object like this, becuase we don’t know the associated
+We can’t create a trait object like this, because we don’t know the associated
 types. Instead, we can write this:
 
 ```rust

trunk/src/doc/trpl/benchmark-tests.md

@@ -0,0 +1,152 @@
+% Benchmark tests
+
+Rust supports benchmark tests, which can test the performance of your
+code. Let's make our `src/lib.rs` look like this (comments elided):
+
+```{rust,ignore}
+#![feature(test)]
+
+extern crate test;
+
+pub fn add_two(a: i32) -> i32 {
+    a + 2
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use test::Bencher;
+
+    #[test]
+    fn it_works() {
+        assert_eq!(4, add_two(2));
+    }
+
+    #[bench]
+    fn bench_add_two(b: &mut Bencher) {
+        b.iter(|| add_two(2));
+    }
+}
+```
+
+Note the `test` feature gate, which enables this unstable feature.
+
+We've imported the `test` crate, which contains our benchmarking support.
+We have a new function as well, with the `bench` attribute. Unlike regular
+tests, which take no arguments, benchmark tests take a `&mut Bencher`. This
+`Bencher` provides an `iter` method, which takes a closure. This closure
+contains the code we'd like to benchmark.
+
+We can run benchmark tests with `cargo bench`:
+
+```bash
+$ cargo bench
+   Compiling adder v0.0.1 (file:///home/steve/tmp/adder)
+     Running target/release/adder-91b3e234d4ed382a
+
+running 2 tests
+test tests::it_works ... ignored
+test tests::bench_add_two ... bench:         1 ns/iter (+/- 0)
+
+test result: ok. 0 passed; 0 failed; 1 ignored; 1 measured
+```
+
+Our non-benchmark test was ignored. You may have noticed that `cargo bench`
+takes a bit longer than `cargo test`. This is because Rust runs our benchmark
+a number of times, and then takes the average. Because we're doing so little
+work in this example, we have a `1 ns/iter (+/- 0)`, but this would show
+the variance if there was one.
+
+Advice on writing benchmarks:
+
+
+* Move setup code outside the `iter` loop; only put the part you want to measure inside
+* Make the code do "the same thing" on each iteration; do not accumulate or change state
+* Make the outer function idempotent too; the benchmark runner is likely to run
+  it many times
+*  Make the inner `iter` loop short and fast so benchmark runs are fast and the
+   calibrator can adjust the run-length at fine resolution
+* Make the code in the `iter` loop do something simple, to assist in pinpointing
+  performance improvements (or regressions)
+
+## Gotcha: optimizations
+
+There's another tricky part to writing benchmarks: benchmarks compiled with
+optimizations activated can be dramatically changed by the optimizer so that
+the benchmark is no longer benchmarking what one expects. For example, the
+compiler might recognize that some calculation has no external effects and
+remove it entirely.
+
+```{rust,ignore}
+#![feature(test)]
+
+extern crate test;
+use test::Bencher;
+
+#[bench]
+fn bench_xor_1000_ints(b: &mut Bencher) {
+    b.iter(|| {
+        (0..1000).fold(0, |old, new| old ^ new);
+    });
+}
+```
+
+gives the following results
+
+```text
+running 1 test
+test bench_xor_1000_ints ... bench:         0 ns/iter (+/- 0)
+
+test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured
+```
+
+The benchmarking runner offers two ways to avoid this. Either, the closure that
+the `iter` method receives can return an arbitrary value which forces the
+optimizer to consider the result used and ensures it cannot remove the
+computation entirely. This could be done for the example above by adjusting the
+`b.iter` call to
+
+```rust
+# struct X;
+# impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X;
+b.iter(|| {
+    // note lack of `;` (could also use an explicit `return`).
+    (0..1000).fold(0, |old, new| old ^ new)
+});
+```
+
+Or, the other option is to call the generic `test::black_box` function, which
+is an opaque "black box" to the optimizer and so forces it to consider any
+argument as used.
+
+```rust
+#![feature(test)]
+
+extern crate test;
+
+# fn main() {
+# struct X;
+# impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X;
+b.iter(|| {
+    let n = test::black_box(1000);
+
+    (0..n).fold(0, |a, b| a ^ b)
+})
+# }
+```
+
+Neither of these read or modify the value, and are very cheap for small values.
+Larger values can be passed indirectly to reduce overhead (e.g.
+`black_box(&huge_struct)`).
+
+Performing either of the above changes gives the following benchmarking results
+
+```text
+running 1 test
+test bench_xor_1000_ints ... bench:       131 ns/iter (+/- 3)
+
+test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured
+```
+
+However, the optimizer can still modify a testcase in an undesirable manner
+even when using either of the above.

trunk/src/doc/trpl/concurrency.md

@@ -280,13 +280,15 @@ it returns an `Result<T, E>`, and because this is just an example, we `unwrap()`
 it to get a reference to the data. Real code would have more robust error handling
 here. We're then free to mutate it, since we have the lock.
 
-This timer bit is a bit awkward, however. We have picked a reasonable amount of
-time to wait, but it's entirely possible that we've picked too high, and that
-we could be taking less time. It's also possible that we've picked too low,
-and that we aren't actually finishing this computation.
-
-Rust's standard library provides a few more mechanisms for two threads to
-synchronize with each other. Let's talk about one: channels.
+Lastly, while the threads are running, we wait on a short timer. But
+this is not ideal: we may have picked a reasonable amount of time to
+wait but it's more likely we'll either be waiting longer than
+necessary or not long enough, depending on just how much time the
+threads actually take to finish computing when the program runs.
+
+A more precise alternative to the timer would be to use one of the
+mechanisms provided by the Rust standard library for synchronizing
+threads with each other. Let's talk about one of them: channels.
 
 ## Channels
 

trunk/src/doc/trpl/documentation.md

@@ -529,7 +529,7 @@ This will create documentation for bar both inside the documentation for the
 crate `foo`, as well as the documentation for your crate. It will use the same
 documentation in both places.
 
-This behavior can be supressed with `no_inline`:
+This behavior can be suppressed with `no_inline`:
 
 ```ignore
 extern crate foo;