> On 21 Sep 2019, at 00:17, Gilles Sadowski <gillese...@gmail.com> wrote:
>
> Hello.
>
> 2019-09-20 18:45 UTC+02:00, Alex Herbert <alex.d.herb...@gmail.com
> <mailto:alex.d.herb...@gmail.com>>:
>> I have added some new sections to the user guide for new additions to
>> the library.
>>
>> Currently the section on JumpableUniformRandomProvider gives an example:
>>
>> RandomSource source = RandomSource.XO_RO_SHI_RO_128_SS; // Known to be
>> jumpable.
>> JumpableUniformRandomProvider master = (JumpableUniformRandomProvider)
>> RandomSource.create(source);
>>
>> It then states:
>>
>> "In the above example, the source is known to implement the
>> JumpableUniformRandomProvider interface. Not all generators support this
>> functionality."
>>
>> There is currently no way to know if a generator is jumpable without
>> first creating it and using 'instanceof':
>>
>> RandomSource source = RandomSource.XO_RO_SHI_RO_128_SS; // Known to be
>> jumpable.
>> UniformRandomProvider master = RandomSource.create(source);
>> if (master instanceof JumpableUniformRandomProvider) {
>> // go ahead ...
>> }
>>
>> This should be improved but how?
>>
>> Currently not all providers have this functionality. This could be
>> handled with a soft option of adding it only to javadoc or an option to
>> add it to the API:
>>
>> 1. Add a note to the RandomSource javadoc for each generator that is a
>> JumpableUniformRandomProvider and LongJumpableUniformRandomProvider.
>> This is manageable for now but may not be if more and more selective
>> features are added later.
>
> Perhaps better to have a code that generates a table (to be added
> to the userguide) with all the properties of each available "source”.
To the user guide or to RandomSource javadoc?
RandomSource,NativeSeed,SeedBytes,Jumpable,LongJumpable
JDK,long,8,N,N
XO_SHI_RO_128_PLUS,int[],16,Y,N
Etc and formatted appropriately.
A recent post on the dev mailing list discussed a method for extracting
snippets from unit tests and updating the source. So it may be possible to
automate the table generation. However it may require a lot of <snippet> tags
all over the source if it is to update the RandomSource enum javadoc for the
native seed size. I will investigate this after I have created the table. A
compromise would be just a single <snippet> tag at the main table location so
the table is automatically kept in sync with the source code.
>
>>
>> 2. Add a method BitSet<T> getSupport() to the RandomSource enum, where T
>> is an enum that can be expanded as more features are added. Initially is
>> would be:
>
> +1
> With "EnumSet", I guess.
Yes.
>
>>
>> enum RandomSourceSupport {
>> /** The source supported the {@link JumpableUniformRandomProvider}
>> interface. */
>> JUMPABLE,
>> /** The source supported the {@link LongJumpableUniformRandomProvider}
>> interface. */
>> LONG_JUMPABLE,
>> }
>
> +1
>
>>
>> Currently the RandomSource only has a isNativeSeed(Object) method. So
>> adding methods does add API clutter. It would be possible to also add
>> getNativeSeedLength() method as this information (available in the
>> javadoc) is now available in the factory code that builds generators.
>
> +1
So this would add to RandomSource:
int getSeedByteLength()
EnumSet<RandomSourceSupport> getSupport()
The first should return the native seed size in bytes. Currently the javadoc
contains the native seed length. This is the length of the seed array or 1 if
the seed is a Long/Integer.
I think having the seed size in bytes is more generic and it doesn’t matter if
the seed is an array or not. So perhaps the javadoc should contain the human
readable array length (if relevant) but the code uses the generic byte length
allowing:
SecureRandom sr = new SecureRandom();
RandomSource source = RandomSource.MWC_256;
UniformRandomProvider rng = RandomSource.create(source,
sr.generateSeed(source.getSeedByteLength());
In the case where the seed is a Long/Integer I suggest dropping the javadoc:
"Native seed size: 1” as it is redundant.
>
> Gilles
>
>>
>> Any other suggestions?
>>
>> Alex
>>
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> <mailto:dev-unsubscr...@commons.apache.org>
> For additional commands, e-mail: dev-h...@commons.apache.org
> <mailto:dev-h...@commons.apache.org>
