jdk-sandbox: comparison src/java.base/share/classes/java/util/random/AbstractSplittableRNG.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.util.Spliterator;
 import java.util.function.Consumer;
+import java.util.function.DoubleConsumer;
 import java.util.function.IntConsumer;
 import java.util.function.LongConsumer;
-import java.util.function.DoubleConsumer;
+import java.util.stream.Stream;
-import java.util.Spliterator;
 import java.util.stream.StreamSupport;
-import java.util.stream.Stream;
 /**
-* This class provides much of the implementation of the {@code SplittableRng}
+* This class provides much of the implementation of the {@link SplittableRNG} interface, to
-* interface, to minimize the effort required to implement this interface.
+* minimize the effort required to implement this interface.
-*
+* <p>
-* To implement a pseudorandom number generator, the programmer needs
+* To implement a pseudorandom number generator, the programmer needs only to extend this class and
-* only to extend this class and provide implementations for the
+* provide implementations for the methods {@code nextInt()}, {@code nextLong()}, {@code period()},
-* methods {@code nextInt()}, {@code nextLong()}, {@code period()},
+* and {@code split(SplittableRNG)}.
-* and {@code split(SplittableRng)}.
+* <p>
-*
+* (If the pseudorandom number generator also has the ability to jump, then the programmer may wish
-* (If the pseudorandom number generator also has the ability to jump,
+* to consider instead extending the class {@link ArbitrarilyJumpableRNG}.  But if the pseudorandom
-* then the programmer may wish to consider instead extending
+* number generator furthermore has the ability to jump an arbitrary specified distance, then the
-* the class {@code AbstractSplittableJumpableRng} or (if it can also leap)
+* programmer may wish to consider instead extending the class {@link
-* {@code AbstractSplittableLeapableRng}.  But if the pseudorandom number
+* AbstractArbitrarilyJumpableRNG}.)
-* generator furthermore has the ability to jump an arbitrary specified
+* <p>
-* distance, then the programmer may wish to consider instead extending
+* The programmer should generally provide at least three constructors: one that takes no arguments,
-* the class {@code * AbstractSplittableArbitrarilyJumpableRng}.)
+* one that accepts a {@code long} seed value, and one that accepts an array of seed {@code byte}
-*
+* values. This class provides a public {@code initialSeed()} method that may be useful in
-* The programmer should generally provide at least three constructors:
+* initializing some static state from which to derive defaults seeds for use by the no-argument
-* one that takes no arguments, one that accepts a {@code long}
+* constructor.
-* seed value, and one that accepts an array of seed {@code byte} values.
+* <p>
-* This class provides a public {@code initialSeed()} method that may
+* For the stream methods (such as {@code ints()} and {@code splits()}), this class provides {@link
-* be useful in initializing some static state from which to derive
+* Spliterator} based implementations that allow parallel execution when appropriate.
-* defaults seeds for use by the no-argument constructor.
+* <p>
-*
+* The documentation for each non-abstract method in this class describes its implementation in
-* For the stream methods (such as {@code ints()} and {@code splits()}),
+* detail. Each of these methods may be overridden if the pseudorandom number generator being
-* this class provides {@code Spliterator}-based implementations that
-* allow parallel execution when appropriate.
-*
-* The documentation for each non-abstract method in this class
-* describes its implementation in detail. Each of these methods may
-* be overridden if the pseudorandom number generator being
 * implemented admits a more efficient implementation.
 *
-* @author  Guy Steele
+* @since 14
-* @author  Doug Lea
-* @since   1.9
 */
