ThreadLocalRandom
public
class
ThreadLocalRandom
extends Random
java.lang.Object | ||
↳ | java.util.Random | |
↳ | java.util.concurrent.ThreadLocalRandom |
A random number generator (with period 264) 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
.
Summary
Public methods | |
---|---|
static
ThreadLocalRandom
|
current()
Returns the current thread's |
DoubleStream
|
doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)
Returns a stream producing the given |
DoubleStream
|
doubles(long streamSize)
Returns a stream producing the given |
DoubleStream
|
doubles()
Returns an effectively unlimited stream of pseudorandom |
DoubleStream
|
doubles(double randomNumberOrigin, double randomNumberBound)
Returns an effectively unlimited stream of pseudorandom |
IntStream
|
ints(long streamSize)
Returns a stream producing the given |
IntStream
|
ints(int randomNumberOrigin, int randomNumberBound)
Returns an effectively unlimited stream of pseudorandom |
IntStream
|
ints()
Returns an effectively unlimited stream of pseudorandom |
IntStream
|
ints(long streamSize, int randomNumberOrigin, int randomNumberBound)
Returns a stream producing the given |
LongStream
|
longs(long streamSize)
Returns a stream producing the given |
LongStream
|
longs()
Returns an effectively unlimited stream of pseudorandom |
LongStream
|
longs(long randomNumberOrigin, long randomNumberBound)
Returns an effectively unlimited stream of pseudorandom |
LongStream
|
longs(long streamSize, long randomNumberOrigin, long randomNumberBound)
Returns a stream producing the given |
boolean
|
nextBoolean()
Returns the next pseudorandom, uniformly distributed
|
double
|
nextDouble()
Returns the next pseudorandom, uniformly distributed
|
double
|
nextDouble(double bound)
|
double
|
nextDouble(double origin, double bound)
|
float
|
nextFloat(float origin, float bound)
|
float
|
nextFloat()
Returns the next pseudorandom, uniformly distributed |
float
|
nextFloat(float bound)
|
int
|
nextInt(int origin, int bound)
|
int
|
nextInt()
Returns the next pseudorandom, uniformly distributed |
int
|
nextInt(int bound)
Returns a pseudorandom, uniformly distributed |
long
|
nextLong(long origin, long bound)
|
long
|
nextLong(long bound)
|
long
|
nextLong()
Returns the next pseudorandom, uniformly distributed |
void
|
setSeed(long seed)
Throws |
Protected methods | |
---|---|
int
|
next(int bits)
Generates a pseudorandom number with the indicated number of low-order bits. |
Inherited methods | |
---|---|
Public methods
current
public static ThreadLocalRandom current ()
Returns the current thread's ThreadLocalRandom
object.
Methods of this object should be called only by the current thread,
not by other threads.
Returns | |
---|---|
ThreadLocalRandom |
the current thread's ThreadLocalRandom |
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).
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;
}
Parameters | |
---|---|
streamSize |
long : the number of values to generate |
randomNumberOrigin |
double : the origin (inclusive) of each random value |
randomNumberBound |
double : the bound (exclusive) of each random value |
Returns | |
---|---|
DoubleStream |
a stream of pseudorandom double values,
each with the given origin (inclusive) and bound (exclusive) |
Throws | |
---|---|
IllegalArgumentException |
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).
A pseudorandom double
value is generated as if it's the result
of calling the method nextDouble()
.
Parameters | |
---|---|
streamSize |
long : the number of values to generate |
Returns | |
---|---|
DoubleStream |
a stream of double values |
Throws | |
---|---|
IllegalArgumentException |
doubles
public DoubleStream doubles ()
Returns an effectively unlimited stream 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 nextDouble()
.
Implementation Note:
- This method is implemented to be equivalent to
doubles(Long.MAX_VALUE)
.
Returns | |
---|---|
DoubleStream |
a stream of pseudorandom double values |
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).
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;
}
Implementation Note:
- This method is implemented to be equivalent to
doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)
.
Parameters | |
---|---|
randomNumberOrigin |
double : the origin (inclusive) of each random value |
randomNumberBound |
double : the bound (exclusive) of each random value |
Returns | |
---|---|
DoubleStream |
a stream of pseudorandom double values,
each with the given origin (inclusive) and bound (exclusive) |
Throws | |
---|---|
IllegalArgumentException |
ints
public IntStream ints (long streamSize)
Returns a stream producing the given streamSize
number of
pseudorandom int
values.
A pseudorandom int
value is generated as if it's the result of
calling the method nextInt()
.
Parameters | |
---|---|
streamSize |
long : the number of values to generate |
Returns | |
---|---|
IntStream |
a stream of pseudorandom int values |
Throws | |
---|---|
IllegalArgumentException |
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).
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;
}
}
Implementation Note:
- This method is implemented to be equivalent to
ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)
.
Parameters | |
---|---|
randomNumberOrigin |
int : the origin (inclusive) of each random value |
randomNumberBound |
int : the bound (exclusive) of each random value |
Returns | |
---|---|
IntStream |
a stream of pseudorandom int values,
each with the given origin (inclusive) and bound (exclusive) |
Throws | |
---|---|
IllegalArgumentException |
ints
public IntStream ints ()
Returns an effectively unlimited stream of pseudorandom int
values.
A pseudorandom int
value is generated as if it's the result of
calling the method nextInt()
.
Implementation Note:
- This method is implemented to be equivalent to
ints(Long.MAX_VALUE)
.
Returns | |
---|---|
IntStream |
a stream of pseudorandom int values |
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).
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;
}
}
Parameters | |
---|---|
streamSize |
long : the number of values to generate |
randomNumberOrigin |
int : the origin (inclusive) of each random value |
randomNumberBound |
int : the bound (exclusive) of each random value |
Returns | |
---|---|
IntStream |
a stream of pseudorandom int values,
each with the given origin (inclusive) and bound (exclusive) |
Throws | |
---|---|
IllegalArgumentException |
longs
public LongStream longs (long streamSize)
Returns a stream producing the given streamSize
number of
pseudorandom long
values.
A pseudorandom long
value is generated as if it's the result
of calling the method nextLong()
.
Parameters | |
---|---|
streamSize |
long : the number of values to generate |
Returns | |
---|---|
LongStream |
a stream of pseudorandom long values |
Throws | |
---|---|
IllegalArgumentException |
longs
public LongStream longs ()
Returns an effectively unlimited stream of pseudorandom long
values.
A pseudorandom long
value is generated as if it's the result
of calling the method nextLong()
.
Implementation Note:
- This method is implemented to be equivalent to
longs(Long.MAX_VALUE)
.
Returns | |
---|---|
LongStream |
a stream of pseudorandom long values |
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).
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;
}
Implementation Note:
- This method is implemented to be equivalent to
longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)
.
Parameters | |
---|---|
randomNumberOrigin |
long : the origin (inclusive) of each random value |
randomNumberBound |
long : the bound (exclusive) of each random value |
Returns | |
---|---|
LongStream |
a stream of pseudorandom long values,
each with the given origin (inclusive) and bound (exclusive) |
Throws | |
---|---|
IllegalArgumentException |
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).
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;
}
Parameters | |
---|---|
streamSize |
long : the number of values to generate |
randomNumberOrigin |
long : the origin (inclusive) of each random value |
randomNumberBound |
long : the bound (exclusive) of each random value |
Returns | |
---|---|
LongStream |
a stream of pseudorandom long values,
each with the given origin (inclusive) and bound (exclusive) |
Throws | |
---|---|
IllegalArgumentException |
nextBoolean
public boolean nextBoolean ()
Returns the next pseudorandom, uniformly distributed
boolean
value from this random number generator's
sequence. The general contract of nextBoolean
is that one
boolean
value is pseudorandomly generated and returned. The
values true
and false
are produced with
(approximately) equal probability.
Returns | |
---|---|
boolean |
the next pseudorandom, uniformly distributed
boolean value from this random number generator's
sequence |
nextDouble
public double nextDouble ()
Returns the next pseudorandom, uniformly distributed
double
value between 0.0
and
1.0
from this random number generator's sequence.
The general contract of nextDouble
is that one
double
value, chosen (approximately) uniformly from the
range 0.0d
(inclusive) to 1.0d
(exclusive), is
pseudorandomly generated and returned.
Returns | |
---|---|
double |
the next pseudorandom, uniformly distributed double
value between 0.0 and 1.0 from this
random number generator's sequence |
nextDouble
public double nextDouble (double bound)
Implementation Note:
Parameters | |
---|---|
bound |
double |
Returns | |
---|---|
double |
Throws | |
---|---|
IllegalArgumentException |
nextDouble
public double nextDouble (double origin, double bound)
Implementation Note:
Parameters | |
---|---|
origin |
double |
bound |
double |
Returns | |
---|---|
double |
Throws | |
---|---|
IllegalArgumentException |
nextFloat
public float nextFloat (float origin, float bound)
Implementation Note:
Parameters | |
---|---|
origin |
float |
bound |
float |
Returns | |
---|---|
float |
Throws | |
---|---|
IllegalArgumentException |
nextFloat
public float nextFloat ()
Returns the next pseudorandom, uniformly distributed float
value between 0.0
and 1.0
from this random
number generator's sequence.
The general contract of nextFloat
is that one
float
value, chosen (approximately) uniformly from the
range 0.0f
(inclusive) to 1.0f
(exclusive), is
pseudorandomly generated and returned. All 224 possible
float
values of the form m x 2-24,
where m is a positive integer less than 224, are
produced with (approximately) equal probability.
Returns | |
---|---|
float |
the next pseudorandom, uniformly distributed float
value between 0.0 and 1.0 from this
random number generator's sequence |
nextFloat
public float nextFloat (float bound)
Implementation Note:
Parameters | |
---|---|
bound |
float |
Returns | |
---|---|
float |
Throws | |
---|---|
IllegalArgumentException |
nextInt
public int nextInt (int origin, int bound)
Parameters | |
---|---|
origin |
int |
bound |
int |
Returns | |
---|---|
int |
Throws | |
---|---|
IllegalArgumentException |
nextInt
public int nextInt ()
Returns the next pseudorandom, uniformly distributed int
value from this random number generator's sequence. The general
contract of nextInt
is that one int
value is
pseudorandomly generated and returned. All 232 possible
int
values are produced with (approximately) equal probability.
Returns | |
---|---|
int |
the next pseudorandom, uniformly distributed int
value from this random number generator's sequence |
nextInt
public 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. 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.
Parameters | |
---|---|
bound |
int : the upper bound (exclusive). Must be positive. |
Returns | |
---|---|
int |
the next pseudorandom, uniformly distributed int
value between zero (inclusive) and bound (exclusive)
from this random number generator's sequence |
Throws | |
---|---|
IllegalArgumentException |
nextLong
public long nextLong (long origin, long bound)
Parameters | |
---|---|
origin |
long |
bound |
long |
Returns | |
---|---|
long |
Throws | |
---|---|
IllegalArgumentException |
nextLong
public long nextLong (long bound)
Parameters | |
---|---|
bound |
long |
Returns | |
---|---|
long |
Throws | |
---|---|
IllegalArgumentException |
nextLong
public long nextLong ()
Returns the next pseudorandom, uniformly distributed long
value from this random number generator's sequence. The general
contract of nextLong
is that one long
value is
pseudorandomly generated and returned.
Returns | |
---|---|
long |
the next pseudorandom, uniformly distributed long
value from this random number generator's sequence |
setSeed
public void setSeed (long seed)
Throws UnsupportedOperationException
. Setting seeds in
this generator is not supported.
Parameters | |
---|---|
seed |
long : the initial seed |
Throws | |
---|---|
UnsupportedOperationException |
always |
Protected methods
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.
Parameters | |
---|---|
bits |
int : random bits |
Returns | |
---|---|
int |
the next pseudorandom value from this random number generator's sequence |