- 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 voidjump()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.voidjump(double distance) Alter the state of this pseudorandom number generator so as to jump forward a specified distance within its state cycle.voidjumpPowerOfTwo(int logDistance) Alter the state of this pseudorandom number generator so as to jump forward a distance equal to 2logDistancewithin its state cycle.jumps(double distance) Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements theRandomGenerator.ArbitrarilyJumpableGeneratorinterface, 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 givenstreamSizenumber of new pseudorandom number generators, each of which implements theRandomGenerator.ArbitrarilyJumpableGeneratorinterface, produced by jumping copies of this generator by different integer multiples of the specified jump distance.default voidleap()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.ArbitrarilyJumpableGeneratorthat utilizes thenamealgorithm.Methods declared in interface java.util.random.RandomGenerator
doubles, doubles, doubles, doubles, 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, nextLongMethods declared in interface java.util.random.RandomGenerator.JumpableGenerator
copyAndJump, jumpDistance, jumps, jumps, rngs, rngsMethods declared in interface java.util.random.RandomGenerator.LeapableGenerator
copyAndLeap, leapDistance, leaps, leaps
-
Method Details
-
of
Returns an instance ofRandomGenerator.ArbitrarilyJumpableGeneratorthat utilizes thenamealgorithm.- 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:
copyin interfaceRandomGenerator.JumpableGenerator- Specified by:
copyin 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 2logDistancewithin its state cycle.- Parameters:
logDistance- the base-2 logarithm of the distance to jump forward within the state cycle- Throws:
IllegalArgumentException- iflogDistanceis 2logDistanceis 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- ifdistanceis 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:
jumpin 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.ArbitrarilyJumpableGeneratorinterface, 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
RandomGeneratorinterface - Throws:
IllegalArgumentException- ifdistanceis 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 givenstreamSizenumber of new pseudorandom number generators, each of which implements theRandomGenerator.ArbitrarilyJumpableGeneratorinterface, 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
RandomGeneratorinterface - Throws:
IllegalArgumentException- ifstreamSizeis less than zero or ifdistanceis 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:
leapin 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- ifdistanceis not greater than or equal to 0.0, or is greater than the period of this generator
-