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 accidently share a `ThreadLocalRandom` across multiple threads.

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

  Since:
    1.7
  Author:
    Doug Lea
  See Also:
    Serialized Form

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ThreadLocalRandom` | `current()` Returns the current thread's `ThreadLocalRandom`.
    `protected int` | `next(int bits)` Generates the next pseudorandom number.
    `double` | `nextDouble(double n)` Returns a pseudorandom, uniformly distributed `double` value between 0 (inclusive) and the specified value (exclusive).
    `double` | `nextDouble(double least, double bound)` Returns a pseudorandom, uniformly distributed value between the given least value (inclusive) and bound (exclusive).
    `int` | `nextInt(int least, int bound)` Returns a pseudorandom, uniformly distributed value between the given least value (inclusive) and bound (exclusive).
    `long` | `nextLong(long n)` Returns a pseudorandom, uniformly distributed value between 0 (inclusive) and the specified value (exclusive).
    `long` | `nextLong(long least, long bound)` Returns a pseudorandom, uniformly distributed value between the given least value (inclusive) and bound (exclusive).
    `void` | `setSeed(long seed)` Throws `UnsupportedOperationException`.

    - ### Methods inherited from class java.util.Random

      `nextBoolean, nextBytes, nextDouble, nextFloat, nextGaussian, nextInt, nextInt, nextLong`

    - ### Methods inherited from 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)

      Description copied from class: `Random`
      Generates the next pseudorandom number. Subclasses should override this, as this is used by all other methods.

      The general contract of `next` is that it returns an `int` value and if the argument `bits` is between `1` and `32` (inclusive), then that many low-order bits of the returned value will be (approximately) independently chosen bit values, each of which is (approximately) equally likely to be `0` or `1`. The method `next` is implemented by class `Random` by atomically updating the seed to

           (seed * 0x5DEECE66DL + 0xBL) & ((1L << 48) - 1)

      and returning

           (int)(seed >>> (48 - bits)).

      This is a linear congruential pseudorandom number generator, as defined by D. H. Lehmer and described by Donald E. Knuth in The Art of Computer Programming, Volume 3: Seminumerical Algorithms, section 3.2.1.
      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(int least,
                             int bound)

      Returns a pseudorandom, uniformly distributed value between the given least value (inclusive) and bound (exclusive).
      Parameters:
        `least` - the least value returned
        `bound` - the upper bound (exclusive)
      Returns:
        the next value
      Throws:
        `IllegalArgumentException` - if least greater than or equal to bound

    - #### nextLong

          public long nextLong(long n)

      Returns a pseudorandom, uniformly distributed value between 0 (inclusive) and the specified value (exclusive).
      Parameters:
        `n` - the bound on the random number to be returned. Must be positive.
      Returns:
        the next value
      Throws:
        `IllegalArgumentException` - if n is not positive

    - #### nextLong

          public long nextLong(long least,
                               long bound)

      Returns a pseudorandom, uniformly distributed value between the given least value (inclusive) and bound (exclusive).
      Parameters:
        `least` - the least value returned
        `bound` - the upper bound (exclusive)
      Returns:
        the next value
      Throws:
        `IllegalArgumentException` - if least greater than or equal to bound

    - #### nextDouble

          public double nextDouble(double n)

      Returns a pseudorandom, uniformly distributed `double` value between 0 (inclusive) and the specified value (exclusive).
      Parameters:
        `n` - the bound on the random number to be returned. Must be positive.
      Returns:
        the next value
      Throws:
        `IllegalArgumentException` - if n is not positive

    - #### nextDouble

          public double nextDouble(double least,
                                   double bound)

      Returns a pseudorandom, uniformly distributed value between the given least value (inclusive) and bound (exclusive).
      Parameters:
        `least` - the least value returned
        `bound` - the upper bound (exclusive)
      Returns:
        the next value
      Throws:
        `IllegalArgumentException` - if least greater than or equal to bound

Copyright © 2025 API Design. All Rights Reserved.