Package io.github.pr0methean.betterrandom.prng.adapter

Class EntropyBlockingRandomWrapper

java.lang.Object

java.util.Random

io.github.pr0methean.betterrandom.prng.BaseRandom

io.github.pr0methean.betterrandom.prng.adapter.RandomWrapper

io.github.pr0methean.betterrandom.prng.adapter.EntropyBlockingRandomWrapper

All Implemented Interfaces:

ByteArrayReseedableRandom, EntropyCountingRandom, Java8CompatRandom, RepeatableRandom, Dumpable, Serializable

public class EntropyBlockingRandomWrapper
extends RandomWrapper

A RandomWrapper with the additional property that it won't return any output that would take its entropy below a minimum amount, and will instead either wait to be reseeded by a SimpleRandomSeeder or, if none is installed, reseed itself on the calling thread with a SeedGenerator. If neither is present, the caller is responsible for reseeding, and any call that would reduce entropy below the minimum will throw IllegalStateException.

See Also:

Serialized Form

Field Summary

Fields inherited from class io.github.pr0methean.betterrandom.prng.BaseRandom

ENTROPY_OF_DOUBLE, ENTROPY_OF_FLOAT, entropyBits, lock, randomSeeder, seed, superConstructorFinished

Constructor Summary

Constructors

Constructor	Description
EntropyBlockingRandomWrapper(byte[] seed, long minimumEntropy, SeedGenerator sameThreadSeedGen)
EntropyBlockingRandomWrapper(long seed, long minimumEntropy, SeedGenerator sameThreadSeedGen)
EntropyBlockingRandomWrapper(long minimumEntropy, SeedGenerator seedGenerator)
EntropyBlockingRandomWrapper(Random wrapped, long minimumEntropy, SeedGenerator sameThreadSeedGen)

Method Summary

Modifier and Type	Method	Description
protected void	checkMaxOutputAtOnce()	Ensures that the attached PRNG can output 64 bits between reseedings, given that its current entropy is the maximum possible.
protected void	debitEntropy(long bits)	Record that entropy has been spent, and schedule a reseeding if this PRNG has now spent as much as it's been seeded with.
SeedGenerator	getSameThreadSeedGen()
boolean	needsReseedingEarly()	If true, this PRNG needs reseeding even though its entropy is positive.
void	nextBytes(byte[] bytes)	Generates random bytes and places them into a user-supplied byte array.
protected void	onSeedingStateChanged(boolean reseeded)	Called when a new seed generator or SimpleRandomSeeder is attached or a new seed is generated, so that operations can unblock.
void	setRandomSeeder(SimpleRandomSeeder randomSeeder)	Registers this PRNG with the SimpleRandomSeeder for the corresponding SeedGenerator, to schedule reseeding when we run out of entropy.
void	setSameThreadSeedGen(SeedGenerator newSeedGen)
void	setSeed(long seed)	Sets the seed of this random number generator using a single long seed, if this implementation supports that.
protected void	setSeedInternal(byte[] seed)	Delegates to one of ByteArrayReseedableRandom.setSeed(byte[]), SecureRandom.setSeed(byte[]) or Random.setSeed(long).

Methods inherited from class io.github.pr0methean.betterrandom.prng.adapter.RandomWrapper

addSubclassFields, getNewSeedLength, getSeed, getWrapped, next, nextBoolean, nextDoubleNoEntropyDebit, nextFloat, nextGaussian, nextInt, nextInt, nextLongNoEntropyDebit, preferSeedWithLong, setWrapped, supportsMultipleSeedLengths, toString, usesParallelStreams

Methods inherited from class io.github.pr0methean.betterrandom.prng.BaseRandom

checkLength, creditEntropyForNewSeed, doubles, doubles, doubles, doubles, dump, entropyOfInt, entropyOfLong, fallbackSetSeedIfInitialized, gaussians, gaussians, getEntropyBits, getRandomSeeder, initTransientFields, internalNextGaussian, ints, ints, ints, ints, lockForNextGaussian, longs, longs, longs, longs, nextDouble, nextDouble, nextDouble, nextElement, nextElement, nextEnum, nextInt, nextLong, nextLong, nextLong, setSeed, unlockForNextGaussian, withProbability, withProbabilityInternal

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

EntropyBlockingRandomWrapper

public EntropyBlockingRandomWrapper(long minimumEntropy,
                                    SeedGenerator seedGenerator)
                             throws SeedException

Throws:

SeedException

EntropyBlockingRandomWrapper

public EntropyBlockingRandomWrapper(byte[] seed,
                                    long minimumEntropy,
                                    @Nullable
                                    SeedGenerator sameThreadSeedGen)

EntropyBlockingRandomWrapper

public EntropyBlockingRandomWrapper(long seed,
                                    long minimumEntropy,
                                    @Nullable
                                    SeedGenerator sameThreadSeedGen)

EntropyBlockingRandomWrapper

public EntropyBlockingRandomWrapper(Random wrapped,
                                    long minimumEntropy,
                                    @Nullable
                                    SeedGenerator sameThreadSeedGen)

Method Detail

nextBytes

public void nextBytes(byte[] bytes)

Description copied from class: BaseRandom

Generates random bytes and places them into a user-supplied byte array. The number of random bytes produced is equal to the length of the byte array. Reimplemented for entropy-counting purposes.

Specified by:

nextBytes in interface Java8CompatRandom

Overrides:

nextBytes in class RandomWrapper

getSameThreadSeedGen

@Nullable
public SeedGenerator getSameThreadSeedGen()

setSameThreadSeedGen

public void setSameThreadSeedGen(@Nullable
                                 SeedGenerator newSeedGen)

setSeedInternal

protected void setSeedInternal(byte[] seed)

Description copied from class: RandomWrapper

Delegates to one of ByteArrayReseedableRandom.setSeed(byte[]), SecureRandom.setSeed(byte[]) or Random.setSeed(long).

Overrides:

setSeedInternal in class RandomWrapper

Parameters:

seed - The new seed.

setRandomSeeder

public void setRandomSeeder(@Nullable
                            SimpleRandomSeeder randomSeeder)

Description copied from class: BaseRandom

Registers this PRNG with the SimpleRandomSeeder for the corresponding SeedGenerator, to schedule reseeding when we run out of entropy. Unregisters this PRNG with the previous SimpleRandomSeeder if it had a different one.

Overrides:

setRandomSeeder in class BaseRandom

Parameters:

randomSeeder - a SeedGenerator whose SimpleRandomSeeder will be used to reseed this PRNG, or null to stop using one.

debitEntropy

protected void debitEntropy(long bits)

Description copied from class: BaseRandom

Record that entropy has been spent, and schedule a reseeding if this PRNG has now spent as much as it's been seeded with.

Overrides:

debitEntropy in class BaseRandom

Parameters:

bits - The number of bits of entropy spent.

setSeed

public void setSeed(long seed)

Description copied from class: BaseRandom

Sets the seed of this random number generator using a single long seed, if this implementation supports that. If it is capable of using 64 bits or less of seed data (i.e. if {@link #getNewSeedLength()} <= {@link Long#BYTES}), then this method shall replace the entire seed as Random.setSeed(long) does; otherwise, it shall either combine the input with the existing seed as SecureRandom.setSeed(long) does, or it shall generate a new seed using the DefaultSeedGenerator. The latter is a backward-compatibility measure and can be very slow.

Specified by:

setSeed in interface Java8CompatRandom

Overrides:

setSeed in class RandomWrapper

needsReseedingEarly

public boolean needsReseedingEarly()

Description copied from interface: EntropyCountingRandom

If true, this PRNG needs reseeding even though its entropy is positive. Added to deal with EntropyBlockingRandomWrapper.

Specified by:

needsReseedingEarly in interface EntropyCountingRandom

Overrides:

needsReseedingEarly in class BaseRandom

Returns:

true if this PRNG needs reseeding regardless of entropy count; false otherwise

checkMaxOutputAtOnce

protected void checkMaxOutputAtOnce()

Ensures that the attached PRNG can output 64 bits between reseedings, given that its current entropy is the maximum possible. Methods such as Random.nextLong() and Random.nextDouble() would become much slower and more complex if we didn't require this.

Throws:

IllegalArgumentException - if the PRNG cannot output 64 bits between reseedings

onSeedingStateChanged

protected void onSeedingStateChanged(boolean reseeded)

Called when a new seed generator or SimpleRandomSeeder is attached or a new seed is generated, so that operations can unblock.

Parameters:

reseeded - true if the seed has changed; false otherwise