[RNG-178] Add stream support to JumpableUniformRandomProvider

• Type: New Feature
• Status: Closed
• Priority: Major
• Resolution: Implemented
• Affects Version/s: 1.4
• Fix Version/s: 1.5
• Component/s: client-api
• difficulty-level: Easy
• Assignee: Alex Herbert
• Reporter: Alex Herbert
• Created: 17/May/22 10:34
• Updated: 10/Oct/22 11:54
• Resolved: 19/May/22 08:17

Description

The JumpableUniformRandomProvider can add default methods to allow a stream of generators to be created:

    default Stream<UniformRandomProvider> jumps() {
        return Stream.generate(this::jump).sequential();
    }

    default Stream<UniformRandomProvider> jumps(long streamSize) {
        return jumps().limit(streamSize);
    }

A similar method for the LongJumpableRandomGenerator can be provided.

Note: This method is found in the JDK 17 JumpableGenerator interface.

Other methods from that interface cannot be added as they have no default implementation. Note the JDK interface has separated the jump from the copy operation:

RandomGenerator.JumpableGenerator copy();
void jump();
default RandomGenerator copyAndJump();
double jumpDistance();
static RandomGenerator.JumpableGenerator of(String name);

Note the factory method is achieved in Commons RNG using:

JumpableUniformRandomProvider rng = (JumpableUniformRandomProvider)
    Arrays.stream(RandomSource.values())
          .filter(RandomSource::isJumpable)
          .findFirst()
          .get().create();

This involves an explicit cast in user code. It may be desirable to formalise this pattern by adding a Stream method to RandomSource:

public static Stream<RandomSource> stream();

JumpableUniformRandomProvider rng = (JumpableUniformRandomProvider)
    RandomSource.stream()
                .filter(RandomSource::isJumpable)
                .findFirst()
                .get().create();

Note that the jump distance is not provided by the Commons RNG API. It cannot be added to the interface due to binary compatibility constraints. It could be added to the RandomSource enum. This would allow filtering in a stream by minimum jump distance. This does however add properties to RandomSource for many instances where the property is not relevant (cluttering the API).

The JDK 17 equivalent feature for this is to create Stream<RandomGeneratorFactory<RandomGenerator>> all() factories and then filter on those. The RandomGeneratorFactory instances are the equivalent of RandomSource instances as these have properties that can be used for filters. However it does not appear that the Jumpable generators can be filtered on their jump distance as this is not exposed by the factory for use in filtering the stream. The jump distance can be obtained after an instance of the generator has been created.

Issue Links

• is related to: RNG-127 Assess future compatibility with JEP 356: Enhanced Pseudo-Random Number Generators