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.

diff --git a/src/libextra/tempfile.rs b/src/libextra/tempfile.rs
index 4e4d80ae292cfb57bcce3cbb718f2ee51f5af3d1..905541604e03d70202dadda55746b04c92119727 100644 (file)
--- 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 @@ pub fn new_in(tmpdir: &Path, suffix: &str) -> Option<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 17c96f1c5aba9a16acb2dd557e0646e6694ecacc..6bf5092bb2d515249ad3abe897e6cd90125b42c1 100644 (file)
--- 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 4c5dd0043b6372cfb4bf6b67879cabe2a1989b2f..87a18497b8afd77ee5e082e0f4b7d2593b46fe00 100644 (file)
--- a/src/librand/lib.rs
+++ b/src/librand/lib.rs
@@ -50,7 +50,7 @@
 ```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 8efa9763ba9ff600bedb665b50facb80b5a67390..e529daaa500d6242923fb3b577af32f6332d5440 100644 (file)
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -1409,7 +1409,7 @@ pub fn test_args() {
     }
 
     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 71ee32b4aade7e434f112bf5977a013a66099a07..cd52ff4b0ac71ac328ffadc0a10a140c489591f8 100644 (file)
--- 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 407da784b68b3bc1aa27fb2070ef2d6e17369149..aa17cd468094809a9a658e82220abf5890e9083a 100644 (file)
--- a/src/libuuid/lib.rs
+++ b/src/libuuid/lib.rs
@@ -780,7 +780,7 @@ fn test_operator_eq() {
 
     #[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 2700b72ae9819928c93467fd0752476edf2570bc..120caa53293a16701fad4e1c21026e310abf7204 100644 (file)
--- 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 349b1ff7b449ef44ab81f1c0a3ac89f375d08755..c09b90ba6fb8b13a72d138b85ed69bd3e1c0a623 100644 (file)
--- 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;