ThreadLocalRandom

AI-generated Key Takeaways

• ThreadLocalRandom provides thread-isolated random number generation, minimizing contention in multi-threaded environments.

• It is not cryptographically secure and should not be used for security-sensitive applications; use SecureRandom instead.

• Access the current thread's instance using ThreadLocalRandom.current() and then call methods like nextInt(), nextDouble(), etc. to generate random numbers.

• RandomGenerator is a base class for generating pseudo-random numbers, offering methods like ints(), longs(), nextDouble(), and others for flexible random number generation.

• Both classes throw exceptions for invalid input parameters, such as negative stream sizes or invalid bounds.

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.

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 {@linkplain System#getProperty system property} java.util.secureRandomSeed is set to true.

Public Method Summary

static ThreadLocalRandom	current() Returns the current thread's ThreadLocalRandom.
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).
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() 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).
IntStream	ints(long streamSize) Returns a stream producing the given streamSize number 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() Returns an effectively unlimited stream 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(long streamSize) Returns a stream producing the given streamSize number of pseudorandom long values.
LongStream	longs() Returns an effectively unlimited stream 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).
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).
double	nextGaussian() Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.
int	nextInt(int origin, int bound) Returns a pseudorandom int value between the specified origin (inclusive) and the specified bound (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).
long	nextLong(long origin, long bound) Returns a pseudorandom long value between the specified origin (inclusive) and the specified bound (exclusive).
long	nextLong(long bound) Returns a pseudorandom long value between zero (inclusive) and the specified bound (exclusive).
long	nextLong() Returns a pseudorandom long value.
void	setSeed(long seed) Throws UnsupportedOperationException.

Protected Method Summary

int	next(int bits) Generates the next pseudorandom number.

Inherited Method Summary

From class java.util.Random

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() 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, 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(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).
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() Returns an effectively unlimited stream of pseudorandom int values.
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).
int	next(int bits) Generates the next pseudorandom number.
boolean	nextBoolean() Returns the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence.
void	nextBytes(byte[] bytes) Generates random bytes and places them into a user-supplied byte array.
double	nextDouble() Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.
float	nextFloat() Returns the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence.
synchronized double	nextGaussian() Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.
int	nextInt() Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence.
int	nextInt(int bound) Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence.
long	nextLong() Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence.
synchronized void	setSeed(long seed) Sets the seed of this random number generator using a single long seed.

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

Public Methods

public static ThreadLocalRandom current ()

Returns the current thread's ThreadLocalRandom.

Returns

• the current thread's ThreadLocalRandom

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).

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
IllegalArgumentException	if randomNumberOrigin is greater than or equal to randomNumberBound

public DoubleStream doubles (long streamSize)

Returns a stream producing the given streamSize number of pseudorandom double values, each between zero (inclusive) and one (exclusive).

Parameters

streamSize	the number of values to generate

Returns

• a stream of double values

Throws

IllegalArgumentException	if streamSize is less than zero

public DoubleStream doubles ()

Returns an effectively unlimited stream of pseudorandom double values, each between zero (inclusive) and one (exclusive).

Returns

• a stream of pseudorandom double values

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).

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

public IntStream ints (long streamSize)

Returns a stream producing the given streamSize number of pseudorandom int values.

Parameters

streamSize	the number of values to generate

Returns

• a stream of pseudorandom int values

Throws

IllegalArgumentException	if streamSize is less than zero

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).

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

public IntStream ints ()

Returns an effectively unlimited stream of pseudorandom int values.

Returns

• a stream of pseudorandom int values

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).

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

public LongStream longs (long streamSize)

Returns a stream producing the given streamSize number of pseudorandom long values.

Parameters

streamSize	the number of values to generate

Returns

• a stream of pseudorandom long values

Throws

IllegalArgumentException	if streamSize is less than zero

public LongStream longs ()

Returns an effectively unlimited stream of pseudorandom long values.

Returns

• a stream of pseudorandom long values

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).

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

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).

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

public boolean nextBoolean ()

Returns a pseudorandom boolean value.

Returns

• a pseudorandom boolean value

public double nextDouble ()

Returns a pseudorandom double value between zero (inclusive) and one (exclusive).

Returns

• a pseudorandom double value between zero (inclusive) and one (exclusive)

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

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

public float nextFloat ()

Returns a pseudorandom float value between zero (inclusive) and one (exclusive).

Returns

• a pseudorandom float value between zero (inclusive) and one (exclusive)

public double nextGaussian ()

Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.

The general contract of nextGaussian is that one double value, chosen from (approximately) the usual normal distribution with mean 0.0 and standard deviation 1.0, is pseudorandomly generated and returned.

The method nextGaussian is implemented by class Random as if by a threadsafe version of the following:

 private double nextNextGaussian;
 private boolean haveNextNextGaussian = false;

 public double nextGaussian() {
   if (haveNextNextGaussian) {
     haveNextNextGaussian = false;
     return nextNextGaussian;
   } else {
     double v1, v2, s;
     do {
       v1 = 2 * nextDouble() - 1;   // between -1.0 and 1.0
       v2 = 2 * nextDouble() - 1;   // between -1.0 and 1.0
       s = v1 * v1 + v2 * v2;
     } while (s >= 1 || s == 0);
     double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s);
     nextNextGaussian = v2 * multiplier;
     haveNextNextGaussian = true;
     return v1 * multiplier;
   }
 }

This uses the polar method of G. E. P. Box, M. E. Muller, and G. Marsaglia, as described by Donald E. Knuth in The Art of Computer Programming, Volume 3: Seminumerical Algorithms, section 3.4.1, subsection C, algorithm P. Note that it generates two independent values at the cost of only one call to StrictMath.log and one call to StrictMath.sqrt.

Returns

• the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence

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

public int nextInt ()

Returns a pseudorandom int value.

Returns

• a pseudorandom int value

public int nextInt (int bound)

Returns a pseudorandom int value between zero (inclusive) and the specified bound (exclusive).

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

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

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

public long nextLong ()

Returns a pseudorandom long value.

Returns

• a pseudorandom long value

public void setSeed (long seed)

Throws UnsupportedOperationException. Setting seeds in this generator is not supported.

Parameters

seed	the initial seed

Throws

UnsupportedOperationException	always

Protected Methods

protected int next (int bits)

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.

Parameters

bits	random bits

Returns

• the next pseudorandom value from this random number generator's sequence