From e1244a66cf9c6c692ed09b4f9d42840fed0d6189 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Sun, 18 Mar 2018 16:56:01 +0000 Subject: [PATCH 1/2] Add trait implementation guidance Close https://github.com/dhardy/rand/issues/13 --- rand-core/src/lib.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/rand-core/src/lib.rs b/rand-core/src/lib.rs index e998d1a368a..0efb2fc85a3 100644 --- a/rand-core/src/lib.rs +++ b/rand-core/src/lib.rs @@ -81,6 +81,14 @@ pub mod le; /// in this trait directly, then use the helper functions from the [`impls`] /// module to implement the other methods. /// +/// It is recommended that implementations also implement: +/// +/// - `Debug` but such that no internal details are output +/// - `Serialize` and `Deserialize` (from Serde), possibly behind a feature gate +/// - `Clone` if, and only if, the clone will have identical output to the original +/// - *never* implement `Copy` (accidental copies may cause repeated values) +/// - `Eq` and `PartialEq` could be implemented, but are probably not useful +/// /// # Example /// /// A simple example, obviously not generating very *random* output: From 5dc1af7cb9a2b2c3b854ad26a43a5401f99542a8 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Mon, 19 Mar 2018 10:40:51 +0000 Subject: [PATCH 2/2] Improve guidance on RngCore trait impls, in response to comments --- rand-core/src/lib.rs | 11 ++++++++--- src/thread_rng.rs | 3 ++- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/rand-core/src/lib.rs b/rand-core/src/lib.rs index 0efb2fc85a3..1c997d50c14 100644 --- a/rand-core/src/lib.rs +++ b/rand-core/src/lib.rs @@ -83,10 +83,15 @@ pub mod le; /// /// It is recommended that implementations also implement: /// -/// - `Debug` but such that no internal details are output -/// - `Serialize` and `Deserialize` (from Serde), possibly behind a feature gate -/// - `Clone` if, and only if, the clone will have identical output to the original +/// - `Debug` with a custom implementation which *does not* print any internal +/// state (at least, `CryptoRng`s should not risk leaking state through Debug) +/// - `Serialize` and `Deserialize` (from Serde), preferably making Serde +/// support optional at the crate level in PRNG libs +/// - `Clone` if, and only if, the clone will have identical output to the +/// original (i.e. all deterministic PRNGs but not external generators) /// - *never* implement `Copy` (accidental copies may cause repeated values) +/// - also *do not* implement `Default`, but instead implement `SeedableRng` +/// thus allowing use of `rand::NewRng` (which is automatically implemented) /// - `Eq` and `PartialEq` could be implemented, but are probably not useful /// /// # Example diff --git a/src/thread_rng.rs b/src/thread_rng.rs index fb15f07118f..87ec8b489ad 100644 --- a/src/thread_rng.rs +++ b/src/thread_rng.rs @@ -45,7 +45,8 @@ use reseeding::ReseedingRng; const THREAD_RNG_RESEED_THRESHOLD: u64 = 32*1024*1024; // 32 MiB /// The type returned by [`thread_rng`], essentially just a reference to the -/// PRNG in thread-local memory. +/// PRNG in thread-local memory. Cloning this handle just produces a new +/// reference to the same thread-local generator. /// /// [`thread_rng`]: fn.thread_rng.html #[derive(Clone, Debug)]