-public abstract class AbstractSplittableRng extends AbstractSpliteratorRng implements SplittableRng {
+public abstract class AbstractSplittableRNG extends AbstractSpliteratorRNG implements SplittableRNG {
 /*
 * Implementation Overview.
 *
 * This class provides most of the "user API" methods needed to
-* satisfy the interface java.util.JumpableRng.  Most of these methods
+* satisfy the interface JumpableRNG.  Most of these methods
-* are in turn inherited from AbstractRng and the non-public class
+* are in turn inherited from AbstractRNG and the non-public class
-* AbstractSpliteratorRng; this file implements two versions of the
+* AbstractSpliteratorRNG; this file implements two versions of the
 * splits method and defines the spliterators necessary to support
 * them.
 *
-* The abstract split() method from interface SplittableRng is redeclared
+* The abstract split() method from interface SplittableRNG is redeclared
-* here so as to narrow the return type to AbstractSplittableRng.
+* here so as to narrow the return type to AbstractSplittableRNG.
 *
 * File organization: First the non-public methods needed by the class
-* AbstractSpliteratorRng, then the main public methods, followed by some
+* AbstractSpliteratorRNG, then the main public methods, followed by some
 * custom spliterator classes.
 */
 Spliterator.OfInt makeIntsSpliterator(long index, long fence, int origin, int bound) {
-	return new RandomIntsSpliterator(this, index, fence, origin, bound);
+return new RandomIntsSpliterator(this, index, fence, origin, bound);
 }
 Spliterator.OfLong makeLongsSpliterator(long index, long fence, long origin, long bound) {
-	return new RandomLongsSpliterator(this, index, fence, origin, bound);
+return new RandomLongsSpliterator(this, index, fence, origin, bound);
 }
 Spliterator.OfDouble makeDoublesSpliterator(long index, long fence, double origin, double bound) {
-	return new RandomDoublesSpliterator(this, index, fence, origin, bound);
+return new RandomDoublesSpliterator(this, index, fence, origin, bound);
 }
-Spliterator<SplittableRng> makeSplitsSpliterator(long index, long fence, SplittableRng source) {
+Spliterator<SplittableRNG> makeSplitsSpliterator(long index, long fence, SplittableRNG source) {
-	return new RandomSplitsSpliterator(source, index, fence, this);
+return new RandomSplitsSpliterator(source, index, fence, this);
 }
 /* ---------------- public methods ---------------- */
 /**
 * Implements the @code{split()} method as {@code this.split(this) }.
 *
-* @return the new {@code AbstractSplittableRng} instance
+* @return the new {@link AbstractSplittableRNG} instance
 */
-public SplittableRng split() { return this.split(this); }
+public SplittableRNG split() {
+return this.split(this);
+}
 // Stream methods for splittings
 /**
-* Returns an effectively unlimited stream of new pseudorandom
+* Returns an effectively unlimited stream of new pseudorandom number generators, each of which
-* number generators, each of which implements the {@code SplittableRng}
+* implements the {@link SplittableRNG} interface.
-* interface.
+* <p>
-*
+* This pseudorandom number generator provides the entropy used to seed the new ones.
-* This pseudorandom number generator provides the
+*
-* entropy used to seed the new ones.
+* @return a stream of {@link SplittableRNG} objects
 *
-* @implNote This method is implemented to be equivalent to
+* @implNote This method is implemented to be equivalent to {@code splits(Long.MAX_VALUE)}.
-* {@code splits(Long.MAX_VALUE)}.
+*/
-*
+public Stream<SplittableRNG> splits() {
-* @return a stream of {@code SplittableRng} objects
-*/
-public Stream<SplittableRng> splits() {
 return this.splits(Long.MAX_VALUE, this);
 }
 /**
-* Returns a stream producing the given {@code streamSize} number of
+* Returns a stream producing the given {@code streamSize} number of new pseudorandom number
-* new pseudorandom number generators, each of which implements the
+* generators, each of which implements the {@link SplittableRNG} interface.
-* {@code SplittableRng} interface.
+* <p>
-*
+* This pseudorandom number generator provides the entropy used to seed the new ones.
-* This pseudorandom number generator provides the
-* entropy used to seed the new ones.
 *
 * @param streamSize the number of values to generate
-* @return a stream of {@code SplittableRng} objects
+*
-* @throws IllegalArgumentException if {@code streamSize} is
+* @return a stream of {@link SplittableRNG} objects
-*         less than zero
+*
-*/
+* @throws IllegalArgumentException if {@code streamSize} is less than zero
-public Stream<SplittableRng> splits(long streamSize) {
+*/
-	return this.splits(streamSize, this);
+public Stream<SplittableRNG> splits(long streamSize) {
-}
+return this.splits(streamSize, this);
+}
-/**
-* Returns an effectively unlimited stream of new pseudorandom
+/**
-* number generators, each of which implements the {@code SplittableRng}
+* Returns an effectively unlimited stream of new pseudorandom number generators, each of which
-* interface.
+* implements the {@link SplittableRNG} interface.
 *
-* @implNote This method is implemented to be equivalent to
+* @param source a {@link SplittableRNG} instance to be used instead of this one as a source of
-* {@code splits(Long.MAX_VALUE)}.
+*               pseudorandom bits used to initialize the state of the new ones.
 *
-* @param source a {@code SplittableRng} instance to be used instead
+* @return a stream of {@link SplittableRNG} objects
-*               of this one as a source of pseudorandom bits used to
+*
-*               initialize the state of the new ones.
+* @implNote This method is implemented to be equivalent to {@code splits(Long.MAX_VALUE)}.
-* @return a stream of {@code SplittableRng} objects
+*/
-*/
+public Stream<SplittableRNG> splits(SplittableRNG source) {
-public Stream<SplittableRng> splits(SplittableRng source) {
 return this.splits(Long.MAX_VALUE, source);
 }
 /**
-* Returns a stream producing the given {@code streamSize} number of
+* Returns a stream producing the given {@code streamSize} number of new pseudorandom number
-* new pseudorandom number generators, each of which implements the
+* generators, each of which implements the {@link SplittableRNG} interface.
-* {@code SplittableRng} interface.
 *
 * @param streamSize the number of values to generate
-* @param source a {@code SplittableRng} instance to be used instead
+* @param source     a {@link SplittableRNG} instance to be used instead of this one as a source
-*               of this one as a source of pseudorandom bits used to
+*                   of pseudorandom bits used to initialize the state of the new ones.
-*               initialize the state of the new ones.
+*
-* @return a stream of {@code SplittableRng} objects
+* @return a stream of {@link SplittableRNG} objects
-* @throws IllegalArgumentException if {@code streamSize} is
+*
-*         less than zero
+* @throws IllegalArgumentException if {@code streamSize} is less than zero
 */
-public Stream<SplittableRng> splits(long streamSize, SplittableRng source) {
+public Stream<SplittableRNG> splits(long streamSize, SplittableRNG source) {
-	RngSupport.checkStreamSize(streamSize);
+RNGSupport.checkStreamSize(streamSize);
 return StreamSupport.stream(makeSplitsSpliterator(0L, streamSize, source), false);
 }
 /**
-* Spliterator for int streams.  We multiplex the four int
+* Spliterator for int streams.  We multiplex the four int versions into one class by treating a
-* versions into one class by treating a bound less than origin as
+* bound less than origin as unbounded, and also by treating "infinite" as equivalent to
-* unbounded, and also by treating "infinite" as equivalent to
+* {@code Long.MAX_VALUE}. For splits, it uses the standard divide-by-two approach. The long and
-* Long.MAX_VALUE. For splits, it uses the standard divide-by-two
+* double versions of this class are identical except for types.
-* approach. The long and double versions of this class are
+*/
-* identical except for types.
+static class RandomIntsSpliterator extends RNGSupport.RandomSpliterator implements Spliterator.OfInt {
-*/
+final SplittableRNG generatingRNG;
-static class RandomIntsSpliterator extends RngSupport.RandomSpliterator implements Spliterator.OfInt {
-	final SplittableRng generatingRng;
 final int origin;
 final int bound;
-RandomIntsSpliterator(SplittableRng generatingRng, long index, long fence, int origin, int bound) {
+RandomIntsSpliterator(SplittableRNG generatingRNG, long index, long fence, int origin, int bound) {
-	    super(index, fence);
+super(index, fence);
-	    this.generatingRng = generatingRng;
+this.generatingRNG = generatingRNG;
 this.origin = origin; this.bound = bound;
 }
 public Spliterator.OfInt trySplit() {
 long i = index, m = (i + fence) >>> 1;
-	    if (m <= i) return null;
+if (m <= i) return null;
-	    index = m;
+index = m;
-	    return new RandomIntsSpliterator(generatingRng.split(), i, m, origin, bound);
+return new RandomIntsSpliterator(generatingRNG.split(), i, m, origin, bound);
 }
 public boolean tryAdvance(IntConsumer consumer) {
 if (consumer == null) throw new NullPointerException();
 long i = index, f = fence;
 if (i < f) {
-consumer.accept(RngSupport.boundedNextInt(generatingRng, origin, bound));
+consumer.accept(RNGSupport.boundedNextInt(generatingRNG, origin, bound));
 index = i + 1;
 return true;
 }
 else return false;
 }
 public void forEachRemaining(IntConsumer consumer) {
 if (consumer == null) throw new NullPointerException();
 long i = index, f = fence;
 if (i < f) {
 index = f;
-Rng r = generatingRng;
+RandomNumberGenerator r = generatingRNG;
 int o = origin, b = bound;
 do {
-consumer.accept(RngSupport.boundedNextInt(r, o, b));
+consumer.accept(RNGSupport.boundedNextInt(r, o, b));
 } while (++i < f);
 }
 }
 }
 /**
 * Spliterator for long streams.
 */
-static class RandomLongsSpliterator extends RngSupport.RandomSpliterator implements Spliterator.OfLong {
+static class RandomLongsSpliterator extends RNGSupport.RandomSpliterator implements Spliterator.OfLong {
-	final SplittableRng generatingRng;
+final SplittableRNG generatingRNG;
 final long origin;
 final long bound;
-RandomLongsSpliterator(SplittableRng generatingRng, long index, long fence, long origin, long bound) {
+RandomLongsSpliterator(SplittableRNG generatingRNG, long index, long fence, long origin, long bound) {
-	    super(index, fence);
+super(index, fence);
-	    this.generatingRng = generatingRng;
+this.generatingRNG = generatingRNG;
 this.origin = origin; this.bound = bound;
 }
 public Spliterator.OfLong trySplit() {
 long i = index, m = (i + fence) >>> 1;
-	    if (m <= i) return null;
+if (m <= i) return null;
-	    index = m;
+index = m;
-	    return new RandomLongsSpliterator(generatingRng.split(), i, m, origin, bound);
+return new RandomLongsSpliterator(generatingRNG.split(), i, m, origin, bound);
 }
 public boolean tryAdvance(LongConsumer consumer) {
 if (consumer == null) throw new NullPointerException();
 long i = index, f = fence;
 if (i < f) {
-consumer.accept(RngSupport.boundedNextLong(generatingRng, origin, bound));
+consumer.accept(RNGSupport.boundedNextLong(generatingRNG, origin, bound));
 index = i + 1;
 return true;
 }
 else return false;
 }
 public void forEachRemaining(LongConsumer consumer) {
 if (consumer == null) throw new NullPointerException();
 long i = index, f = fence;
 if (i < f) {
 index = f;
-Rng r = generatingRng;
+RandomNumberGenerator r = generatingRNG;
 long o = origin, b = bound;
 do {
-consumer.accept(RngSupport.boundedNextLong(r, o, b));
+consumer.accept(RNGSupport.boundedNextLong(r, o, b));
 } while (++i < f);
 }
 }
 }
 /**
 * Spliterator for double streams.
 */
-static class RandomDoublesSpliterator extends RngSupport.RandomSpliterator implements Spliterator.OfDouble {
+static class RandomDoublesSpliterator extends RNGSupport.RandomSpliterator implements Spliterator.OfDouble {
-	final SplittableRng generatingRng;
+final SplittableRNG generatingRNG;
 final double origin;
 final double bound;
-RandomDoublesSpliterator(SplittableRng generatingRng, long index, long fence, double origin, double bound) {
+RandomDoublesSpliterator(SplittableRNG generatingRNG, long index, long fence, double origin, double bound) {
-	    super(index, fence);
+super(index, fence);
-	    this.generatingRng = generatingRng;
+this.generatingRNG = generatingRNG;
 this.origin = origin; this.bound = bound;
 }
 public Spliterator.OfDouble trySplit() {
 long i = index, m = (i + fence) >>> 1;
-	    if (m <= i) return null;
+if (m <= i) return null;
-	    index = m;
+index = m;
-	    return new RandomDoublesSpliterator(generatingRng.split(), i, m, origin, bound);
+return new RandomDoublesSpliterator(generatingRNG.split(), i, m, origin, bound);
 }
 public boolean tryAdvance(DoubleConsumer consumer) {
 if (consumer == null) throw new NullPointerException();
 long i = index, f = fence;
 if (i < f) {
-consumer.accept(RngSupport.boundedNextDouble(generatingRng, origin, bound));
+consumer.accept(RNGSupport.boundedNextDouble(generatingRNG, origin, bound));
 index = i + 1;
 return true;
 }
 else return false;
 }
 public void forEachRemaining(DoubleConsumer consumer) {
 if (consumer == null) throw new NullPointerException();
 long i = index, f = fence;
 if (i < f) {
 index = f;
-Rng r = generatingRng;
+RandomNumberGenerator r = generatingRNG;
 double o = origin, b = bound;
 do {
-consumer.accept(RngSupport.boundedNextDouble(r, o, b));
+consumer.accept(RNGSupport.boundedNextDouble(r, o, b));
 } while (++i < f);
 }
 }
 }
 /**
-* Spliterator for stream of generators of type SplittableRng.  We multiplex the two
+* Spliterator for stream of generators of type SplittableRNG.  We multiplex the two
 * versions into one class by treating "infinite" as equivalent to Long.MAX_VALUE.
 * For splits, it uses the standard divide-by-two approach.
 */
-static class RandomSplitsSpliterator extends RngSupport.RandomSpliterator implements Spliterator<SplittableRng> {
+static class RandomSplitsSpliterator extends RNGSupport.RandomSpliterator implements Spliterator<SplittableRNG> {
-	final SplittableRng generatingRng;
+final SplittableRNG generatingRNG;
-	final SplittableRng constructingRng;
+final SplittableRNG constructingRNG;
-RandomSplitsSpliterator(SplittableRng generatingRng, long index, long fence, SplittableRng constructingRng) {
+RandomSplitsSpliterator(SplittableRNG generatingRNG, long index, long fence, SplittableRNG constructingRNG) {
-	    super(index, fence);
+super(index, fence);
-	    this.generatingRng = generatingRng;
+this.generatingRNG = generatingRNG;
-	    this.constructingRng = constructingRng;
+this.constructingRNG = constructingRNG;
 }
-public Spliterator<SplittableRng> trySplit() {
+public Spliterator<SplittableRNG> trySplit() {
 long i = index, m = (i + fence) >>> 1;
-	    if (m <= i) return null;
+if (m <= i) return null;
-	    index = m;
+index = m;
-	    return new RandomSplitsSpliterator(generatingRng.split(), i, m, constructingRng);
+return new RandomSplitsSpliterator(generatingRNG.split(), i, m, constructingRNG);
 }
-public boolean tryAdvance(Consumer<? super SplittableRng> consumer) {
+public boolean tryAdvance(Consumer<? super SplittableRNG> consumer) {
 if (consumer == null) throw new NullPointerException();
 long i = index, f = fence;
 if (i < f) {
-consumer.accept(constructingRng.split(generatingRng));
+consumer.accept(constructingRNG.split(generatingRNG));
 index = i + 1;
 return true;
 }
 else return false;
 }
-public void forEachRemaining(Consumer<? super SplittableRng> consumer) {
+public void forEachRemaining(Consumer<? super SplittableRNG> consumer) {
 if (consumer == null) throw new NullPointerException();
 long i = index, f = fence;
 if (i < f) {
 index = f;
-		SplittableRng c = constructingRng;
+SplittableRNG c = constructingRNG;
-SplittableRng r = generatingRng;
+SplittableRNG r = generatingRNG;
 do {
 consumer.accept(c.split(r));
 } while (++i < f);
 }
 }

branch	JDK-8193209-branch
changeset 57437	f02ffcb61dce
parent 57436	b0c958c0e6c6