From 6a7f0a99d8005187736c3c26c5cc2d538a42590f Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Mon, 12 Jan 2015 17:57:28 -0500
Subject: [PATCH] Add note about TLS lookups in random()

Fixes #16072
---
 src/libstd/rand/mod.rs | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/src/libstd/rand/mod.rs b/src/libstd/rand/mod.rs
index 60d490982db..8130a6c82ec 100644
--- a/src/libstd/rand/mod.rs
+++ b/src/libstd/rand/mod.rs
@@ -374,9 +374,13 @@ impl Rng for ThreadRng {
 /// `random()` can generate various types of random things, and so may require
 /// type hinting to generate the specific type you want.
 ///
+/// This function uses the thread local random number generator. This means
+/// that if you're calling `random()` in a loop, caching the generator can
+/// increase performance. An example is shown below.
+///
 /// # Examples
 ///
-/// ```rust
+/// ```
 /// use std::rand;
 ///
 /// let x = rand::random();
@@ -389,6 +393,27 @@ impl Rng for ThreadRng {
 ///     println!("Better lucky than good!");
 /// }
 /// ```
+///
+/// Caching the thread local random number generator:
+///
+/// ```
+/// use std::rand;
+/// use std::rand::Rng;
+///
+/// let mut v = vec![1, 2, 3];
+///
+/// for x in v.iter_mut() {
+///     *x = rand::random()
+/// }
+///
+/// // would be faster as
+///
+/// let mut rng = rand::thread_rng();
+///
+/// for x in v.iter_mut() {
+///     *x = rng.gen();
+/// }
+/// ```
 #[inline]
 pub fn random<T: Rand>() -> T {
     thread_rng().gen()