--- a/src/java.base/share/classes/java/util/Random.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/Random.java Thu Aug 08 11:06:54 2019 -0300
@@ -578,12 +578,14 @@
* by class AbstractSpliteratorGenerator. Each one needs to define only a constructor and two
* methods.
*/
- static class RandomIntsSpliterator extends RandomSupport.RandomSpliterator implements Spliterator.OfInt {
+ static class RandomIntsSpliterator extends RandomSupport.RandomSpliterator
+ implements Spliterator.OfInt {
final AbstractSpliteratorGenerator generatingGenerator;
final int origin;
final int bound;
- RandomIntsSpliterator(AbstractSpliteratorGenerator generatingGenerator, long index, long fence, int origin, int bound) {
+ RandomIntsSpliterator(AbstractSpliteratorGenerator generatingGenerator,
+ long index, long fence, int origin, int bound) {
super(index, fence);
this.generatingGenerator = generatingGenerator;
this.origin = origin; this.bound = bound;
@@ -625,12 +627,14 @@
/**
* Spliterator for long streams.
*/
- static class RandomLongsSpliterator extends RandomSupport.RandomSpliterator implements Spliterator.OfLong {
+ static class RandomLongsSpliterator extends RandomSupport.RandomSpliterator
+ implements Spliterator.OfLong {
final AbstractSpliteratorGenerator generatingGenerator;
final long origin;
final long bound;
- RandomLongsSpliterator(AbstractSpliteratorGenerator generatingGenerator, long index, long fence, long origin, long bound) {
+ RandomLongsSpliterator(AbstractSpliteratorGenerator generatingGenerator,
+ long index, long fence, long origin, long bound) {
super(index, fence);
this.generatingGenerator = generatingGenerator;
this.origin = origin; this.bound = bound;
@@ -672,12 +676,14 @@
/**
* Spliterator for double streams.
*/
- static class RandomDoublesSpliterator extends RandomSupport.RandomSpliterator implements Spliterator.OfDouble {
+ static class RandomDoublesSpliterator extends RandomSupport.RandomSpliterator
+ implements Spliterator.OfDouble {
final AbstractSpliteratorGenerator generatingGenerator;
final double origin;
final double bound;
- RandomDoublesSpliterator(AbstractSpliteratorGenerator generatingGenerator, long index, long fence, double origin, double bound) {
+ RandomDoublesSpliterator(AbstractSpliteratorGenerator generatingGenerator,
+ long index, long fence, double origin, double bound) {
super(index, fence);
this.generatingGenerator = generatingGenerator;
this.origin = origin; this.bound = bound;
--- a/src/java.base/share/classes/java/util/random/L128X256MixRandom.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/L128X256MixRandom.java Thu Aug 08 11:06:54 2019 -0300
@@ -62,7 +62,7 @@
* The LCG subgenerator for {@link L128X256MixRandom} has an update step of the
* form {@code s = m * s + a}, where {@code s}, {@code m}, and {@code a} are all
* 128-bit integers; {@code s} is the mutable state, the multiplier {@code m}
- * is fixed (the same for all instances of {@link L128X256MixRandom}}) and the addend
+ * is fixed (the same for all instances of {@link L128X256MixRandom}) and the addend
* {@code a} is a parameter (a final field of the instance). The parameter
* {@code a} is required to be odd (this allows the LCG to have the maximal
* period, namely 2<sup>128</sup>); therefore there are 2<sup>127</sup> distinct choices
@@ -309,7 +309,8 @@
public L128X256MixRandom(byte[] seed) {
// Convert the seed to 6 long values, of which the last 4 are not all zero.
long[] data = RandomSupport.convertSeedBytesToLongs(seed, 6, 4);
- long ah = data[0], al = data[1], sh = data[2], sl = data[3], x0 = data[4], x1 = data[5], x2 = data[6], x3 = data[7];
+ long ah = data[0], al = data[1], sh = data[2], sl = data[3],
+ x0 = data[4], x1 = data[5], x2 = data[6], x3 = data[7];
// Force a to be odd.
this.ah = ah;
this.al = al | 1;
@@ -360,7 +361,15 @@
sl = u + al;
if (Long.compareUnsigned(sl, u) < 0) ++sh; // Handle the carry propagation from low half to high half.
long q0 = x0, q1 = x1, q2 = x2, q3 = x3;
- { long t = q1 << 17; q2 ^= q0; q3 ^= q1; q1 ^= q2; q0 ^= q3; q2 ^= t; q3 = Long.rotateLeft(q3, 45); } // xoshiro256 1.0
+ { // xoshiro256 1.0
+ long t = q1 << 17;
+ q2 ^= q0;
+ q3 ^= q1;
+ q1 ^= q2;
+ q0 ^= q3;
+ q2 ^= t;
+ q3 = Long.rotateLeft(q3, 45);
+ }
x0 = q0; x1 = q1; x2 = q2; x3 = q3;
return RandomSupport.mixLea64(z); // mixing function
}
--- a/src/java.base/share/classes/java/util/random/L32X64MixRandom.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/L32X64MixRandom.java Thu Aug 08 11:06:54 2019 -0300
@@ -61,7 +61,7 @@
* The LCG subgenerator for {@link L32X64MixRandom} has an update step of the
* form {@code s = m * s + a}, where {@code s}, {@code m}, and {@code a} are all
* of type {@code int}; {@code s} is the mutable state, the multiplier {@code m}
- * is fixed (the same for all instances of {@link L32X64MixRandom}}) and the addend
+ * is fixed (the same for all instances of {@link L32X64MixRandom}) and the addend
* {@code a} is a parameter (a final field of the instance). The parameter
* {@code a} is required to be odd (this allows the LCG to have the maximal
* period, namely 2<sup>32</sup>); therefore there are 2<sup>31</sup> distinct choices
@@ -290,8 +290,8 @@
* the same expected statistical properties apply to the entire set of generators constructed by
* such recursive splitting.
*
- * @param source a {@link SplittableGenerator} instance to be used instead of this one as a source of
- * pseudorandom bits used to initialize the state of the new ones.
+ * @param source a {@link SplittableGenerator} instance to be used instead of this one as
+ * a source of pseudorandom bits used to initialize the state of the new ones.
*
* @return a new instance of {@link L32X64MixRandom}
*/
@@ -310,7 +310,12 @@
final int z = s + x0;
s = M * s + a; // LCG
int q0 = x0, q1 = x1;
- { q1 ^= q0; q0 = Integer.rotateLeft(q0, 26); q0 = q0 ^ q1 ^ (q1 << 9); q1 = Integer.rotateLeft(q1, 13); } // xoroshiro64
+ { // xoroshiro64
+ q1 ^= q0;
+ q0 = Integer.rotateLeft(q0, 26);
+ q0 = q0 ^ q1 ^ (q1 << 9);
+ q1 = Integer.rotateLeft(q1, 13);
+ }
x0 = q0; x1 = q1;
return Integer.rotateLeft(z * 5, 7) * 9; // "starstar" mixing function
}
--- a/src/java.base/share/classes/java/util/random/L64X1024MixRandom.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/L64X1024MixRandom.java Thu Aug 08 11:06:54 2019 -0300
@@ -61,7 +61,7 @@
* The LCG subgenerator for {@link L64X1024MixRandom} has an update step of the
* form {@code s = m * s + a}, where {@code s}, {@code m}, and {@code a} are all
* of type {@code long}; {@code s} is the mutable state, the multiplier {@code m}
- * is fixed (the same for all instances of {@link L64X1024MixRandom}}) and the addend
+ * is fixed (the same for all instances of {@link L64X1024MixRandom}) and the addend
* {@code a} is a parameter (a final field of the instance). The parameter
* {@code a} is required to be odd (this allows the LCG to have the maximal
* period, namely 2<sup>64</sup>); therefore there are 2<sup>63</sup> distinct choices
--- a/src/java.base/share/classes/java/util/random/L64X1024Random.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/L64X1024Random.java Thu Aug 08 11:06:54 2019 -0300
@@ -61,7 +61,7 @@
* The LCG subgenerator for {@link L64X1024Random} has an update step of the
* form {@code s = m * s + a}, where {@code s}, {@code m}, and {@code a} are all
* of type {@code long}; {@code s} is the mutable state, the multiplier {@code m}
- * is fixed (the same for all instances of {@link L64X1024Random}}) and the addend
+ * is fixed (the same for all instances of {@link L64X1024Random}) and the addend
* {@code a} is a parameter (a final field of the instance). The parameter
* {@code a} is required to be odd (this allows the LCG to have the maximal
* period, namely 2<sup>64</sup>); therefore there are 2<sup>63</sup> distinct choices
--- a/src/java.base/share/classes/java/util/random/L64X128MixRandom.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/L64X128MixRandom.java Thu Aug 08 11:06:54 2019 -0300
@@ -315,7 +315,12 @@
final long z = s + x0;
s = M * s + a; // LCG
long q0 = x0, q1 = x1;
- { q1 ^= q0; q0 = Long.rotateLeft(q0, 24); q0 = q0 ^ q1 ^ (q1 << 16); q1 = Long.rotateLeft(q1, 37); } // xoroshiro128v1_0
+ { // xoroshiro128v1_0
+ q1 ^= q0;
+ q0 = Long.rotateLeft(q0, 24);
+ q0 = q0 ^ q1 ^ (q1 << 16);
+ q1 = Long.rotateLeft(q1, 37);
+ }
x0 = q0; x1 = q1;
return Long.rotateLeft(z * 5, 7) * 9; // "starstar" mixing function
}
--- a/src/java.base/share/classes/java/util/random/L64X128Random.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/L64X128Random.java Thu Aug 08 11:06:54 2019 -0300
@@ -61,7 +61,7 @@
* The LCG subgenerator for {@link L64X128Random} has an update step of the
* form {@code s = m * s + a}, where {@code s}, {@code m}, and {@code a} are all
* of type {@code long}; {@code s} is the mutable state, the multiplier {@code m}
- * is fixed (the same for all instances of {@link L64X128Random}}) and the addend
+ * is fixed (the same for all instances of {@link L64X128Random}) and the addend
* {@code a} is a parameter (a final field of the instance). The parameter
* {@code a} is required to be odd (this allows the LCG to have the maximal
* period, namely 2<sup>64</sup>); therefore there are 2<sup>63</sup> distinct choices
@@ -311,7 +311,12 @@
final long z = s + x0;
s = M * s + a; // LCG
long q0 = x0, q1 = x1;
- { q1 ^= q0; q0 = Long.rotateLeft(q0, 24); q0 = q0 ^ q1 ^ (q1 << 16); q1 = Long.rotateLeft(q1, 37); } // xoroshiro128v1_0
+ { // xoroshiro128v1_0
+ q1 ^= q0;
+ q0 = Long.rotateLeft(q0, 24);
+ q0 = q0 ^ q1 ^ (q1 << 16);
+ q1 = Long.rotateLeft(q1, 37);
+ }
x0 = q0; x1 = q1;
return z;
}
--- a/src/java.base/share/classes/java/util/random/L64X256MixRandom.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/L64X256MixRandom.java Thu Aug 08 11:06:54 2019 -0300
@@ -61,7 +61,7 @@
* The LCG subgenerator for {@link L64X256MixRandom} has an update step of the
* form {@code s = m * s + a}, where {@code s}, {@code m}, and {@code a} are all
* of type {@code long}; {@code s} is the mutable state, the multiplier {@code m}
- * is fixed (the same for all instances of {@link L64X256MixRandom}}) and the addend
+ * is fixed (the same for all instances of {@link L64X256MixRandom}) and the addend
* {@code a} is a parameter (a final field of the instance). The parameter
* {@code a} is required to be odd (this allows the LCG to have the maximal
* period, namely 2<sup>64</sup>); therefore there are 2<sup>63</sup> distinct choices
@@ -327,7 +327,15 @@
final long z = s + x0;
s = M * s + a; // LCG
long q0 = x0, q1 = x1, q2 = x2, q3 = x3;
- { long t = q1 << 17; q2 ^= q0; q3 ^= q1; q1 ^= q2; q0 ^= q3; q2 ^= t; q3 = Long.rotateLeft(q3, 45); } // xoshiro256 1.0
+ { // xoshiro256 1.0
+ long t = q1 << 17;
+ q2 ^= q0;
+ q3 ^= q1;
+ q1 ^= q2;
+ q0 ^= q3;
+ q2 ^= t;
+ q3 = Long.rotateLeft(q3, 45);
+ }
x0 = q0; x1 = q1; x2 = q2; x3 = q3;
return RandomSupport.mixLea64(z); // mixing function
}
--- a/src/java.base/share/classes/java/util/random/L64X256Random.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/L64X256Random.java Thu Aug 08 11:06:54 2019 -0300
@@ -61,7 +61,7 @@
* The LCG subgenerator for {@link L64X256Random} has an update step of the
* form {@code s = m * s + a}, where {@code s}, {@code m}, and {@code a} are all
* of type {@code long}; {@code s} is the mutable state, the multiplier {@code m}
- * is fixed (the same for all instances of {@link L64X256Random}}) and the addend
+ * is fixed (the same for all instances of {@link L64X256Random}) and the addend
* {@code a} is a parameter (a final field of the instance). The parameter
* {@code a} is required to be odd (this allows the LCG to have the maximal
* period, namely 2<sup>64</sup>); therefore there are 2<sup>63</sup> distinct choices
@@ -325,7 +325,15 @@
final long z = s + x0;
s = M * s + a; // LCG
long q0 = x0, q1 = x1, q2 = x2, q3 = x3;
- { long t = q1 << 17; q2 ^= q0; q3 ^= q1; q1 ^= q2; q0 ^= q3; q2 ^= t; q3 = Long.rotateLeft(q3, 45); } // xoshiro256 1.0
+ { // xoshiro256 1.0
+ long t = q1 << 17;
+ q2 ^= q0;
+ q3 ^= q1;
+ q1 ^= q2;
+ q0 ^= q3;
+ q2 ^= t;
+ q3 = Long.rotateLeft(q3, 45);
+ }
x0 = q0; x1 = q1; x2 = q2; x3 = q3;
return z;
}
--- a/src/java.base/share/classes/java/util/random/RandomGenerator.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/RandomGenerator.java Thu Aug 08 11:06:54 2019 -0300
@@ -33,9 +33,9 @@
import java.util.stream.Stream;
/**
- * The {@link RandomGenerator} interface is designed to provide a common protocol for objects
- * that generate random or (more typically) pseudorandom sequences of numbers (or Boolean values).
- * Such a sequence may be obtained by either repeatedly invoking a method that returns a single
+ * The {@link RandomGenerator} interface is designed to provide a common protocol for objects that
+ * generate random or (more typically) pseudorandom sequences of numbers (or Boolean values). Such a
+ * sequence may be obtained by either repeatedly invoking a method that returns a single
* (pseudo)randomly chosen value, or by invoking a method that returns a stream of (pseudo)randomly
* chosen values.
* <p>
@@ -53,37 +53,38 @@
* <p>
* Each method that returns a stream produces a stream of values each of which is chosen in the same
* manner as for a method that returns a single (pseudo)randomly chosen value. For example, if
- * {@code r} implements {@link RandomGenerator}, then the method call {@code r.ints(100)}
- * returns a stream of 100 {@code int} values. These are not necessarily the exact same values that
- * would have been returned if instead {@code r.nextInt()} had been called 100 times; all that is
+ * {@code r} implements {@link RandomGenerator}, then the method call {@code r.ints(100)} returns a
+ * stream of 100 {@code int} values. These are not necessarily the exact same values that would
+ * have been returned if instead {@code r.nextInt()} had been called 100 times; all that is
* guaranteed is that each value in the stream is chosen in a similar (pseudo)random manner from the
* same range.
* <p>
- * Every object that implements the {@link RandomGenerator} interface is assumed to contain a
- * finite amount of state. Using such an object to generate a pseudorandomly chosen value alters
- * its state. The number of distinct possible states of such an object is called its
+ * Every object that implements the {@link RandomGenerator} interface is assumed to contain a finite
+ * amount of state. Using such an object to generate a pseudorandomly chosen value alters its
+ * state. The number of distinct possible states of such an object is called its
* <i>period</i>. (Some implementations of the {@link RandomGenerator} interface
* may be truly random rather than pseudorandom, for example relying on the statistical behavior of
* a physical object to derive chosen values. Such implementations do not have a fixed period.)
* <p>
- * As a rule, objects that implement the {@link RandomGenerator} interface need not be
- * thread-safe. It is recommended that multithreaded applications use either {@link
- * ThreadLocalRandom} or (preferably) pseudorandom number generators that implement the {@link
- * SplittableGenerator} or {@link JumpableGenerator} interface.
+ * As a rule, objects that implement the {@link RandomGenerator} interface need not be thread-safe.
+ * It is recommended that multithreaded applications use either {@link ThreadLocalRandom} or
+ * (preferably) pseudorandom number generators that implement the {@link SplittableGenerator} or
+ * {@link JumpableGenerator} interface.
* <p>
* To implement this interface, a class only needs to provide concrete definitions for the methods
* {@code nextLong()} and {@code period()}. Default implementations are provided for all other
* methods (but it may be desirable to override some of them, especially {@code nextInt()} if the
* underlying algorithm is {@code int}-based). Moerover, it may be preferable instead to implement
- * another interface such as {@link JumpableGenerator} or {@link LeapableGenerator}, or to extend an abstract
- * class such as {@link AbstractSplittableGenerator} or {@link AbstractArbitrarilyJumpableGenerator}.
+ * another interface such as {@link JumpableGenerator} or {@link LeapableGenerator}, or to extend an
+ * abstract class such as {@link AbstractSplittableGenerator} or {@link
+ * AbstractArbitrarilyJumpableGenerator}.
* <p>
* Objects that implement {@link RandomGenerator} are typically not cryptographically secure.
* Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure
* pseudorandom number generator for use by security-sensitive applications. Note, however, that
- * {@code java.security.SecureRandom} does implement the {@link RandomGenerator} interface, so
- * that instances of {@code java.security.SecureRandom} may be used interchangeably with other types
- * of pseudorandom generators in applications that do not require a secure generator.
+ * {@code java.security.SecureRandom} does implement the {@link RandomGenerator} interface, so that
+ * instances of {@code java.security.SecureRandom} may be used interchangeably with other types of
+ * pseudorandom generators in applications that do not require a secure generator.
*
* @since 14
*/
@@ -144,13 +145,32 @@
private String name;
- Algorithm(String name) {
+ private Algorithm(String name) {
this.name = name;
}
public String toString() {
return name;
}
+
+ /**
+ * Returns an instance of {@link RandomGenerator} that utilizes this algorithm.
+ *
+ * @return An instance of {@link RandomGenerator}
+ */
+ public RandomGenerator instance() {
+ return RandomGeneratorFactory.of(name, RandomGenerator.class);
+ }
+
+ /**
+ * Returns a {@link RandomGeneratorFactory} that can produce instances
+ * of {@link RandomGenerator} that utilizes this algorithm.
+ *
+ * @return {@link RandomGeneratorFactory} of {@link RandomGenerator}
+ */
+ public RandomGeneratorFactory<RandomGenerator> factory() {
+ return RandomGeneratorFactory.factoryOf(name, RandomGenerator.class);
+ }
}
/**
@@ -185,7 +205,7 @@
*
* @param name Name of random number generator algorithm
*
- * @return Factory of {@link RandomGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link RandomGenerator}
*/
public static RandomGeneratorFactory<RandomGenerator> factoryOf(String name) {
Objects.requireNonNull(name);
@@ -198,7 +218,7 @@
*
* @param algorithm Random number generator algorithm
*
- * @return Factory of {@link RandomGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link RandomGenerator}
*/
public static RandomGeneratorFactory<RandomGenerator> factoryOf(Algorithm algorithm) {
Objects.requireNonNull(algorithm);
@@ -821,7 +841,7 @@
*
* @param name Name of random number generator algorithm
*
- * @return Factory of {@link StreamableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link StreamableGenerator}
*/
public static RandomGeneratorFactory<StreamableGenerator> factoryOf(String name) {
Objects.requireNonNull(name);
@@ -834,7 +854,7 @@
*
* @param algorithm Random number generator algorithm
*
- * @return Factory of {@link StreamableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link StreamableGenerator}
*/
public static RandomGeneratorFactory<StreamableGenerator> factoryOf(Algorithm algorithm) {
Objects.requireNonNull(algorithm);
@@ -948,7 +968,7 @@
*
* @param name Name of random number generator algorithm
*
- * @return Factory of {@link SplittableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link SplittableGenerator}
*/
public static RandomGeneratorFactory<SplittableGenerator> factoryOf(String name) {
Objects.requireNonNull(name);
@@ -961,7 +981,7 @@
*
* @param algorithm Random number generator algorithm
*
- * @return Factory of {@link SplittableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link SplittableGenerator}
*/
public static RandomGeneratorFactory<SplittableGenerator> factoryOf(Algorithm algorithm) {
Objects.requireNonNull(algorithm);
@@ -1097,36 +1117,38 @@
}
/**
- * This interface is designed to provide a common protocol for objects that generate pseudorandom
- * sequences of numbers (or Boolean values) and furthermore can easily <i>jump</i> forward (by a
- * fixed amount) to a distant point in the state cycle.
+ * This interface is designed to provide a common protocol for objects that generate
+ * pseudorandom sequences of numbers (or Boolean values) and furthermore can easily <i>jump</i>
+ * forward (by a fixed amount) to a distant point in the state cycle.
* <p>
- * Ideally, all {@link JumpableGenerator} objects produced by iterative jumping from a single original
- * {@link JumpableGenerator} object are statistically independent of one another and individually uniform.
- * In practice, one must settle for some approximation to independence and uniformity. In
- * particular, a specific implementation may assume that each generator in a stream produced by the
- * {@code jumps} method is used to produce a number of values no larger than either 2<sup>64</sup>
- * or the square root of its period. Implementors are advised to use algorithms whose period is at
- * least 2<sup>127</sup>.
+ * Ideally, all {@link JumpableGenerator} objects produced by iterative jumping from a single
+ * original {@link JumpableGenerator} object are statistically independent of one another and
+ * individually uniform. In practice, one must settle for some approximation to independence and
+ * uniformity. In particular, a specific implementation may assume that each generator in a
+ * stream produced by the {@code jumps} method is used to produce a number of values no larger
+ * than either 2<sup>64</sup> or the square root of its period. Implementors are advised to use
+ * algorithms whose period is at least 2<sup>127</sup>.
* <p>
* Methods are provided to perform a single jump operation and also to produce a stream of
* generators produced from the original by iterative copying and jumping of internal state. A
- * typical strategy for a multithreaded application is to create a single {@link JumpableGenerator}
- * object, calls its {@code jumps} method exactly once, and then parcel out generators from the
- * resulting stream, one to each thread. It is generally not a good idea to call {@code jump} on a
- * generator that was itself produced by the {@code jumps} method, because the result may be a
- * generator identical to another generator already produce by that call to the {@code jumps}
- * method. For this reason, the return type of the {@code jumps} method is {@code
- * Stream<RandomGenerator>} rather than {@code Stream<JumpableGenerator>}, even though the actual
- * generator objects in that stream likely do also implement the {@link JumpableGenerator} interface.
+ * typical strategy for a multithreaded application is to create a single {@link
+ * JumpableGenerator} object, calls its {@code jumps} method exactly once, and then parcel out
+ * generators from the resulting stream, one to each thread. It is generally not a good idea to
+ * call {@code jump} on a generator that was itself produced by the {@code jumps} method,
+ * because the result may be a generator identical to another generator already produce by that
+ * call to the {@code jumps} method. For this reason, the return type of the {@code jumps}
+ * method is {@code Stream<RandomGenerator>} rather than {@code Stream<JumpableGenerator>}, even
+ * though the actual generator objects in that stream likely do also implement the {@link
+ * JumpableGenerator} interface.
* <p>
- * An implementation of the {@link JumpableGenerator} interface must provide concrete definitions for the
- * methods {@code nextInt()}, {@code nextLong}, {@code period()}, {@code copy()}, {@code jump()},
- * and {@code defaultJumpDistance()}. Default implementations are provided for all other methods.
+ * An implementation of the {@link JumpableGenerator} interface must provide concrete
+ * definitions for the methods {@code nextInt()}, {@code nextLong}, {@code period()}, {@code
+ * copy()}, {@code jump()}, and {@code defaultJumpDistance()}. Default implementations are
+ * provided for all other methods.
* <p>
- * Objects that implement {@link JumpableGenerator} are typically not cryptographically secure. Consider
- * instead using {@link java.security.SecureRandom} to get a cryptographically secure pseudo-random
- * number generator for use by security-sensitive applications.
+ * Objects that implement {@link JumpableGenerator} are typically not cryptographically secure.
+ * Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure
+ * pseudo-random number generator for use by security-sensitive applications.
*
* @since 14
*/
@@ -1164,7 +1186,7 @@
*
* @param name Name of random number generator algorithm
*
- * @return Factory of {@link JumpableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link JumpableGenerator}
*/
public static RandomGeneratorFactory<JumpableGenerator> factoryOf(String name) {
Objects.requireNonNull(name);
@@ -1177,7 +1199,7 @@
*
* @param algorithm Random number generator algorithm
*
- * @return Factory of {@link JumpableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link JumpableGenerator}
*/
public static RandomGeneratorFactory<JumpableGenerator> factoryOf(Algorithm algorithm) {
Objects.requireNonNull(algorithm);
@@ -1282,40 +1304,43 @@
}
/**
- * This interface is designed to provide a common protocol for objects that generate sequences of
- * pseudorandom numbers (or Boolean values) and furthermore can easily not only jump but also
+ * This interface is designed to provide a common protocol for objects that generate sequences
+ * of pseudorandom numbers (or Boolean values) and furthermore can easily not only jump but
+ * also
* <i>leap</i> to a very distant point in the state cycle.
* <p>
- * Typically one will construct a series of {@link LeapableGenerator} objects by iterative leaping from a
- * single original {@link LeapableGenerator} object, and then for each such object produce a subseries of
- * objects by iterative jumping. There is little conceptual difference between leaping and jumping,
- * but typically a leap will be a very long jump in the state cycle (perhaps distance
- * 2<sup>128</sup> or so).
+ * Typically one will construct a series of {@link LeapableGenerator} objects by iterative
+ * leaping from a single original {@link LeapableGenerator} object, and then for each such
+ * object produce a subseries of objects by iterative jumping. There is little conceptual
+ * difference between leaping and jumping, but typically a leap will be a very long jump in the
+ * state cycle (perhaps distance 2<sup>128</sup> or so).
* <p>
- * Ideally, all {@link LeapableGenerator} objects produced by iterative leaping and jumping from a single
- * original {@link LeapableGenerator} object are statistically independent of one another and individually
- * uniform. In practice, one must settle for some approximation to independence and uniformity. In
- * particular, a specific implementation may assume that each generator in a stream produced by the
- * {@code leaps} method is used to produce (by jumping) a number of objects no larger than
- * 2<sup>64</sup>. Implementors are advised to use algorithms whose period is at least
- * 2<sup>191</sup>.
+ * Ideally, all {@link LeapableGenerator} objects produced by iterative leaping and jumping from
+ * a single original {@link LeapableGenerator} object are statistically independent of one
+ * another and individually uniform. In practice, one must settle for some approximation to
+ * independence and uniformity. In particular, a specific implementation may assume that each
+ * generator in a stream produced by the {@code leaps} method is used to produce (by jumping) a
+ * number of objects no larger than 2<sup>64</sup>. Implementors are advised to use algorithms
+ * whose period is at least 2<sup>191</sup>.
* <p>
* Methods are provided to perform a single leap operation and also to produce a stream of
- * generators produced from the original by iterative copying and leaping of internal state. The
- * generators produced must implement the {@link JumpableGenerator} interface but need not also implement
- * the {@link LeapableGenerator} interface. A typical strategy for a multithreaded application is to
- * create a single {@link LeapableGenerator} object, calls its {@code leaps} method exactly once, and then
- * parcel out generators from the resulting stream, one to each thread. Then the {@code jumps}
- * method of each such generator be called to produce a substream of generator objects.
+ * generators produced from the original by iterative copying and leaping of internal state.
+ * The generators produced must implement the {@link JumpableGenerator} interface but need not
+ * also implement the {@link LeapableGenerator} interface. A typical strategy for a
+ * multithreaded application is to create a single {@link LeapableGenerator} object, calls its
+ * {@code leaps} method exactly once, and then parcel out generators from the resulting stream,
+ * one to each thread. Then the {@code jumps} method of each such generator be called to
+ * produce a substream of generator objects.
* <p>
- * An implementation of the {@link LeapableGenerator} interface must provide concrete definitions for the
- * methods {@code nextInt()}, {@code nextLong}, {@code period()}, {@code copy()}, {@code jump()},
- * {@code defaultJumpDistance()}, {@code leap()}, and {@code defaultLeapDistance()}. Default
- * implementations are provided for all other methods.
+ * An implementation of the {@link LeapableGenerator} interface must provide concrete
+ * definitions for the methods {@code nextInt()}, {@code nextLong}, {@code period()},
+ * {@code copy()}, {@code jump()}, {@code defaultJumpDistance()}, {@code leap()},
+ * and {@code defaultLeapDistance()}. Default implementations are provided for all other
+ * methods.
* <p>
- * Objects that implement {@link LeapableGenerator} are typically not cryptographically secure. Consider
- * instead using {@link java.security.SecureRandom} to get a cryptographically secure pseudo-random
- * number generator for use by security-sensitive applications.
+ * Objects that implement {@link LeapableGenerator} are typically not cryptographically secure.
+ * Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure
+ * pseudo-random number generator for use by security-sensitive applications.
*
* @since 14
*/
@@ -1353,7 +1378,7 @@
*
* @param name Name of random number generator algorithm
*
- * @return Factory of {@link LeapableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link LeapableGenerator}
*/
public static RandomGeneratorFactory<LeapableGenerator> factoryOf(String name) {
Objects.requireNonNull(name);
@@ -1366,7 +1391,7 @@
*
* @param algorithm Random number generator algorithm
*
- * @return Factory of {@link LeapableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link LeapableGenerator}
*/
public static RandomGeneratorFactory<LeapableGenerator> factoryOf(Algorithm algorithm) {
Objects.requireNonNull(algorithm);
@@ -1442,42 +1467,45 @@
}
/**
- * This interface is designed to provide a common protocol for objects that generate sequences of
- * pseudorandom numbers (or Boolean values) and furthermore can easily <i>jump</i> to an arbitrarily
- * specified distant point in the state cycle.
+ * This interface is designed to provide a common protocol for objects that generate sequences
+ * of pseudorandom numbers (or Boolean values) and furthermore can easily <i>jump</i> to an
+ * arbitrarily specified distant point in the state cycle.
* <p>
- * Ideally, all {@link ArbitrarilyJumpableGenerator} objects produced by iterative jumping from a single
- * original {@link ArbitrarilyJumpableGenerator} object are statistically independent of one another and
- * individually uniform, provided that they do not traverse overlapping portions of the state cycle.
- * In practice, one must settle for some approximation to independence and uniformity. In
- * particular, a specific implementation may assume that each generator in a stream produced by the
- * {@code jumps} method is used to produce a number of values no larger than the jump distance
- * specified. Implementors are advised to use algorithms whose period is at least 2<sup>127</sup>.
+ * Ideally, all {@link ArbitrarilyJumpableGenerator} objects produced by iterative jumping from
+ * a single original {@link ArbitrarilyJumpableGenerator} object are statistically independent
+ * of one another and individually uniform, provided that they do not traverse overlapping
+ * portions of the state cycle. In practice, one must settle for some approximation to
+ * independence and uniformity. In particular, a specific implementation may assume that each
+ * generator in a stream produced by the {@code jumps} method is used to produce a number of
+ * values no larger than the jump distance specified. Implementors are advised to use
+ * algorithms whose period is at least 2<sup>127</sup>.
* <p>
- * For many applications, it suffices to jump forward by a power of two or some small multiple of a
- * power of two, but this power of two may not be representable as a {@code long} value. To avoid
- * the use of {@link java.math.BigInteger} values as jump distances, {@code double} values are used
- * instead.
+ * For many applications, it suffices to jump forward by a power of two or some small multiple
+ * of a power of two, but this power of two may not be representable as a {@code long} value.
+ * To avoid the use of {@link java.math.BigInteger} values as jump distances, {@code double}
+ * values are used instead.
* <p>
* Methods are provided to perform a single jump operation and also to produce a stream of
* generators produced from the original by iterative copying and jumping of internal state. A
- * typical strategy for a multithreaded application is to create a single {@link
- * ArbitrarilyJumpableGenerator} object, call its {@code jumps} method exactly once, and then parcel out
- * generators from the resulting stream, one to each thread. However, each generator produced also
- * has type {@link ArbitrarilyJumpableGenerator}; with care, different jump distances can be used to
- * traverse the entire state cycle in various ways.
+ * typical strategy for a multithreaded application is to create a single
+ * {@link ArbitrarilyJumpableGenerator} object, call its {@code jumps} method exactly once, and
+ * then parcel out generators from the resulting stream, one to each thread. However, each
+ * generator produced also has type {@link ArbitrarilyJumpableGenerator}; with care, different
+ * jump distances can be used to traverse the entire state cycle in various ways.
* <p>
* An implementation of the {@link ArbitrarilyJumpableGenerator} interface must provide concrete
- * definitions for the methods {@code nextInt()}, {@code nextLong}, {@code period()}, {@code
- * copy()}, {@code jump(double)}, {@code defaultJumpDistance()}, and {@code defaultLeapDistance()}.
- * Default implementations are provided for all other methods. Perhaps the most convenient way to
- * implement this interface is to extend the abstract class {@link ArbitrarilyJumpableGenerator}, which
- * provides spliterator-based implementations of the methods {@code ints}, {@code longs}, {@code
- * doubles}, {@code rngs}, {@code jumps}, and {@code leaps}.
+ * definitions for the methods {@code nextInt()}, {@code nextLong}, {@code period()},
+ * {@code copy()}, {@code jump(double)}, {@code defaultJumpDistance()}, and
+ * {@code defaultLeapDistance()}. Default implementations are provided for all other methods.
+ * Perhaps the most convenient way to implement this interface is to extend the abstract class
+ * {@link ArbitrarilyJumpableGenerator}, which provides spliterator-based implementations of the
+ * methods {@code ints}, {@code longs}, {@code doubles}, {@code rngs}, {@code jumps}, and
+ * {@code leaps}.
* <p>
- * Objects that implement {@link ArbitrarilyJumpableGenerator} are typically not cryptographically secure.
- * Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure
- * pseudo-random number generator for use by security-sensitive applications.
+ * Objects that implement {@link ArbitrarilyJumpableGenerator} are typically not
+ * cryptographically secure. Consider instead using {@link java.security.SecureRandom} to get a
+ * cryptographically secure pseudo-random number generator for use by security-sensitive
+ * applications.
*
* @since 14
*/
@@ -1515,7 +1543,7 @@
*
* @param name Name of random number generator algorithm
*
- * @return Factory of {@link ArbitrarilyJumpableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link ArbitrarilyJumpableGenerator}
*/
public static RandomGeneratorFactory<ArbitrarilyJumpableGenerator> factoryOf(String name) {
Objects.requireNonNull(name);
@@ -1528,7 +1556,7 @@
*
* @param algorithm Random number generator algorithm
*
- * @return Factory of {@link ArbitrarilyJumpableGenerator}
+ * @return {@link RandomGeneratorFactory} of {@link ArbitrarilyJumpableGenerator}
*/
public static RandomGeneratorFactory<ArbitrarilyJumpableGenerator> factoryOf(Algorithm algorithm) {
Objects.requireNonNull(algorithm);
@@ -1575,9 +1603,9 @@
default void jump() { jump(defaultJumpDistance()); }
/**
- * Returns an effectively unlimited stream of new pseudorandom number generators, each of which
- * implements the {@link ArbitrarilyJumpableGenerator} interface, produced by jumping copies of this
- * generator by different integer multiples of the specified jump distance.
+ * Returns an effectively unlimited stream of new pseudorandom number generators, each of
+ * which implements the {@link ArbitrarilyJumpableGenerator} interface, produced by jumping
+ * copies of this generator by different integer multiples of the specified jump distance.
*
* @param distance a distance to jump forward within the state cycle
*
@@ -1591,9 +1619,9 @@
/**
* Returns a stream producing the given {@code streamSize} number of new pseudorandom number
- * generators, each of which implements the {@link ArbitrarilyJumpableGenerator} interface, produced
- * by jumping copies of this generator by different integer multiples of the specified jump
- * distance.
+ * generators, each of which implements the {@link ArbitrarilyJumpableGenerator} interface,
+ * produced by jumping copies of this generator by different integer multiples of the
+ * specified jump distance.
*
* @param streamSize the number of generators to generate
* @param distance a distance to jump forward within the state cycle
@@ -1608,8 +1636,8 @@
/**
* Alter the state of this pseudorandom number generator so as to jump forward a very large,
- * fixed distance (typically 2<sup>128</sup> or more) within its state cycle. The distance used
- * is that returned by method {@code defaultJLeapDistance()}.
+ * fixed distance (typically 2<sup>128</sup> or more) within its state cycle. The distance
+ * used is that returned by method {@code defaultJLeapDistance()}.
*/
default void leap() { jump(defaultLeapDistance()); }
--- a/src/java.base/share/classes/java/util/random/RandomSupport.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/RandomSupport.java Thu Aug 08 11:06:54 2019 -0300
@@ -931,7 +931,8 @@
long UA = rng.nextLong();
int j = (int)UA & DoubleZigguratTables.exponentialAliasMask;
if (UA >= DoubleZigguratTables.exponentialAliasThreshold[j]) {
- j = DoubleZigguratTables.exponentialAliasMap[j] & DoubleZigguratTables.exponentialSignCorrectionMask;
+ j = DoubleZigguratTables.exponentialAliasMap[j] &
+ DoubleZigguratTables.exponentialSignCorrectionMask;
}
if (j > 0) { // Sample overhang j
// For the exponential distribution, every overhang is convex.
@@ -944,8 +945,8 @@
// Does the point lie below the curve?
long Udiff = U2 - U1;
if (Udiff < 0) {
- // We picked a point in the upper-right triangle. None of those can be accepted.
- // So remap the point into the lower-left triangle and try that.
+ // We picked a point in the upper-right triangle. None of those can be
+ // accepted. So remap the point into the lower-left triangle and try that.
// In effect, we swap U1 and U2, and invert the sign of Udiff.
Udiff = -Udiff;
U2 = U1;
@@ -1079,7 +1080,7 @@
// Compute the actual y-coordinate of the randomly chosen point.
double y = (Y[j] * 0x1.0p63) + ((Y[j] - Y[j-1]) * (double)U2);
// Now see how that y-coordinate compares to the curve
- if (y <= Math.exp(-0.5*x*x)) break; // The chosen point is below the curve; accept it.
+ if (y <= Math.exp(-0.5*x*x)) break; // The chosen point is below the curve; accept it.
// Otherwise, we reject this sample and have to try again.
}
} else {
--- a/src/java.base/share/classes/java/util/random/Xoshiro256StarStar.java Wed Aug 07 15:35:55 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/Xoshiro256StarStar.java Thu Aug 08 11:06:54 2019 -0300
@@ -235,7 +235,15 @@
public long nextLong() {
final long z = x0;
long q0 = x0, q1 = x1, q2 = x2, q3 = x3;
- { long t = q1 << 17; q2 ^= q0; q3 ^= q1; q1 ^= q2; q0 ^= q3; q2 ^= t; q3 = Long.rotateLeft(q3, 45); } // xoshiro256 1.0
+ { // xoshiro256 1.0
+ long t = q1 << 17;
+ q2 ^= q0;
+ q3 ^= q1;
+ q1 ^= q2;
+ q0 ^= q3;
+ q2 ^= t;
+ q3 = Long.rotateLeft(q3, 45);
+ }
x0 = q0; x1 = q1; x2 = q2; x3 = q3;
return Long.rotateLeft(z * 5, 7) * 9; // "starstar" mixing function
}