Interface RandomGenerator.ArbitrarilyJumpableGenerator
 All Superinterfaces:
RandomGenerator
,RandomGenerator.JumpableGenerator
,RandomGenerator.LeapableGenerator
,RandomGenerator.StreamableGenerator
 Enclosing interface:
RandomGenerator
Ideally, all RandomGenerator.ArbitrarilyJumpableGenerator
objects produced by
iterative jumping from a single original
RandomGenerator.ArbitrarilyJumpableGenerator
object are statistically independent
of one another and individually uniform, provided that they do not
traverse overlapping portions of the state cycle. In practice, one must
settle for some approximation to independence and uniformity. In
particular, a specific implementation may assume that each generator in a
stream produced by the jump
() method is
used to produce a number of values no larger than the jump distance
specified. Implementors are advised to use algorithms whose period is at
least 2^{127}.
For many applications, it suffices to jump forward by a power of two
or some small multiple of a power of two, but this power of two may not
be representable as a long
value. To avoid the use of
BigInteger
values as jump distances, double
values are
used instead.
Methods are provided to perform a single jump operation and also to
produce a stream of generators produced from the original by iterative
copying and jumping of internal state. A typical strategy for a
multithreaded application is to create a single
RandomGenerator.ArbitrarilyJumpableGenerator
object, call its
jump
() method exactly once, and then
parcel out generators from the resulting stream, one to each thread.
However, each generator produced also has type
RandomGenerator.ArbitrarilyJumpableGenerator
; with care, different jump distances
can be used to traverse the entire state cycle in various ways.
Objects that implement RandomGenerator.ArbitrarilyJumpableGenerator
are
typically not cryptographically secure. Consider instead using
SecureRandom
to get a cryptographically secure pseudorandom
number generator for use by securitysensitive applications.

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 TypeMethodDescriptioncopy()
Returns a new generator whose internal state is an exact copy of this generator (therefore their future behavior should be identical if subjected to the same series of operations).copyAndJump
(double distance) Copy this generator, jump this generator forward, then return the copy.default void
jump()
Alter the state of this pseudorandom number generator so as to jump forward a large, fixed distance (typically 2^{64} or more) within its state cycle.void
jump
(double distance) Alter the state of this pseudorandom number generator so as to jump forward a specified distance within its state cycle.void
jumpPowerOfTwo
(int logDistance) Alter the state of this pseudorandom number generator so as to jump forward a distance equal to 2^{logDistance} within its state cycle.jumps
(double distance) Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements theRandomGenerator.ArbitrarilyJumpableGenerator
interface, produced by jumping copies of this generator by different integer multiples of the specified jump distance.jumps
(long streamSize, double distance) Returns a stream producing the givenstreamSize
number of new pseudorandom number generators, each of which implements theRandomGenerator.ArbitrarilyJumpableGenerator
interface, produced by jumping copies of this generator by different integer multiples of the specified jump distance.default void
leap()
Alter the state of this pseudorandom number generator so as to jump forward a very large, fixed distance (typically 2^{128} or more) within its state cycle.Returns an instance ofRandomGenerator.ArbitrarilyJumpableGenerator
that utilizes thename
algorithm.Methods declared in interface java.util.random.RandomGenerator
doubles, doubles, doubles, doubles, equiDoubles, ints, ints, ints, ints, isDeprecated, longs, longs, longs, longs, nextBoolean, nextBytes, nextDouble, nextDouble, nextDouble, nextExponential, nextFloat, nextFloat, nextFloat, nextGaussian, nextGaussian, nextInt, nextInt, nextInt, nextLong, nextLong, nextLong
Methods declared in interface java.util.random.RandomGenerator.JumpableGenerator
copyAndJump, jumpDistance, jumps, jumps, rngs, rngs
Methods declared in interface java.util.random.RandomGenerator.LeapableGenerator
copyAndLeap, leapDistance, leaps, leaps

Method Details

of
Returns an instance ofRandomGenerator.ArbitrarilyJumpableGenerator
that utilizes thename
algorithm. Parameters:
name
 Name of random number generator algorithm Returns:
 An instance of
RandomGenerator.ArbitrarilyJumpableGenerator
 Throws:
NullPointerException
 if name is nullIllegalArgumentException
 if the named algorithm is not found

copy
Returns a new generator whose internal state is an exact copy of this generator (therefore their future behavior should be identical if subjected to the same series of operations). Specified by:
copy
in interfaceRandomGenerator.JumpableGenerator
 Specified by:
copy
in interfaceRandomGenerator.LeapableGenerator
 Returns:
 a new object that is a copy of this generator

jumpPowerOfTwo
void jumpPowerOfTwo(int logDistance) Alter the state of this pseudorandom number generator so as to jump forward a distance equal to 2^{logDistance} within its state cycle. Parameters:
logDistance
 the base2 logarithm of the distance to jump forward within the state cycle Throws:
IllegalArgumentException
 iflogDistance
is 2^{logDistance} is greater than the period of this generator

jump
void jump(double distance) Alter the state of this pseudorandom number generator so as to jump forward a specified distance within its state cycle. Parameters:
distance
 the distance to jump forward within the state cycle Throws:
IllegalArgumentException
 ifdistance
is not greater than or equal to 0.0, or is greater than the period of this generator

jump
default void jump()Alter the state of this pseudorandom number generator so as to jump forward a large, fixed distance (typically 2^{64} or more) within its state cycle. The distance used is that returned by methodjumpDistance
(). Specified by:
jump
in interfaceRandomGenerator.JumpableGenerator
 Implementation Requirements:
 The default implementation invokes jump(jumpDistance()).

jumps
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements theRandomGenerator.ArbitrarilyJumpableGenerator
interface, produced by jumping copies of this generator by different integer multiples of the specified jump distance. Implementation Requirements:
 The default implementation is equivalent to
jumps
(Long.MAX_VALUE
).  Parameters:
distance
 a distance to jump forward within the state cycle Returns:
 a stream of objects that implement the
RandomGenerator
interface  Throws:
IllegalArgumentException
 ifdistance
is not greater than or equal to 0.0, or is greater than the period of this generator

jumps
default Stream<RandomGenerator.ArbitrarilyJumpableGenerator> jumps(long streamSize, double distance) Returns a stream producing the givenstreamSize
number of new pseudorandom number generators, each of which implements theRandomGenerator.ArbitrarilyJumpableGenerator
interface, produced by jumping copies of this generator by different integer multiples of the specified jump distance. Implementation Requirements:
 The default implementation is equivalent to jumps(distance).limit(streamSize).
 Parameters:
streamSize
 the number of generators to generatedistance
 a distance to jump forward within the state cycle Returns:
 a stream of objects that implement the
RandomGenerator
interface  Throws:
IllegalArgumentException
 ifstreamSize
is less than zero or ifdistance
is not greater than or equal to 0.0, or is greater than the period of this generator

leap
default void leap()Alter the state of this pseudorandom number generator so as to jump forward a very large, fixed distance (typically 2^{128} or more) within its state cycle. The distance used is that returned by methodleapDistance
(). Specified by:
leap
in interfaceRandomGenerator.LeapableGenerator

copyAndJump
Copy this generator, jump this generator forward, then return the copy. Implementation Requirements:
 The default implementation copies this, jumps(distance) and then returns the copy.
 Parameters:
distance
 a distance to jump forward within the state cycle Returns:
 a copy of this generator object before the jump occurred
 Throws:
IllegalArgumentException
 ifdistance
is not greater than or equal to 0.0, or is greater than the period of this generator
