jdk-sandbox: comparison src/java.base/share/classes/java/util/random/Xoshiro256StarStar.java

equal deleted inserted replaced

-:b0c958c0e6c6
+:f02ffcb61dce
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
-package java.util;
+package java.util.random;
 import java.math.BigInteger;
 import java.util.concurrent.atomic.AtomicLong;
 /**
 * A generator of uniform pseudorandom values applicable for use in
 * (among other contexts) isolated parallel computations that may
-* generate subtasks.  Class {@code Xoshiro256StarStar} implements
+* generate subtasks.  Class {@link Xoshiro256StarStar} implements
-* interfaces {@link java.util.Rng} and {@link java.util.LeapableRng},
+* interfaces {@link RandomNumberGenerator} and {@link LeapableRNG},
 * and therefore supports methods for producing pseudorandomly chosen
 * numbers of type {@code int}, {@code long}, {@code float}, and {@code double}
-* as well as creating new {@code Xoshiro256StarStar} objects
+* as well as creating new {@link Xoshiro256StarStar} objects
 * by "jumping" or "leaping".
-*
+* <p>
-* <p>Series of generated values pass the TestU01 BigCrush and PractRand test suites
+* Series of generated values pass the TestU01 BigCrush and PractRand test suites
 * that measure independence and uniformity properties of random number generators.
 * (Most recently validated with
 * <a href="http://simul.iro.umontreal.ca/testu01/tu01.html">version 1.2.3 of TestU01</a>
 * and <a href="http://pracrand.sourceforge.net">version 0.90 of PractRand</a>.
 * Note that TestU01 BigCrush was used to test not only values produced by the {@code nextLong()}
 * method but also the result of bit-reversing each value produced by {@code nextLong()}.)
 * These tests validate only the methods for certain
 * types and ranges, but similar properties are expected to hold, at
 * least approximately, for others as well.
-*
+* <p>
-* <p>The class {@code Xoshiro256StarStar} uses the {@code xoshiro256} algorithm,
+* The class {@link Xoshiro256StarStar} uses the {@code xoshiro256} algorithm,
 * version 1.0 (parameters 17, 45), with the "**" scrambler (a mixing function).
 * Its state consists of four {@code long} fields {@code x0}, {@code x1}, {@code x2},
 * and {@code x3}, which can take on any values provided that they are not all zero.
 * The period of this generator is 2<sup>256</sup>-1.
-*
+* <p>
-* <p>The 64-bit values produced by the {@code nextLong()} method are equidistributed.
+* The 64-bit values produced by the {@code nextLong()} method are equidistributed.
 * To be precise, over the course of the cycle of length 2<sup>256</sup>-1,
 * each nonzero {@code long} value is generated 2<sup>192</sup> times,
 * but the value 0 is generated only 2<sup>192</sup>-1 times.
 * The values produced by the {@code nextInt()}, {@code nextFloat()}, and {@code nextDouble()}
 * methods are likewise equidistributed.
-*
+* <p>
-* <p>In fact, the 64-bit values produced by the {@code nextLong()} method are 4-equidistributed.
+* In fact, the 64-bit values produced by the {@code nextLong()} method are 4-equidistributed.
 * To be precise: consider the (overlapping) length-4 subsequences of the cycle of 64-bit
 * values produced by {@code nextLong()} (assuming no other methods are called that would
 * affect the state).  There are 2<sup>256</sup>-1 such subsequences, and each subsequence,
 * which consists of 4 64-bit values, can have one of 2<sup>256</sup> values.  Of those
 * 2<sup>256</sup> subsequence values, each one is generated exactly once over the course
 * of the entire cycle, except that the subsequence (0, 0, 0, 0) never appears.
 * The values produced by the {@code nextInt()}, {@code nextFloat()}, and {@code nextDouble()}
 * methods are likewise 4-equidistributed, but note that that the subsequence (0, 0, 0, 0)
 * can also appear (but occurring somewhat less frequently than all other subsequences),
 * because the values produced by those methods have fewer than 64 randomly chosen bits.
-*
+* <p>
-* <p>Instances {@code Xoshiro256StarStar} are <em>not</em> thread-safe.
+* Instances {@link Xoshiro256StarStar} are <em>not</em> thread-safe.
 * They are designed to be used so that each thread as its own instance.
 * The methods {@link #jump} and {@link #leap} and {@link #jumps} and {@link #leaps}
-* can be used to construct new instances of {@code Xoshiro256StarStar} that traverse
+* can be used to construct new instances of {@link Xoshiro256StarStar} that traverse
 * other parts of the state cycle.
-*
+* <p>
-* <p>Instances of {@code Xoshiro256StarStar} are not cryptographically
+* Instances of {@link Xoshiro256StarStar} are not cryptographically
 * secure.  Consider instead using {@link java.security.SecureRandom}
 * in security-sensitive applications. Additionally,
 * default-constructed instances do not use a cryptographically random
 * seed unless the {@linkplain System#getProperty system property}
 * {@code java.util.secureRandomSeed} is set to {@code true}.
 *
-* @author  Guy Steele
+* @since 14
-* @since   1.9
 */
