--- jsr166/src/main/java/util/SplittableRandom.java 2013/07/25 13:19:09 1.13 +++ jsr166/src/main/java/util/SplittableRandom.java 2016/11/13 03:36:50 1.36 @@ -25,21 +25,19 @@ package java.util; -import java.security.SecureRandom; import java.util.concurrent.atomic.AtomicLong; -import java.util.Spliterator; +import java.util.function.DoubleConsumer; import java.util.function.IntConsumer; import java.util.function.LongConsumer; -import java.util.function.DoubleConsumer; -import java.util.stream.StreamSupport; +import java.util.stream.DoubleStream; import java.util.stream.IntStream; import java.util.stream.LongStream; -import java.util.stream.DoubleStream; +import java.util.stream.StreamSupport; /** * A generator of uniform pseudorandom values applicable for use in * (among other contexts) isolated parallel computations that may - * generate subtasks. Class SplittableRandom supports methods for + * generate subtasks. Class {@code SplittableRandom} supports methods for * producing pseudorandom numbers of type {@code int}, {@code long}, * and {@code double} with similar usages as for class * {@link java.util.Random} but differs in the following ways: @@ -54,15 +52,15 @@ import java.util.stream.DoubleStream; * types and ranges, but similar properties are expected to hold, at * least approximately, for others as well. The period * (length of any series of generated values before it repeats) is at - * least 264. + * least 264. * - *
  • Method {@link #split} constructs and returns a new + *
  • Method {@link #split} constructs and returns a new * SplittableRandom instance that shares no mutable state with the * current instance. However, with very high probability, the * values collectively generated by the two objects have the same * statistical properties as if the same quantity of values were * generated by a single thread using a single {@code - * SplittableRandom} object.
    • + * SplittableRandom} object. * *
  • Instances of SplittableRandom are not thread-safe. * They are designed to be split, not shared, across threads. For @@ -73,25 +71,22 @@ import java.util.stream.DoubleStream; * *
  • This class provides additional methods for generating random * streams, that employ the above techniques when used in {@code - * stream.parallel()} mode.
    • + * stream.parallel()} mode. * * * + *

    Instances of {@code SplittableRandom} 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 * @author Doug Lea * @since 1.8 */ -public class SplittableRandom { - - /* - * File organization: First the non-public methods that constitute - * the main algorithm, then the main public methods, followed by - * some custom spliterator classes needed for stream methods. - * - * Credits: Primary algorithm and code by Guy Steele. Stream - * support methods by Doug Lea. Documentation jointly produced - * with additional help from Brian Goetz. - */ +public final class SplittableRandom { /* * Implementation Overview. @@ -99,228 +94,156 @@ public class SplittableRandom { * This algorithm was inspired by the "DotMix" algorithm by * Leiserson, Schardl, and Sukha "Deterministic Parallel * Random-Number Generation for Dynamic-Multithreading Platforms", - * PPoPP 2012, but improves and extends it in several ways. + * PPoPP 2012, as well as those in "Parallel random numbers: as + * easy as 1, 2, 3" by Salmon, Morae, Dror, and Shaw, SC 2011. It + * differs mainly in simplifying and cheapening operations. + * + * The primary update step (method nextSeed()) is to add a + * constant ("gamma") to the current (64 bit) seed, forming a + * simple sequence. The seed and the gamma values for any two + * SplittableRandom instances are highly likely to be different. + * + * Methods nextLong, nextInt, and derivatives do not return the + * sequence (seed) values, but instead a hash-like bit-mix of + * their bits, producing more independently distributed sequences. + * For nextLong, the mix64 function is based on David Stafford's + * (http://zimbry.blogspot.com/2011/09/better-bit-mixing-improving-on.html) + * "Mix13" variant of the "64-bit finalizer" function in Austin + * Appleby's MurmurHash3 algorithm (see + * http://code.google.com/p/smhasher/wiki/MurmurHash3). The mix32 + * function is based on Stafford's Mix04 mix function, but returns + * the upper 32 bits cast as int. + * + * The split operation uses the current generator to form the seed + * and gamma for another SplittableRandom. To conservatively + * avoid potential correlations between seed and value generation, + * gamma selection (method mixGamma) uses different + * (Murmurhash3's) mix constants. To avoid potential weaknesses + * in bit-mixing transformations, we restrict gammas to odd values + * with at least 24 0-1 or 1-0 bit transitions. Rather than + * rejecting candidates with too few or too many bits set, method + * mixGamma flips some bits (which has the effect of mapping at + * most 4 to any given gamma value). This reduces the effective + * set of 64bit odd gamma values by about 2%, and serves as an + * automated screening for sequence constant selection that is + * left as an empirical decision in some other hashing and crypto + * algorithms. + * + * The resulting generator thus transforms a sequence in which + * (typically) many bits change on each step, with an inexpensive + * mixer with good (but less than cryptographically secure) + * avalanching. + * + * The default (no-argument) constructor, in essence, invokes + * split() for a common "defaultGen" SplittableRandom. Unlike + * other cases, this split must be performed in a thread-safe + * manner, so we use an AtomicLong to represent the seed rather + * than use an explicit SplittableRandom. To bootstrap the + * defaultGen, we start off using a seed based on current time + * unless the java.util.secureRandomSeed property is set. This + * serves as a slimmed-down (and insecure) variant of SecureRandom + * that also avoids stalls that may occur when using /dev/random. + * + * It is a relatively simple matter to apply the basic design here + * to use 128 bit seeds. However, emulating 128bit arithmetic and + * carrying around twice the state add more overhead than appears + * warranted for current usages. * - * The primary update step (see method nextSeed()) is simply to - * add a constant ("gamma") to the current seed, modulo a prime - * ("George"). However, the nextLong and nextInt methods do not - * return this value, but instead the results of bit-mixing - * transformations that produce more uniformly distributed - * sequences. - * - * "George" is the otherwise nameless (because it cannot be - * represented) prime number 2^64+13. Using a prime number larger - * than can fit in a long ensures that all possible long values - * can occur, plus 13 others that just get skipped over when they - * are encountered; see method addGammaModGeorge. For this to - * work, initial gamma values must be at least 13. - * - * The mix64 bit-mixing function called by nextLong and other - * methods computes the same value as the "64-bit finalizer" - * function in Austin Appleby's MurmurHash3 algorithm. See - * http://code.google.com/p/smhasher/wiki/MurmurHash3 , which - * comments: "The constants for the finalizers were generated by a - * simple simulated-annealing algorithm, and both avalanche all - * bits of 'h' to within 0.25% bias." - * - * The value of gamma differs for each instance across a series of - * splits, and is generated using an independent variant of the - * same algorithm, but operating across calls to split(), not - * calls to nextSeed(): Each instance carries the state of this - * generator as nextSplit. Gammas are treated as 57bit values, - * advancing by adding GAMMA_GAMMA mod GAMMA_PRIME, and bit-mixed - * with a 57-bit version of mix, using the "Mix01" multiplicative - * constants for MurmurHash3 described by David Stafford - * (http://zimbry.blogspot.com/2011/09/better-bit-mixing-improving-on.html). - * The value of GAMMA_GAMMA is arbitrary (except must be at least - * 13 and less than GAMMA_PRIME), but because it serves as the - * base of split sequences, should be subject to validation of - * consequent random number quality metrics. - * - * The mix32 function used for nextInt just consists of two of the - * five lines of mix64; avalanche testing shows that the 64-bit - * result has its top 32 bits avalanched well, though not the - * bottom 32 bits. DieHarder tests show that it is adequate for - * generating one random int from the 64-bit result of nextSeed. - * - * Support for the default (no-argument) constructor relies on an - * AtomicLong (defaultSeedGenerator) to help perform the - * equivalent of a split of a statically constructed - * SplittableRandom. Unlike other cases, this split must be - * performed in a thread-safe manner. We use - * AtomicLong.compareAndSet as the (typically) most efficient - * mechanism. To bootstrap, we start off using a SecureRandom - * initial default seed, and update using a fixed - * DEFAULT_SEED_GAMMA. The default constructor uses GAMMA_GAMMA, - * not 0, for its splitSeed argument (addGammaModGeorge(0, - * GAMMA_GAMMA) == GAMMA_GAMMA) to reflect that each is split from - * this root generator, even though the root is not explicitly - * represented as a SplittableRandom. - */ - - /** - * The prime modulus for gamma values. - */ - private static final long GAMMA_PRIME = (1L << 57) - 13L; - - /** - * The value for producing new gamma values. Must be greater or - * equal to 13 and less than GAMMA_PRIME. Otherwise, the value is - * arbitrary subject to validation of the resulting statistical - * quality of splits. - */ - private static final long GAMMA_GAMMA = 0x00aae38294f712aabL; - - /** - * The seed update value for default constructors. Must be - * greater or equal to 13. Otherwise, the value is arbitrary - * subject to quality checks. + * File organization: First the non-public methods that constitute + * the main algorithm, then the main public methods, followed by + * some custom spliterator classes needed for stream methods. */ - private static final long DEFAULT_SEED_GAMMA = 0x9e3779b97f4a7c15L; /** - * The value 13 with 64bit sign bit set. Used in the signed - * comparison in addGammaModGeorge. + * The golden ratio scaled to 64bits, used as the initial gamma + * value for (unsplit) SplittableRandoms. */ - private static final long BOTTOM13 = 0x800000000000000DL; + private static final long GOLDEN_GAMMA = 0x9e3779b97f4a7c15L; /** * The least non-zero value returned by nextDouble(). This value * is scaled by a random value of 53 bits to produce a result. */ - private static final double DOUBLE_UNIT = 1.0 / (1L << 53); + private static final double DOUBLE_UNIT = 0x1.0p-53; // 1.0 / (1L << 53); /** - * The next seed for default constructors. - */ - private static final AtomicLong defaultSeedGenerator = - new AtomicLong(getInitialDefaultSeed()); - - /** - * The seed, updated only via method nextSeed. + * The seed. Updated only via method nextSeed. */ private long seed; /** - * The constant value added to seed (mod George) on each update. + * The step value. */ private final long gamma; /** - * The next seed to use for splits. Propagated using - * addGammaModGeorge across instances. + * Internal constructor used by all others except default constructor. */ - private final long nextSplit; - - /** - * Adds the given gamma value, g, to the given seed value s, mod - * George (2^64+13). We regard s and g as unsigned values - * (ranging from 0 to 2^64-1). We add g to s either once or twice - * (mod George) as necessary to produce an (unsigned) result less - * than 2^64. We require that g must be at least 13. This - * guarantees that if (s+g) mod George >= 2^64 then (s+g+g) mod - * George < 2^64; thus we need only a conditional, not a loop, - * to be sure of getting a representable value. - * - * Because Java comparison operators are signed, we implement this - * by conceptually offsetting seed values downwards by 2^63, so - * 0..13 is represented as Long.MIN_VALUE..BOTTOM13. - * - * @param s a seed value, viewed as a signed long - * @param g a gamma value, 13 <= g (as unsigned) - */ - private static long addGammaModGeorge(long s, long g) { - long p = s + g; - return (p >= s) ? p : ((p >= BOTTOM13) ? p : p + g) - 13L; + private SplittableRandom(long seed, long gamma) { + this.seed = seed; + this.gamma = gamma; } /** - * Returns a bit-mixed transformation of its argument. - * See above for explanation. + * Computes Stafford variant 13 of 64bit mix function. */ private static long mix64(long z) { - z ^= (z >>> 33); - z *= 0xff51afd7ed558ccdL; - z ^= (z >>> 33); - z *= 0xc4ceb9fe1a85ec53L; - z ^= (z >>> 33); - return z; + z = (z ^ (z >>> 30)) * 0xbf58476d1ce4e5b9L; + z = (z ^ (z >>> 27)) * 0x94d049bb133111ebL; + return z ^ (z >>> 31); } /** - * Returns a bit-mixed int transformation of its argument. - * See above for explanation. + * Returns the 32 high bits of Stafford variant 4 mix64 function as int. */ private static int mix32(long z) { - z ^= (z >>> 33); - z *= 0xc4ceb9fe1a85ec53L; - return (int)(z >>> 32); + z = (z ^ (z >>> 33)) * 0x62a9d9ed799705f5L; + return (int)(((z ^ (z >>> 28)) * 0xcb24d0a5c88c35b3L) >>> 32); } /** - * Returns a 57-bit mixed transformation of its argument. See - * above for explanation. + * Returns the gamma value to use for a new split instance. */ - private static long mix57(long z) { - z ^= (z >>> 33); - z *= 0x7fb5d329728ea185L; - z &= 0x01FFFFFFFFFFFFFFL; - z ^= (z >>> 33); - z *= 0x81dadef4bc2dd44dL; - z &= 0x01FFFFFFFFFFFFFFL; - z ^= (z >>> 33); - return z; + private static long mixGamma(long z) { + z = (z ^ (z >>> 33)) * 0xff51afd7ed558ccdL; // MurmurHash3 mix constants + z = (z ^ (z >>> 33)) * 0xc4ceb9fe1a85ec53L; + z = (z ^ (z >>> 33)) | 1L; // force to be odd + int n = Long.bitCount(z ^ (z >>> 1)); // ensure enough transitions + return (n < 24) ? z ^ 0xaaaaaaaaaaaaaaaaL : z; } /** - * Internal constructor used by all other constructors and by - * method split. Establishes the initial seed for this instance, - * and uses the given splitSeed to establish gamma, as well as the - * nextSplit to use by this instance. The loop to skip ineligible - * gammas very rarely iterates, and does so at most 13 times. - */ - private SplittableRandom(long seed, long splitSeed) { - this.seed = seed; - long s = splitSeed, g; - do { // ensure gamma >= 13, considered as an unsigned integer - s += GAMMA_GAMMA; - if (s >= GAMMA_PRIME) - s -= GAMMA_PRIME; - g = mix57(s); - } while (g < 13L); - this.gamma = g; - this.nextSplit = s; - } - - /** - * Updates in-place and returns seed. - * See above for explanation. + * Adds gamma to seed. */ private long nextSeed() { - return seed = addGammaModGeorge(seed, gamma); + return seed += gamma; } - /** - * Atomically updates and returns next seed for default constructor. - */ - private static long nextDefaultSeed() { - long oldSeed, newSeed; - do { - oldSeed = defaultSeedGenerator.get(); - newSeed = addGammaModGeorge(oldSeed, DEFAULT_SEED_GAMMA); - } while (!defaultSeedGenerator.compareAndSet(oldSeed, newSeed)); - return mix64(newSeed); - } - - /** - * Returns an initial default seed. - */ - private static long getInitialDefaultSeed() { - byte[] seedBytes = java.security.SecureRandom.getSeed(8); - long s = (long)(seedBytes[0]) & 0xffL; - for (int i = 1; i < 8; ++i) - s = (s << 8) | ((long)(seedBytes[i]) & 0xffL); - return s; + // IllegalArgumentException messages + static final String BAD_BOUND = "bound must be positive"; + static final String BAD_RANGE = "bound must be greater than origin"; + static final String BAD_SIZE = "size must be non-negative"; + + /** + * The seed generator for default constructors. + */ + private static final AtomicLong defaultGen + = new AtomicLong(mix64(System.currentTimeMillis()) ^ + mix64(System.nanoTime())); + + // at end of to survive static initialization circularity + static { + if (java.security.AccessController.doPrivileged( + new java.security.PrivilegedAction() { + public Boolean run() { + return Boolean.getBoolean("java.util.secureRandomSeed"); + }})) { + byte[] seedBytes = java.security.SecureRandom.getSeed(8); + long s = (long)seedBytes[0] & 0xffL; + for (int i = 1; i < 8; ++i) + s = (s << 8) | ((long)seedBytes[i] & 0xffL); + defaultGen.set(s); + } } /* @@ -442,7 +365,7 @@ public class SplittableRandom { * @param seed the initial seed */ public SplittableRandom(long seed) { - this(seed, 0L); + this(seed, GOLDEN_GAMMA); } /** @@ -451,8 +374,10 @@ public class SplittableRandom { * of those of any other instances in the current program; and * may, and typically does, vary across program invocations. */ - public SplittableRandom() { - this(nextDefaultSeed(), GAMMA_GAMMA); + public SplittableRandom() { // emulate defaultGen.split() + long s = defaultGen.getAndAdd(2 * GOLDEN_GAMMA); + this.seed = mix64(s); + this.gamma = mixGamma(s + GOLDEN_GAMMA); } /** @@ -470,7 +395,7 @@ public class SplittableRandom { * @return the new SplittableRandom instance */ public SplittableRandom split() { - return new SplittableRandom(nextSeed(), nextSplit); + return new SplittableRandom(nextLong(), mixGamma(nextSeed())); } /** @@ -486,15 +411,14 @@ public class SplittableRandom { * Returns a pseudorandom {@code int} value between zero (inclusive) * and the specified bound (exclusive). * - * @param bound the bound on the random number to be returned. Must be - * positive. + * @param bound the upper bound (exclusive). Must be positive. * @return a pseudorandom {@code int} value between zero * (inclusive) and the bound (exclusive) - * @throws IllegalArgumentException if the bound is less than zero + * @throws IllegalArgumentException if {@code bound} is not positive */ public int nextInt(int bound) { if (bound <= 0) - throw new IllegalArgumentException("bound must be positive"); + throw new IllegalArgumentException(BAD_BOUND); // Specialize internalNextInt for origin 0 int r = mix32(nextSeed()); int m = bound - 1; @@ -522,7 +446,7 @@ public class SplittableRandom { */ public int nextInt(int origin, int bound) { if (origin >= bound) - throw new IllegalArgumentException("bound must be greater than origin"); + throw new IllegalArgumentException(BAD_RANGE); return internalNextInt(origin, bound); } @@ -539,15 +463,14 @@ public class SplittableRandom { * Returns a pseudorandom {@code long} value between zero (inclusive) * and the specified bound (exclusive). * - * @param bound the bound on the random number to be returned. Must be - * positive. + * @param bound the upper bound (exclusive). Must be positive. * @return a pseudorandom {@code long} value between zero * (inclusive) and the bound (exclusive) - * @throws IllegalArgumentException if {@code bound} is less than zero + * @throws IllegalArgumentException if {@code bound} is not positive */ public long nextLong(long bound) { if (bound <= 0) - throw new IllegalArgumentException("bound must be positive"); + throw new IllegalArgumentException(BAD_BOUND); // Specialize internalNextLong for origin 0 long r = mix64(nextSeed()); long m = bound - 1; @@ -575,7 +498,7 @@ public class SplittableRandom { */ public long nextLong(long origin, long bound) { if (origin >= bound) - throw new IllegalArgumentException("bound must be greater than origin"); + throw new IllegalArgumentException(BAD_RANGE); return internalNextLong(origin, bound); } @@ -584,7 +507,7 @@ public class SplittableRandom { * (inclusive) and one (exclusive). * * @return a pseudorandom {@code double} value between zero - * (inclusive) and one (exclusive) + * (inclusive) and one (exclusive) */ public double nextDouble() { return (mix64(nextSeed()) >>> 11) * DOUBLE_UNIT; @@ -594,26 +517,38 @@ public class SplittableRandom { * Returns a pseudorandom {@code double} value between 0.0 * (inclusive) and the specified bound (exclusive). * - * @param bound the bound on the random number to be returned. Must be - * positive. + * @param bound the upper bound (exclusive). Must be positive. * @return a pseudorandom {@code double} value between zero * (inclusive) and the bound (exclusive) - * @throws IllegalArgumentException if {@code bound} is less than zero + * @throws IllegalArgumentException if {@code bound} is not positive */ public double nextDouble(double bound) { if (!(bound > 0.0)) - throw new IllegalArgumentException("bound must be positive"); + throw new IllegalArgumentException(BAD_BOUND); double result = (mix64(nextSeed()) >>> 11) * DOUBLE_UNIT * bound; return (result < bound) ? result : // correct for rounding Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1); } /** + * Generates a pseudorandom number with the indicated number of + * low-order bits. Because this class has no subclasses, this + * method cannot be invoked or overridden. + * + * @param bits random bits + * @return the next pseudorandom value from this random number + * generator's sequence + */ + protected int next(int bits) { + return nextInt() >>> (32 - bits); + } + + /** * Returns a pseudorandom {@code double} value between the specified * origin (inclusive) and bound (exclusive). * * @param origin the least value returned - * @param bound the upper bound + * @param bound the upper bound (exclusive) * @return a pseudorandom {@code double} value between the origin * (inclusive) and the bound (exclusive) * @throws IllegalArgumentException if {@code origin} is greater than @@ -621,7 +556,7 @@ public class SplittableRandom { */ public double nextDouble(double origin, double bound) { if (!(origin < bound)) - throw new IllegalArgumentException("bound must be greater than origin"); + throw new IllegalArgumentException(BAD_RANGE); return internalNextDouble(origin, bound); } @@ -638,8 +573,9 @@ public class SplittableRandom { // maintenance purposes the small differences across forms. /** - * Returns a stream producing the given {@code streamSize} number of - * pseudorandom {@code int} values. + * Returns a stream producing the given {@code streamSize} number + * of pseudorandom {@code int} values from this generator and/or + * one split from it. * * @param streamSize the number of values to generate * @return a stream of pseudorandom {@code int} values @@ -648,7 +584,7 @@ public class SplittableRandom { */ public IntStream ints(long streamSize) { if (streamSize < 0L) - throw new IllegalArgumentException("negative Stream size"); + throw new IllegalArgumentException(BAD_SIZE); return StreamSupport.intStream (new RandomIntsSpliterator (this, 0L, streamSize, Integer.MAX_VALUE, 0), @@ -657,7 +593,7 @@ public class SplittableRandom { /** * Returns an effectively unlimited stream of pseudorandom {@code int} - * values. + * values from this generator and/or one split from it. * * @implNote This method is implemented to be equivalent to {@code * ints(Long.MAX_VALUE)}. @@ -672,15 +608,16 @@ public class SplittableRandom { } /** - * Returns a stream producing the given {@code streamSize} number of - * pseudorandom {@code int} values, each conforming to the given - * origin and bound. + * Returns a stream producing the given {@code streamSize} number + * of pseudorandom {@code int} values from this generator and/or one split + * from it; each value conforms to the given origin (inclusive) and bound + * (exclusive). * * @param streamSize the number of values to generate - * @param randomNumberOrigin the origin of each random value - * @param randomNumberBound the bound of each random value + * @param randomNumberOrigin the origin (inclusive) of each random value + * @param randomNumberBound the bound (exclusive) of each random value * @return a stream of pseudorandom {@code int} values, - * each with the given origin and bound + * each with the given origin (inclusive) and bound (exclusive) * @throws IllegalArgumentException if {@code streamSize} is * less than zero, or {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} @@ -688,9 +625,9 @@ public class SplittableRandom { public IntStream ints(long streamSize, int randomNumberOrigin, int randomNumberBound) { if (streamSize < 0L) - throw new IllegalArgumentException("negative Stream size"); + throw new IllegalArgumentException(BAD_SIZE); if (randomNumberOrigin >= randomNumberBound) - throw new IllegalArgumentException("bound must be greater than origin"); + throw new IllegalArgumentException(BAD_RANGE); return StreamSupport.intStream (new RandomIntsSpliterator (this, 0L, streamSize, randomNumberOrigin, randomNumberBound), @@ -699,21 +636,22 @@ public class SplittableRandom { /** * Returns an effectively unlimited stream of pseudorandom {@code - * int} values, each conforming to the given origin and bound. + * int} values from this generator and/or one split from it; each value + * conforms to the given origin (inclusive) and bound (exclusive). * * @implNote This method is implemented to be equivalent to {@code * ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}. * - * @param randomNumberOrigin the origin of each random value - * @param randomNumberBound the bound of each random value + * @param randomNumberOrigin the origin (inclusive) of each random value + * @param randomNumberBound the bound (exclusive) of each random value * @return a stream of pseudorandom {@code int} values, - * each with the given origin and bound + * each with the given origin (inclusive) and bound (exclusive) * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} */ public IntStream ints(int randomNumberOrigin, int randomNumberBound) { if (randomNumberOrigin >= randomNumberBound) - throw new IllegalArgumentException("bound must be greater than origin"); + throw new IllegalArgumentException(BAD_RANGE); return StreamSupport.intStream (new RandomIntsSpliterator (this, 0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound), @@ -721,8 +659,9 @@ public class SplittableRandom { } /** - * Returns a stream producing the given {@code streamSize} number of - * pseudorandom {@code long} values. + * Returns a stream producing the given {@code streamSize} number + * of pseudorandom {@code long} values from this generator and/or + * one split from it. * * @param streamSize the number of values to generate * @return a stream of pseudorandom {@code long} values @@ -731,7 +670,7 @@ public class SplittableRandom { */ public LongStream longs(long streamSize) { if (streamSize < 0L) - throw new IllegalArgumentException("negative Stream size"); + throw new IllegalArgumentException(BAD_SIZE); return StreamSupport.longStream (new RandomLongsSpliterator (this, 0L, streamSize, Long.MAX_VALUE, 0L), @@ -739,8 +678,8 @@ public class SplittableRandom { } /** - * Returns an effectively unlimited stream of pseudorandom {@code long} - * values. + * Returns an effectively unlimited stream of pseudorandom {@code + * long} values from this generator and/or one split from it. * * @implNote This method is implemented to be equivalent to {@code * longs(Long.MAX_VALUE)}. @@ -756,14 +695,15 @@ public class SplittableRandom { /** * Returns a stream producing the given {@code streamSize} number of - * pseudorandom {@code long} values, each conforming to the - * given origin and bound. + * pseudorandom {@code long} values from this generator and/or one split + * from it; each value conforms to the given origin (inclusive) and bound + * (exclusive). * * @param streamSize the number of values to generate - * @param randomNumberOrigin the origin of each random value - * @param randomNumberBound the bound of each random value + * @param randomNumberOrigin the origin (inclusive) of each random value + * @param randomNumberBound the bound (exclusive) of each random value * @return a stream of pseudorandom {@code long} values, - * each with the given origin and bound + * each with the given origin (inclusive) and bound (exclusive) * @throws IllegalArgumentException if {@code streamSize} is * less than zero, or {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} @@ -771,9 +711,9 @@ public class SplittableRandom { public LongStream longs(long streamSize, long randomNumberOrigin, long randomNumberBound) { if (streamSize < 0L) - throw new IllegalArgumentException("negative Stream size"); + throw new IllegalArgumentException(BAD_SIZE); if (randomNumberOrigin >= randomNumberBound) - throw new IllegalArgumentException("bound must be greater than origin"); + throw new IllegalArgumentException(BAD_RANGE); return StreamSupport.longStream (new RandomLongsSpliterator (this, 0L, streamSize, randomNumberOrigin, randomNumberBound), @@ -782,21 +722,22 @@ public class SplittableRandom { /** * Returns an effectively unlimited stream of pseudorandom {@code - * long} values, each conforming to the given origin and bound. + * long} values from this generator and/or one split from it; each value + * conforms to the given origin (inclusive) and bound (exclusive). * * @implNote This method is implemented to be equivalent to {@code * longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}. * - * @param randomNumberOrigin the origin of each random value - * @param randomNumberBound the bound of each random value + * @param randomNumberOrigin the origin (inclusive) of each random value + * @param randomNumberBound the bound (exclusive) of each random value * @return a stream of pseudorandom {@code long} values, - * each with the given origin and bound + * each with the given origin (inclusive) and bound (exclusive) * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} */ public LongStream longs(long randomNumberOrigin, long randomNumberBound) { if (randomNumberOrigin >= randomNumberBound) - throw new IllegalArgumentException("bound must be greater than origin"); + throw new IllegalArgumentException(BAD_RANGE); return StreamSupport.longStream (new RandomLongsSpliterator (this, 0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound), @@ -805,8 +746,8 @@ public class SplittableRandom { /** * Returns a stream producing the given {@code streamSize} number of - * pseudorandom {@code double} values, each between zero - * (inclusive) and one (exclusive). + * pseudorandom {@code double} values from this generator and/or one split + * from it; each value is between zero (inclusive) and one (exclusive). * * @param streamSize the number of values to generate * @return a stream of {@code double} values @@ -815,7 +756,7 @@ public class SplittableRandom { */ public DoubleStream doubles(long streamSize) { if (streamSize < 0L) - throw new IllegalArgumentException("negative Stream size"); + throw new IllegalArgumentException(BAD_SIZE); return StreamSupport.doubleStream (new RandomDoublesSpliterator (this, 0L, streamSize, Double.MAX_VALUE, 0.0), @@ -824,8 +765,8 @@ public class SplittableRandom { /** * Returns an effectively unlimited stream of pseudorandom {@code - * double} values, each between zero (inclusive) and one - * (exclusive). + * double} values from this generator and/or one split from it; each value + * is between zero (inclusive) and one (exclusive). * * @implNote This method is implemented to be equivalent to {@code * doubles(Long.MAX_VALUE)}. @@ -841,25 +782,26 @@ public class SplittableRandom { /** * Returns a stream producing the given {@code streamSize} number of - * pseudorandom {@code double} values, each conforming to the - * given origin and bound. + * pseudorandom {@code double} values from this generator and/or one split + * from it; each value conforms to the given origin (inclusive) and bound + * (exclusive). * * @param streamSize the number of values to generate - * @param randomNumberOrigin the origin of each random value - * @param randomNumberBound the bound of each random value + * @param randomNumberOrigin the origin (inclusive) of each random value + * @param randomNumberBound the bound (exclusive) of each random value * @return a stream of pseudorandom {@code double} values, - * each with the given origin and bound + * each with the given origin (inclusive) and bound (exclusive) * @throws IllegalArgumentException if {@code streamSize} is - * less than zero + * less than zero * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} */ public DoubleStream doubles(long streamSize, double randomNumberOrigin, double randomNumberBound) { if (streamSize < 0L) - throw new IllegalArgumentException("negative Stream size"); + throw new IllegalArgumentException(BAD_SIZE); if (!(randomNumberOrigin < randomNumberBound)) - throw new IllegalArgumentException("bound must be greater than origin"); + throw new IllegalArgumentException(BAD_RANGE); return StreamSupport.doubleStream (new RandomDoublesSpliterator (this, 0L, streamSize, randomNumberOrigin, randomNumberBound), @@ -868,21 +810,22 @@ public class SplittableRandom { /** * Returns an effectively unlimited stream of pseudorandom {@code - * double} values, each conforming to the given origin and bound. + * double} values from this generator and/or one split from it; each value + * conforms to the given origin (inclusive) and bound (exclusive). * * @implNote This method is implemented to be equivalent to {@code * doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}. * - * @param randomNumberOrigin the origin of each random value - * @param randomNumberBound the bound of each random value + * @param randomNumberOrigin the origin (inclusive) of each random value + * @param randomNumberBound the bound (exclusive) of each random value * @return a stream of pseudorandom {@code double} values, - * each with the given origin and bound + * each with the given origin (inclusive) and bound (exclusive) * @throws IllegalArgumentException if {@code randomNumberOrigin} * is greater than or equal to {@code randomNumberBound} */ public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) { if (!(randomNumberOrigin < randomNumberBound)) - throw new IllegalArgumentException("bound must be greater than origin"); + throw new IllegalArgumentException(BAD_RANGE); return StreamSupport.doubleStream (new RandomDoublesSpliterator (this, 0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound), @@ -897,7 +840,8 @@ public class SplittableRandom { * approach. The long and double versions of this class are * identical except for types. */ - static final class RandomIntsSpliterator implements Spliterator.OfInt { + private static final class RandomIntsSpliterator + implements Spliterator.OfInt { final SplittableRandom rng; long index; final long fence; @@ -940,9 +884,10 @@ public class SplittableRandom { long i = index, f = fence; if (i < f) { index = f; + SplittableRandom r = rng; int o = origin, b = bound; do { - consumer.accept(rng.internalNextInt(o, b)); + consumer.accept(r.internalNextInt(o, b)); } while (++i < f); } } @@ -951,7 +896,8 @@ public class SplittableRandom { /** * Spliterator for long streams. */ - static final class RandomLongsSpliterator implements Spliterator.OfLong { + private static final class RandomLongsSpliterator + implements Spliterator.OfLong { final SplittableRandom rng; long index; final long fence; @@ -994,9 +940,10 @@ public class SplittableRandom { long i = index, f = fence; if (i < f) { index = f; + SplittableRandom r = rng; long o = origin, b = bound; do { - consumer.accept(rng.internalNextLong(o, b)); + consumer.accept(r.internalNextLong(o, b)); } while (++i < f); } } @@ -1006,7 +953,8 @@ public class SplittableRandom { /** * Spliterator for double streams. */ - static final class RandomDoublesSpliterator implements Spliterator.OfDouble { + private static final class RandomDoublesSpliterator + implements Spliterator.OfDouble { final SplittableRandom rng; long index; final long fence; @@ -1049,9 +997,10 @@ public class SplittableRandom { long i = index, f = fence; if (i < f) { index = f; + SplittableRandom r = rng; double o = origin, b = bound; do { - consumer.accept(rng.internalNextDouble(o, b)); + consumer.accept(r.internalNextDouble(o, b)); } while (++i < f); } }