1 /*

     2  * Copyright (c) 2016, 2019, Oracle and/or its affiliates. All rights reserved.

     3  * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

     4  *

     5  *

     6  *

     7  *

     8  *

     9  *

    10  *

    11  *

    12  *

    13  *

    14  *

    15  *

    16  *

    17  *

    18  *

    19  *

    20  *

    21  *

    22  *

    23  *

    24  */

    25 

    26 // package java.util;

    27 

    28 import java.util.function.Consumer;

    29 import java.util.function.IntConsumer;

    30 import java.util.function.LongConsumer;

    31 import java.util.function.DoubleConsumer;

    32 import java.util.Spliterator;

    33 import java.util.stream.StreamSupport;

    34 import java.util.stream.Stream;

    35 

    36 /**

    37  * This class provides much of the implementation of the {@code SplittableRng}

    38  * interface, to minimize the effort required to implement this interface.

    39  *

    40  * To implement a pseudorandom number generator, the programmer needs

    41  * only to extend this class and provide implementations for the

    42  * methods {@code nextInt()}, {@code nextLong()}, {@code period()},

    43  * and {@code split(SplittableRng)}.

    44  *

    45  * (If the pseudorandom number generator also has the ability to jump,

    46  * then the programmer may wish to consider instead extending

    47  * the class {@code AbstractSplittableJumpableRng} or (if it can also leap)

    48  * {@code AbstractSplittableLeapableRng}.  But if the pseudorandom number

    49  * generator furthermore has the ability to jump an arbitrary specified

    50  * distance, then the programmer may wish to consider instead extending

    51  * the class {@code * AbstractSplittableArbitrarilyJumpableRng}.)

    52  *

    53  * The programmer should generally provide at least three constructors:

    54  * one that takes no arguments, one that accepts a {@code long}

    55  * seed value, and one that accepts an array of seed {@code byte} values.

    56  * This class provides a public {@code initialSeed()} method that may

    57  * be useful in initializing some static state from which to derive

    58  * defaults seeds for use by the no-argument constructor.

    59  *

    60  * For the stream methods (such as {@code ints()} and {@code splits()}),

    61  * this class provides {@code Spliterator}-based implementations that

    62  * allow parallel execution when appropriate.

    63  *

    64  * The documentation for each non-abstract method in this class

    65  * describes its implementation in detail. Each of these methods may

    66  * be overridden if the pseudorandom number generator being

    67  * implemented admits a more efficient implementation.

    68  *

    69  * @author  Guy Steele

    70  * @author  Doug Lea

    71  * @since   1.9

    72  */

    73 public abstract class AbstractSplittableRng extends AbstractSpliteratorRng implements SplittableRng {

    74 

    75     /*

    76      * Implementation Overview.

    77      *

    78      * This class provides most of the "user API" methods needed to

    79      * satisfy the interface java.util.JumpableRng.  Most of these methods

    80      * are in turn inherited from AbstractRng and the non-public class

    81      * AbstractSpliteratorRng; this file implements two versions of the

    82      * splits method and defines the spliterators necessary to support

    83      * them.

    84      *

    85      * The abstract split() method from interface SplittableRng is redeclared

    86      * here so as to narrow the return type to AbstractSplittableRng.

    87      *

    88      * File organization: First the non-public methods needed by the class

    89      * AbstractSpliteratorRng, then the main public methods, followed by some

    90      * custom spliterator classes.

    91      */

    92 

    93     Spliterator.OfInt makeIntsSpliterator(long index, long fence, int origin, int bound) {

    94 	return new RandomIntsSpliterator(this, index, fence, origin, bound);

    95     }

    96     

    97     Spliterator.OfLong makeLongsSpliterator(long index, long fence, long origin, long bound) {

    98 	return new RandomLongsSpliterator(this, index, fence, origin, bound);

    99     }

   100     

   101     Spliterator.OfDouble makeDoublesSpliterator(long index, long fence, double origin, double bound) {

   102 	return new RandomDoublesSpliterator(this, index, fence, origin, bound);

   103     }

   104 

   105     Spliterator<SplittableRng> makeSplitsSpliterator(long index, long fence, SplittableRng source) {

   106 	return new RandomSplitsSpliterator(source, index, fence, this);

   107     }

   108 

   109     /* ---------------- public methods ---------------- */

   110 

   111     /**

   112      * Implements the @code{split()} method as {@code this.split(this) }.

   113      *

   114      * @return the new {@code AbstractSplittableRng} instance

   115      */

   116     public SplittableRng split() { return this.split(this); }

   117     

   118     // Stream methods for splittings

   119 

   120     /**

   121      * Returns an effectively unlimited stream of new pseudorandom

   122      * number generators, each of which implements the {@code SplittableRng}

   123      * interface.

   124      *

   125      * This pseudorandom number generator provides the

   126      * entropy used to seed the new ones.

   127      *

   128      * @implNote This method is implemented to be equivalent to

   129      * {@code splits(Long.MAX_VALUE)}.

   130      *

   131      * @return a stream of {@code SplittableRng} objects

   132      */

   133     public Stream<SplittableRng> splits() {

   134         return this.splits(Long.MAX_VALUE, this);

   135     }

   136 

   137     /**

   138      * Returns a stream producing the given {@code streamSize} number of

   139      * new pseudorandom number generators, each of which implements the

   140      * {@code SplittableRng} interface.

   141      *

   142      * This pseudorandom number generator provides the

   143      * entropy used to seed the new ones.

   144      *

   145      * @param streamSize the number of values to generate

   146      * @return a stream of {@code SplittableRng} objects

   147      * @throws IllegalArgumentException if {@code streamSize} is

   148      *         less than zero

   149      */

   150     public Stream<SplittableRng> splits(long streamSize) {

   151 	return this.splits(streamSize, this);

   152     }

   153 

   154     /**

   155      * Returns an effectively unlimited stream of new pseudorandom

   156      * number generators, each of which implements the {@code SplittableRng}

   157      * interface.

   158      *

   159      * @implNote This method is implemented to be equivalent to

   160      * {@code splits(Long.MAX_VALUE)}.

   161      *

   162      * @param source a {@code SplittableRng} instance to be used instead

   163      *               of this one as a source of pseudorandom bits used to

   164      *               initialize the state of the new ones.

   165      * @return a stream of {@code SplittableRng} objects

   166      */

   167     public Stream<SplittableRng> splits(SplittableRng source) {

   168         return this.splits(Long.MAX_VALUE, source);

   169     }

   170 

   171     /**

   172      * Returns a stream producing the given {@code streamSize} number of

   173      * new pseudorandom number generators, each of which implements the

   174      * {@code SplittableRng} interface.

   175      *

   176      * @param streamSize the number of values to generate

   177      * @param source a {@code SplittableRng} instance to be used instead

   178      *               of this one as a source of pseudorandom bits used to

   179      *               initialize the state of the new ones.

   180      * @return a stream of {@code SplittableRng} objects

   181      * @throws IllegalArgumentException if {@code streamSize} is

   182      *         less than zero

   183      */

   184     public Stream<SplittableRng> splits(long streamSize, SplittableRng source) {

   185 	RngSupport.checkStreamSize(streamSize);

   186         return StreamSupport.stream(makeSplitsSpliterator(0L, streamSize, source), false);

   187     }

   188         

   189     /**

   190      * Spliterator for int streams.  We multiplex the four int

   191      * versions into one class by treating a bound less than origin as

   192      * unbounded, and also by treating "infinite" as equivalent to

   193      * Long.MAX_VALUE. For splits, it uses the standard divide-by-two

   194      * approach. The long and double versions of this class are

   195      * identical except for types.

   196      */

   197     static class RandomIntsSpliterator extends RngSupport.RandomSpliterator implements Spliterator.OfInt {

   198 	final SplittableRng generatingRng;

   199         final int origin;

   200         final int bound;

   201 

   202         RandomIntsSpliterator(SplittableRng generatingRng, long index, long fence, int origin, int bound) {

   203 	    super(index, fence);

   204 	    this.generatingRng = generatingRng;

   205             this.origin = origin; this.bound = bound;

   206         }

   207 	

   208         public Spliterator.OfInt trySplit() {

   209             long i = index, m = (i + fence) >>> 1;

   210 	    if (m <= i) return null;

   211 	    index = m;

   212 	    return new RandomIntsSpliterator(generatingRng.split(), i, m, origin, bound);

   213         }

   214 

   215         public boolean tryAdvance(IntConsumer consumer) {

   216             if (consumer == null) throw new NullPointerException();

   217             long i = index, f = fence;

   218             if (i < f) {

   219                 consumer.accept(RngSupport.boundedNextInt(generatingRng, origin, bound));

   220                 index = i + 1;

   221                 return true;

   222             }

   223             else return false;

   224         }

   225 

   226         public void forEachRemaining(IntConsumer consumer) {

   227             if (consumer == null) throw new NullPointerException();

   228             long i = index, f = fence;

   229             if (i < f) {

   230                 index = f;

   231                 Rng r = generatingRng;

   232                 int o = origin, b = bound;

   233                 do {

   234                     consumer.accept(RngSupport.boundedNextInt(r, o, b));

   235                 } while (++i < f);

   236             }

   237         }

   238     }

   239 

   240     /**

   241      * Spliterator for long streams.

   242      */

   243     static class RandomLongsSpliterator extends RngSupport.RandomSpliterator implements Spliterator.OfLong {

   244 	final SplittableRng generatingRng;

   245         final long origin;

   246         final long bound;

   247 

   248         RandomLongsSpliterator(SplittableRng generatingRng, long index, long fence, long origin, long bound) {

   249 	    super(index, fence);

   250 	    this.generatingRng = generatingRng;

   251             this.origin = origin; this.bound = bound;

   252         }

   253 	

   254         public Spliterator.OfLong trySplit() {

   255             long i = index, m = (i + fence) >>> 1;

   256 	    if (m <= i) return null;

   257 	    index = m;

   258 	    return new RandomLongsSpliterator(generatingRng.split(), i, m, origin, bound);

   259         }

   260 

   261         public boolean tryAdvance(LongConsumer consumer) {

   262             if (consumer == null) throw new NullPointerException();

   263             long i = index, f = fence;

   264             if (i < f) {

   265                 consumer.accept(RngSupport.boundedNextLong(generatingRng, origin, bound));

   266                 index = i + 1;

   267                 return true;

   268             }

   269             else return false;

   270         }

   271 

   272         public void forEachRemaining(LongConsumer consumer) {

   273             if (consumer == null) throw new NullPointerException();

   274             long i = index, f = fence;

   275             if (i < f) {

   276                 index = f;

   277                 Rng r = generatingRng;

   278                 long o = origin, b = bound;

   279                 do {

   280                     consumer.accept(RngSupport.boundedNextLong(r, o, b));

   281                 } while (++i < f);

   282             }

   283         }

   284     }

   285 

   286     /**

   287      * Spliterator for double streams.

   288      */

   289     static class RandomDoublesSpliterator extends RngSupport.RandomSpliterator implements Spliterator.OfDouble {

   290 	final SplittableRng generatingRng;

   291         final double origin;

   292         final double bound;

   293 

   294         RandomDoublesSpliterator(SplittableRng generatingRng, long index, long fence, double origin, double bound) {

   295 	    super(index, fence);

   296 	    this.generatingRng = generatingRng;

   297             this.origin = origin; this.bound = bound;

   298         }

   299 	

   300         public Spliterator.OfDouble trySplit() {

   301             long i = index, m = (i + fence) >>> 1;

   302 	    if (m <= i) return null;

   303 	    index = m;

   304 	    return new RandomDoublesSpliterator(generatingRng.split(), i, m, origin, bound);

   305         }

   306 

   307         public boolean tryAdvance(DoubleConsumer consumer) {

   308             if (consumer == null) throw new NullPointerException();

   309             long i = index, f = fence;

   310             if (i < f) {

   311                 consumer.accept(RngSupport.boundedNextDouble(generatingRng, origin, bound));

   312                 index = i + 1;

   313                 return true;

   314             }

   315             else return false;

   316         }

   317 

   318         public void forEachRemaining(DoubleConsumer consumer) {

   319             if (consumer == null) throw new NullPointerException();

   320             long i = index, f = fence;

   321             if (i < f) {

   322                 index = f;

   323                 Rng r = generatingRng;

   324                 double o = origin, b = bound;

   325                 do {

   326                     consumer.accept(RngSupport.boundedNextDouble(r, o, b));

   327                 } while (++i < f);

   328             }

   329         }

   330     }

   331 

   332     /**

   333      * Spliterator for stream of generators of type SplittableRng.  We multiplex the two

   334      * versions into one class by treating "infinite" as equivalent to Long.MAX_VALUE.

   335      * For splits, it uses the standard divide-by-two approach.

   336      */

   337     static class RandomSplitsSpliterator extends RngSupport.RandomSpliterator implements Spliterator<SplittableRng> {

   338 	final SplittableRng generatingRng;

   339 	final SplittableRng constructingRng;

   340 

   341         RandomSplitsSpliterator(SplittableRng generatingRng, long index, long fence, SplittableRng constructingRng) {

   342 	    super(index, fence);

   343 	    this.generatingRng = generatingRng;

   344 	    this.constructingRng = constructingRng;

   345         }

   346 	

   347         public Spliterator<SplittableRng> trySplit() {

   348             long i = index, m = (i + fence) >>> 1;

   349 	    if (m <= i) return null;

   350 	    index = m;

   351 	    return new RandomSplitsSpliterator(generatingRng.split(), i, m, constructingRng);

   352         }

   353 

   354         public boolean tryAdvance(Consumer<? super SplittableRng> consumer) {

   355             if (consumer == null) throw new NullPointerException();

   356             long i = index, f = fence;

   357             if (i < f) {

   358                 consumer.accept(constructingRng.split(generatingRng));

   359                 index = i + 1;

   360                 return true;

   361             }

   362             else return false;

   363         }

   364 

   365         public void forEachRemaining(Consumer<? super SplittableRng> consumer) {

   366             if (consumer == null) throw new NullPointerException();

   367             long i = index, f = fence;

   368             if (i < f) {

   369                 index = f;

   370 		SplittableRng c = constructingRng;

   371                 SplittableRng r = generatingRng;

   372                 do {

   373                     consumer.accept(c.split(r));

   374                 } while (++i < f);

   375             }

   376         }

   377     }

   378 

   379 }