---

yaml
---
r: 145825
b: refs/heads/try2
c: 9886979
h: refs/heads/master
i:
  145823: 9bc546d
v: v3

Author: huonw

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: 0b1a0d01a8d0a769cc2c0bd9b11bfb71864d2f36
+refs/heads/try2: 98869799eb2604ecd7c947db117794df10890a2c
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/src/libstd/rand/mod.rs

@@ -19,6 +19,22 @@ suffice, but sometimes an annotation is required, e.g. `rand::random::<f64>()`.
 See the `distributions` submodule for sampling random numbers from
 distributions like normal and exponential.
 
+# Task-local RNG
+
+There is built-in support for a RNG associated with each task stored
+in task-local storage. This RNG can be accessed via `task_rng`, or
+used implicitly via `random`. This RNG is normally randomly seeded
+from an operating-system source of randomness, e.g. `/dev/urandom` on
+Unix systems, and will automatically reseed itself from this source
+after generating 32 KiB of random data.
+
+It can be explicitly seeded on a per-task basis with `seed_task_rng`;
+this only affects the task-local generator in the task in which it is
+called. It can be seeded globally using the `RUST_SEED` environment
+variable, which should be an integer. Setting `RUST_SEED` will seed
+every task-local RNG with the same seed. Using either of these will
+disable the automatic reseeding.
+
 # Examples
 
 ```rust
@@ -126,7 +142,7 @@ pub trait Rng {
     /// fn main() {
     ///    let mut v = [0u8, .. 13579];
     ///    task_rng().fill_bytes(v);
-    ///    printfln!(v);
+    ///    println!("{:?}", v);
     /// }
     /// ```
     fn fill_bytes(&mut self, mut dest: &mut [u8]) {
@@ -486,7 +502,7 @@ pub trait SeedableRng<Seed>: Rng {
     /// use std::rand::Rng;
     ///
     /// fn main() {
-    ///     let mut rng: rand::XorShiftRng = rand::SeedableRng::from_seed(&[1, 2, 3, 4]);
+    ///     let mut rng: rand::StdRng = rand::SeedableRng::from_seed(&[1, 2, 3, 4]);
     ///     println!("{}", rng.gen::<f64>());
     ///     rng.reseed([5, 6, 7, 8]);
     ///     println!("{}", rng.gen::<f64>());
@@ -503,7 +519,7 @@ pub trait SeedableRng<Seed>: Rng {
     /// use std::rand::Rng;
     ///
     /// fn main() {
-    ///     let mut rng: rand::XorShiftRng = rand::SeedableRng::from_seed(&[1, 2, 3, 4]);
+    ///     let mut rng: rand::StdRng = rand::SeedableRng::from_seed(&[1, 2, 3, 4]);
     ///     println!("{}", rng.gen::<f64>());
     /// }
     /// ```
@@ -748,10 +764,10 @@ pub fn task_rng() -> @mut TaskRng {
 ///
 /// fn main() {
 ///     rand::seed_task_rng(&[10u]);
-///     printfln!("Same every time: %u", rand::random::<uint>());
+///     println!("Same every time: {}", rand::random::<uint>());
 ///
 ///     rand::seed_task_rng(&[1u, 2, 3, 4, 5, 6, 7, 8]);
-///     printfln!("Same every time: %f", rand::random::<float>());
+///     println!("Same every time: {}", rand::random::<float>());
 /// }
 /// ```
 pub fn seed_task_rng(seed: &[uint]) {
@@ -783,9 +799,9 @@ impl<R: Rng> Rng for @mut R {
 /// fn main() {
 ///     if random() {
 ///         let x = random();
-///         printfln!(2u * x);
+///         println!("{}", 2u * x);
 ///     } else {
-///         printfln!(random::<float>());
+///         println!("{}", random::<float>());
 ///     }
 /// }
 /// ```

branches/try2/src/libstd/rand/reader.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! A wrapper around any Reader to treat it as an RNG.
+
 use option::{Some, None};
 use rt::io::Reader;
 use rt::io::ReaderByteConversions;
@@ -22,12 +24,12 @@ use rand::Rng;
 /// # Example
 ///
 /// ```rust
-/// use std::rand::reader;
+/// use std::rand::{reader, Rng};
 /// use std::rt::io::mem;
 ///
 /// fn main() {
 ///     let mut rng = reader::ReaderRng::new(mem::MemReader::new(~[1,2,3,4,5,6,7,8]));
-///     println!("{}", rng.gen::<uint>());
+///     println!("{:x}", rng.gen::<uint>());
 /// }
 /// ```
 pub struct ReaderRng<R> {

branches/try2/src/libstd/rand/reseeding.rs

@@ -94,6 +94,31 @@ impl<S, R: SeedableRng<S>, Rsdr: Reseeder<R> + Default> SeedableRng<S> for Resee
 }
 
 /// Something that can be used to reseed an RNG via `ReseedingRng`.
+///
+/// # Example
+///
+/// ```rust
+/// use std::rand;
+/// use std::rand::{Rng, SeedableRng};
+/// use std::rand::reseeding::{Reseeder, ReseedingRng};
+///
+/// struct TickTockReseeder { tick: bool }
+/// impl Reseeder<rand::StdRng> for TickTockReseeder {
+///     fn reseed(&mut self, rng: &mut rand::StdRng) {
+///         let val = if self.tick {0} else {1};
+///         rng.reseed(&[val]);
+///         self.tick = !self.tick;
+///     }
+/// }
+/// fn main() {
+///     let rsdr = TickTockReseeder { tick: true };
+///     let mut rng = ReseedingRng::new(rand::StdRng::new(), 10, rsdr);
+///
+///     // this will repeat, because it gets reseeded very regularly.
+///     println(rng.gen_ascii_str(100));
+/// }
+///
+/// ```
 pub trait Reseeder<R> {
     /// Reseed the given RNG.
     fn reseed(&mut self, rng: &mut R);