ThreadLocalRandom (Java SE 11 & JDK 11 )
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

    All Methods Static Methods Instance Methods Concrete Methods
    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 Detail

    - #### 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