APIdia Launch Partner
Top Description Inners Fields Constructors Methods
java.util

public final Class SplittableRandom

extends Object
implements RandomGenerator, SplittableGenerator
Class Inheritance
All Implemented Interfaces
java.util.random.RandomGenerator.SplittableGenerator, java.util.random.RandomGenerator.StreamableGenerator, java.util.random.RandomGenerator
Imports
java.util.concurrent.atomic.AtomicLong, java.util.random.RandomGenerator, .RandomGenerator.SplittableGenerator, java.util.stream.DoubleStream, .IntStream, .LongStream, .Stream, jdk.internal.util.random.RandomSupport, .RandomSupport.AbstractSplittableGenerator
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 java.util.Random but differs in the following ways:

Instances of SplittableRandom 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 system property java.util.secureRandomSeed is set to true.

Authors
Guy Steele, Doug Lea
Since
1.8

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
SplittableRandom.AbstractSplittableGeneratorProxy

Proxy class to non-public RandomSupportAbstractSplittableGenerator.

Field Summary

Modifier and TypeField and Description
private static final AtomicLong
defaultGen

The seed generator for default constructors.

private final long
gamma

The step value.

private static final long
GOLDEN_GAMMA

The golden ratio scaled to 64bits, used as the initial gamma value for (unsplit) SplittableRandoms.

private SplittableRandom.AbstractSplittableGeneratorProxy
proxy

Proxy object to non-public RandomSupportAbstractSplittableGenerator.

private long
seed

The seed.

Constructor Summary

AccessConstructor and Description
private
SplittableRandom(long seed, long gamma)

Internal constructor used by all others except default constructor.

public
SplittableRandom(long
the initial seed
seed)

Creates a new SplittableRandom instance using the specified initial seed.

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.

Method Summary

Modifier and TypeMethod and Description
public DoubleStream

Returns:

a stream of double values
doubles(long
the number of values to generate
streamSize)

Overrides default java.util.random.RandomGenerator.doubles.

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).

public DoubleStream

Returns:

a stream of pseudorandom double values
doubles()

Overrides default java.util.random.RandomGenerator.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).

public DoubleStream

Returns:

a stream of pseudorandom double values, each with the given origin (inclusive) and bound (exclusive)
doubles(long
the number of values to generate
streamSize, double
the origin (inclusive) of each random value
randomNumberOrigin, double
the bound (exclusive) of each random value
randomNumberBound)

Overrides default java.util.random.RandomGenerator.doubles.

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).

public DoubleStream

Returns:

a stream of pseudorandom double values, each with the given origin (inclusive) and bound (exclusive)
doubles(double
the origin (inclusive) of each random value
randomNumberOrigin, double
the bound (exclusive) of each random value
randomNumberBound)

Overrides default java.util.random.RandomGenerator.doubles.

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).

public IntStream

Returns:

a stream of pseudorandom int values
ints(long
the number of values to generate
streamSize)

Overrides default java.util.random.RandomGenerator.ints.

Returns a stream producing the given streamSize number of pseudorandom int values from this generator and/or one split from it.

public IntStream

Returns:

a stream of pseudorandom int values
ints()

Overrides default java.util.random.RandomGenerator.ints.

Returns an effectively unlimited stream of pseudorandom int values from this generator and/or one split from it.

public IntStream

Returns:

a stream of pseudorandom int values, each with the given origin (inclusive) and bound (exclusive)
ints(long
the number of values to generate
streamSize, int
the origin (inclusive) of each random value
randomNumberOrigin, int
the bound (exclusive) of each random value
randomNumberBound)

Overrides default java.util.random.RandomGenerator.ints.

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).

public IntStream

Returns:

a stream of pseudorandom int values, each with the given origin (inclusive) and bound (exclusive)
ints(int
the origin (inclusive) of each random value
randomNumberOrigin, int
the bound (exclusive) of each random value
randomNumberBound)

Overrides default java.util.random.RandomGenerator.ints.

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).

public LongStream

Returns:

a stream of pseudorandom long values
longs(long
the number of values to generate
streamSize)

Overrides default java.util.random.RandomGenerator.longs.

Returns a stream producing the given streamSize number of pseudorandom long values from this generator and/or one split from it.

public LongStream

