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 2127.
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 pseudo-random
number generator for use by security-sensitive 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 264 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 2logDistance
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 2128 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 2logDistance
within its state cycle.- Parameters:
logDistance
- the base-2 logarithm of the distance to jump forward within the state cycle- Throws:
IllegalArgumentException
- iflogDistance
is 2logDistance
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 264 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 2128 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
-