ThreadLocalRandom (Java SE 15 & JDK 15)
Description: declaration: module: java.base, package: java.util.concurrent, class: ThreadLocalRandom
Keywords: java.util.concurrent.ThreadLocalRandom class

Module java.base
Package java.util.concurrent

# Class ThreadLocalRandom

java.lang.Object
java.util.Random
java.util.concurrent.ThreadLocalRandom

All Implemented Interfaces:
  `Serializable`

    public class ThreadLocalRandom
    extends Random

A random number generator isolated to the current thread. Like the global `Random` generator used by the `Math` class, a `ThreadLocalRandom` is initialized with an internally generated seed that may not otherwise be modified. When applicable, use of `ThreadLocalRandom` rather than shared `Random` objects in concurrent programs will typically encounter much less overhead and contention. Use of `ThreadLocalRandom` is particularly appropriate when multiple tasks (for example, each a `ForkJoinTask`) use random numbers in parallel in thread pools.

Usages of this class should typically be of the form: `ThreadLocalRandom.current().nextX(...)` (where `X` is `Int`, `Long`, etc). When all usages are of this form, it is never possible to accidentally share a `ThreadLocalRandom` across multiple threads.

This class also provides additional commonly used bounded random generation methods.

Instances of `ThreadLocalRandom` are not cryptographically secure. Consider instead using `SecureRandom` in security-sensitive applications. Additionally, default-constructed instances do not use a cryptographically random seed unless the system property `java.util.secureRandomSeed` is set to `true`.

Since:
  1.7