Returns:

a stream of pseudorandom long values
longs()

Overrides default java.util.random.RandomGenerator.longs.

Returns an effectively unlimited stream of pseudorandom long values from this generator and/or one split from it.

public LongStream

Returns:

a stream of pseudorandom long values, each with the given origin (inclusive) and bound (exclusive)
longs(long
the number of values to generate
streamSize, long
the origin (inclusive) of each random value
randomNumberOrigin, long
the bound (exclusive) of each random value
randomNumberBound)

Overrides default java.util.random.RandomGenerator.longs.

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).

public LongStream

Returns:

a stream of pseudorandom long values, each with the given origin (inclusive) and bound (exclusive)
longs(long
the origin (inclusive) of each random value
randomNumberOrigin, long
the bound (exclusive) of each random value
randomNumberBound)

Overrides default java.util.random.RandomGenerator.longs.

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).

private static int
mix32(long z)

Returns the 32 high bits of Stafford variant 4 mix64 function as int.

private static long
mix64(long z)

Computes Stafford variant 13 of 64bit mix function.

private static long
mixGamma(long z)

Returns the gamma value to use for a new split instance.

public void
nextBytes(byte[] bytes)

Overrides default java.util.random.RandomGenerator.nextBytes.

Fills a user-supplied byte array with generated byte values pseudorandomly chosen uniformly from the range of values between -128 (inclusive) and 127 (inclusive).

public int
nextInt()

Overrides default java.util.random.RandomGenerator.nextInt.

Returns a pseudorandomly chosen int value.

public long
nextLong()

Implements java.util.random.RandomGenerator.nextLong.

Returns a pseudorandomly chosen long value.

private long
nextSeed()

Adds gamma to seed.

public SplittableRandom

Returns:

the new SplittableRandom instance
split()

Implements java.util.random.RandomGenerator.SplittableGenerator.split.

Constructs and returns a new SplittableRandom instance that shares no mutable state with this instance.

public SplittableRandom
split(RandomGenerator.SplittableGenerator source)

Implements java.util.random.RandomGenerator.SplittableGenerator.split.

Returns a new pseudorandom number generator, split off from this one, that implements the RandomGenerator and SplittableGenerator interfaces.

public Stream<RandomGenerator.SplittableGenerator>
splits()

Overrides default java.util.random.RandomGenerator.SplittableGenerator.splits.

Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the SplittableGenerator interface.

public Stream<RandomGenerator.SplittableGenerator>
splits(long streamSize)

Implements java.util.random.RandomGenerator.SplittableGenerator.splits.

Returns a stream producing the given streamSize number of new pseudorandom number generators, each of which implements the SplittableGenerator interface.

public Stream<RandomGenerator.SplittableGenerator>
splits(RandomGenerator.SplittableGenerator source)

Implements java.util.random.RandomGenerator.SplittableGenerator.splits.

Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the SplittableGenerator interface.

public Stream<RandomGenerator.SplittableGenerator>
splits(long streamSize, RandomGenerator.SplittableGenerator source)

Implements java.util.random.RandomGenerator.SplittableGenerator.splits.

Returns a stream producing the given streamSize number of new pseudorandom number generators, each of which implements the SplittableGenerator interface.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

defaultGenback to summary
private static final AtomicLong defaultGen

The seed generator for default constructors.

gammaback to summary
private final long gamma

The step value.

GOLDEN_GAMMAback to summary
private static final long GOLDEN_GAMMA

The golden ratio scaled to 64bits, used as the initial gamma value for (unsplit) SplittableRandoms.

proxyback to summary
private SplittableRandom.AbstractSplittableGeneratorProxy proxy

Proxy object to non-public RandomSupportAbstractSplittableGenerator.

seedback to summary
private long seed

The seed. Updated only via method nextSeed.

Constructor Detail

SplittableRandomback to summary
private SplittableRandom(long seed, long gamma)

Internal constructor used by all others except default constructor.

SplittableRandomback to summary
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

SplittableRandomback to summary
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.

Method Detail

doublesback to summary
public DoubleStream doubles(long streamSize)

Overrides default java.util.random.RandomGenerator.doubles.

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

Returns:DoubleStream

a stream of double values

Annotations
@Override
Exceptions
IllegalArgumentException:
if streamSize is less than zero
doublesback to summary
public DoubleStream doubles()

Overrides default java.util.random.RandomGenerator.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).

Returns:DoubleStream

a stream of pseudorandom double values

Annotations
@Override
doublesback to summary
public DoubleStream doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)

Overrides default java.util.random.RandomGenerator.doubles.

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)

Annotations
@Override
Exceptions
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
doublesback to summary
public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound)

Overrides default java.util.random.RandomGenerator.doubles.

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)

Annotations
@Override
Exceptions
IllegalArgumentException:
if randomNumberOrigin is not finite, or randomNumberBound is not finite, or randomNumberOrigin is greater than or equal to randomNumberBound
intsback to summary
public IntStream ints(long streamSize)

Overrides default java.util.random.RandomGenerator.ints.

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

Annotations
@Override
Exceptions
IllegalArgumentException:
if streamSize is less than zero
intsback to summary
public IntStream ints()

Overrides default java.util.random.RandomGenerator.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

Annotations
@Override
intsback to summary
public IntStream ints(long streamSize, int randomNumberOrigin, int randomNumberBound)

Overrides default java.util.random.RandomGenerator.ints.

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)

Annotations
@Override
Exceptions
IllegalArgumentException:
if streamSize is less than zero, or randomNumberOrigin is greater than or equal to randomNumberBound
intsback to summary
public IntStream ints(int randomNumberOrigin, int randomNumberBound)

Overrides default java.util.random.RandomGenerator.ints.

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)

Annotations
@Override
Exceptions
IllegalArgumentException:
if randomNumberOrigin is greater than or equal to randomNumberBound
longsback to summary
public LongStream longs(long streamSize)

Overrides default java.util.random.RandomGenerator.longs.

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

Annotations
@Override
Exceptions
IllegalArgumentException:
if streamSize is less than zero
longsback to summary
public LongStream longs()

Overrides default java.util.random.RandomGenerator.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

Annotations
@Override
longsback to summary
public LongStream longs(long streamSize, long randomNumberOrigin, long randomNumberBound)

Overrides default java.util.random.RandomGenerator.longs.

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)

Annotations
@Override
Exceptions
IllegalArgumentException:
if streamSize is less than zero, or randomNumberOrigin is greater than or equal to randomNumberBound
longsback to summary
public LongStream longs(long randomNumberOrigin, long randomNumberBound)

Overrides default java.util.random.RandomGenerator.longs.

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)

Annotations
@Override
Exceptions
IllegalArgumentException:
if randomNumberOrigin is greater than or equal to randomNumberBound
mix32back to summary
private static int mix32(long z)

Returns the 32 high bits of Stafford variant 4 mix64 function as int. http://zimbry.blogspot.com/2011/09/better-bit-mixing-improving-on.html

mix64back to summary
private static long mix64(long z)

Computes Stafford variant 13 of 64bit mix function. http://zimbry.blogspot.com/2011/09/better-bit-mixing-improving-on.html

mixGammaback to summary
private static long mixGamma(long z)

Returns the gamma value to use for a new split instance. Uses the 64bit mix function from MurmurHash3. https://github.com/aappleby/smhasher/wiki/MurmurHash3

nextBytesback to summary
public void nextBytes(byte[] bytes)

Overrides default java.util.random.RandomGenerator.nextBytes.

Doc from java.util.random.RandomGenerator.nextBytes.

Fills a user-supplied byte array with generated byte values pseudorandomly chosen uniformly from the range of values between -128 (inclusive) and 127 (inclusive).

Annotations
@Override
Exceptions
NullPointerException:
if bytes is null
Since
10
nextIntback to summary
public int nextInt()

Overrides default java.util.random.RandomGenerator.nextInt.

Doc from java.util.random.RandomGenerator.nextInt.

Returns a pseudorandomly chosen int value.

Annotations
@Override
nextLongback to summary
public long nextLong()

Implements java.util.random.RandomGenerator.nextLong.

Doc from java.util.random.RandomGenerator.nextLong.

Returns a pseudorandomly chosen long value.

Annotations
@Override
nextSeedback to summary
private long nextSeed()

Adds gamma to seed.

splitback to summary
public SplittableRandom split()

