Improve JitterRng documentation

Author: pitdicker

src/jitter.rs

@@ -16,6 +16,11 @@
 
 //! Non-physical true random number generator based on timing jitter.
 
+// Note: the C implementation of `Jitterentropy` relies on being compiled
+// without optimizations. This implementation goes through lengths to make the
+// compiler not optimise out what is technically dead code, but that does
+// influence timing jitter.
+
 use rand_core::{RngCore, CryptoRng, Error, ErrorKind, impls};
 
 use core::{fmt, mem, ptr};
@@ -31,7 +36,7 @@ const MEMORY_SIZE: usize = MEMORY_BLOCKS * MEMORY_BLOCKSIZE;
 ///
 /// This is a true random number generator, as opposed to pseudo-random
 /// generators. Random numbers generated by `JitterRng` can be seen as fresh
-/// entropy. A consequence is that is orders of magnitude slower than `OsRng`
+/// entropy. A consequence is that is orders of magnitude slower than [`OsRng`]
 /// and PRNGs (about 10<sup>3</sup>..10<sup>6</sup> slower).
 ///
 /// There are very few situations where using this RNG is appropriate. Only very
@@ -40,21 +45,19 @@ const MEMORY_SIZE: usize = MEMORY_BLOCKS * MEMORY_BLOCKSIZE;
 /// predict.
 ///
 /// Use of `JitterRng` is recommended for initializing cryptographic PRNGs when
-/// `OsRng` is not available.
+/// [`OsRng`] is not available.
 ///
 /// This implementation is based on
 /// [Jitterentropy](http://www.chronox.de/jent.html) version 2.1.0.
-//
-// Note: the C implementation relies on being compiled without optimizations.
-// This implementation goes through lengths to make the compiler not optimise
-// out what is technically dead code, but that does influence timing jitter.
+///
+/// [`OsRng`]: os/struct.OsRng.html
 pub struct JitterRng {
     data: u64, // Actual random number
     // Number of rounds to run the entropy collector per 64 bits
     rounds: u8,
     // Timer used by `measure_jitter`
     timer: fn() -> u64,
-    // Memory for the Memory Access noise source FIXME
+    // Memory for the Memory Access noise source
     mem_prev_index: u16,
     // Make `next_u32` not waste 32 bits
     data_half_used: bool,
@@ -100,7 +103,9 @@ impl fmt::Debug for JitterRng {
     }
 }
 
