Hi.
2019-09-21 9:53 UTC+02:00, Alex Herbert <alex.d.herb...@gmail.com>:
>
>
>> 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?
To the userguide IMO (with a @link to there in the Javadoc).
> RandomSource,NativeSeed,SeedBytes,Jumpable,LongJumpable
> JDK,long,8,N,N
> XO_SHI_RO_128_PLUS,int[],16,Y,N
>
> Etc and formatted appropriately.
+1
>
> 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.
The idea seemed interesting but when I started to read the
details, I felt (perhaps wrongly) that it is too much work,
especially for the kind of code in [RNG].
> 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.
And that will make the source code more difficult to read
for developers.
> 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.
This is just one update for each new implementation.
And we are talking about doc that mostly impacts application
developers, not users: Bugs due to incorrect documentation
will either be detected at compile time or won't have any
dire consequence.
In this particular case, I wouldn't trade Javadoc clarity for
the hypothetical risk of mistakes in a convenience summary
of those few properties.
>>
>>>
>>> 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()
I think that the API should not specify the type of "Set".
Also, the enum should be an inner class. Thus:
public class RandomSource {
// ...
public enum Support {
JUMPABLE,
// etc.
}
public Set<Support> getSupport() {
final Set<Support> s = new EnumSet<>(Support.class);
// ...
return s;
}
}
>
> 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:
+1
>
> 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.
+1
Regards,
Gilles
>>
>>>
>>> Any other suggestions?
>>>
>>> Alex
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