See Also:
  Serialized Form

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `static ThreadLocalRandom` | `current()` | Returns the current thread's `ThreadLocalRandom`.
  `DoubleStream` | `doubles()` | Returns an effectively unlimited stream of pseudorandom `double` values, each between zero (inclusive) and one (exclusive).
  `DoubleStream` | `doubles​(double randomNumberOrigin, double randomNumberBound)` | Returns an effectively unlimited stream of pseudorandom `double` values, each conforming to the given origin (inclusive) and bound (exclusive).
  `DoubleStream` | `doubles​(long streamSize)` | Returns a stream producing the given `streamSize` number of pseudorandom `double` values, each between zero (inclusive) and one (exclusive).
  `DoubleStream` | `doubles​(long streamSize, double randomNumberOrigin, double randomNumberBound)` | Returns a stream producing the given `streamSize` number of pseudorandom `double` values, each conforming to the given origin (inclusive) and bound (exclusive).
  `IntStream` | `ints()` | Returns an effectively unlimited stream of pseudorandom `int` values.
  `IntStream` | `ints​(int randomNumberOrigin, int randomNumberBound)` | Returns an effectively unlimited stream of pseudorandom `int` values, each conforming to the given origin (inclusive) and bound (exclusive).
  `IntStream` | `ints​(long streamSize)` | Returns a stream producing the given `streamSize` number of pseudorandom `int` values.
  `IntStream` | `ints​(long streamSize, int randomNumberOrigin, int randomNumberBound)` | Returns a stream producing the given `streamSize` number of pseudorandom `int` values, each conforming to the given origin (inclusive) and bound (exclusive).
  `LongStream` | `longs()` | Returns an effectively unlimited stream of pseudorandom `long` values.
  `LongStream` | `longs​(long streamSize)` | Returns a stream producing the given `streamSize` number of pseudorandom `long` values.
  `LongStream` | `longs​(long randomNumberOrigin, long randomNumberBound)` | Returns an effectively unlimited stream of pseudorandom `long` values, each conforming to the given origin (inclusive) and bound (exclusive).
  `LongStream` | `longs​(long streamSize, long randomNumberOrigin, long randomNumberBound)` | Returns a stream producing the given `streamSize` number of pseudorandom `long`, each conforming to the given origin (inclusive) and bound (exclusive).
  `protected int` | `next​(int bits)` | Generates a pseudorandom number with the indicated number of low-order bits.
  `boolean` | `nextBoolean()` | Returns a pseudorandom `boolean` value.
  `double` | `nextDouble()` | Returns a pseudorandom `double` value between zero (inclusive) and one (exclusive).
  `double` | `nextDouble​(double bound)` | Returns a pseudorandom `double` value between 0.0 (inclusive) and the specified bound (exclusive).
  `double` | `nextDouble​(double origin, double bound)` | Returns a pseudorandom `double` value between the specified origin (inclusive) and bound (exclusive).
  `float` | `nextFloat()` | Returns a pseudorandom `float` value between zero (inclusive) and one (exclusive).
  `int` | `nextInt()` | Returns a pseudorandom `int` value.
  `int` | `nextInt​(int bound)` | Returns a pseudorandom `int` value between zero (inclusive) and the specified bound (exclusive).
  `int` | `nextInt​(int origin, int bound)` | Returns a pseudorandom `int` value between the specified origin (inclusive) and the specified bound (exclusive).
  `long` | `nextLong()` | Returns a pseudorandom `long` value.
  `long` | `nextLong​(long bound)` | Returns a pseudorandom `long` value between zero (inclusive) and the specified bound (exclusive).
  `long` | `nextLong​(long origin, long bound)` | Returns a pseudorandom `long` value between the specified origin (inclusive) and the specified bound (exclusive).
  `void` | `setSeed​(long seed)` | Throws `UnsupportedOperationException`.

  ### Methods declared in class java.util.Random

  `nextBytes, nextGaussian`

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### current

    public static ThreadLocalRandom current()
    Returns the current thread's `ThreadLocalRandom`.
    Returns:
      the current thread's `ThreadLocalRandom`

  - ### setSeed

    public void setSeed​(long seed)
    Throws `UnsupportedOperationException`. Setting seeds in this generator is not supported.
    Overrides:
      `setSeed` in class `Random`
    Parameters:
      `seed` - the initial seed
    Throws:
      `UnsupportedOperationException` - always

  - ### next

    protected int next​(int bits)
    Generates a pseudorandom number with the indicated number of low-order bits. Because this class has no subclasses, this method cannot be invoked or overridden.
    Overrides:
      `next` in class `Random`
    Parameters:
      `bits` - random bits
    Returns:
      the next pseudorandom value from this random number generator's sequence

  - ### nextInt

    public int nextInt()
    Returns a pseudorandom `int` value.
    Overrides:
      `nextInt` in class `Random`
    Returns:
      a pseudorandom `int` value

  - ### nextInt

    public int nextInt​(int bound)
    Returns a pseudorandom `int` value between zero (inclusive) and the specified bound (exclusive).
    Overrides:
      `nextInt` in class `Random`
    Parameters:
      `bound` - the upper bound (exclusive). Must be positive.
    Returns:
      a pseudorandom `int` value between zero (inclusive) and the bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `bound` is not positive

  - ### nextInt

    public int nextInt​(int origin, int bound)
    Returns a pseudorandom `int` value between the specified origin (inclusive) and the specified bound (exclusive).
    Parameters:
      `origin` - the least value returned
      `bound` - the upper bound (exclusive)
    Returns:
      a pseudorandom `int` value between the origin (inclusive) and the bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `origin` is greater than or equal to `bound`

  - ### nextLong

    public long nextLong()
    Returns a pseudorandom `long` value.
    Overrides:
      `nextLong` in class `Random`
    Returns:
      a pseudorandom `long` value

  - ### nextLong

    public long nextLong​(long bound)
    Returns a pseudorandom `long` value between zero (inclusive) and the specified bound (exclusive).
    Parameters:
      `bound` - the upper bound (exclusive). Must be positive.
    Returns:
      a pseudorandom `long` value between zero (inclusive) and the bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `bound` is not positive

  - ### nextLong

    public long nextLong​(long origin, long bound)
    Returns a pseudorandom `long` value between the specified origin (inclusive) and the specified bound (exclusive).
    Parameters:
      `origin` - the least value returned
      `bound` - the upper bound (exclusive)
    Returns:
      a pseudorandom `long` value between the origin (inclusive) and the bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `origin` is greater than or equal to `bound`

  - ### nextDouble

    public double nextDouble()
    Returns a pseudorandom `double` value between zero (inclusive) and one (exclusive).
    Overrides:
      `nextDouble` in class `Random`
    Returns:
      a pseudorandom `double` value between zero (inclusive) and one (exclusive)
    See Also:
      `Math.random()`

  - ### nextDouble

    public double nextDouble​(double bound)
    Returns a pseudorandom `double` value between 0.0 (inclusive) and the specified bound (exclusive).
    Parameters:
      `bound` - the upper bound (exclusive). Must be positive.
    Returns:
      a pseudorandom `double` value between zero (inclusive) and the bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `bound` is not positive

  - ### nextDouble

    public double nextDouble​(double origin, double bound)
    Returns a pseudorandom `double` value between the specified origin (inclusive) and bound (exclusive).
    Parameters:
      `origin` - the least value returned
      `bound` - the upper bound (exclusive)
    Returns:
      a pseudorandom `double` value between the origin (inclusive) and the bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `origin` is greater than or equal to `bound`

  - ### nextBoolean

    public boolean nextBoolean()
    Returns a pseudorandom `boolean` value.
    Overrides:
      `nextBoolean` in class `Random`
    Returns:
      a pseudorandom `boolean` value

  - ### nextFloat

    public float nextFloat()
    Returns a pseudorandom `float` value between zero (inclusive) and one (exclusive).
    Overrides:
      `nextFloat` in class `Random`
    Returns:
      a pseudorandom `float` value between zero (inclusive) and one (exclusive)

  - ### ints

    public IntStream ints​(long streamSize)
    Returns a stream producing the given `streamSize` number of pseudorandom `int` values.
    Overrides:
      `ints` in class `Random`
    Parameters:
      `streamSize` - the number of values to generate
    Returns:
      a stream of pseudorandom `int` values
    Throws:
      `IllegalArgumentException` - if `streamSize` is less than zero
    Since:
      1.8

  - ### ints

    public IntStream ints()
    Returns an effectively unlimited stream of pseudorandom `int` values.
    Overrides:
      `ints` in class `Random`
    Implementation Note:
      This method is implemented to be equivalent to `ints(Long.MAX_VALUE)`.
    Returns:
      a stream of pseudorandom `int` values
    Since:
      1.8

  - ### ints

    public IntStream ints​(long streamSize, int randomNumberOrigin, int randomNumberBound)
    Returns a stream producing the given `streamSize` number of pseudorandom `int` values, each conforming to the given origin (inclusive) and bound (exclusive).
    Overrides:
      `ints` in class `Random`
    Parameters:
      `streamSize` - the number of values to generate
      `randomNumberOrigin` - the origin (inclusive) of each random value
      `randomNumberBound` - the bound (exclusive) of each random value
    Returns:
      a stream of pseudorandom `int` values, each with the given origin (inclusive) and bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `streamSize` is less than zero, or `randomNumberOrigin` is greater than or equal to `randomNumberBound`
    Since:
      1.8

  - ### ints

    public IntStream ints​(int randomNumberOrigin, int randomNumberBound)
    Returns an effectively unlimited stream of pseudorandom `int` values, each conforming to the given origin (inclusive) and bound (exclusive).
    Overrides:
      `ints` in class `Random`
    Implementation Note:
      This method is implemented to be equivalent to `ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)`.
    Parameters:
      `randomNumberOrigin` - the origin (inclusive) of each random value
      `randomNumberBound` - the bound (exclusive) of each random value
    Returns:
      a stream of pseudorandom `int` values, each with the given origin (inclusive) and bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `randomNumberOrigin` is greater than or equal to `randomNumberBound`
    Since:
      1.8

  - ### longs

    public LongStream longs​(long streamSize)
    Returns a stream producing the given `streamSize` number of pseudorandom `long` values.
    Overrides:
      `longs` in class `Random`
    Parameters:
      `streamSize` - the number of values to generate
    Returns:
      a stream of pseudorandom `long` values
    Throws:
      `IllegalArgumentException` - if `streamSize` is less than zero
    Since:
      1.8

  - ### longs

    public LongStream longs()
    Returns an effectively unlimited stream of pseudorandom `long` values.
    Overrides:
      `longs` in class `Random`
    Implementation Note:
      This method is implemented to be equivalent to `longs(Long.MAX_VALUE)`.
    Returns:
      a stream of pseudorandom `long` values
    Since:
      1.8

  - ### longs

    public LongStream longs​(long streamSize, long randomNumberOrigin, long randomNumberBound)
    Returns a stream producing the given `streamSize` number of pseudorandom `long`, each conforming to the given origin (inclusive) and bound (exclusive).
    Overrides:
      `longs` in class `Random`
    Parameters:
      `streamSize` - the number of values to generate
      `randomNumberOrigin` - the origin (inclusive) of each random value
      `randomNumberBound` - the bound (exclusive) of each random value
    Returns:
      a stream of pseudorandom `long` values, each with the given origin (inclusive) and bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `streamSize` is less than zero, or `randomNumberOrigin` is greater than or equal to `randomNumberBound`
    Since:
      1.8

  - ### longs

    public LongStream longs​(long randomNumberOrigin, long randomNumberBound)
    Returns an effectively unlimited stream of pseudorandom `long` values, each conforming to the given origin (inclusive) and bound (exclusive).
    Overrides:
      `longs` in class `Random`
    Implementation Note:
      This method is implemented to be equivalent to `longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)`.
    Parameters:
      `randomNumberOrigin` - the origin (inclusive) of each random value
      `randomNumberBound` - the bound (exclusive) of each random value
    Returns:
      a stream of pseudorandom `long` values, each with the given origin (inclusive) and bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `randomNumberOrigin` is greater than or equal to `randomNumberBound`
    Since:
      1.8

  - ### doubles

    public DoubleStream doubles​(long streamSize)
    Returns a stream producing the given `streamSize` number of pseudorandom `double` values, each between zero (inclusive) and one (exclusive).
    Overrides:
      `doubles` in class `Random`
    Parameters:
      `streamSize` - the number of values to generate
    Returns:
      a stream of `double` values
    Throws:
      `IllegalArgumentException` - if `streamSize` is less than zero
    Since:
      1.8

  - ### doubles

    public DoubleStream doubles()
    Returns an effectively unlimited stream of pseudorandom `double` values, each between zero (inclusive) and one (exclusive).
    Overrides:
      `doubles` in class `Random`
    Implementation Note:
      This method is implemented to be equivalent to `doubles(Long.MAX_VALUE)`.
    Returns:
      a stream of pseudorandom `double` values
    Since:
      1.8

  - ### doubles

    public DoubleStream doubles​(long streamSize, double randomNumberOrigin, double randomNumberBound)
    Returns a stream producing the given `streamSize` number of pseudorandom `double` values, each conforming to the given origin (inclusive) and bound (exclusive).
    Overrides:
      `doubles` in class `Random`
    Parameters:
      `streamSize` - the number of values to generate
      `randomNumberOrigin` - the origin (inclusive) of each random value
      `randomNumberBound` - the bound (exclusive) of each random value
    Returns:
      a stream of pseudorandom `double` values, each with the given origin (inclusive) and bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `streamSize` is less than zero, or `randomNumberOrigin` is greater than or equal to `randomNumberBound`
    Since:
      1.8

  - ### doubles

    public DoubleStream doubles​(double randomNumberOrigin, double randomNumberBound)
    Returns an effectively unlimited stream of pseudorandom `double` values, each conforming to the given origin (inclusive) and bound (exclusive).
    Overrides:
      `doubles` in class `Random`
    Implementation Note:
      This method is implemented to be equivalent to `doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)`.
    Parameters:
      `randomNumberOrigin` - the origin (inclusive) of each random value
      `randomNumberBound` - the bound (exclusive) of each random value
    Returns:
      a stream of pseudorandom `double` values, each with the given origin (inclusive) and bound (exclusive)
    Throws:
      `IllegalArgumentException` - if `randomNumberOrigin` is greater than or equal to `randomNumberBound`
    Since:
      1.8