Class ThreadLocalRandom
- All Implemented Interfaces:
-
Serializable
,RandomGenerator
public class ThreadLocalRandom extends Random
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:
Nested Class Summary
Nested classes/interfaces declared in interface java.util.random.RandomGenerator
RandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, RandomGenerator.StreamableGenerator
Method Summary
Modifier and Type | Method | Description |
---|---|---|
static ThreadLocalRandom |
current() |
Returns the current thread's ThreadLocalRandom object. |
DoubleStream |
doubles() |
Returns an effectively unlimited stream of pseudorandom
double values, each between zero (inclusive) and one (exclusive). |
DoubleStream |
doubles |
Returns an effectively unlimited stream of pseudorandom
double values, each conforming to the given origin (inclusive) and bound (exclusive). |
DoubleStream |
doubles |
Returns a stream producing the given streamSize number of pseudorandom double values, each between zero (inclusive) and one (exclusive). |
DoubleStream |
doubles |
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 |
Returns an effectively unlimited stream of pseudorandom
int values, each conforming to the given origin (inclusive) and bound (exclusive). |
IntStream |
ints |
Returns a stream producing the given streamSize number of pseudorandom int values. |
IntStream |
ints |
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 |
Returns a stream producing the given streamSize number of pseudorandom long values. |
LongStream |
longs |
Returns an effectively unlimited stream of pseudorandom
long values, each conforming to the given origin (inclusive) and bound (exclusive). |
LongStream |
longs |
Returns a stream producing the given streamSize number of pseudorandom long , each conforming to the given origin (inclusive) and bound (exclusive). |
protected int |
next |
Generates a pseudorandom number with the indicated number of low-order bits. |
double |
nextDouble |
Returns a pseudorandomly chosen double value between zero (inclusive) and the specified bound (exclusive). |
double |
nextDouble |
Returns a pseudorandomly chosen double value between the specified origin (inclusive) and the specified bound (exclusive). |
float |
nextFloat |
Returns a pseudorandomly chosen float value between zero (inclusive) and the specified bound (exclusive). |
float |
nextFloat |
Returns a pseudorandomly chosen float value between the specified origin (inclusive) and the specified bound (exclusive). |
int |
nextInt |
Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. |
int |
nextInt |
Returns a pseudorandomly chosen int value between the specified origin (inclusive) and the specified bound (exclusive). |
long |
nextLong |
Returns a pseudorandomly chosen long value between zero (inclusive) and the specified bound (exclusive). |
long |
nextLong |
Returns a pseudorandomly chosen long value between the specified origin (inclusive) and the specified bound (exclusive). |
void |
setSeed |
Throws UnsupportedOperationException . |
Methods declared in class java.util.Random
nextBoolean, nextBytes, nextDouble, nextFloat, nextGaussian, nextInt, nextLong
Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods declared in interface java.util.random.RandomGenerator
isDeprecated, nextExponential, nextGaussian
Method Details
current
public static ThreadLocalRandom current()
ThreadLocalRandom
object. Methods of this object should be called only by the current thread, not by other threads.- Returns:
- the current thread's
ThreadLocalRandom
setSeed
public void setSeed(long seed)
UnsupportedOperationException
. Setting seeds in this generator is not supported.- Overrides:
-
setSeed
in classRandom
- Parameters:
-
seed
- the initial seed - Throws:
-
UnsupportedOperationException
- always
next
protected int next(int bits)
nextInt
public int nextInt(int bound)
int
value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract of nextInt
is that one int
value in the specified range is pseudorandomly generated and returned. All bound
possible int
values are produced with (approximately) equal probability.- Specified by:
-
nextInt
in interfaceRandomGenerator
- Overrides:
-
nextInt
in classRandom
- Parameters:
-
bound
- the upper bound (exclusive). Must be positive. - Returns:
- the next pseudorandom, uniformly distributed
int
value between zero (inclusive) andbound
(exclusive) from this random number generator's sequence - Throws:
-
IllegalArgumentException
- if bound is not positive
nextInt
public int nextInt(int origin, int bound)
int
value between the specified origin (inclusive) and the specified bound (exclusive).- Parameters:
-
origin
- the least value that can be returned -
bound
- the upper bound (exclusive) for the returned value - Returns:
- a pseudorandomly chosen
int
value between the origin (inclusive) and the bound (exclusive) - Throws:
-
IllegalArgumentException
- iforigin
is greater than or equal tobound
nextLong
public long nextLong(long bound)
long
value between zero (inclusive) and the specified bound (exclusive).- Parameters:
-
bound
- the upper bound (exclusive) for the returned value. Must be positive. - Returns:
- a pseudorandomly chosen
long
value between zero (inclusive) and the bound (exclusive) - Throws:
-
IllegalArgumentException
- ifbound
is not positive
nextLong
public long nextLong(long origin, long bound)
long
value between the specified origin (inclusive) and the specified bound (exclusive).- Parameters:
-
origin
- the least value that can be returned -
bound
- the upper bound (exclusive) for the returned value - Returns:
- a pseudorandomly chosen
long
value between the origin (inclusive) and the bound (exclusive) - Throws:
-
IllegalArgumentException
- iforigin
is greater than or equal tobound
nextFloat
public float nextFloat(float bound)
float
value between zero (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
-
bound
- the upper bound (exclusive) for the returned value. Must be positive and finite - Returns:
- a pseudorandomly chosen
float
value between zero (inclusive) and the bound (exclusive) - Throws:
-
IllegalArgumentException
- ifbound
is not both positive and finite
nextFloat
public float nextFloat(float origin, float bound)
float
value between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
-
origin
- the least value that can be returned -
bound
- the upper bound (exclusive) - Returns:
- a pseudorandomly chosen
float
value between the origin (inclusive) and the bound (exclusive) - Throws:
-
IllegalArgumentException
- iforigin
is not finite, orbound
is not finite, ororigin
is greater than or equal tobound
nextDouble
public double nextDouble(double bound)
double
value between zero (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
-
bound
- the upper bound (exclusive) for the returned value. Must be positive and finite - Returns:
- a pseudorandomly chosen
double
value between zero (inclusive) and the bound (exclusive) - Throws:
-
IllegalArgumentException
- ifbound
is not both positive and finite
nextDouble
public double nextDouble(double origin, double bound)
double
value between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
-
origin
- the least value that can be returned -
bound
- the upper bound (exclusive) for the returned value - Returns:
- a pseudorandomly chosen
double
value between the origin (inclusive) and the bound (exclusive) - Throws:
-
IllegalArgumentException
- iforigin
is not finite, orbound
is not finite, ororigin
is greater than or equal tobound
ints
public IntStream ints(long streamSize)
streamSize
number of pseudorandom int
values. A pseudorandom int
value is generated as if it's the result of calling the method Random.nextInt()
.
- Specified by:
-
ints
in interfaceRandomGenerator
- Overrides:
-
ints
in classRandom
- Parameters:
-
streamSize
- the number of values to generate - Returns:
- a stream of pseudorandom
int
values - Throws:
-
IllegalArgumentException
- ifstreamSize
is less than zero - Since:
- 1.8
ints
public IntStream ints()
int
values. A pseudorandom int
value is generated as if it's the result of calling the method Random.nextInt()
.
- Specified by:
-
ints
in interfaceRandomGenerator
- Overrides:
-
ints
in classRandom
- 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)
streamSize
number of pseudorandom int
values, each conforming to the given origin (inclusive) and bound (exclusive). A pseudorandom int
value is generated as if it's the result of calling the following method with the origin and bound:
int nextInt(int origin, int bound) {
int n = bound - origin;
if (n > 0) {
return nextInt(n) + origin;
}
else { // range not representable as int
int r;
do {
r = nextInt();
} while (r < origin || r >= bound);
return r;
}
}
- Specified by:
-
ints
in interfaceRandomGenerator
- Overrides:
-
ints
in classRandom
- 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
- ifstreamSize
is less than zero, orrandomNumberOrigin
is greater than or equal torandomNumberBound
- Since:
- 1.8
ints
public IntStream ints(int randomNumberOrigin, int randomNumberBound)
int
values, each conforming to the given origin (inclusive) and bound (exclusive). A pseudorandom int
value is generated as if it's the result of calling the following method with the origin and bound:
int nextInt(int origin, int bound) {
int n = bound - origin;
if (n > 0) {
return nextInt(n) + origin;
}
else { // range not representable as int
int r;
do {
r = nextInt();
} while (r < origin || r >= bound);
return r;
}
}
- Specified by:
-
ints
in interfaceRandomGenerator
- Overrides:
-
ints
in classRandom
- 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
- ifrandomNumberOrigin
is greater than or equal torandomNumberBound
- Since:
- 1.8
longs
public LongStream longs(long streamSize)
streamSize
number of pseudorandom long
values. A pseudorandom long
value is generated as if it's the result of calling the method Random.nextLong()
.
- Specified by:
-
longs
in interfaceRandomGenerator
- Overrides:
-
longs
in classRandom
- Parameters:
-
streamSize
- the number of values to generate - Returns:
- a stream of pseudorandom
long
values - Throws:
-
IllegalArgumentException
- ifstreamSize
is less than zero - Since:
- 1.8
longs
public LongStream longs()
long
values. A pseudorandom long
value is generated as if it's the result of calling the method Random.nextLong()
.
- Specified by:
-
longs
in interfaceRandomGenerator
- Overrides:
-
longs
in classRandom
- 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)
streamSize
number of pseudorandom long
, each conforming to the given origin (inclusive) and bound (exclusive). A pseudorandom long
value is generated as if it's the result of calling the following method with the origin and bound:
long nextLong(long origin, long bound) {
long r = nextLong();
long n = bound - origin, m = n - 1;
if ((n & m) == 0L) // power of two
r = (r & m) + origin;
else if (n > 0L) { // reject over-represented candidates
for (long u = r >>> 1; // ensure nonnegative
u + m - (r = u % n) < 0L; // rejection check
u = nextLong() >>> 1) // retry
;
r += origin;
}
else { // range not representable as long
while (r < origin || r >= bound)
r = nextLong();
}
return r;
}
- Specified by:
-
longs
in interfaceRandomGenerator
- Overrides:
-
longs
in classRandom
- 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
- ifstreamSize
is less than zero, orrandomNumberOrigin
is greater than or equal torandomNumberBound
- Since:
- 1.8
longs
public LongStream longs(long randomNumberOrigin, long randomNumberBound)
long
values, each conforming to the given origin (inclusive) and bound (exclusive). A pseudorandom long
value is generated as if it's the result of calling the following method with the origin and bound:
long nextLong(long origin, long bound) {
long r = nextLong();
long n = bound - origin, m = n - 1;
if ((n & m) == 0L) // power of two
r = (r & m) + origin;
else if (n > 0L) { // reject over-represented candidates
for (long u = r >>> 1; // ensure nonnegative
u + m - (r = u % n) < 0L; // rejection check
u = nextLong() >>> 1) // retry
;
r += origin;
}
else { // range not representable as long
while (r < origin || r >= bound)
r = nextLong();
}
return r;
}
- Specified by:
-
longs
in interfaceRandomGenerator
- Overrides:
-
longs
in classRandom
- 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
- ifrandomNumberOrigin
is greater than or equal torandomNumberBound
- Since:
- 1.8
doubles
public DoubleStream doubles(long streamSize)
streamSize
number of pseudorandom double
values, each between zero (inclusive) and one (exclusive). A pseudorandom double
value is generated as if it's the result of calling the method Random.nextDouble()
.
- Specified by:
-
doubles
in interfaceRandomGenerator
- Overrides:
-
doubles
in classRandom
- Parameters:
-
streamSize
- the number of values to generate - Returns:
- a stream of
double
values - Throws:
-
IllegalArgumentException
- ifstreamSize
is less than zero - Since:
- 1.8
doubles
public DoubleStream doubles()
double
values, each between zero (inclusive) and one (exclusive). A pseudorandom double
value is generated as if it's the result of calling the method Random.nextDouble()
.
- Specified by:
-
doubles
in interfaceRandomGenerator
- Overrides:
-
doubles
in classRandom
- 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)
streamSize
number of pseudorandom double
values, each conforming to the given origin (inclusive) and bound (exclusive). A pseudorandom double
value is generated as if it's the result of calling the following method with the origin and bound:
double nextDouble(double origin, double bound) {
double r = nextDouble();
r = r * (bound - origin) + origin;
if (r >= bound) // correct for rounding
r = Math.nextDown(bound);
return r;
}
- Specified by:
-
doubles
in interfaceRandomGenerator
- Overrides:
-
doubles
in classRandom
- 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
- ifstreamSize
is less than zero, orrandomNumberOrigin
is not finite, orrandomNumberBound
is not finite, orrandomNumberOrigin
is greater than or equal torandomNumberBound
- Since:
- 1.8
doubles
public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound)
double
values, each conforming to the given origin (inclusive) and bound (exclusive). A pseudorandom double
value is generated as if it's the result of calling the following method with the origin and bound:
double nextDouble(double origin, double bound) {
double r = nextDouble();
r = r * (bound - origin) + origin;
if (r >= bound) // correct for rounding
r = Math.nextDown(bound);
return r;
}
- Specified by:
-
doubles
in interfaceRandomGenerator
- Overrides:
-
doubles
in classRandom
- 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
- ifrandomNumberOrigin
is greater than or equal torandomNumberBound
- Since:
- 1.8
© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ThreadLocalRandom.html