Skip to content

Rename NewRng::new → FromEntropy::from_entropy#375

Merged
dhardy merged 1 commit into
rust-random:masterfrom
dhardy:from_entropy
Apr 15, 2018
Merged

Rename NewRng::new → FromEntropy::from_entropy#375
dhardy merged 1 commit into
rust-random:masterfrom
dhardy:from_entropy

Conversation

@dhardy

@dhardy dhardy commented Apr 5, 2018

Copy link
Copy Markdown
Member

Implement #360.

I wanted to try this, but personally I'm not so keen.

Advantage:

  • it's clearer what SmallRng::from_entropy() does than SmallRng::new()

Disadvantages:

  • inconsistent with OsRng::new()?
  • from_entropy is a little long

Alternatives:

  • SmallRng::from_rng(entropy_rng())? — but this is longer and has error handling
  • NewRng::new_fresh() — just a rename

@pitdicker

Copy link
Copy Markdown
Contributor

I still think the new() method is great to have. Maybe we just need to sell it a little better.

The new trait NewRng makes functionality we already had for StdRng easily available to all seedable RNG implementations. It provides easy seeding of PRNGs using EntropyRng as source, which internally uses OsRng or a fallback.

If we decide to change anything here, NewRng::new_fresh() is something I could get behind.

@pitdicker

Copy link
Copy Markdown
Contributor

But always good to try to do something with critique, and see if we can get something better. So 👍 for the PR.

@pitdicker

Copy link
Copy Markdown
Contributor

What do you think of having two methods in NewRng: new_fresh and from_thread_rng?

@dhardy

dhardy commented Apr 5, 2018

Copy link
Copy Markdown
Member Author

I was thinking about that; there's some sense to it but I'm not sure; it's not a lot easier than writing from_rng(thread_rng())? and there's a chance we could move thread_rng into a separate crate later.

@pitdicker

Copy link
Copy Markdown
Contributor

it's not a lot easier than writing from_rng(thread_rng())?

No, it is not for us. But it takes two imports (rand::{SeedableRng, thread_rng}, two methods (SomeRng::from_rng and thread_rng(), and some way to handle errors (? or unwrap()). SomeRng::from_thread_rng would be one method and one import NewRng.

I don't care all that strongly. But I believe such a convenience method would put both source on a more even foot.

there's a chance we could move thread_rng into a separate crate later.

That idea is new to me. What would be the reason for doing something like that?

@dhardy

dhardy commented Apr 5, 2018

Copy link
Copy Markdown
Member Author

thread_rng is a derived component so would be easy to separate out (apart from this usage), but probably there's no value in doing so.

So maybe as follows:

pub trait NewRng {
    // both methods panic on error since this trait is pure convenience:
    fn from_entropy() -> Self;
    fn from_thread_rng() -> Self;
}

Reasoning:

  • from_* type methods are commonly used to construct an object from something else (e.g. from_str, from_iter)
  • as @pitdicker points out, a single method is easier to remember, less to import, and expecting users to call unwrap() or handle extremely unlikely errors (which often can't be worked around properly anyway) is not ideal, so there is some value in these
  • the trait is for constructing RNGs so the name does seem appropriate; also FromEntropy::from_entropy is redundant naming (poor design) and FromEntropy::from_thread_rng doesn't make much sense

@vks @burdges @huonw any thoughts?

@burdges

burdges commented Apr 5, 2018

Copy link
Copy Markdown
Contributor

What's the difference between the two methods?

@dhardy

dhardy commented Apr 6, 2018

Copy link
Copy Markdown
Member Author

One uses EntropyRng for external entropy and the other uses the local thread_rng for fast "entropy" from a crypto rng.

@pitdicker

Copy link
Copy Markdown
Contributor

I prefer something with fresh in the name, as you suggested in the first comment, over from_entropy.

It sounds more approachable, and I have my doubts whether "construct an RNG from entropy" is a correct expression.

@vks

vks commented Apr 7, 2018 via email

Copy link
Copy Markdown
Contributor

@dhardy

dhardy commented Apr 8, 2018

Copy link
Copy Markdown
Member Author

If we go with from_entropy we have several similarly-named ways of constructing RNGs:

  • SeedableRng::from_seed
  • SeedableRng::from_rng
  • FromEntropy::from_entropy
  • FromEntropy::from_thread_rng — possible addition

Contrary to what I said earlier, the redundant name FromEntropy::from_entropy is helpful to describe where the method comes from (if seen like SmallRng::from_entropy()), and FromEntropy::from_thread_rng still makes some sense (thread_rng is used as an entropy source).

So I'm tempted to merge this PR as is, or possibly with the from_thread_rng addition.

@vks

vks commented Apr 9, 2018

Copy link
Copy Markdown
Contributor

So I'm tempted to merge this PR as is, or possibly with the from_thread_rng addition.

👍 for merging as is.

StdRng::from_thread_rng() should probably be avoided, so I'm not sure from_thread_rng is a good idea. I think I would rather err on the side of caution and mention the benefits of from_rng(thread_rng())? in the documentation of from_entropy.

On an unrelated note, does it make sense to rename thread_rng to ThreadRng::new()? This seems more consistent with JitterRng, EntropyRng and OsRng.

@pitdicker pitdicker left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not the greatest fan of this renaming, but feel free to merge. (Maybe do something with my one comment)

On thing that just now occured to me: The release note and changelog should mention that it is no longer possible to call StdRng::new(), and that FromEntropy::from_entropy is the replacement.

/// use rand::{thread_rng, Rng};
/// use rand::distributions::Exp1;
///
/// let val: f64 = SmallRng::new().sample(Exp1);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using SmallRng in these examples seems like something nice to preserve. It does not matter much, but I expect this code to be mostly used in combination with the simpler non-cryptographic RNGs. So it would fit more with the way users use it.

@vks vks Apr 9, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, I missed this change. I completely agree.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, fair point.

@dhardy dhardy merged commit ecb9647 into rust-random:master Apr 15, 2018
@dhardy dhardy deleted the from_entropy branch April 19, 2018 10:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants