SplittableRandom
public
final
class
SplittableRandom
extends Object
implements
RandomGenerator,
RandomGenerator.SplittableGenerator
A generator of uniform pseudorandom values (with period 264)
applicable for use in (among other contexts) isolated parallel
computations that may generate subtasks. Class SplittableRandom
supports methods for producing pseudorandom numbers of type int
,
long
, and double
with similar usages as for class
Random
but differs in the following ways:
- Series of generated values pass the DieHarder suite testing
independence and uniformity properties of random number generators.
(Most recently validated with version
3.31.1.) These tests validate only the methods for certain
types and ranges, but similar properties are expected to hold, at
least approximately, for others as well. The period
(length of any series of generated values before it repeats) is
264.
- Method
split()
constructs and returns a new
SplittableRandom instance that shares no mutable state with the
current instance. However, with very high probability, the
values collectively generated by the two objects have the same
statistical properties as if the same quantity of values were
generated by a single thread using a single SplittableRandom
object.
- Instances of SplittableRandom are not thread-safe.
They are designed to be split, not shared, across threads. For
example, a
fork/join-style
computation using random numbers might include a
construction of the form new
Subtask(aSplittableRandom.split()).fork()
.
- This class provides additional methods for generating random
streams, that employ the above techniques when used in
stream.parallel()
mode.
Instances of SplittableRandom
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 constructors |
SplittableRandom()
Creates a new SplittableRandom instance that is likely to
generate sequences of values that are statistically independent
of those of any other instances in the current program; and
may, and typically does, vary across program invocations.
|
SplittableRandom(long seed)
Creates a new SplittableRandom instance using the specified
initial seed.
|
Public methods |
DoubleStream
|
doubles(long streamSize)
Returns a stream producing the given streamSize number of
pseudorandom double values from this generator and/or one split
from it; each value is between zero (inclusive) and one (exclusive).
|
DoubleStream
|
doubles()
Returns an effectively unlimited stream of pseudorandom double values from this generator and/or one split from it; each value
is between zero (inclusive) and one (exclusive).
|
DoubleStream
|
doubles(double randomNumberOrigin, double randomNumberBound)
Returns an effectively unlimited stream of pseudorandom double values from this generator and/or one split from it; each value
conforms 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 from this generator and/or one split
from it; each value conforms to the given origin (inclusive) and bound
(exclusive).
|
IntStream
|
ints(long streamSize)
Returns a stream producing the given streamSize number
of pseudorandom int values from this generator and/or
one split from it.
|
IntStream
|
ints(int randomNumberOrigin, int randomNumberBound)
Returns an effectively unlimited stream of pseudorandom int values from this generator and/or one split from it; each value
conforms to the given origin (inclusive) and bound (exclusive).
|
IntStream
|
ints(long streamSize, int randomNumberOrigin, int randomNumberBound)
Returns a stream producing the given streamSize number
of pseudorandom int values from this generator and/or one split
from it; each value conforms to the given origin (inclusive) and bound
(exclusive).
|
IntStream
|
ints()
Returns an effectively unlimited stream of pseudorandom int
values from this generator and/or one split from it.
|
LongStream
|
longs()
Returns an effectively unlimited stream of pseudorandom long values from this generator and/or one split from it.
|
LongStream
|
longs(long streamSize)
Returns a stream producing the given streamSize number
of pseudorandom long values from this generator and/or
one split from it.
|
LongStream
|
longs(long randomNumberOrigin, long randomNumberBound)
Returns an effectively unlimited stream of pseudorandom long values from this generator and/or one split from it; each value
conforms 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 values from this generator and/or one split
from it; each value conforms to the given origin (inclusive) and bound
(exclusive).
|
void
|
nextBytes(byte[] bytes)
Fills a user-supplied byte array with generated byte values
pseudorandomly chosen uniformly from the range of values between -128
(inclusive) and 127 (inclusive).
|
int
|
nextInt()
Returns a pseudorandomly chosen int value.
|
long
|
nextLong()
Returns a pseudorandomly chosen long value.
|
SplittableRandom
|
split(RandomGenerator.SplittableGenerator source)
Returns a new pseudorandom number generator, split off from this one,
that implements the RandomGenerator and
SplittableGenerator interfaces.
|
SplittableRandom
|
split()
Constructs and returns a new SplittableRandom instance that
shares no mutable state with this instance.
|
Stream<RandomGenerator.SplittableGenerator>
|
splits(long streamSize, RandomGenerator.SplittableGenerator source)
Returns a stream producing the given streamSize number of new
pseudorandom number generators, each of which implements the
SplittableGenerator interface.
|
Stream<RandomGenerator.SplittableGenerator>
|
splits()
Returns an effectively unlimited stream of new pseudorandom number
generators, each of which implements the SplittableGenerator
interface.
|
Stream<RandomGenerator.SplittableGenerator>
|
splits(long streamSize)
Returns a stream producing the given streamSize number of new
pseudorandom number generators, each of which implements the
SplittableGenerator interface.
|
Stream<RandomGenerator.SplittableGenerator>
|
splits(RandomGenerator.SplittableGenerator source)
Returns an effectively unlimited stream of new pseudorandom number
generators, each of which implements the SplittableGenerator
interface.
|
Inherited methods |
From class
java.lang.Object
Object
|
clone()
Creates and returns a copy of this object.
|
boolean
|
equals(Object obj)
Indicates whether some other object is "equal to" this one.
|
void
|
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
final
Class<?>
|
getClass()
Returns the runtime class of this Object .
|
int
|
hashCode()
Returns a hash code value for the object.
|
final
void
|
notify()
Wakes up a single thread that is waiting on this object's
monitor.
|
final
void
|
notifyAll()
Wakes up all threads that are waiting on this object's monitor.
|
String
|
toString()
Returns a string representation of the object.
|
final
void
|
wait(long timeoutMillis, int nanos)
Causes the current thread to wait until it is awakened, typically
by being notified or interrupted, or until a
certain amount of real time has elapsed.
|
final
void
|
wait(long timeoutMillis)
Causes the current thread to wait until it is awakened, typically
by being notified or interrupted, or until a
certain amount of real time has elapsed.
|
final
void
|
wait()
Causes the current thread to wait until it is awakened, typically
by being notified or interrupted.
|
|
From interface
java.util.random.RandomGenerator
default
DoubleStream
|
doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)
Returns a stream producing the given streamSize number of
pseudorandomly chosen double values, where each value is
between the specified origin (inclusive) and the specified bound
(exclusive).
|
default
DoubleStream
|
doubles(long streamSize)
Returns a stream producing the given streamSize number of
pseudorandomly chosen double values.
|
default
DoubleStream
|
doubles()
Returns an effectively unlimited stream of pseudorandomly chosen
double values.
|
default
DoubleStream
|
doubles(double randomNumberOrigin, double randomNumberBound)
Returns an effectively unlimited stream of pseudorandomly chosen
double values, where each value is between the specified origin
(inclusive) and the specified bound (exclusive).
|
static
RandomGenerator
|
getDefault()
Returns a RandomGenerator meeting the minimal requirement
of having an algorithm
whose state bits are greater than or equal 64.
|
default
IntStream
|
ints(long streamSize)
Returns a stream producing the given streamSize number of
pseudorandomly chosen int values.
|
default
IntStream
|
ints(int randomNumberOrigin, int randomNumberBound)
Returns an effectively unlimited stream of pseudorandomly chosen
int values, where each value is between the specified origin
(inclusive) and the specified bound (exclusive).
|
default
IntStream
|
ints()
Returns an effectively unlimited stream of pseudorandomly chosen
int values.
|
default
IntStream
|
ints(long streamSize, int randomNumberOrigin, int randomNumberBound)
Returns a stream producing the given streamSize number of
pseudorandomly chosen int values, where each value is between
the specified origin (inclusive) and the specified bound (exclusive).
|
default
boolean
|
isDeprecated()
Return true if the implementation of RandomGenerator (algorithm) has been
marked for deprecation.
|
default
LongStream
|
longs(long streamSize)
Returns a stream producing the given streamSize number of
pseudorandomly chosen long values.
|
default
LongStream
|
longs()
Returns an effectively unlimited stream of pseudorandomly chosen
long values.
|
default
LongStream
|
longs(long randomNumberOrigin, long randomNumberBound)
Returns an effectively unlimited stream of pseudorandomly chosen
long values, where each value is between the specified origin
(inclusive) and the specified bound (exclusive).
|
default
LongStream
|
longs(long streamSize, long randomNumberOrigin, long randomNumberBound)
Returns a stream producing the given streamSize number of
pseudorandomly chosen long values, where each value is between
the specified origin (inclusive) and the specified bound (exclusive).
|
default
boolean
|
nextBoolean()
Returns a pseudorandomly chosen boolean value.
|
default
void
|
nextBytes(byte[] bytes)
Fills a user-supplied byte array with generated byte values
pseudorandomly chosen uniformly from the range of values between -128
(inclusive) and 127 (inclusive).
|
default
double
|
nextDouble()
Returns a pseudorandom double value between zero (inclusive) and
one (exclusive).
|
default
double
|
nextDouble(double bound)
Returns a pseudorandomly chosen double value between zero
(inclusive) and the specified bound (exclusive).
|
default
double
|
nextDouble(double origin, double bound)
Returns a pseudorandomly chosen double value between the
specified origin (inclusive) and the specified bound (exclusive).
|
default
double
|
nextExponential()
Returns a nonnegative double value pseudorandomly chosen from
an exponential distribution whose mean is 1.
|
default
float
|
nextFloat(float origin, float bound)
Returns a pseudorandomly chosen float value between the
specified origin (inclusive) and the specified bound (exclusive).
|
default
float
|
nextFloat()
Returns a pseudorandom float value between zero (inclusive) and
one (exclusive).
|
default
float
|
nextFloat(float bound)
Returns a pseudorandomly chosen float value between zero
(inclusive) and the specified bound (exclusive).
|
default
double
|
nextGaussian(double mean, double stddev)
Returns a double value pseudorandomly chosen from a Gaussian
(normal) distribution with a mean and standard deviation specified by the
arguments.
|
default
double
|
nextGaussian()
Returns a double value pseudorandomly chosen from a Gaussian
(normal) distribution whose mean is 0 and whose standard deviation is 1.
|
default
int
|
nextInt(int origin, int bound)
Returns a pseudorandomly chosen int value between the specified
origin (inclusive) and the specified bound (exclusive).
|
default
int
|
nextInt()
Returns a pseudorandomly chosen int value.
|
default
int
|
nextInt(int bound)
Returns a pseudorandomly chosen int value between zero
(inclusive) and the specified bound (exclusive).
|
default
long
|
nextLong(long origin, long bound)
Returns a pseudorandomly chosen long value between the
specified origin (inclusive) and the specified bound (exclusive).
|
default
long
|
nextLong(long bound)
Returns a pseudorandomly chosen long value between zero
(inclusive) and the specified bound (exclusive).
|
abstract
long
|
nextLong()
Returns a pseudorandomly chosen long value.
|
static
RandomGenerator
|
of(String name)
Returns an instance of RandomGenerator that utilizes the
name algorithm.
|
|
From interface
java.util.random.RandomGenerator.SplittableGenerator
static
RandomGenerator.SplittableGenerator
|
of(String name)
Returns an instance of SplittableGenerator that utilizes the
name algorithm.
|
default
Stream<RandomGenerator>
|
rngs(long streamSize)
Returns a stream producing the given streamSize number of new
pseudorandom number generators, each of which implements the
RandomGenerator interface.
|
default
Stream<RandomGenerator>
|
rngs()
Returns an effectively unlimited stream of new pseudorandom number
generators, each of which implements the RandomGenerator
interface.
|
abstract
RandomGenerator.SplittableGenerator
|
split(RandomGenerator.SplittableGenerator source)
Returns a new pseudorandom number generator, split off from this one,
that implements the RandomGenerator and
SplittableGenerator interfaces.
|
abstract
RandomGenerator.SplittableGenerator
|
split()
Returns a new pseudorandom number generator, split off from this one,
that implements the RandomGenerator and
SplittableGenerator interfaces.
|
default
Stream<RandomGenerator.SplittableGenerator>
|
splits()
Returns an effectively unlimited stream of new pseudorandom number
generators, each of which implements the SplittableGenerator
interface.
|
abstract
Stream<RandomGenerator.SplittableGenerator>
|
splits(long streamSize, RandomGenerator.SplittableGenerator source)
Returns a stream producing the given streamSize number of new
pseudorandom number generators, each of which implements the
SplittableGenerator interface.
|
abstract
Stream<RandomGenerator.SplittableGenerator>
|
splits(long streamSize)
Returns a stream producing the given streamSize number of new
pseudorandom number generators, each of which implements the
SplittableGenerator interface.
|
abstract
Stream<RandomGenerator.SplittableGenerator>
|
splits(RandomGenerator.SplittableGenerator source)
Returns an effectively unlimited stream of new pseudorandom number
generators, each of which implements the SplittableGenerator
interface.
|
|
|
Public constructors
SplittableRandom
public SplittableRandom ()
Creates a new SplittableRandom instance that is likely to
generate sequences of values that are statistically independent
of those of any other instances in the current program; and
may, and typically does, vary across program invocations.
SplittableRandom
public SplittableRandom (long seed)
Creates a new SplittableRandom instance using the specified
initial seed. SplittableRandom instances created with the same
seed in the same program generate identical sequences of values.
Parameters |
seed |
long : the initial seed |
Public methods
doubles
public DoubleStream doubles (long streamSize)
Returns a stream producing the given streamSize
number of
pseudorandom double
values from this generator and/or one split
from it; each value is between zero (inclusive) and one (exclusive).
Parameters |
streamSize |
long : the number of values to generate |
doubles
public DoubleStream doubles ()
Returns an effectively unlimited stream of pseudorandom double
values from this generator and/or one split from it; each value
is between zero (inclusive) and one (exclusive).
Implementation Note:
- This method is implemented to be equivalent to
doubles(Long.MAX_VALUE)
.
doubles
public DoubleStream doubles (double randomNumberOrigin,
double randomNumberBound)
Returns an effectively unlimited stream of pseudorandom double
values from this generator and/or one split from it; each value
conforms to the given origin (inclusive) and bound (exclusive).
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) |
doubles
public DoubleStream doubles (long streamSize,
double randomNumberOrigin,
double randomNumberBound)
Returns a stream producing the given streamSize
number of
pseudorandom double
values from this generator and/or one split
from it; each value conforms to the given origin (inclusive) and bound
(exclusive).
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 |
if streamSize is
less than zero, or randomNumberOrigin
is greater than or equal to randomNumberBound |
ints
public IntStream ints (long streamSize)
Returns a stream producing the given streamSize
number
of pseudorandom int
values from this generator and/or
one split from it.
Parameters |
streamSize |
long : the number of values to generate |
Returns |
IntStream |
a stream of pseudorandom int values |
ints
public IntStream ints (int randomNumberOrigin,
int randomNumberBound)
Returns an effectively unlimited stream of pseudorandom int
values from this generator and/or one split from it; each value
conforms to the given origin (inclusive) and bound (exclusive).
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) |
ints
public IntStream ints (long streamSize,
int randomNumberOrigin,
int randomNumberBound)
Returns a stream producing the given streamSize
number
of pseudorandom int
values from this generator and/or one split
from it; each value conforms to the given origin (inclusive) and bound
(exclusive).
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 |
if streamSize is
less than zero, or randomNumberOrigin
is greater than or equal to randomNumberBound |
ints
public IntStream ints ()
Returns an effectively unlimited stream of pseudorandom int
values from this generator and/or one split from it.
Implementation Note:
- This method is implemented to be equivalent to
ints(Long.MAX_VALUE)
.
Returns |
IntStream |
a stream of pseudorandom int values |
longs
public LongStream longs ()
Returns an effectively unlimited stream of pseudorandom long
values from this generator and/or one split from it.
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 streamSize)
Returns a stream producing the given streamSize
number
of pseudorandom long
values from this generator and/or
one split from it.
Parameters |
streamSize |
long : the number of values to generate |
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 from this generator and/or one split from it; each value
conforms to the given origin (inclusive) and bound (exclusive).
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) |
longs
public LongStream longs (long streamSize,
long randomNumberOrigin,
long randomNumberBound)
Returns a stream producing the given streamSize
number of
pseudorandom long
values from this generator and/or one split
from it; each value conforms to the given origin (inclusive) and bound
(exclusive).
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 |
if streamSize is
less than zero, or randomNumberOrigin
is greater than or equal to randomNumberBound |
nextBytes
public void nextBytes (byte[] bytes)
Fills a user-supplied byte array with generated byte values
pseudorandomly chosen uniformly from the range of values between -128
(inclusive) and 127 (inclusive).
Parameters |
bytes |
byte : the byte array to fill with pseudorandom bytes |
nextInt
public int nextInt ()
Returns a pseudorandomly chosen int
value.
Returns |
int |
a pseudorandomly chosen int value |
nextLong
public long nextLong ()
Returns a pseudorandomly chosen long
value.
Returns |
long |
a pseudorandomly chosen long value |
split
public SplittableRandom split ()
Constructs and returns a new SplittableRandom instance that
shares no mutable state with this instance. However, with very
high probability, the set of values collectively generated by
the two objects has the same statistical properties as if the
same quantity of values were generated by a single thread using
a single SplittableRandom object. Either or both of the two
objects may be further split using the split()
method,
and the same expected statistical properties apply to the
entire set of generators constructed by such recursive
splitting.
splits
public Stream<RandomGenerator.SplittableGenerator> splits ()
Returns an effectively unlimited stream of new pseudorandom number
generators, each of which implements the SplittableGenerator
interface.
This pseudorandom number generator may be used as a source of
pseudorandom bits used to initialize the state the new ones.
Implementation Requirements:
splits
public Stream<RandomGenerator.SplittableGenerator> splits (long streamSize)
Returns a stream producing the given streamSize
number of new
pseudorandom number generators, each of which implements the
SplittableGenerator
interface.
This pseudorandom number generator may be used as a source of
pseudorandom bits used to initialize the state the new ones.
Implementation Requirements:
Parameters |
streamSize |
long : the number of values to generate |