Class ThreadLocalRandom
- All Implemented Interfaces:
Serializable
,RandomGenerator
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 TypeMethodDescriptionstatic ThreadLocalRandom
current()
Returns the current thread'sThreadLocalRandom
object.doubles()
Returns an effectively unlimited stream of pseudorandomdouble
values, each between zero (inclusive) and one (exclusive).doubles
(double randomNumberOrigin, double randomNumberBound) Returns an effectively unlimited stream of pseudorandomdouble
values, each conforming to the given origin (inclusive) and bound (exclusive).doubles
(long streamSize) Returns a stream producing the givenstreamSize
number of pseudorandomdouble
values, each between zero (inclusive) and one (exclusive).doubles
(long streamSize, double randomNumberOrigin, double randomNumberBound) Returns a stream producing the givenstreamSize
number of pseudorandomdouble
values, each conforming to the given origin (inclusive) and bound (exclusive).ints()
Returns an effectively unlimited stream of pseudorandomint
values.ints
(int randomNumberOrigin, int randomNumberBound) Returns an effectively unlimited stream of pseudorandomint
values, each conforming to the given origin (inclusive) and bound (exclusive).ints
(long streamSize) Returns a stream producing the givenstreamSize
number of pseudorandomint
values.ints
(long streamSize, int randomNumberOrigin, int randomNumberBound) Returns a stream producing the givenstreamSize
number of pseudorandomint
values, each conforming to the given origin (inclusive) and bound (exclusive).longs()
Returns an effectively unlimited stream of pseudorandomlong
values.longs
(long streamSize) Returns a stream producing the givenstreamSize
number of pseudorandomlong
values.longs
(long randomNumberOrigin, long randomNumberBound) Returns an effectively unlimited stream of pseudorandomlong
values, each conforming to the given origin (inclusive) and bound (exclusive).longs
(long streamSize, long randomNumberOrigin, long randomNumberBound) Returns a stream producing the givenstreamSize
number of pseudorandomlong
, 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.double
nextDouble
(double bound) Returns a pseudorandomly chosendouble
value between zero (inclusive) and the specified bound (exclusive).double
nextDouble
(double origin, double bound) Returns a pseudorandomly chosendouble
value between the specified origin (inclusive) and the specified bound (exclusive).float
nextFloat
(float bound) Returns a pseudorandomly chosenfloat
value between zero (inclusive) and the specified bound (exclusive).float
nextFloat
(float origin, float bound) Returns a pseudorandomly chosenfloat
value between the specified origin (inclusive) and the specified bound (exclusive).int
nextInt
(int bound) Returns a pseudorandom, uniformly distributedint
value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence.int
nextInt
(int origin, int bound) Returns a pseudorandomly chosenint
value between the specified origin (inclusive) and the specified bound (exclusive).long
nextLong
(long bound) Returns a pseudorandomly chosenlong
value between zero (inclusive) and the specified bound (exclusive).long
nextLong
(long origin, long bound) Returns a pseudorandomly chosenlong
value between the specified origin (inclusive) and the specified bound (exclusive).void
setSeed
(long seed) ThrowsUnsupportedOperationException
.Methods declared in class java.util.Random
from, 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
equiDoubles, isDeprecated, nextExponential, nextGaussian
-
Method Details
-
current
Returns the current thread'sThreadLocalRandom
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) ThrowsUnsupportedOperationException
. Setting seeds in this generator is not supported.- Overrides:
setSeed
in classRandom
- Parameters:
seed
- the seed value- 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. -
nextInt
public int nextInt(int bound) Returns a pseudorandom, uniformly distributedint
value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract ofnextInt
is that oneint
value in the specified range is pseudorandomly generated and returned. Allbound
possibleint
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) Returns a pseudorandomly chosenint
value between the specified origin (inclusive) and the specified bound (exclusive).- Parameters:
origin
- the least value that can be returnedbound
- 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) Returns a pseudorandomly chosenlong
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) Returns a pseudorandomly chosenlong
value between the specified origin (inclusive) and the specified bound (exclusive).- Parameters:
origin
- the least value that can be returnedbound
- 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) Returns a pseudorandomly chosenfloat
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) Returns a pseudorandomly chosenfloat
value between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
origin
- the least value that can be returnedbound
- 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) Returns a pseudorandomly chosendouble
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) Returns a pseudorandomly chosendouble
value between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Note:
- Parameters:
origin
- the least value that can be returnedbound
- 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
Returns a stream producing the givenstreamSize
number of pseudorandomint
values.A pseudorandom
int
value is generated as if it's the result of calling the methodRandom.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
Returns an effectively unlimited stream of pseudorandomint
values.A pseudorandom
int
value is generated as if it's the result of calling the methodRandom.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
Returns a stream producing the givenstreamSize
number of pseudorandomint
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 generaterandomNumberOrigin
- the origin (inclusive) of each random valuerandomNumberBound
- 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
Returns an effectively unlimited stream of pseudorandomint
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 valuerandomNumberBound
- 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
Returns a stream producing the givenstreamSize
number of pseudorandomlong
values.A pseudorandom
long
value is generated as if it's the result of calling the methodRandom.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
Returns an effectively unlimited stream of pseudorandomlong
values.A pseudorandom
long
value is generated as if it's the result of calling the methodRandom.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
Returns a stream producing the givenstreamSize
number of pseudorandomlong
, 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 generaterandomNumberOrigin
- the origin (inclusive) of each random valuerandomNumberBound
- 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
Returns an effectively unlimited stream of pseudorandomlong
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 valuerandomNumberBound
- 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
Returns a stream producing the givenstreamSize
number of pseudorandomdouble
values, each between zero (inclusive) and one (exclusive).A pseudorandom
double
value is generated as if it's the result of calling the methodRandom.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
Returns an effectively unlimited stream of pseudorandomdouble
values, each between zero (inclusive) and one (exclusive).A pseudorandom
double
value is generated as if it's the result of calling the methodRandom.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
Returns a stream producing the givenstreamSize
number of pseudorandomdouble
values, each conforming to the given origin (inclusive) and bound (exclusive).- Specified by:
doubles
in interfaceRandomGenerator
- Overrides:
doubles
in classRandom
- Parameters:
streamSize
- the number of values to generaterandomNumberOrigin
- the origin (inclusive) of each random valuerandomNumberBound
- 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
Returns an effectively unlimited stream of pseudorandomdouble
values, each conforming to the given origin (inclusive) and bound (exclusive).- 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 valuerandomNumberBound
- 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 not finite, orrandomNumberBound
is not finite, orrandomNumberOrigin
is greater than or equal torandomNumberBound
- Since:
- 1.8
-