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.
- Since:
- 17
- 
Nested Class SummaryNested classes/interfaces declared in interface java.util.random.RandomGeneratorRandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, RandomGenerator.StreamableGenerator
- 
Method SummaryModifier 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.RandomGeneratordoubles, 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, nextLongMethods declared in interface java.util.random.RandomGenerator.JumpableGeneratorcopyAndJump, jumpDistance, jumps, jumps, rngs, rngsMethods declared in interface java.util.random.RandomGenerator.LeapableGeneratorcopyAndLeap, leapDistance, leaps, leaps
- 
Method Details- 
ofReturns 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 null
- IllegalArgumentException- if the named algorithm is not found
 
- 
copyReturns 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 interface- RandomGenerator.JumpableGenerator
- Specified by:
- copyin interface- RandomGenerator.LeapableGenerator
- Returns:
- a new object that is a copy of this generator
 
- 
jumpPowerOfTwovoid 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- if- logDistanceis 2- logDistanceis greater than the period of this generator
 
- 
jumpvoid 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- if- distanceis not greater than or equal to 0.0, or is greater than the period of this generator
 
- 
jumpdefault 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 interface- RandomGenerator.JumpableGenerator
- Implementation Requirements:
- The default implementation invokes jump(jumpDistance()).
 
- 
jumpsReturns 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- if- distanceis not greater than or equal to 0.0, or is greater than the period of this generator
 
- 
jumpsdefault 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 generate
- distance- a distance to jump forward within the state cycle
- Returns:
- a stream of objects that implement the RandomGeneratorinterface
- Throws:
- IllegalArgumentException- if- streamSizeis less than zero or if- distanceis not greater than or equal to 0.0, or is greater than the period of this generator
 
- 
leapdefault 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 interface- RandomGenerator.LeapableGenerator
 
- 
copyAndJumpCopy 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- if- distanceis not greater than or equal to 0.0, or is greater than the period of this generator
 
 
-