[RNG-180] New SplittableUniformRandomProvider interface

• Type: New Feature
• Status: Closed
• Priority: Major
• Resolution: Implemented
• Affects Version/s: 1.5
• Fix Version/s: 1.5
• Component/s: client-api
• difficulty-level: Easy
• Assignee: Alex Herbert
• Reporter: Alex Herbert
• Created: 30/Aug/22 16:42
• Updated: 10/Oct/22 11:54
• Resolved: 05/Sep/22 12:28

Description

The minimum java version for RNG is now 1.8. Stream support has been added for the UniformRandomProvider and Sampler interfaces. These all operate using a sequential stream. To use a parallel stream requires the concept of splitting the source of randomness.

I propose to add a Splittable interface. This can be modelled on the interface in the JDK 17 random package SplittableGenerator (javadoc):

public interface SplittableUniformRandomProvider 
    extends UniformRandomProvider {

    SplittableUniformRandomProvider split();
    SplittableUniformRandomProvider split(SplittableUniformRandomProvider source);
    Stream<SplittableUniformRandomProvider> splits();
    Stream<SplittableUniformRandomProvider> splits(SplittableUniformRandomProvider source);
    Stream<SplittableUniformRandomProvider> splits(long streamSize);
    Stream<SplittableUniformRandomProvider> splits(long streamSize,
        SplittableUniformRandomProvider source);

The JDK interface has both a split and split(source) method, and similar for the stream created by repeat splitting. The source is to provide the random bits to initialise the new instances. In most cases this will just be the current instance. However it provides a means to provide a small state splittable generator for the random source of bits and use a larger state generator to provide new instances from those bits, or vice versa. This allows more flexibility to control the source of random bits, and the instance type of the new split generators.

Note: It is possible to implement the entire interface using default methods except:

    SplittableUniformRandomProvider split(SplittableUniformRandomProvider source);

The stream can be created by recursively splitting the current instance via a custom Spliterator<SplittableUniformRandomProvider>.

Also note that the stream methods in UniformRandomProvider can be overridden to support parallel streams. This requires for example a custom Spliterator.OfInt to split the generator for parallel generation.