-public final class Xoshiro256StarStar implements LeapableRng {
+public final class Xoshiro256StarStar implements LeapableRNG {
 /*
 * Implementation Overview.
 *
 * This is an implementation of the xoroshiro128** algorithm written
 /* ---------------- static fields ---------------- */
 /**
 * The seed generator for default constructors.
 */
-private static final AtomicLong defaultGen = new AtomicLong(RngSupport.initialSeed());
+private static final AtomicLong DEFAULT_GEN = new AtomicLong(RNGSupport.initialSeed());
 /*
 * The period of this generator, which is 2**256 - 1.
 */
-private static final BigInteger thePeriod =
+private static final BigInteger PERIOD =
-	BigInteger.ONE.shiftLeft(256).subtract(BigInteger.ONE);
+BigInteger.ONE.shiftLeft(256).subtract(BigInteger.ONE);
 /* ---------------- instance fields ---------------- */
 /**
 * The per-instance state.
 * @param x1 second word of the initial state
 * @param x2 third word of the initial state
 * @param x3 fourth word of the initial state
 */
 public Xoshiro256StarStar(long x0, long x1, long x2, long x3) {
-	this.x0 = x0;
-this.x1 = x1;
-this.x2 = x2;
-this.x3 = x3;
-	// If x0, x1, x2, and x3 are all zero, we must choose nonzero values.
-if ((x0 | x1 | x2 | x3) == 0) {
-	    // At least three of the four values generated here will be nonzero.
-	    this.x0 = RngSupport.mixStafford13(x0 += RngSupport.GOLDEN_RATIO_64);
-	    this.x1 = (x0 += RngSupport.GOLDEN_RATIO_64);
-	    this.x2 = (x0 += RngSupport.GOLDEN_RATIO_64);
-	    this.x3 = (x0 += RngSupport.GOLDEN_RATIO_64);
-	}
-}
-/**
-* Creates a new instance of {@code Xoshiro256StarStar} using the
-* specified {@code long} value as the initial seed. Instances of
-* {@code Xoshiro256StarStar} created with the same seed in the same
-* program generate identical sequences of values.
-*
-* @param seed the initial seed
-*/
-public Xoshiro256StarStar(long seed) {
-	// Using a value with irregularly spaced 1-bits to xor the seed
-	// argument tends to improve "pedestrian" seeds such as 0 or
-	// other small integers.  We may as well use SILVER_RATIO_64.
-	//
-	// The x values are then filled in as if by a SplitMix PRNG with
-	// GOLDEN_RATIO_64 as the gamma value and Stafford13 as the mixer.
-this(RngSupport.mixStafford13(seed ^= RngSupport.SILVER_RATIO_64),
-	     RngSupport.mixStafford13(seed += RngSupport.GOLDEN_RATIO_64),
-	     RngSupport.mixStafford13(seed += RngSupport.GOLDEN_RATIO_64),
-	     RngSupport.mixStafford13(seed + RngSupport.GOLDEN_RATIO_64));
-}
-/**
-* Creates a new instance of {@code Xoshiro256StarStar} that is likely to
-* generate sequences of values that are statistically independent
-* of those of any other instances in the current program execution,
-* but may, and typically does, vary across program invocations.
-*/
-public Xoshiro256StarStar() {
-	// Using GOLDEN_RATIO_64 here gives us a good Weyl sequence of values.
-this(defaultGen.getAndAdd(RngSupport.GOLDEN_RATIO_64));
-}
-/**
-* Creates a new instance of {@code Xoshiro256StarStar} using the specified array of
-* initial seed bytes. Instances of {@code Xoshiro256StarStar} created with the same
-* seed array in the same program execution generate identical sequences of values.
-*
-* @param seed the initial seed
-*/
-public Xoshiro256StarStar(byte[] seed) {
-	// Convert the seed to 4 long values, which are not all zero.
-	long[] data = RngSupport.convertSeedBytesToLongs(seed, 4, 4);
-	long x0 = data[0], x1 = data[1], x2 = data[2], x3 = data[3];
 this.x0 = x0;
 this.x1 = x1;
 this.x2 = x2;
 this.x3 = x3;
+// If x0, x1, x2, and x3 are all zero, we must choose nonzero values.
+if ((x0 | x1 | x2 | x3) == 0) {
+// At least three of the four values generated here will be nonzero.
+this.x0 = RNGSupport.mixStafford13(x0 += RNGSupport.GOLDEN_RATIO_64);
+this.x1 = (x0 += RNGSupport.GOLDEN_RATIO_64);
+this.x2 = (x0 += RNGSupport.GOLDEN_RATIO_64);
+this.x3 = (x0 += RNGSupport.GOLDEN_RATIO_64);
+}
+}
+/**
+* Creates a new instance of {@link Xoshiro256StarStar} using the
+* specified {@code long} value as the initial seed. Instances of
+* {@link Xoshiro256StarStar} created with the same seed in the same
+* program generate identical sequences of values.
+*
+* @param seed the initial seed
+*/
+public Xoshiro256StarStar(long seed) {
+// Using a value with irregularly spaced 1-bits to xor the seed
+// argument tends to improve "pedestrian" seeds such as 0 or
+// other small integers.  We may as well use SILVER_RATIO_64.
+//
+// The x values are then filled in as if by a SplitMix PRNG with
+// GOLDEN_RATIO_64 as the gamma value and Stafford13 as the mixer.
+this(RNGSupport.mixStafford13(seed ^= RNGSupport.SILVER_RATIO_64),
+RNGSupport.mixStafford13(seed += RNGSupport.GOLDEN_RATIO_64),
+RNGSupport.mixStafford13(seed += RNGSupport.GOLDEN_RATIO_64),
+RNGSupport.mixStafford13(seed + RNGSupport.GOLDEN_RATIO_64));
+}
+/**
+* Creates a new instance of {@link Xoshiro256StarStar} that is likely to
+* generate sequences of values that are statistically independent
+* of those of any other instances in the current program execution,
+* but may, and typically does, vary across program invocations.
+*/
+public Xoshiro256StarStar() {
+// Using GOLDEN_RATIO_64 here gives us a good Weyl sequence of values.
+this(DEFAULT_GEN.getAndAdd(RNGSupport.GOLDEN_RATIO_64));
+}
+/**
+* Creates a new instance of {@link Xoshiro256StarStar} using the specified array of
+* initial seed bytes. Instances of {@link Xoshiro256StarStar} created with the same
+* seed array in the same program execution generate identical sequences of values.
+*
+* @param seed the initial seed
+*/
+public Xoshiro256StarStar(byte[] seed) {
+// Convert the seed to 4 long values, which are not all zero.
+long[] data = RNGSupport.convertSeedBytesToLongs(seed, 4, 4);
+long x0 = data[0], x1 = data[1], x2 = data[2], x3 = data[3];
+this.x0 = x0;
+this.x1 = x1;
+this.x2 = x2;
+this.x3 = x3;
 }
 /* ---------------- public methods ---------------- */
-public Xoshiro256StarStar copy() { return new Xoshiro256StarStar(x0, x1, x2, x3); }
+public Xoshiro256StarStar copy() {
+return new Xoshiro256StarStar(x0, x1, x2, x3);
+}
 /**
 * Returns a pseudorandom {@code long} value.
 *
 * @return a pseudorandom {@code long} value
 */
+public long nextLong() {
-public long nextLong() {
+final long z = x0;
-	final long z = x0;
+long q0 = x0, q1 = x1, q2 = x2, q3 = x3;
-	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
-	{ long t = q1 << 17; q2 ^= q0; q3 ^= q1; q1 ^= q2; q0 ^= q3; q2 ^= t; q3 = Long.rotateLeft(q3, 45); }  // xoshiro256 1.0
+x0 = q0; x1 = q1; x2 = q2; x3 = q3;
-	x0 = q0; x1 = q1; x2 = q2; x3 = q3;
+return Long.rotateLeft(z * 5, 7) * 9;  // "starstar" mixing function
-	return Long.rotateLeft(z * 5, 7) * 9;  // "starstar" mixing function
+}
-}
+public BigInteger period() {
-public BigInteger period() { return thePeriod; }
+return PERIOD;
+}
-public double defaultJumpDistance() { return 0x1.0p64; }
+public double defaultJumpDistance() {
-public double defaultLeapDistance() { return 0x1.0p96; }
+return 0x1.0p64;
+}
+public double defaultLeapDistance() {
+return 0x1.0p96;
+}
 private static final long[] JUMP_TABLE = {
-	0x180ec6d33cfd0abaL, 0xd5a61266f0c9392cL, 0xa9582618e03fc9aaL, 0x39abdc4529b1661cL };
+0x180ec6d33cfd0abaL, 0xd5a61266f0c9392cL, 0xa9582618e03fc9aaL, 0x39abdc4529b1661cL };
 private static final long[] LEAP_TABLE = {
-	0x76e15d3efefdcbbfL, 0xc5004e441c522fb3L, 0x77710069854ee241L, 0x39109bb02acbe635L };
+0x76e15d3efefdcbbfL, 0xc5004e441c522fb3L, 0x77710069854ee241L, 0x39109bb02acbe635L };
-/* This is the jump function for the generator. It is equivalent
+/**
-to 2**128 calls to next(); it can be used to generate 2**128
+* This is the jump function for the generator. It is equivalent to 2**128 calls to next(); it
-non-overlapping subsequences for parallel computations. */
+* can be used to generate 2**128 non-overlapping subsequences for parallel computations.
+*/
-public void jump() { jumpAlgorithm(JUMP_TABLE); }
+public void jump() {
+jumpAlgorithm(JUMP_TABLE);
-/* This is the long-jump function for the generator. It is equivalent to
+}
-2**192 calls to next(); it can be used to generate 2**64 starting points,
-from each of which jump() will generate 2**64 non-overlapping
+/**
-subsequences for parallel distributed computations. */
+* This is the long-jump function for the generator. It is equivalent to 2**192 calls to next();
+* it can be used to generate 2**64 starting points, from each of which jump() will generate
-public void leap() { jumpAlgorithm(LEAP_TABLE); }
+* 2**64 non-overlapping subsequences for parallel distributed computations.
+*/
+public void leap() {
+jumpAlgorithm(LEAP_TABLE);
+}
 private void jumpAlgorithm(long[] table) {
-	long s0 = 0, s1 = 0, s2 = 0, s3 = 0;
+long s0 = 0, s1 = 0, s2 = 0, s3 = 0;
-	for (int i = 0; i < table.length; i++) {
+for (int i = 0; i < table.length; i++) {
-	    for (int b = 0; b < 64; b++) {
+for (int b = 0; b < 64; b++) {
-		if ((table[i] & (1L << b)) != 0) {
+if ((table[i] & (1L << b)) != 0) {
-		    s0 ^= x0;
+s0 ^= x0;
-		    s1 ^= x1;
+s1 ^= x1;
-		    s2 ^= x2;
+s2 ^= x2;
-		    s3 ^= x3;
+s3 ^= x3;
-		}
+}
-		nextLong();
+nextLong();
-	    }
+}
-	    x0 = s0;
+x0 = s0;
-	    x1 = s1;
+x1 = s1;
-	    x2 = s2;
+x2 = s2;
-	    x3 = s3;
+x3 = s3;
-	}
+}
 }
 }

branch	JDK-8193209-branch
changeset 57437	f02ffcb61dce
parent 57436	b0c958c0e6c6
child 57547	56cbdc3ea079