1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3  *
   4  * This code is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License version 2 only, as
   6  * published by the Free Software Foundation.  Oracle designates this
   7  * particular file as subject to the "Classpath" exception as provided
   8  * by Oracle in the LICENSE file that accompanied this code.
   9  *
  10  * This code is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * version 2 for more details (a copy is included in the LICENSE file that
  14  * accompanied this code).
  15  *
  16  * You should have received a copy of the GNU General Public License version
  17  * 2 along with this work; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  19  *
  20  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  21  * or visit www.oracle.com if you need additional information or have any
  22  * questions.
  23  */
  24 
  25 /*
  26  * This file is available under and governed by the GNU General Public
  27  * License version 2 only, as published by the Free Software Foundation.
  28  * However, the following notice accompanied the original version of this
  29  * file:
  30  *
  31  * Written by Doug Lea with assistance from members of JCP JSR-166
  32  * Expert Group and released to the public domain, as explained at
  33  * http://creativecommons.org/publicdomain/zero/1.0/
  34  */
  35 
  36 package java.util.concurrent;
  37 
  38 import java.io.ObjectStreamField;
  39 import java.security.AccessControlContext;
  40 import java.util.Random;
  41 import java.util.Spliterator;
  42 import java.util.concurrent.atomic.AtomicInteger;
  43 import java.util.concurrent.atomic.AtomicLong;
  44 import java.util.function.DoubleConsumer;
  45 import java.util.function.IntConsumer;
  46 import java.util.function.LongConsumer;
  47 import java.util.stream.DoubleStream;
  48 import java.util.stream.IntStream;
  49 import java.util.stream.LongStream;
  50 import java.util.stream.StreamSupport;
  51 import jdk.internal.misc.Unsafe;
  52 import jdk.internal.misc.VM;
  53 
  54 /**
  55  * A random number generator isolated to the current thread.  Like the
  56  * global {@link java.util.Random} generator used by the {@link
  57  * java.lang.Math} class, a {@code ThreadLocalRandom} is initialized
  58  * with an internally generated seed that may not otherwise be
  59  * modified. When applicable, use of {@code ThreadLocalRandom} rather
  60  * than shared {@code Random} objects in concurrent programs will
  61  * typically encounter much less overhead and contention.  Use of
  62  * {@code ThreadLocalRandom} is particularly appropriate when multiple
  63  * tasks (for example, each a {@link ForkJoinTask}) use random numbers
  64  * in parallel in thread pools.
  65  *
  66  * <p>Usages of this class should typically be of the form:
  67  * {@code ThreadLocalRandom.current().nextX(...)} (where
  68  * {@code X} is {@code Int}, {@code Long}, etc).
  69  * When all usages are of this form, it is never possible to
  70  * accidentally share a {@code ThreadLocalRandom} across multiple threads.
  71  *
  72  * <p>This class also provides additional commonly used bounded random
  73  * generation methods.
  74  *
  75  * <p>Instances of {@code ThreadLocalRandom} are not cryptographically
  76  * secure.  Consider instead using {@link java.security.SecureRandom}
  77  * in security-sensitive applications. Additionally,
  78  * default-constructed instances do not use a cryptographically random
  79  * seed unless the {@linkplain System#getProperty system property}
  80  * {@code java.util.secureRandomSeed} is set to {@code true}.
  81  *
  82  * @since 1.7
  83  * @author Doug Lea
  84  */
  85 public class ThreadLocalRandom extends Random {
  86     /*
  87      * This class implements the java.util.Random API (and subclasses
  88      * Random) using a single static instance that accesses random
  89      * number state held in class Thread (primarily, field
  90      * threadLocalRandomSeed). In doing so, it also provides a home
  91      * for managing package-private utilities that rely on exactly the
  92      * same state as needed to maintain the ThreadLocalRandom
  93      * instances. We leverage the need for an initialization flag
  94      * field to also use it as a "probe" -- a self-adjusting thread
  95      * hash used for contention avoidance, as well as a secondary
  96      * simpler (xorShift) random seed that is conservatively used to
  97      * avoid otherwise surprising users by hijacking the
  98      * ThreadLocalRandom sequence.  The dual use is a marriage of
  99      * convenience, but is a simple and efficient way of reducing
 100      * application-level overhead and footprint of most concurrent
 101      * programs. Even more opportunistically, we also define here
 102      * other package-private utilities that access Thread class
 103      * fields.
 104      *
 105      * Even though this class subclasses java.util.Random, it uses the
 106      * same basic algorithm as java.util.SplittableRandom.  (See its
 107      * internal documentation for explanations, which are not repeated
 108      * here.)  Because ThreadLocalRandoms are not splittable
 109      * though, we use only a single 64bit gamma.
 110      *
 111      * Because this class is in a different package than class Thread,
 112      * field access methods use Unsafe to bypass access control rules.
 113      * To conform to the requirements of the Random superclass
 114      * constructor, the common static ThreadLocalRandom maintains an
 115      * "initialized" field for the sake of rejecting user calls to
 116      * setSeed while still allowing a call from constructor.  Note
 117      * that serialization is completely unnecessary because there is
 118      * only a static singleton.  But we generate a serial form
 119      * containing "rnd" and "initialized" fields to ensure
 120      * compatibility across versions.
 121      *
 122      * Implementations of non-core methods are mostly the same as in
 123      * SplittableRandom, that were in part derived from a previous
 124      * version of this class.
 125      *
 126      * The nextLocalGaussian ThreadLocal supports the very rarely used
 127      * nextGaussian method by providing a holder for the second of a
 128      * pair of them. As is true for the base class version of this
 129      * method, this time/space tradeoff is probably never worthwhile,
 130      * but we provide identical statistical properties.
 131      */
 132 
 133     private static long mix64(long z) {
 134         z = (z ^ (z >>> 33)) * 0xff51afd7ed558ccdL;
 135         z = (z ^ (z >>> 33)) * 0xc4ceb9fe1a85ec53L;
 136         return z ^ (z >>> 33);
 137     }
 138 
 139     private static int mix32(long z) {
 140         z = (z ^ (z >>> 33)) * 0xff51afd7ed558ccdL;
 141         return (int)(((z ^ (z >>> 33)) * 0xc4ceb9fe1a85ec53L) >>> 32);
 142     }
 143 
 144     /**
 145      * Field used only during singleton initialization.
 146      * True when constructor completes.
 147      */
 148     boolean initialized;
 149 
 150     /** Constructor used only for static singleton */
 151     private ThreadLocalRandom() {
 152         initialized = true; // false during super() call
 153     }
 154 
 155     /**
 156      * Initialize Thread fields for the current thread.  Called only
 157      * when Thread.threadLocalRandomProbe is zero, indicating that a
 158      * thread local seed value needs to be generated. Note that even
 159      * though the initialization is purely thread-local, we need to
 160      * rely on (static) atomic generators to initialize the values.
 161      */
 162     static final void localInit() {
 163         int p = probeGenerator.addAndGet(PROBE_INCREMENT);
 164         int probe = (p == 0) ? 1 : p; // skip 0
 165         long seed = mix64(seeder.getAndAdd(SEEDER_INCREMENT));
 166         Thread t = Thread.currentThread();
 167         U.putLong(t, SEED, seed);
 168         U.putInt(t, PROBE, probe);
 169     }
 170 
 171     /**
 172      * Returns the current thread's {@code ThreadLocalRandom}.
 173      *
 174      * @return the current thread's {@code ThreadLocalRandom}
 175      */
 176     public static ThreadLocalRandom current() {
 177         if (U.getInt(Thread.currentThread(), PROBE) == 0)
 178             localInit();
 179         return instance;
 180     }
 181 
 182     /**
 183      * Throws {@code UnsupportedOperationException}.  Setting seeds in
 184      * this generator is not supported.
 185      *
 186      * @throws UnsupportedOperationException always
 187      */
 188     public void setSeed(long seed) {
 189         // only allow call from super() constructor
 190         if (initialized)
 191             throw new UnsupportedOperationException();
 192     }
 193 
 194     final long nextSeed() {
 195         Thread t; long r; // read and update per-thread seed
 196         U.putLong(t = Thread.currentThread(), SEED,
 197                   r = U.getLong(t, SEED) + GAMMA);
 198         return r;
 199     }
 200 
 201     /**
 202      * Generates a pseudorandom number with the indicated number of
 203      * low-order bits.  Because this class has no subclasses, this
 204      * method cannot be invoked or overridden.
 205      *
 206      * @param  bits random bits
 207      * @return the next pseudorandom value from this random number
 208      *         generator's sequence
 209      */
 210     protected int next(int bits) {
 211         return nextInt() >>> (32 - bits);
 212     }
 213 
 214     /**
 215      * The form of nextLong used by LongStream Spliterators.  If
 216      * origin is greater than bound, acts as unbounded form of
 217      * nextLong, else as bounded form.
 218      *
 219      * @param origin the least value, unless greater than bound
 220      * @param bound the upper bound (exclusive), must not equal origin
 221      * @return a pseudorandom value
 222      */
 223     final long internalNextLong(long origin, long bound) {
 224         long r = mix64(nextSeed());
 225         if (origin < bound) {
 226             long n = bound - origin, m = n - 1;
 227             if ((n & m) == 0L)  // power of two
 228                 r = (r & m) + origin;
 229             else if (n > 0L) {  // reject over-represented candidates
 230                 for (long u = r >>> 1;            // ensure nonnegative
 231                      u + m - (r = u % n) < 0L;    // rejection check
 232                      u = mix64(nextSeed()) >>> 1) // retry
 233                     ;
 234                 r += origin;
 235             }
 236             else {              // range not representable as long
 237                 while (r < origin || r >= bound)
 238                     r = mix64(nextSeed());
 239             }
 240         }
 241         return r;
 242     }
 243 
 244     /**
 245      * The form of nextInt used by IntStream Spliterators.
 246      * Exactly the same as long version, except for types.
 247      *
 248      * @param origin the least value, unless greater than bound
 249      * @param bound the upper bound (exclusive), must not equal origin
 250      * @return a pseudorandom value
 251      */
 252     final int internalNextInt(int origin, int bound) {
 253         int r = mix32(nextSeed());
 254         if (origin < bound) {
 255             int n = bound - origin, m = n - 1;
 256             if ((n & m) == 0)
 257                 r = (r & m) + origin;
 258             else if (n > 0) {
 259                 for (int u = r >>> 1;
 260                      u + m - (r = u % n) < 0;
 261                      u = mix32(nextSeed()) >>> 1)
 262                     ;
 263                 r += origin;
 264             }
 265             else {
 266                 while (r < origin || r >= bound)
 267                     r = mix32(nextSeed());
 268             }
 269         }
 270         return r;
 271     }
 272 
 273     /**
 274      * The form of nextDouble used by DoubleStream Spliterators.
 275      *
 276      * @param origin the least value, unless greater than bound
 277      * @param bound the upper bound (exclusive), must not equal origin
 278      * @return a pseudorandom value
 279      */
 280     final double internalNextDouble(double origin, double bound) {
 281         double r = (nextLong() >>> 11) * DOUBLE_UNIT;
 282         if (origin < bound) {
 283             r = r * (bound - origin) + origin;
 284             if (r >= bound) // correct for rounding
 285                 r = Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1);
 286         }
 287         return r;
 288     }
 289 
 290     /**
 291      * Returns a pseudorandom {@code int} value.
 292      *
 293      * @return a pseudorandom {@code int} value
 294      */
 295     public int nextInt() {
 296         return mix32(nextSeed());
 297     }
 298 
 299     /**
 300      * Returns a pseudorandom {@code int} value between zero (inclusive)
 301      * and the specified bound (exclusive).
 302      *
 303      * @param bound the upper bound (exclusive).  Must be positive.
 304      * @return a pseudorandom {@code int} value between zero
 305      *         (inclusive) and the bound (exclusive)
 306      * @throws IllegalArgumentException if {@code bound} is not positive
 307      */
 308     public int nextInt(int bound) {
 309         if (bound <= 0)
 310             throw new IllegalArgumentException(BAD_BOUND);
 311         int r = mix32(nextSeed());
 312         int m = bound - 1;
 313         if ((bound & m) == 0) // power of two
 314             r &= m;
 315         else { // reject over-represented candidates
 316             for (int u = r >>> 1;
 317                  u + m - (r = u % bound) < 0;
 318                  u = mix32(nextSeed()) >>> 1)
 319                 ;
 320         }
 321         return r;
 322     }
 323 
 324     /**
 325      * Returns a pseudorandom {@code int} value between the specified
 326      * origin (inclusive) and the specified bound (exclusive).
 327      *
 328      * @param origin the least value returned
 329      * @param bound the upper bound (exclusive)
 330      * @return a pseudorandom {@code int} value between the origin
 331      *         (inclusive) and the bound (exclusive)
 332      * @throws IllegalArgumentException if {@code origin} is greater than
 333      *         or equal to {@code bound}
 334      */
 335     public int nextInt(int origin, int bound) {
 336         if (origin >= bound)
 337             throw new IllegalArgumentException(BAD_RANGE);
 338         return internalNextInt(origin, bound);
 339     }
 340 
 341     /**
 342      * Returns a pseudorandom {@code long} value.
 343      *
 344      * @return a pseudorandom {@code long} value
 345      */
 346     public long nextLong() {
 347         return mix64(nextSeed());
 348     }
 349 
 350     /**
 351      * Returns a pseudorandom {@code long} value between zero (inclusive)
 352      * and the specified bound (exclusive).
 353      *
 354      * @param bound the upper bound (exclusive).  Must be positive.
 355      * @return a pseudorandom {@code long} value between zero
 356      *         (inclusive) and the bound (exclusive)
 357      * @throws IllegalArgumentException if {@code bound} is not positive
 358      */
 359     public long nextLong(long bound) {
 360         if (bound <= 0)
 361             throw new IllegalArgumentException(BAD_BOUND);
 362         long r = mix64(nextSeed());
 363         long m = bound - 1;
 364         if ((bound & m) == 0L) // power of two
 365             r &= m;
 366         else { // reject over-represented candidates
 367             for (long u = r >>> 1;
 368                  u + m - (r = u % bound) < 0L;
 369                  u = mix64(nextSeed()) >>> 1)
 370                 ;
 371         }
 372         return r;
 373     }
 374 
 375     /**
 376      * Returns a pseudorandom {@code long} value between the specified
 377      * origin (inclusive) and the specified bound (exclusive).
 378      *
 379      * @param origin the least value returned
 380      * @param bound the upper bound (exclusive)
 381      * @return a pseudorandom {@code long} value between the origin
 382      *         (inclusive) and the bound (exclusive)
 383      * @throws IllegalArgumentException if {@code origin} is greater than
 384      *         or equal to {@code bound}
 385      */
 386     public long nextLong(long origin, long bound) {
 387         if (origin >= bound)
 388             throw new IllegalArgumentException(BAD_RANGE);
 389         return internalNextLong(origin, bound);
 390     }
 391 
 392     /**
 393      * Returns a pseudorandom {@code double} value between zero
 394      * (inclusive) and one (exclusive).
 395      *
 396      * @return a pseudorandom {@code double} value between zero
 397      *         (inclusive) and one (exclusive)
 398      */
 399     public double nextDouble() {
 400         return (mix64(nextSeed()) >>> 11) * DOUBLE_UNIT;
 401     }
 402 
 403     /**
 404      * Returns a pseudorandom {@code double} value between 0.0
 405      * (inclusive) and the specified bound (exclusive).
 406      *
 407      * @param bound the upper bound (exclusive).  Must be positive.
 408      * @return a pseudorandom {@code double} value between zero
 409      *         (inclusive) and the bound (exclusive)
 410      * @throws IllegalArgumentException if {@code bound} is not positive
 411      */
 412     public double nextDouble(double bound) {
 413         if (!(bound > 0.0))
 414             throw new IllegalArgumentException(BAD_BOUND);
 415         double result = (mix64(nextSeed()) >>> 11) * DOUBLE_UNIT * bound;
 416         return (result < bound) ? result : // correct for rounding
 417             Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1);
 418     }
 419 
 420     /**
 421      * Returns a pseudorandom {@code double} value between the specified
 422      * origin (inclusive) and bound (exclusive).
 423      *
 424      * @param origin the least value returned
 425      * @param bound the upper bound (exclusive)
 426      * @return a pseudorandom {@code double} value between the origin
 427      *         (inclusive) and the bound (exclusive)
 428      * @throws IllegalArgumentException if {@code origin} is greater than
 429      *         or equal to {@code bound}
 430      */
 431     public double nextDouble(double origin, double bound) {
 432         if (!(origin < bound))
 433             throw new IllegalArgumentException(BAD_RANGE);
 434         return internalNextDouble(origin, bound);
 435     }
 436 
 437     /**
 438      * Returns a pseudorandom {@code boolean} value.
 439      *
 440      * @return a pseudorandom {@code boolean} value
 441      */
 442     public boolean nextBoolean() {
 443         return mix32(nextSeed()) < 0;
 444     }
 445 
 446     /**
 447      * Returns a pseudorandom {@code float} value between zero
 448      * (inclusive) and one (exclusive).
 449      *
 450      * @return a pseudorandom {@code float} value between zero
 451      *         (inclusive) and one (exclusive)
 452      */
 453     public float nextFloat() {
 454         return (mix32(nextSeed()) >>> 8) * FLOAT_UNIT;
 455     }
 456 
 457     public double nextGaussian() {
 458         // Use nextLocalGaussian instead of nextGaussian field
 459         Double d = nextLocalGaussian.get();
 460         if (d != null) {
 461             nextLocalGaussian.set(null);
 462             return d.doubleValue();
 463         }
 464         double v1, v2, s;
 465         do {
 466             v1 = 2 * nextDouble() - 1; // between -1 and 1
 467             v2 = 2 * nextDouble() - 1; // between -1 and 1
 468             s = v1 * v1 + v2 * v2;
 469         } while (s >= 1 || s == 0);
 470         double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s);
 471         nextLocalGaussian.set(Double.valueOf(v2 * multiplier));
 472         return v1 * multiplier;
 473     }
 474 
 475     // stream methods, coded in a way intended to better isolate for
 476     // maintenance purposes the small differences across forms.
 477 
 478     /**
 479      * Returns a stream producing the given {@code streamSize} number of
 480      * pseudorandom {@code int} values.
 481      *
 482      * @param streamSize the number of values to generate
 483      * @return a stream of pseudorandom {@code int} values
 484      * @throws IllegalArgumentException if {@code streamSize} is
 485      *         less than zero
 486      * @since 1.8
 487      */
 488     public IntStream ints(long streamSize) {
 489         if (streamSize < 0L)
 490             throw new IllegalArgumentException(BAD_SIZE);
 491         return StreamSupport.intStream
 492             (new RandomIntsSpliterator
 493              (0L, streamSize, Integer.MAX_VALUE, 0),
 494              false);
 495     }
 496 
 497     /**
 498      * Returns an effectively unlimited stream of pseudorandom {@code int}
 499      * values.
 500      *
 501      * @implNote This method is implemented to be equivalent to {@code
 502      * ints(Long.MAX_VALUE)}.
 503      *
 504      * @return a stream of pseudorandom {@code int} values
 505      * @since 1.8
 506      */
 507     public IntStream ints() {
 508         return StreamSupport.intStream
 509             (new RandomIntsSpliterator
 510              (0L, Long.MAX_VALUE, Integer.MAX_VALUE, 0),
 511              false);
 512     }
 513 
 514     /**
 515      * Returns a stream producing the given {@code streamSize} number
 516      * of pseudorandom {@code int} values, each conforming to the given
 517      * origin (inclusive) and bound (exclusive).
 518      *
 519      * @param streamSize the number of values to generate
 520      * @param randomNumberOrigin the origin (inclusive) of each random value
 521      * @param randomNumberBound the bound (exclusive) of each random value
 522      * @return a stream of pseudorandom {@code int} values,
 523      *         each with the given origin (inclusive) and bound (exclusive)
 524      * @throws IllegalArgumentException if {@code streamSize} is
 525      *         less than zero, or {@code randomNumberOrigin}
 526      *         is greater than or equal to {@code randomNumberBound}
 527      * @since 1.8
 528      */
 529     public IntStream ints(long streamSize, int randomNumberOrigin,
 530                           int randomNumberBound) {
 531         if (streamSize < 0L)
 532             throw new IllegalArgumentException(BAD_SIZE);
 533         if (randomNumberOrigin >= randomNumberBound)
 534             throw new IllegalArgumentException(BAD_RANGE);
 535         return StreamSupport.intStream
 536             (new RandomIntsSpliterator
 537              (0L, streamSize, randomNumberOrigin, randomNumberBound),
 538              false);
 539     }
 540 
 541     /**
 542      * Returns an effectively unlimited stream of pseudorandom {@code
 543      * int} values, each conforming to the given origin (inclusive) and bound
 544      * (exclusive).
 545      *
 546      * @implNote This method is implemented to be equivalent to {@code
 547      * ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
 548      *
 549      * @param randomNumberOrigin the origin (inclusive) of each random value
 550      * @param randomNumberBound the bound (exclusive) of each random value
 551      * @return a stream of pseudorandom {@code int} values,
 552      *         each with the given origin (inclusive) and bound (exclusive)
 553      * @throws IllegalArgumentException if {@code randomNumberOrigin}
 554      *         is greater than or equal to {@code randomNumberBound}
 555      * @since 1.8
 556      */
 557     public IntStream ints(int randomNumberOrigin, int randomNumberBound) {
 558         if (randomNumberOrigin >= randomNumberBound)
 559             throw new IllegalArgumentException(BAD_RANGE);
 560         return StreamSupport.intStream
 561             (new RandomIntsSpliterator
 562              (0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),
 563              false);
 564     }
 565 
 566     /**
 567      * Returns a stream producing the given {@code streamSize} number of
 568      * pseudorandom {@code long} values.
 569      *
 570      * @param streamSize the number of values to generate
 571      * @return a stream of pseudorandom {@code long} values
 572      * @throws IllegalArgumentException if {@code streamSize} is
 573      *         less than zero
 574      * @since 1.8
 575      */
 576     public LongStream longs(long streamSize) {
 577         if (streamSize < 0L)
 578             throw new IllegalArgumentException(BAD_SIZE);
 579         return StreamSupport.longStream
 580             (new RandomLongsSpliterator
 581              (0L, streamSize, Long.MAX_VALUE, 0L),
 582              false);
 583     }
 584 
 585     /**
 586      * Returns an effectively unlimited stream of pseudorandom {@code long}
 587      * values.
 588      *
 589      * @implNote This method is implemented to be equivalent to {@code
 590      * longs(Long.MAX_VALUE)}.
 591      *
 592      * @return a stream of pseudorandom {@code long} values
 593      * @since 1.8
 594      */
 595     public LongStream longs() {
 596         return StreamSupport.longStream
 597             (new RandomLongsSpliterator
 598              (0L, Long.MAX_VALUE, Long.MAX_VALUE, 0L),
 599              false);
 600     }
 601 
 602     /**
 603      * Returns a stream producing the given {@code streamSize} number of
 604      * pseudorandom {@code long}, each conforming to the given origin
 605      * (inclusive) and bound (exclusive).
 606      *
 607      * @param streamSize the number of values to generate
 608      * @param randomNumberOrigin the origin (inclusive) of each random value
 609      * @param randomNumberBound the bound (exclusive) of each random value
 610      * @return a stream of pseudorandom {@code long} values,
 611      *         each with the given origin (inclusive) and bound (exclusive)
 612      * @throws IllegalArgumentException if {@code streamSize} is
 613      *         less than zero, or {@code randomNumberOrigin}
 614      *         is greater than or equal to {@code randomNumberBound}
 615      * @since 1.8
 616      */
 617     public LongStream longs(long streamSize, long randomNumberOrigin,
 618                             long randomNumberBound) {
 619         if (streamSize < 0L)
 620             throw new IllegalArgumentException(BAD_SIZE);
 621         if (randomNumberOrigin >= randomNumberBound)
 622             throw new IllegalArgumentException(BAD_RANGE);
 623         return StreamSupport.longStream
 624             (new RandomLongsSpliterator
 625              (0L, streamSize, randomNumberOrigin, randomNumberBound),
 626              false);
 627     }
 628 
 629     /**
 630      * Returns an effectively unlimited stream of pseudorandom {@code
 631      * long} values, each conforming to the given origin (inclusive) and bound
 632      * (exclusive).
 633      *
 634      * @implNote This method is implemented to be equivalent to {@code
 635      * longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
 636      *
 637      * @param randomNumberOrigin the origin (inclusive) of each random value
 638      * @param randomNumberBound the bound (exclusive) of each random value
 639      * @return a stream of pseudorandom {@code long} values,
 640      *         each with the given origin (inclusive) and bound (exclusive)
 641      * @throws IllegalArgumentException if {@code randomNumberOrigin}
 642      *         is greater than or equal to {@code randomNumberBound}
 643      * @since 1.8
 644      */
 645     public LongStream longs(long randomNumberOrigin, long randomNumberBound) {
 646         if (randomNumberOrigin >= randomNumberBound)
 647             throw new IllegalArgumentException(BAD_RANGE);
 648         return StreamSupport.longStream
 649             (new RandomLongsSpliterator
 650              (0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),
 651              false);
 652     }
 653 
 654     /**
 655      * Returns a stream producing the given {@code streamSize} number of
 656      * pseudorandom {@code double} values, each between zero
 657      * (inclusive) and one (exclusive).
 658      *
 659      * @param streamSize the number of values to generate
 660      * @return a stream of {@code double} values
 661      * @throws IllegalArgumentException if {@code streamSize} is
 662      *         less than zero
 663      * @since 1.8
 664      */
 665     public DoubleStream doubles(long streamSize) {
 666         if (streamSize < 0L)
 667             throw new IllegalArgumentException(BAD_SIZE);
 668         return StreamSupport.doubleStream
 669             (new RandomDoublesSpliterator
 670              (0L, streamSize, Double.MAX_VALUE, 0.0),
 671              false);
 672     }
 673 
 674     /**
 675      * Returns an effectively unlimited stream of pseudorandom {@code
 676      * double} values, each between zero (inclusive) and one
 677      * (exclusive).
 678      *
 679      * @implNote This method is implemented to be equivalent to {@code
 680      * doubles(Long.MAX_VALUE)}.
 681      *
 682      * @return a stream of pseudorandom {@code double} values
 683      * @since 1.8
 684      */
 685     public DoubleStream doubles() {
 686         return StreamSupport.doubleStream
 687             (new RandomDoublesSpliterator
 688              (0L, Long.MAX_VALUE, Double.MAX_VALUE, 0.0),
 689              false);
 690     }
 691 
 692     /**
 693      * Returns a stream producing the given {@code streamSize} number of
 694      * pseudorandom {@code double} values, each conforming to the given origin
 695      * (inclusive) and bound (exclusive).
 696      *
 697      * @param streamSize the number of values to generate
 698      * @param randomNumberOrigin the origin (inclusive) of each random value
 699      * @param randomNumberBound the bound (exclusive) of each random value
 700      * @return a stream of pseudorandom {@code double} values,
 701      *         each with the given origin (inclusive) and bound (exclusive)
 702      * @throws IllegalArgumentException if {@code streamSize} is
 703      *         less than zero, or {@code randomNumberOrigin}
 704      *         is greater than or equal to {@code randomNumberBound}
 705      * @since 1.8
 706      */
 707     public DoubleStream doubles(long streamSize, double randomNumberOrigin,
 708                                 double randomNumberBound) {
 709         if (streamSize < 0L)
 710             throw new IllegalArgumentException(BAD_SIZE);
 711         if (!(randomNumberOrigin < randomNumberBound))
 712             throw new IllegalArgumentException(BAD_RANGE);
 713         return StreamSupport.doubleStream
 714             (new RandomDoublesSpliterator
 715              (0L, streamSize, randomNumberOrigin, randomNumberBound),
 716              false);
 717     }
 718 
 719     /**
 720      * Returns an effectively unlimited stream of pseudorandom {@code
 721      * double} values, each conforming to the given origin (inclusive) and bound
 722      * (exclusive).
 723      *
 724      * @implNote This method is implemented to be equivalent to {@code
 725      * doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
 726      *
 727      * @param randomNumberOrigin the origin (inclusive) of each random value
 728      * @param randomNumberBound the bound (exclusive) of each random value
 729      * @return a stream of pseudorandom {@code double} values,
 730      *         each with the given origin (inclusive) and bound (exclusive)
 731      * @throws IllegalArgumentException if {@code randomNumberOrigin}
 732      *         is greater than or equal to {@code randomNumberBound}
 733      * @since 1.8
 734      */
 735     public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) {
 736         if (!(randomNumberOrigin < randomNumberBound))
 737             throw new IllegalArgumentException(BAD_RANGE);
 738         return StreamSupport.doubleStream
 739             (new RandomDoublesSpliterator
 740              (0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),
 741              false);
 742     }
 743 
 744     /**
 745      * Spliterator for int streams.  We multiplex the four int
 746      * versions into one class by treating a bound less than origin as
 747      * unbounded, and also by treating "infinite" as equivalent to
 748      * Long.MAX_VALUE. For splits, it uses the standard divide-by-two
 749      * approach. The long and double versions of this class are
 750      * identical except for types.
 751      */
 752     private static final class RandomIntsSpliterator
 753             implements Spliterator.OfInt {
 754         long index;
 755         final long fence;
 756         final int origin;
 757         final int bound;
 758         RandomIntsSpliterator(long index, long fence,
 759                               int origin, int bound) {
 760             this.index = index; this.fence = fence;
 761             this.origin = origin; this.bound = bound;
 762         }
 763 
 764         public RandomIntsSpliterator trySplit() {
 765             long i = index, m = (i + fence) >>> 1;
 766             return (m <= i) ? null :
 767                 new RandomIntsSpliterator(i, index = m, origin, bound);
 768         }
 769 
 770         public long estimateSize() {
 771             return fence - index;
 772         }
 773 
 774         public int characteristics() {
 775             return (Spliterator.SIZED | Spliterator.SUBSIZED |
 776                     Spliterator.NONNULL | Spliterator.IMMUTABLE);
 777         }
 778 
 779         public boolean tryAdvance(IntConsumer consumer) {
 780             if (consumer == null) throw new NullPointerException();
 781             long i = index, f = fence;
 782             if (i < f) {
 783                 consumer.accept(ThreadLocalRandom.current().internalNextInt(origin, bound));
 784                 index = i + 1;
 785                 return true;
 786             }
 787             return false;
 788         }
 789 
 790         public void forEachRemaining(IntConsumer consumer) {
 791             if (consumer == null) throw new NullPointerException();
 792             long i = index, f = fence;
 793             if (i < f) {
 794                 index = f;
 795                 int o = origin, b = bound;
 796                 ThreadLocalRandom rng = ThreadLocalRandom.current();
 797                 do {
 798                     consumer.accept(rng.internalNextInt(o, b));
 799                 } while (++i < f);
 800             }
 801         }
 802     }
 803 
 804     /**
 805      * Spliterator for long streams.
 806      */
 807     private static final class RandomLongsSpliterator
 808             implements Spliterator.OfLong {
 809         long index;
 810         final long fence;
 811         final long origin;
 812         final long bound;
 813         RandomLongsSpliterator(long index, long fence,
 814                                long origin, long bound) {
 815             this.index = index; this.fence = fence;
 816             this.origin = origin; this.bound = bound;
 817         }
 818 
 819         public RandomLongsSpliterator trySplit() {
 820             long i = index, m = (i + fence) >>> 1;
 821             return (m <= i) ? null :
 822                 new RandomLongsSpliterator(i, index = m, origin, bound);
 823         }
 824 
 825         public long estimateSize() {
 826             return fence - index;
 827         }
 828 
 829         public int characteristics() {
 830             return (Spliterator.SIZED | Spliterator.SUBSIZED |
 831                     Spliterator.NONNULL | Spliterator.IMMUTABLE);
 832         }
 833 
 834         public boolean tryAdvance(LongConsumer consumer) {
 835             if (consumer == null) throw new NullPointerException();
 836             long i = index, f = fence;
 837             if (i < f) {
 838                 consumer.accept(ThreadLocalRandom.current().internalNextLong(origin, bound));
 839                 index = i + 1;
 840                 return true;
 841             }
 842             return false;
 843         }
 844 
 845         public void forEachRemaining(LongConsumer consumer) {
 846             if (consumer == null) throw new NullPointerException();
 847             long i = index, f = fence;
 848             if (i < f) {
 849                 index = f;
 850                 long o = origin, b = bound;
 851                 ThreadLocalRandom rng = ThreadLocalRandom.current();
 852                 do {
 853                     consumer.accept(rng.internalNextLong(o, b));
 854                 } while (++i < f);
 855             }
 856         }
 857 
 858     }
 859 
 860     /**
 861      * Spliterator for double streams.
 862      */
 863     private static final class RandomDoublesSpliterator
 864             implements Spliterator.OfDouble {
 865         long index;
 866         final long fence;
 867         final double origin;
 868         final double bound;
 869         RandomDoublesSpliterator(long index, long fence,
 870                                  double origin, double bound) {
 871             this.index = index; this.fence = fence;
 872             this.origin = origin; this.bound = bound;
 873         }
 874 
 875         public RandomDoublesSpliterator trySplit() {
 876             long i = index, m = (i + fence) >>> 1;
 877             return (m <= i) ? null :
 878                 new RandomDoublesSpliterator(i, index = m, origin, bound);
 879         }
 880 
 881         public long estimateSize() {
 882             return fence - index;
 883         }
 884 
 885         public int characteristics() {
 886             return (Spliterator.SIZED | Spliterator.SUBSIZED |
 887                     Spliterator.NONNULL | Spliterator.IMMUTABLE);
 888         }
 889 
 890         public boolean tryAdvance(DoubleConsumer consumer) {
 891             if (consumer == null) throw new NullPointerException();
 892             long i = index, f = fence;
 893             if (i < f) {
 894                 consumer.accept(ThreadLocalRandom.current().internalNextDouble(origin, bound));
 895                 index = i + 1;
 896                 return true;
 897             }
 898             return false;
 899         }
 900 
 901         public void forEachRemaining(DoubleConsumer consumer) {
 902             if (consumer == null) throw new NullPointerException();
 903             long i = index, f = fence;
 904             if (i < f) {
 905                 index = f;
 906                 double o = origin, b = bound;
 907                 ThreadLocalRandom rng = ThreadLocalRandom.current();
 908                 do {
 909                     consumer.accept(rng.internalNextDouble(o, b));
 910                 } while (++i < f);
 911             }
 912         }
 913     }
 914 
 915 
 916     // Within-package utilities
 917 
 918     /*
 919      * Descriptions of the usages of the methods below can be found in
 920      * the classes that use them. Briefly, a thread's "probe" value is
 921      * a non-zero hash code that (probably) does not collide with
 922      * other existing threads with respect to any power of two
 923      * collision space. When it does collide, it is pseudo-randomly
 924      * adjusted (using a Marsaglia XorShift). The nextSecondarySeed
 925      * method is used in the same contexts as ThreadLocalRandom, but
 926      * only for transient usages such as random adaptive spin/block
 927      * sequences for which a cheap RNG suffices and for which it could
 928      * in principle disrupt user-visible statistical properties of the
 929      * main ThreadLocalRandom if we were to use it.
 930      *
 931      * Note: Because of package-protection issues, versions of some
 932      * these methods also appear in some subpackage classes.
 933      */
 934 
 935     /**
 936      * Returns the probe value for the current thread without forcing
 937      * initialization. Note that invoking ThreadLocalRandom.current()
 938      * can be used to force initialization on zero return.
 939      */
 940     static final int getProbe() {
 941         return U.getInt(Thread.currentThread(), PROBE);
 942     }
 943 
 944     /**
 945      * Pseudo-randomly advances and records the given probe value for the
 946      * given thread.
 947      */
 948     static final int advanceProbe(int probe) {
 949         probe ^= probe << 13;   // xorshift
 950         probe ^= probe >>> 17;
 951         probe ^= probe << 5;
 952         U.putInt(Thread.currentThread(), PROBE, probe);
 953         return probe;
 954     }
 955 
 956     /**
 957      * Returns the pseudo-randomly initialized or updated secondary seed.
 958      */
 959     static final int nextSecondarySeed() {
 960         int r;
 961         Thread t = Thread.currentThread();
 962         if ((r = U.getInt(t, SECONDARY)) != 0) {
 963             r ^= r << 13;   // xorshift
 964             r ^= r >>> 17;
 965             r ^= r << 5;
 966         }
 967         else if ((r = mix32(seeder.getAndAdd(SEEDER_INCREMENT))) == 0)
 968             r = 1; // avoid zero
 969         U.putInt(t, SECONDARY, r);
 970         return r;
 971     }
 972 
 973     // Support for other package-private ThreadLocal access
 974 
 975     /**
 976      * Erases ThreadLocals by nulling out Thread maps.
 977      */
 978     static final void eraseThreadLocals(Thread thread) {
 979         U.putReference(thread, THREADLOCALS, null);
 980         U.putReference(thread, INHERITABLETHREADLOCALS, null);
 981     }
 982 
 983     static final void setInheritedAccessControlContext(Thread thread,
 984                                                        AccessControlContext acc) {
 985         U.putReferenceRelease(thread, INHERITEDACCESSCONTROLCONTEXT, acc);
 986     }
 987 
 988     // Serialization support
 989 
 990     private static final long serialVersionUID = -5851777807851030925L;
 991 
 992     /**
 993      * @serialField rnd long
 994      *              seed for random computations
 995      * @serialField initialized boolean
 996      *              always true
 997      */
 998     private static final ObjectStreamField[] serialPersistentFields = {
 999         new ObjectStreamField("rnd", long.class),
1000         new ObjectStreamField("initialized", boolean.class),
1001     };
1002 
1003     /**
1004      * Saves the {@code ThreadLocalRandom} to a stream (that is, serializes it).
1005      * @param s the stream
1006      * @throws java.io.IOException if an I/O error occurs
1007      */
1008     private void writeObject(java.io.ObjectOutputStream s)
1009         throws java.io.IOException {
1010 
1011         java.io.ObjectOutputStream.PutField fields = s.putFields();
1012         fields.put("rnd", U.getLong(Thread.currentThread(), SEED));
1013         fields.put("initialized", true);
1014         s.writeFields();
1015     }
1016 
1017     /**
1018      * Returns the {@link #current() current} thread's {@code ThreadLocalRandom}.
1019      * @return the {@link #current() current} thread's {@code ThreadLocalRandom}
1020      */
1021     private Object readResolve() {
1022         return current();
1023     }
1024 
1025     // Static initialization
1026 
1027     /**
1028      * The seed increment.
1029      */
1030     private static final long GAMMA = 0x9e3779b97f4a7c15L;
1031 
1032     /**
1033      * The increment for generating probe values.
1034      */
1035     private static final int PROBE_INCREMENT = 0x9e3779b9;
1036 
1037     /**
1038      * The increment of seeder per new instance.
1039      */
1040     private static final long SEEDER_INCREMENT = 0xbb67ae8584caa73bL;
1041 
1042     /**
1043      * The least non-zero value returned by nextDouble(). This value
1044      * is scaled by a random value of 53 bits to produce a result.
1045      */
1046     private static final double DOUBLE_UNIT = 0x1.0p-53;  // 1.0  / (1L << 53)
1047     private static final float  FLOAT_UNIT  = 0x1.0p-24f; // 1.0f / (1 << 24)
1048 
1049     // IllegalArgumentException messages
1050     static final String BAD_BOUND = "bound must be positive";
1051     static final String BAD_RANGE = "bound must be greater than origin";
1052     static final String BAD_SIZE  = "size must be non-negative";
1053 
1054     // Unsafe mechanics
1055     private static final Unsafe U = Unsafe.getUnsafe();
1056     private static final long SEED
1057         = U.objectFieldOffset(Thread.class, "threadLocalRandomSeed");
1058     private static final long PROBE
1059         = U.objectFieldOffset(Thread.class, "threadLocalRandomProbe");
1060     private static final long SECONDARY
1061         = U.objectFieldOffset(Thread.class, "threadLocalRandomSecondarySeed");
1062     private static final long THREADLOCALS
1063         = U.objectFieldOffset(Thread.class, "threadLocals");
1064     private static final long INHERITABLETHREADLOCALS
1065         = U.objectFieldOffset(Thread.class, "inheritableThreadLocals");
1066     private static final long INHERITEDACCESSCONTROLCONTEXT
1067         = U.objectFieldOffset(Thread.class, "inheritedAccessControlContext");
1068 
1069     /** Rarely-used holder for the second of a pair of Gaussians */
1070     private static final ThreadLocal<Double> nextLocalGaussian =
1071         new ThreadLocal<>();
1072 
1073     /** Generates per-thread initialization/probe field */
1074     private static final AtomicInteger probeGenerator = new AtomicInteger();
1075 
1076     /** The common ThreadLocalRandom */
1077     static final ThreadLocalRandom instance = new ThreadLocalRandom();
1078 
1079     /**
1080      * The next seed for default constructors.
1081      */
1082     private static final AtomicLong seeder
1083         = new AtomicLong(mix64(System.currentTimeMillis()) ^
1084                          mix64(System.nanoTime()));
1085 
1086     // at end of <clinit> to survive static initialization circularity
1087     static {
1088         String sec = VM.getSavedProperty("java.util.secureRandomSeed");
1089         if (Boolean.parseBoolean(sec)) {
1090             byte[] seedBytes = java.security.SecureRandom.getSeed(8);
1091             long s = (long)seedBytes[0] & 0xffL;
1092             for (int i = 1; i < 8; ++i)
1093                 s = (s << 8) | ((long)seedBytes[i] & 0xffL);
1094             seeder.set(s);
1095         }
1096     }
1097 }