Implements java.util.random.RandomGenerator.SplittableGenerator.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.

Returns:SplittableRandom

the new SplittableRandom instance

splitback to summary
public SplittableRandom split(RandomGenerator.SplittableGenerator source)

Implements java.util.random.RandomGenerator.SplittableGenerator.split.

Doc from java.util.random.RandomGenerator.SplittableGenerator.split.

Returns a new pseudorandom number generator, split off from this one, that implements the RandomGenerator and SplittableGenerator interfaces.

Exceptions
NullPointerException:
if source is null
Since
17
splitsback to summary
public Stream<RandomGenerator.SplittableGenerator> splits()

Overrides default java.util.random.RandomGenerator.SplittableGenerator.splits.

Doc from java.util.random.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 Specification

The default implementation invokes splits(this).

Annotations
@Override
Since
17
splitsback to summary
public Stream<RandomGenerator.SplittableGenerator> splits(long streamSize)

Implements java.util.random.RandomGenerator.SplittableGenerator.splits.

Doc from java.util.random.RandomGenerator.SplittableGenerator.splits.

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.

Annotations
@Override
Exceptions
IllegalArgumentException:
if streamSize is less than zero
Since
17
splitsback to summary
public Stream<RandomGenerator.SplittableGenerator> splits(RandomGenerator.SplittableGenerator source)

Implements java.util.random.RandomGenerator.SplittableGenerator.splits.

Doc from java.util.random.RandomGenerator.SplittableGenerator.splits.

Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the SplittableGenerator interface.

Implementation Specification

It is permitted to implement this method in a manner equivalent to splits (Long.MAX_VALUE, source).

Annotations
@Override
Exceptions
NullPointerException:
if source is null
Since
17
splitsback to summary
public Stream<RandomGenerator.SplittableGenerator> splits(long streamSize, RandomGenerator.SplittableGenerator source)

Implements java.util.random.RandomGenerator.SplittableGenerator.splits.

Doc from java.util.random.RandomGenerator.SplittableGenerator.splits.

Returns a stream producing the given streamSize number of new pseudorandom number generators, each of which implements the SplittableGenerator interface.

Annotations
@Override
Exceptions
NullPointerException:
if source is null
IllegalArgumentException:
if streamSize is less than zero
Since
17
java.util back to summary

private Class SplittableRandom.AbstractSplittableGeneratorProxy

extends AbstractSplittableGenerator
Class Inheritance
Proxy class to non-public RandomSupportAbstractSplittableGenerator.

Constructor Summary

AccessConstructor and Description
private
AbstractSplittableGeneratorProxy()

Method Summary

Modifier and TypeMethod and Description
public int
nextInt()

Overrides default java.util.random.RandomGenerator.nextInt.

Returns a pseudorandomly chosen int value.

public long
nextLong()

Implements java.util.random.RandomGenerator.nextLong.

Returns a pseudorandomly chosen long value.

public SplittableRandom
split(RandomGenerator.SplittableGenerator source)

Implements java.util.random.RandomGenerator.SplittableGenerator.split.

Returns a new pseudorandom number generator, split off from this one, that implements the RandomGenerator and SplittableGenerator interfaces.

Inherited from jdk.internal.util.random.RandomSupport.AbstractSplittableGenerator:
splitsplitssplitssplitssplits

Constructor Detail

AbstractSplittableGeneratorProxyback to summary
private AbstractSplittableGeneratorProxy()

Method Detail

nextIntback to summary
public int nextInt()

Overrides default java.util.random.RandomGenerator.nextInt.

Doc from java.util.random.RandomGenerator.nextInt.

Returns a pseudorandomly chosen int value.

Annotations
@Override
nextLongback to summary
public long nextLong()

Implements java.util.random.RandomGenerator.nextLong.

Doc from java.util.random.RandomGenerator.nextLong.

Returns a pseudorandomly chosen long value.

Annotations
@Override
splitback to summary
public SplittableRandom split(RandomGenerator.SplittableGenerator source)

Implements java.util.random.RandomGenerator.SplittableGenerator.split.

Doc from java.util.random.RandomGenerator.SplittableGenerator.split.

Returns a new pseudorandom number generator, split off from this one, that implements the RandomGenerator and SplittableGenerator interfaces.

Annotations
@Override