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

Class EntropyBlockingRandomWrapper<T extends Random>

java.lang.Object

java.util.Random

io.github.pr0methean.betterrandom.prng.BaseRandom

io.github.pr0methean.betterrandom.prng.adapter.RandomWrapper<T>

io.github.pr0methean.betterrandom.prng.adapter.EntropyBlockingRandomWrapper<T>

All Implemented Interfaces:

ByteArrayReseedableRandom, EntropyCountingRandom, RepeatableRandom, Dumpable, Serializable

public class EntropyBlockingRandomWrapper<T extends Random>
extends RandomWrapper<T>

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 RandomSeeder 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(T 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()	Returns the seed generator that is used on the calling thread if not registered with a running RandomSeeder.
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 RandomSeeder is attached or a new seed is generated, so that operations can unblock.
void	setRandomSeeder(RandomSeeder randomSeeder)	Registers this PRNG with the RandomSeeder for the corresponding SeedGenerator, to schedule reseeding when we run out of entropy.
void	setSameThreadSeedGen(SeedGenerator newSeedGen)	Sets the seed generator that is used on the calling thread if not registered with a running RandomSeeder.
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).
void	setWrapped(T wrapped)	Replaces the wrapped PRNG with the given one on subsequent calls.
static EntropyBlockingRandomWrapper<Random>	wrapJavaUtilRandom(long minimumEntropy, byte[] seed, SeedGenerator sameThreadSeedGen)	Creates an instance wrapping a basic Random.
static EntropyBlockingRandomWrapper<Random>	wrapJavaUtilRandom(long minimumEntropy, SeedGenerator seedGenerator)	Creates an instance wrapping a basic Random.

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

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

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

checkLength, checkValidRange, 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(T wrapped,
                                    long minimumEntropy,
                                    @Nullable
                                    SeedGenerator sameThreadSeedGen)

Parameters:

wrapped - the Random to wrap

minimumEntropy - the minimum entropy, below which requests for pseudorandom numbers will block until the PRNG is reseeded

sameThreadSeedGen - a SeedGenerator, if any, to use on the calling thread if this PRNG does not have a running RandomSeeder

Method Detail

wrapJavaUtilRandom

public static EntropyBlockingRandomWrapper<Random> wrapJavaUtilRandom(long minimumEntropy,
                                                                      SeedGenerator seedGenerator)
                                                               throws SeedException

Creates an instance wrapping a basic Random.

Parameters:

minimumEntropy - the minimum entropy, below which requests for pseudorandom numbers will block until the PRNG is reseeded

seedGenerator - a SeedGenerator to generate the initial seed; also used for reseeding if this PRNG does not have a running RandomSeeder

Returns:

an instance

Throws:

SeedException - if the SeedGenerator fails to generate an initial seed

wrapJavaUtilRandom

public static EntropyBlockingRandomWrapper<Random> wrapJavaUtilRandom(long minimumEntropy,
                                                                      byte[] seed,
                                                                      @Nullable
                                                                      SeedGenerator sameThreadSeedGen)

Creates an instance wrapping a basic Random.

Parameters:

seed - the seed

minimumEntropy - the minimum entropy, below which requests for pseudorandom numbers will block until the PRNG is reseeded

sameThreadSeedGen - a SeedGenerator, if any, to use on the calling thread if this PRNG does not have a running RandomSeeder

Returns:

an instance

setWrapped

public void setWrapped(T wrapped)

Description copied from class: RandomWrapper

Replaces the wrapped PRNG with the given one on subsequent calls.

Overrides:

setWrapped in class RandomWrapper<T extends Random>

Parameters:

wrapped - an Random instance to wrap

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.

Overrides:

nextBytes in class RandomWrapper<T extends Random>

getSameThreadSeedGen

@Nullable
public SeedGenerator getSameThreadSeedGen()

Returns the seed generator that is used on the calling thread if not registered with a running RandomSeeder.

Returns:

the seed generator

setSameThreadSeedGen

public void setSameThreadSeedGen(@Nullable
                                 SeedGenerator newSeedGen)

Sets the seed generator that is used on the calling thread if not registered with a running RandomSeeder.

Parameters:

newSeedGen - the new seed generator

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<T extends Random>

Parameters:

seed - The new seed.

setRandomSeeder

public void setRandomSeeder(@Nullable
                            RandomSeeder randomSeeder)

Description copied from class: BaseRandom

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

Overrides:

setRandomSeeder in class BaseRandom

Parameters:

randomSeeder - a SeedGenerator whose RandomSeeder 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.

Overrides:

setSeed in class RandomWrapper<T extends Random>

See Also:

ByteArrayReseedableRandom.preferSeedWithLong()

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.

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 RandomSeeder is attached or a new seed is generated, so that operations can unblock.

Parameters:

reseeded - true if the seed has changed; false otherwise