rand: deprecate `rng`.

This should be called far less than it is because it does expensive OS
interactions and seeding of the internal RNG, `task_rng` amortises this
cost. The main problem is the name is so short and suggestive.

The direct equivalent is `StdRng::new`, which does precisely the same
thing.

The deprecation will make migrating away from the function easier.

8 files changed, 28 insertions, 16 deletions

diff --git a/src/libextra/tempfile.rs b/src/libextra/tempfile.rs
index 4e4d80ae292..905541604e0 100644
--- a/src/libextra/tempfile.rs
+++ b/src/libextra/tempfile.rs
@@ -12,8 +12,7 @@
 
 
 use std::os;
-use rand::Rng;
-use rand;
+use rand::{task_rng, Rng};
 use std::io;
 use std::io::fs;
 
@@ -35,7 +34,7 @@ impl TempDir {
             return TempDir::new_in(&abs_tmpdir, suffix);
         }
 
-        let mut r = rand::rng();
+        let mut r = task_rng();
         for _ in range(0u, 1000) {
             let p = tmpdir.join(r.gen_ascii_str(16) + suffix);
             match fs::mkdir(&p, io::UserRWX) {
diff --git a/src/libflate/lib.rs b/src/libflate/lib.rs
index 17c96f1c5ab..6bf5092bb2d 100644
--- a/src/libflate/lib.rs
+++ b/src/libflate/lib.rs
@@ -97,7 +97,7 @@ mod tests {
 
     #[test]
     fn test_flate_round_trip() {
-        let mut r = rand::rng();
+        let mut r = rand::task_rng();
         let mut words = ~[];
         for _ in range(0, 20) {
             let range = r.gen_range(1u, 10);
diff --git a/src/librand/lib.rs b/src/librand/lib.rs
index 4c5dd0043b6..87a18497b8a 100644
--- a/src/librand/lib.rs
+++ b/src/librand/lib.rs
@@ -50,7 +50,7 @@ randomness.
 ```rust
 use rand::Rng;
 
-let mut rng = rand::rng();
+let mut rng = rand::task_rng();
 if rng.gen() { // bool
     println!("int: {}, uint: {}", rng.gen::<int>(), rng.gen::<uint>())
 }
@@ -396,6 +396,7 @@ pub trait SeedableRng<Seed>: Rng {
 /// operation. If one does not require high performance generation of
 /// random numbers, `task_rng` and/or `random` may be more
 /// appropriate.
+#[deprecated="use `task_rng` or `StdRng::new`"]
 pub fn rng() -> StdRng {
     StdRng::new()
 }
@@ -411,14 +412,26 @@ pub struct StdRng { priv rng: IsaacRng }
 pub struct StdRng { priv rng: Isaac64Rng }
 
 impl StdRng {
-    /// Create a randomly seeded instance of `StdRng`. This reads
-    /// randomness from the OS to seed the PRNG.
+    /// Create a randomly seeded instance of `StdRng`.
+    ///
+    /// This is a very expensive operation as it has to read
+    /// randomness from the operating system and use this in an
+    /// expensive seeding operation. If one is only generating a small
+    /// number of random numbers, or doesn't need the utmost speed for
+    /// generating each number, `task_rng` and/or `random` may be more
+    /// appropriate.
     #[cfg(not(target_word_size="64"))]
     pub fn new() -> StdRng {
         StdRng { rng: IsaacRng::new() }
     }
-    /// Create a randomly seeded instance of `StdRng`. This reads
-    /// randomness from the OS to seed the PRNG.
+    /// Create a randomly seeded instance of `StdRng`.
+    ///
+    /// This is a very expensive operation as it has to read
+    /// randomness from the operating system and use this in an
+    /// expensive seeding operation. If one is only generating a small
+    /// number of random numbers, or doesn't need the utmost speed for
+    /// generating each number, `task_rng` and/or `random` may be more
+    /// appropriate.
     #[cfg(target_word_size="64")]
     pub fn new() -> StdRng {
         StdRng { rng: Isaac64Rng::new() }
diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index 8efa9763ba9..e529daaa500 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -1409,7 +1409,7 @@ mod tests {
     }
 
     fn make_rand_name() -> ~str {
-        let mut rng = rand::rng();
+        let mut rng = rand::task_rng();
         let n = ~"TEST" + rng.gen_ascii_str(10u);
         assert!(getenv(n).is_none());
         n
diff --git a/src/libsyntax/parse/token.rs b/src/libsyntax/parse/token.rs
index 71ee32b4aad..cd52ff4b0ac 100644
--- a/src/libsyntax/parse/token.rs
+++ b/src/libsyntax/parse/token.rs
@@ -670,7 +670,7 @@ pub fn fresh_name(src: &ast::Ident) -> Name {
     // following: debug version. Could work in final except that it's incompatible with
     // good error messages and uses of struct names in ambiguous could-be-binding
     // locations. Also definitely destroys the guarantee given above about ptr_eq.
-    /*let num = rand::rng().gen_uint_range(0,0xffff);
+    /*let num = rand::task_rng().gen_uint_range(0,0xffff);
     gensym(format!("{}_{}",ident_to_str(src),num))*/
 }
 
diff --git a/src/libuuid/lib.rs b/src/libuuid/lib.rs
index 407da784b68..aa17cd46809 100644
--- a/src/libuuid/lib.rs
+++ b/src/libuuid/lib.rs
@@ -780,7 +780,7 @@ mod test {
 
     #[test]
     fn test_rand_rand() {
-        let mut rng = rand::rng();
+        let mut rng = rand::task_rng();
         let u: ~Uuid = rand::Rand::rand(&mut rng);
         let ub = u.as_bytes();
 
diff --git a/src/test/bench/core-std.rs b/src/test/bench/core-std.rs
index 2700b72ae98..120caa53293 100644
--- a/src/test/bench/core-std.rs
+++ b/src/test/bench/core-std.rs
@@ -83,7 +83,7 @@ fn read_line() {
 }
 
 fn vec_plus() {
-    let mut r = rand::rng();
+    let mut r = rand::task_rng();
 
     let mut v = ~[];
     let mut i = 0;
@@ -99,7 +99,7 @@ fn vec_plus() {
 }
 
 fn vec_append() {
-    let mut r = rand::rng();
+    let mut r = rand::task_rng();
 
     let mut v = ~[];
     let mut i = 0;
@@ -116,7 +116,7 @@ fn vec_append() {
 }
 
 fn vec_push_all() {
-    let mut r = rand::rng();
+    let mut r = rand::task_rng();
 
     let mut v = ~[];
     for i in range(0u, 1500) {
diff --git a/src/test/run-pass/morestack6.rs b/src/test/run-pass/morestack6.rs
index 349b1ff7b44..c09b90ba6fb 100644
--- a/src/test/run-pass/morestack6.rs
+++ b/src/test/run-pass/morestack6.rs
@@ -67,7 +67,7 @@ pub fn main() {
         calllink08,
         calllink10
     ];
-    let mut rng = rand::rng();
+    let mut rng = rand::task_rng();
     for f in fns.iter() {
         let f = *f;
         let sz = rng.gen::<u32>() % 256u32 + 256u32;