---

yaml
---
r: 156246
b: refs/heads/snap-stage3
c: 86509d8
h: refs/heads/master
v: v3

Author: bors

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: c29a7520e7fb4a5b4d4eccfc594e05793ef6688d
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 151aaaf46ba7ba9c53f3e7df7a04b93cf1b8fd9f
+refs/heads/snap-stage3: 86509d8d7ab68c5e4202dea9ff1bfb79409f2f8d
 refs/heads/try: 6601b0501e31d08d3892a2d5a7d8a57ab120bf75
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/mk/crates.mk

@@ -101,7 +101,7 @@ DEPS_regex := std
 DEPS_regex_macros = rustc syntax std regex
 DEPS_fmt_macros = std
 
-TOOL_DEPS_compiletest := test getopts
+TOOL_DEPS_compiletest := test getopts native
 TOOL_DEPS_rustdoc := rustdoc native
 TOOL_DEPS_rustc := rustc native
 TOOL_SOURCE_compiletest := $(S)src/compiletest/compiletest.rs

branches/snap-stage3/src/libcollections/btree/map.rs

@@ -29,6 +29,47 @@ use ringbuf::RingBuf;
 
 
 /// A map based on a B-Tree.
+///
+/// B-Trees represent a fundamental compromise between cache-efficiency and actually minimizing
+/// the amount of work performed in a search. In theory, a binary search tree (BST) is the optimal
+/// choice for a sorted map, as a perfectly balanced BST performs the theoretical minimum amount of
+/// comparisons necessary to find an element (log<sub>2</sub>n). However, in practice the way this
+/// is done is *very* inefficient for modern computer architectures. In particular, every element
+/// is stored in its own individually heap-allocated node. This means that every single insertion
+/// triggers a heap-allocation, and every single comparison should be a cache-miss. Since these
+/// are both notably expensive things to do in practice, we are forced to at very least reconsider
+/// the BST strategy.
+///
+/// A B-Tree instead makes each node contain B-1 to 2B-1 elements in a contiguous array. By doing
+/// this, we reduce the number of allocations by a factor of B, and improve cache effeciency in
+/// searches. However, this does mean that searches will have to do *more* comparisons on average.
+/// The precise number of comparisons depends on the node search strategy used. For optimal cache
+/// effeciency, one could search the nodes linearly. For optimal comparisons, one could search
+/// the node using binary search. As a compromise, one could also perform a linear search
+/// that initially only checks every i<sup>th</sup> element for some choice of i.
+///
+/// Currently, our implementation simply performs naive linear search. This provides excellent
+/// performance on *small* nodes of elements which are cheap to compare. However in the future we
+/// would like to further explore choosing the optimal search strategy based on the choice of B,
+/// and possibly other factors. Using linear search, searching for a random element is expected
+/// to take O(B log<sub>B</sub>n) comparisons, which is generally worse than a BST. In practice,
+/// however, performance is excellent. `BTreeMap` is able to readily outperform `TreeMap` under
+/// many workloads, and is competetive where it doesn't. BTreeMap also generally *scales* better
+/// than TreeMap, making it more appropriate for large datasets.
+///
+/// However, `TreeMap` may still be more appropriate to use in many contexts. If elements are very
+/// large or expensive to compare, `TreeMap` may be more appropriate. It won't allocate any
+/// more space than is needed, and will perform the minimal number of comparisons necessary.
+/// `TreeMap` also provides much better performance stability guarantees. Generally, very few
+/// changes need to be made to update a BST, and two updates are expected to take about the same
+/// amount of time on roughly equal sized BSTs. However a B-Tree's performance is much more
+/// amortized. If a node is overfull, it must be split into two nodes. If a node is underfull, it
+/// may be merged with another. Both of these operations are relatively expensive to perform, and
+/// it's possible to force one to occur at every single level of the tree in a single insertion or
+/// deletion. In fact, a malicious or otherwise unlucky sequence of insertions and deletions can
+/// force this degenerate behaviour to occur on every operation. While the total amount of work
+/// done on each operation isn't *catastrophic*, and *is* still bounded by O(B log<sub>B</sub>n),
+/// it is certainly much slower when it does.
 #[deriving(Clone)]
 pub struct BTreeMap<K, V> {
     root: Node<K, V>,
@@ -93,6 +134,8 @@ impl<K: Ord, V> BTreeMap<K, V> {
     }
 
     /// Makes a new empty BTreeMap with the given B.
+    ///
+    /// B cannot be less than 2.
     pub fn with_b(b: uint) -> BTreeMap<K, V> {
         assert!(b > 1, "B must be greater than 1");
         BTreeMap {
@@ -1145,9 +1188,12 @@ mod test {
 
 #[cfg(test)]
 mod bench {
-    use test::Bencher;
+    use std::prelude::*;
+    use std::rand::{weak_rng, Rng};
+    use test::{Bencher, black_box};
 
     use super::BTreeMap;
+    use MutableMap;
     use deque::bench::{insert_rand_n, insert_seq_n, find_rand_n, find_seq_n};
 
     #[bench]
@@ -1200,4 +1246,34 @@ mod bench {
         let mut m : BTreeMap<uint,uint> = BTreeMap::new();
         find_seq_n(10_000, &mut m, b);
     }
+
+    fn bench_iter(b: &mut Bencher, size: uint) {
+        let mut map = BTreeMap::<uint, uint>::new();
+        let mut rng = weak_rng();
+
+        for _ in range(0, size) {
+            map.swap(rng.gen(), rng.gen());
+        }
+
+        b.iter(|| {
+            for entry in map.iter() {
+                black_box(entry);
+            }
+        });
+    }
+
+    #[bench]
+    pub fn iter_20(b: &mut Bencher) {
+        bench_iter(b, 20);
+    }
+
+    #[bench]
+    pub fn iter_1000(b: &mut Bencher) {
+        bench_iter(b, 1000);
+    }
+
+    #[bench]
+    pub fn iter_100000(b: &mut Bencher) {
+        bench_iter(b, 100000);
+    }
 }

branches/snap-stage3/src/libcollections/btree/set.rs

@@ -23,6 +23,9 @@ use core::fmt::Show;
 use {Mutable, Set, MutableSet, MutableMap, Map};
 
 /// A set based on a B-Tree.
+///
+/// See BTreeMap's documentation for a detailed discussion of this collection's performance
+/// benefits and drawbacks.
 #[deriving(Clone, Hash, PartialEq, Eq, Ord, PartialOrd)]
 pub struct BTreeSet<T>{
     map: BTreeMap<T, ()>,
@@ -65,6 +68,8 @@ impl<T: Ord> BTreeSet<T> {
     }
 
     /// Makes a new BTreeSet with the given B.
+    ///
+    /// B cannot be less than 2.
     pub fn with_b(b: uint) -> BTreeSet<T> {
         BTreeSet { map: BTreeMap::with_b(b) }
     }

branches/snap-stage3/src/libcollections/slice.rs

@@ -277,12 +277,14 @@ pub trait CloneableVector<T> {
     }
 
     /// Converts `self` into an owned vector, not making a copy if possible.
+    /// Deprecated. Use 'to_vec'
+    #[deprecated = "Replaced by `to_vec`"]
     fn into_vec(self) -> Vec<T>;
 
-    /// Deprecated. Use `into_vec`
-    #[deprecated = "Replaced by `into_vec`"]
+    /// Deprecated. Use `to_vec`
+    #[deprecated = "Replaced by `to_vec`"]
     fn into_owned(self) -> Vec<T> {
-        self.into_vec()
+        self.to_vec()
     }
 }
 
@@ -2328,9 +2330,9 @@ mod tests {
     }
 
     #[test]
-    fn test_into_vec() {
+    fn test_to_vec() {
         let xs = box [1u, 2, 3];
-        let ys = xs.into_vec();
+        let ys = xs.to_vec();
         assert_eq!(ys.as_slice(), [1u, 2, 3].as_slice());
     }
 }

branches/snap-stage3/src/libcollections/treemap.rs

@@ -2232,9 +2232,12 @@ mod test_treemap {
 
 #[cfg(test)]
 mod bench {
-    use test::Bencher;
+    use std::prelude::*;
+    use std::rand::{weak_rng, Rng};
+    use test::{Bencher, black_box};
 
     use super::TreeMap;
+    use MutableMap;
     use deque::bench::{insert_rand_n, insert_seq_n, find_rand_n, find_seq_n};
 
     // Find seq
@@ -2288,6 +2291,36 @@ mod bench {
         let mut m : TreeMap<uint,uint> = TreeMap::new();
         find_seq_n(10_000, &mut m, b);
     }
+
+    fn bench_iter(b: &mut Bencher, size: uint) {
+        let mut map = TreeMap::<uint, uint>::new();
+        let mut rng = weak_rng();
+
+        for _ in range(0, size) {
+            map.swap(rng.gen(), rng.gen());
+        }
+
+        b.iter(|| {
+            for entry in map.iter() {
+                black_box(entry);
+            }
+        });
+    }
+
+    #[bench]
+    pub fn iter_20(b: &mut Bencher) {
+        bench_iter(b, 20);
+    }
+
+    #[bench]
+    pub fn iter_1000(b: &mut Bencher) {
+        bench_iter(b, 1000);
+    }
+
+    #[bench]
+    pub fn iter_100000(b: &mut Bencher) {
+        bench_iter(b, 100000);
+    }
 }
 
 #[cfg(test)]

branches/snap-stage3/src/libcollections/trie.rs

@@ -949,8 +949,8 @@ macro_rules! iterator_impl {
                 // rules, and are just manipulating raw pointers like there's no
                 // such thing as invalid pointers and memory unsafety. The
                 // reason is performance, without doing this we can get the
-                // bench_iter_large microbenchmark down to about 30000 ns/iter
-                // (using .unsafe_get to index self.stack directly, 38000
+                // (now replaced) bench_iter_large microbenchmark down to about
+                // 30000 ns/iter (using .unsafe_get to index self.stack directly, 38000
                 // ns/iter with [] checked indexing), but this smashes that down
                 // to 13500 ns/iter.
                 //
@@ -1459,31 +1459,39 @@ mod test_map {
 mod bench_map {
     use std::prelude::*;
     use std::rand::{weak_rng, Rng};
-    use test::Bencher;
+    use test::{Bencher, black_box};
 
     use MutableMap;
     use super::TrieMap;
 
-    #[bench]
-    fn bench_iter_small(b: &mut Bencher) {
-        let mut m = TrieMap::<uint>::new();
+    fn bench_iter(b: &mut Bencher, size: uint) {
+        let mut map = TrieMap::<uint>::new();
         let mut rng = weak_rng();
-        for _ in range(0u, 20) {
-            m.insert(rng.gen(), rng.gen());
+
+        for _ in range(0, size) {
+            map.swap(rng.gen(), rng.gen());
         }
 
-        b.iter(|| for _ in m.iter() {})
+        b.iter(|| {
+            for entry in map.iter() {
+                black_box(entry);
+            }
+        });
     }
 
     #[bench]
-    fn bench_iter_large(b: &mut Bencher) {
-        let mut m = TrieMap::<uint>::new();
-        let mut rng = weak_rng();
-        for _ in range(0u, 1000) {
-            m.insert(rng.gen(), rng.gen());
-        }
+    pub fn iter_20(b: &mut Bencher) {
+        bench_iter(b, 20);
+    }
 
-        b.iter(|| for _ in m.iter() {})
+    #[bench]
+    pub fn iter_1000(b: &mut Bencher) {
+        bench_iter(b, 1000);
+    }
+
+    #[bench]
+    pub fn iter_100000(b: &mut Bencher) {
+        bench_iter(b, 100000);
     }
 
     #[bench]

branches/snap-stage3/src/libcollections/vec.rs

@@ -570,13 +570,6 @@ impl<T> Collection for Vec<T> {
     }
 }
 
-impl<T: Clone> CloneableVector<T> for Vec<T> {
-    #[deprecated = "call .clone() instead"]
-    fn to_vec(&self) -> Vec<T> { self.clone() }
-    #[deprecated = "move the vector instead"]
-    fn into_vec(self) -> Vec<T> { self }
-}
-
 // FIXME: #13996: need a way to mark the return value as `noalias`
 #[inline(never)]
 unsafe fn alloc_or_realloc<T>(ptr: *mut T, old_size: uint, size: uint) -> *mut T {

branches/snap-stage3/src/libgraphviz/maybe_owned_vec.rs

@@ -140,7 +140,7 @@ impl<'a,T:Clone> CloneableVector<T> for MaybeOwnedVector<'a,T> {
 impl<'a, T: Clone> Clone for MaybeOwnedVector<'a, T> {
     fn clone(&self) -> MaybeOwnedVector<'a, T> {
         match *self {
-            Growable(ref v) => Growable(v.to_vec()),
+            Growable(ref v) => Growable(v.clone()),
             Borrowed(v) => Borrowed(v)
         }
     }

branches/snap-stage3/src/librustc/middle/traits/select.rs

@@ -1014,7 +1014,7 @@ impl<'cx, 'tcx> SelectionContext<'cx, 'tcx> {
 
             ty::ty_tup(ref tys) => {
                 // (T1, ..., Tn) -- meets any bound that all of T1...Tn meet
-                Ok(If(tys.to_owned()))
+                Ok(If(tys.clone()))
             }
 
             ty::ty_unboxed_closure(def_id, _) => {

branches/snap-stage3/src/librustdoc/html/format.rs

@@ -478,7 +478,25 @@ impl fmt::Show for clean::Type {
                     Some(ref l) => format!("{} ", *l),
                     _ => "".to_string(),
                 };
-                write!(f, "&{}{}{}", lt, MutableSpace(mutability), **ty)
+                let m = MutableSpace(mutability);
+                match **ty {
+                    clean::Vector(ref bt) => { // BorrowedRef{ ... Vector(T) } is &[T]
+                        match **bt {
+                            clean::Generic(_) =>
+                                primitive_link(f, clean::Slice,
+                                    format!("&{}{}[{}]", lt, m, **bt).as_slice()),
+                            _ => {
+                                try!(primitive_link(f, clean::Slice,
+                                    format!("&{}{}[", lt, m).as_slice()));
+                                try!(write!(f, "{}", **bt));
+                                primitive_link(f, clean::Slice, "]")
+                            }
+                        }
+                    }
+                    _ => {
+                        write!(f, "&{}{}{}", lt, m, **ty)
+                    }
+                }
             }
             clean::Unique(..) => {
                 fail!("should have been cleaned")