-/// An error that can occur when `test_timer` fails.
+/// An error that can occur when [`JitterRng::test_timer`] fails.
+///
+/// [`JitterRng::test_timer`]: struct.JitterRng.html#method.test_timer
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum TimerError {
     /// No timer available.
@@ -157,8 +162,9 @@ impl From<TimerError> for Error {
 static JITTER_ROUNDS: AtomicUsize = ATOMIC_USIZE_INIT;
 
 impl JitterRng {
-    /// Create a new `JitterRng`.
-    /// Makes use of `std::time` for a timer.
+    /// Create a new `JitterRng`. Makes use of `std::time` for a timer, or a
+    /// platform-specific function with higher accuracy if necessary and
+    /// available.
     ///
     /// During initialization CPU execution timing jitter is measured a few
     /// hundred times. If this does not pass basic quality tests, an error is
@@ -188,10 +194,44 @@ impl JitterRng {
     /// The timer must have nanosecond precision.
     ///
     /// This method is more low-level than `new()`. It is the responsibility of
-    /// the caller to run `test_timer` before using any numbers generated with
-    /// `JitterRng`, and optionally call `set_rounds()`. Also it is important to
-    /// call `gen_entropy` once before using the first result to initialize the
-    /// entropy collection pool.
+    /// the caller to run [`test_timer`] before using any numbers generated with
+    /// `JitterRng`, and optionally call [`set_rounds`]. Also it is important to
+    /// consume at least one `u64` before using the first result to initialize
+    /// the entropy collection pool.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use rand::{Rng, Error};
+    /// use rand::JitterRng;
+    ///
+    /// # fn try_inner() -> Result<(), Error> {
+    /// fn get_nstime() -> u64 {
+    ///     use std::time::{SystemTime, UNIX_EPOCH};
+    ///
+    ///     let dur = SystemTime::now().duration_since(UNIX_EPOCH).unwrap();
+    ///     // The correct way to calculate the current time is
+    ///     // `dur.as_secs() * 1_000_000_000 + dur.subsec_nanos() as u64`
+    ///     // But this is faster, and the difference in terms of entropy is
+    ///     // negligible (log2(10^9) == 29.9).
+    ///     dur.as_secs() << 30 | dur.subsec_nanos() as u64
+    /// }
+    ///
+    /// let mut rng = JitterRng::new_with_timer(get_nstime);
+    /// let rounds = rng.test_timer()?;
+    /// rng.set_rounds(rounds); // optional
+    /// let _ = rng.gen::<u64>();
+    ///
+    /// // Ready for use
+    /// let v: u64 = rng.gen();
+    /// # Ok(())
+    /// # }
+    ///
+    /// # try_inner().unwrap();
+    /// ```
+    ///
+    /// [`test_timer`]: struct.JitterRng.html#method.test_timer
+    /// [`set_rounds`]: struct.JitterRng.html#method.set_rounds
     pub fn new_with_timer(timer: fn() -> u64) -> JitterRng {
         JitterRng {
             data: 0,
@@ -206,10 +246,12 @@ impl JitterRng {
     /// This must be greater than zero, and has a big impact on performance
     /// and output quality.
     ///
-    /// `new_with_timer` conservatively uses 64 rounds, but often less rounds
+    /// [`new_with_timer`] conservatively uses 64 rounds, but often less rounds
     /// can be used. The `test_timer()` function returns the minimum number of
     /// rounds required for full strength (platform dependent), so one may use
     /// `rng.set_rounds(rng.test_timer()?);` or cache the value.
+    ///
+    /// [`new_with_timer`]: struct.JitterRng.html#method.new_with_timer
     pub fn set_rounds(&mut self, rounds: u8) {
         assert!(rounds > 0);
         self.rounds = rounds;
@@ -447,17 +489,14 @@ impl JitterRng {
         self.data
     }
 
-    #[cfg(all(target_arch = "wasm32", not(target_os = "emscripten")))]
-    pub fn test_timer(&mut self) -> Result<u8, TimerError> {
-        return Err(TimerError::NoTimer);
-    }
-
     /// Basic quality tests on the timer, by measuring CPU timing jitter a few
     /// hundred times.
     ///
     /// If succesful, this will return the estimated number of rounds necessary
-    /// to collect 64 bits of entropy. Otherwise a `TimerError` with the cause
+    /// to collect 64 bits of entropy. Otherwise a [`TimerError`] with the cause
     /// of the failure will be returned.
+    ///
+    /// [`TimerError`]: jitter/enum.TimerError.html
     #[cfg(not(all(target_arch = "wasm32", not(target_os = "emscripten"))))]
     pub fn test_timer(&mut self) -> Result<u8, TimerError> {
         debug!("JitterRng: testing timer ...");
@@ -595,6 +634,10 @@ impl JitterRng {
             Ok(log2_lookup[delta_average as usize])
         }
     }
+    #[cfg(all(target_arch = "wasm32", not(target_os = "emscripten")))]
+    pub fn test_timer(&mut self) -> Result<u8, TimerError> {
+        return Err(TimerError::NoTimer);
+    }
 
     /// Statistical test: return the timer delta of one normal run of the
     /// `JitterEntropy` entropy collector.
@@ -640,33 +683,17 @@ impl JitterRng {
     ///
     /// ```rust,no_run
     /// use rand::JitterRng;
-    ///
+    /// #
     /// # use std::error::Error;
     /// # use std::fs::File;
     /// # use std::io::Write;
     /// #
     /// # fn try_main() -> Result<(), Box<Error>> {
-    /// fn get_nstime() -> u64 {
-    ///     use std::time::{SystemTime, UNIX_EPOCH};
-    ///
-    ///     let dur = SystemTime::now().duration_since(UNIX_EPOCH).unwrap();
-    ///     // The correct way to calculate the current time is
-    ///     // `dur.as_secs() * 1_000_000_000 + dur.subsec_nanos() as u64`
-    ///     // But this is faster, and the difference in terms of entropy is
-    ///     // negligible (log2(10^9) == 29.9).
-    ///     dur.as_secs() << 30 | dur.subsec_nanos() as u64
-    /// }
-    ///
-    /// // Do not initialize with `JitterRng::new`, but with `new_with_timer`.
-    /// // 'new' always runst `test_timer`, and can therefore fail to
-    /// // initialize. We want to be able to get the statistics even when the
-    /// // timer test fails.
-    /// let mut rng = JitterRng::new_with_timer(get_nstime);
+    /// let mut rng = JitterRng::new()?;
     ///
     /// // 1_000_000 results are required for the NIST SP 800-90B Entropy
     /// // Estimation Suite
-    /// // FIXME: this number is smaller here, otherwise the Doc-test is too slow
-    /// const ROUNDS: usize = 10_000;
+    /// const ROUNDS: usize = 1_000_000;
     /// let mut deltas_variable: Vec<u8> = Vec::with_capacity(ROUNDS);
     /// let mut deltas_minimal: Vec<u8> = Vec::with_capacity(ROUNDS);
     ///
@@ -687,6 +714,7 @@ impl JitterRng {
     /// #     try_main().unwrap();
     /// # }
     /// ```
+    ///
     #[cfg(feature="std")]
     pub fn timer_stats(&mut self, var_rounds: bool) -> i64 {
         let mut mem = [0; MEMORY_SIZE];
@@ -701,27 +729,28 @@ impl JitterRng {
 
 #[cfg(feature="std")]
 mod platform {
-    #[cfg(not(any(target_os = "macos", target_os = "ios", target_os = "windows", all(target_arch = "wasm32", not(target_os = "emscripten")))))]
+    #[cfg(not(any(target_os = "macos", target_os = "ios", target_os = "windows",
+                  all(target_arch = "wasm32", not(target_os = "emscripten")))))]
     pub fn get_nstime() -> u64 {
         use std::time::{SystemTime, UNIX_EPOCH};
 
         let dur = SystemTime::now().duration_since(UNIX_EPOCH).unwrap();
         // The correct way to calculate the current time is
         // `dur.as_secs() * 1_000_000_000 + dur.subsec_nanos() as u64`
-        // But this is faster, and the difference in terms of entropy is negligible
-        // (log2(10^9) == 29.9).
+        // But this is faster, and the difference in terms of entropy is
+        // negligible (log2(10^9) == 29.9).
         dur.as_secs() << 30 | dur.subsec_nanos() as u64
     }
 
     #[cfg(any(target_os = "macos", target_os = "ios"))]
     pub fn get_nstime() -> u64 {
         extern crate libc;
         // On Mac OS and iOS std::time::SystemTime only has 1000ns resolution.
-        // We use `mach_absolute_time` instead. This provides a CPU dependent unit,
-        // to get real nanoseconds the result should by multiplied by numer/denom
-        // from `mach_timebase_info`.
-        // But we are not interested in the exact nanoseconds, just entropy. So we
-        // use the raw result.
+        // We use `mach_absolute_time` instead. This provides a CPU dependent
+        // unit, to get real nanoseconds the result should by multiplied by
+        // numer/denom from `mach_timebase_info`.
+        // But we are not interested in the exact nanoseconds, just entropy. So
+        // we use the raw result.
         unsafe { libc::mach_absolute_time() }
     }