ThreadLocalRandom
open class ThreadLocalRandom : Random
kotlin.Any | ||
↳ | java.util.Random | |
↳ | java.util.concurrent.ThreadLocalRandom |
A random number generator (with period 264) isolated to the current thread. Like the global java.util.Random
generator used by the java.lang.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 java.security.SecureRandom
in security-sensitive applications. Additionally, default-constructed instances do not use a cryptographically random seed unless the java.lang.System#getProperty java.util.secureRandomSeed
is set to true
.
Summary
Public methods | |
---|---|
open static ThreadLocalRandom! |
current() Returns the current thread's |
open DoubleStream! |
Returns a stream producing the given |
open DoubleStream! |
doubles() Returns an effectively unlimited stream of pseudorandom |
open DoubleStream! |
Returns a stream producing the given |
open DoubleStream! |
Returns an effectively unlimited stream of pseudorandom |
open IntStream! |
Returns a stream producing the given |
open IntStream! |
ints() Returns an effectively unlimited stream of pseudorandom |
open IntStream! |
Returns a stream producing the given |
open IntStream! |
Returns an effectively unlimited stream of pseudorandom |
open LongStream! |
Returns a stream producing the given |
open LongStream! |
longs() Returns an effectively unlimited stream of pseudorandom |
open LongStream! |
Returns a stream producing the given |
open LongStream! |
Returns an effectively unlimited stream of pseudorandom |
open Boolean |
Returns the next pseudorandom, uniformly distributed |
open Double |
Returns the next pseudorandom, uniformly distributed |
open Double |
nextDouble(bound: Double) Returns a pseudorandomly chosen |
open Double |
nextDouble(origin: Double, bound: Double) Returns a pseudorandomly chosen |
open Float |
Returns the next pseudorandom, uniformly distributed |
open Float |
Returns a pseudorandomly chosen |
open Float |
Returns a pseudorandomly chosen |
open Int |
nextInt() Returns the next pseudorandom, uniformly distributed |
open Int |
Returns a pseudorandom, uniformly distributed |
open Int |
Returns a pseudorandomly chosen |
open Long |
nextLong() Returns the next pseudorandom, uniformly distributed |
open Long |
Returns a pseudorandomly chosen |
open Long |
Returns a pseudorandomly chosen |
open Unit |
Throws |
Protected methods | |
---|---|
open Int |
Generates a pseudorandom number with the indicated number of low-order bits. |
Inherited functions | |
---|---|
Public methods
current
open static fun current(): ThreadLocalRandom!
Returns the current thread's ThreadLocalRandom
object. Methods of this object should be called only by the current thread, not by other threads.
Return | |
---|---|
ThreadLocalRandom! |
the current thread's ThreadLocalRandom |
doubles
open fun doubles(streamSize: Long): DoubleStream!
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 |
Return | |
---|---|
DoubleStream! |
a stream of double values |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero |
doubles
open fun doubles(): DoubleStream!
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()
.
Return | |
---|---|
DoubleStream! |
a stream of pseudorandom double values |
doubles
open fun doubles(
streamSize: Long,
randomNumberOrigin: Double,
randomNumberBound: Double
): DoubleStream!
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:
<code>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; }</code>
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 |
Return | |
---|---|
DoubleStream! |
a stream of pseudorandom double values, each with the given origin (inclusive) and bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero, or randomNumberOrigin is not finite, or randomNumberBound is not finite, or randomNumberOrigin is greater than or equal to randomNumberBound |
doubles
open fun doubles(
randomNumberOrigin: Double,
randomNumberBound: Double
): DoubleStream!
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:
<code>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; }</code>
Parameters | |
---|---|
randomNumberOrigin |
Double: the origin (inclusive) of each random value |
randomNumberBound |
Double: the bound (exclusive) of each random value |
Return | |
---|---|
DoubleStream! |
a stream of pseudorandom double values, each with the given origin (inclusive) and bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if randomNumberOrigin is greater than or equal to randomNumberBound |
ints
open fun ints(streamSize: Long): IntStream!
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 |
Return | |
---|---|
IntStream! |
a stream of pseudorandom int values |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero |
ints
open fun ints(): IntStream!
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()
.
Return | |
---|---|
IntStream! |
a stream of pseudorandom int values |
ints
open fun ints(
streamSize: Long,
randomNumberOrigin: Int,
randomNumberBound: Int
): IntStream!
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:
<code>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; } }</code>
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 |
Return | |
---|---|
IntStream! |
a stream of pseudorandom int values, each with the given origin (inclusive) and bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero, or randomNumberOrigin is greater than or equal to randomNumberBound |
ints
open fun ints(
randomNumberOrigin: Int,
randomNumberBound: Int
): IntStream!
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:
<code>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; } }</code>
Parameters | |
---|---|
randomNumberOrigin |
Int: the origin (inclusive) of each random value |
randomNumberBound |
Int: the bound (exclusive) of each random value |
Return | |
---|---|
IntStream! |
a stream of pseudorandom int values, each with the given origin (inclusive) and bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if randomNumberOrigin is greater than or equal to randomNumberBound |
longs
open fun longs(streamSize: Long): LongStream!
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 |
Return | |
---|---|
LongStream! |
a stream of pseudorandom long values |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero |
longs
open fun longs(): LongStream!
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()
.
Return | |
---|---|
LongStream! |
a stream of pseudorandom long values |
longs
open fun longs(
streamSize: Long,
randomNumberOrigin: Long,
randomNumberBound: Long
): LongStream!
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:
<code>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; }</code>
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 |
Return | |
---|---|
LongStream! |
a stream of pseudorandom long values, each with the given origin (inclusive) and bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero, or randomNumberOrigin is greater than or equal to randomNumberBound |
longs
open fun longs(
randomNumberOrigin: Long,
randomNumberBound: Long
): LongStream!
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:
<code>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; }</code>
Parameters | |
---|---|
randomNumberOrigin |
Long: the origin (inclusive) of each random value |
randomNumberBound |
Long: the bound (exclusive) of each random value |
Return | |
---|---|
LongStream! |
a stream of pseudorandom long values, each with the given origin (inclusive) and bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if randomNumberOrigin is greater than or equal to randomNumberBound |
nextBoolean
open fun nextBoolean(): Boolean
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.
Return | |
---|---|
Boolean |
the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence |
nextDouble
open fun nextDouble(): Double
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.
Return | |
---|---|
Double |
the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence |
nextDouble
open fun nextDouble(bound: Double): Double
Returns a pseudorandomly chosen double
value between zero (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
bound |
Double: the upper bound (exclusive) for the returned value. Must be positive and finite |
Return | |
---|---|
Double |
a pseudorandomly chosen double value between zero (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if bound is not both positive and finite |
nextDouble
open fun nextDouble(
origin: Double,
bound: Double
): Double
Returns a pseudorandomly chosen double
value between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
origin |
Double: the least value that can be returned |
bound |
Double: the upper bound (exclusive) for the returned value |
Return | |
---|---|
Double |
a pseudorandomly chosen double value between the origin (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if origin is not finite, or bound is not finite, or origin is greater than or equal to bound |
nextFloat
open fun nextFloat(): Float
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.
Return | |
---|---|
Float |
the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence |
nextFloat
open fun nextFloat(bound: Float): Float
Returns a pseudorandomly chosen float
value between zero (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
bound |
Float: the upper bound (exclusive) for the returned value. Must be positive and finite |
Return | |
---|---|
Float |
a pseudorandomly chosen float value between zero (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if bound is not both positive and finite |
nextFloat
open fun nextFloat(
origin: Float,
bound: Float
): Float
Returns a pseudorandomly chosen float
value between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
origin |
Float: the least value that can be returned |
bound |
Float: the upper bound (exclusive) |
Return | |
---|---|
Float |
a pseudorandomly chosen float value between the origin (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if origin is not finite, or bound is not finite, or origin is greater than or equal to bound |
nextInt
open fun nextInt(): Int
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.
Return | |
---|---|
Int |
the next pseudorandom, uniformly distributed int value from this random number generator's sequence |
nextInt
open fun nextInt(bound: Int): Int
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. |
Return | |
---|---|
Int |
the next pseudorandom, uniformly distributed int value between zero (inclusive) and bound (exclusive) from this random number generator's sequence |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if bound is not positive |
nextInt
open fun nextInt(
origin: Int,
bound: Int
): Int
Returns a pseudorandomly chosen int
value between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
origin |
Int: the least value that can be returned |
bound |
Int: the upper bound (exclusive) for the returned value |
Return | |
---|---|
Int |
a pseudorandomly chosen int value between the origin (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if origin is greater than or equal to bound |
nextLong
open fun nextLong(): Long
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.
Return | |
---|---|
Long |
the next pseudorandom, uniformly distributed long value from this random number generator's sequence |
nextLong
open fun nextLong(bound: Long): Long
Returns a pseudorandomly chosen long
value between zero (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
bound |
Long: the upper bound (exclusive) for the returned value. Must be positive. |
Return | |
---|---|
Long |
a pseudorandomly chosen long value between zero (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if bound is not positive |
nextLong
open fun nextLong(
origin: Long,
bound: Long
): Long
Returns a pseudorandomly chosen long
value between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
origin |
Long: the least value that can be returned |
bound |
Long: the upper bound (exclusive) for the returned value |
Return | |
---|---|
Long |
a pseudorandomly chosen long value between the origin (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if origin is greater than or equal to bound |
setSeed
open fun setSeed(seed: Long): Unit
Throws UnsupportedOperationException
. Setting seeds in this generator is not supported.
Parameters | |
---|---|
seed |
Long: the initial seed |
Exceptions | |
---|---|
java.lang.UnsupportedOperationException |
always |
Protected methods
next
protected open fun next(bits: Int): Int
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 |
Return | |
---|---|
Int |
the next pseudorandom value from this random number generator's sequence |