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