Draft: Options API

[josephlr]

Looking through the wonderful review by @m-ou-se in m-ou-se#1, I realized that at some point we might need a separate API for generating hashmap seeds. This is because when generating a hashmap seed on Linux, we would not want to block waiting on the RNG to initialize.

However, if we decided to add a different source or configuration for the RNG one day, it wouldn't make sense to just have it be a free function in this crate. This is because with the addition of #291 (and potentially #293), we also use free functions to get the random bytes in different ways (fill a &mut [u8], fill a &mut [MaybeUninit<u8>], return an array).

This PR contains the proposed Options API:

• The different variants of Options would determine the RNG source/configuration.
• The methods on Options would be used to get random bytes in different ways:
  • fill
  • fill_uninit
  • array (not in this PR, see Add Options::array method for creating random arrays #352 for how we might add it)

Right now we only have a single option: Options::DEFAULT. However, in the future, we could add Options to:

• use a insecure but non-blocking system source (for seeding hashmaps).
• guarantee the function doesn't block (would return an error on most targets)
• not use a fallback mechanism (@briansmith had something like this for ring at one point).
• never use the custom RNG source
• always prefere the custom RNG source if it exists

Not all of these are things we should necessarily do, but this gives
us the flexibility to add such options in the future.

Bikeshed: This enum could be called Options/Source/Config, it could also be an opaque struct at this point rather than an enum (as we only have one variant).

Signed-off-by: Joe Richey [email protected]

[newpavlov]

I understand rationale behind exposing less secure, but non-blocking getrandom. It's reasonable to expect that both variants will be used in a same application. But I don't think it applies to the other options you listed. Those are better served by crate's configuration options or by replacing getrandom with something custom.

I suggest we focus on the HashMap use case. I don't quite like your Option approach. It feels backward. I think we should do one of the following:

1. Introduce separate functions. Increasing number of public functions from 3 to 6 looks fine to me.
2. Introduce flag-like argument for the functions. It will mirror how getrandom works on Linux with its GRND_RANDOM and GRND_NONBLOCK flags.

[newpavlov]

Closing it in favor of #365.