Class SeedFactory
This class provides methods to generate random seeds (single values
or arrays of values, of int
or long
types) that can
be passed to the methods that create a generator instance
.
Although the seed-generating methods defined in this class will likely
return different values for all calls, there is no guarantee that the
produced seed will result always in a "good" sequence of numbers (even
if the generator initialized with that seed is good).
There is no guarantee that sequences will not overlap.
- Since:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final int
Size of block to fill in anint[]
seed per synchronized operation.private static final ReentrantLock
The lock to own when using the seed generator.private static final int
Size of block to fill in along[]
seed per synchronized operation.private static final UniformRandomProvider
Generator with a long period.private static final int
Size of the state array of "XoRoShiRo1024PlusPlus". -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) static byte[]
createByteArray
(UniformRandomProvider source, int n, int from, int to) Creates an array ofbyte
numbers for use as a seed using the supplied source of randomness.static int
Creates anint
number for use as a seed.static int[]
createIntArray
(int n) Creates an array ofint
numbers for use as a seed.(package private) static int[]
createIntArray
(int n, int from, int to) Creates an array ofint
numbers for use as a seed.static long
Creates along
number for use as a seed.static long[]
createLongArray
(int n) Creates an array oflong
numbers for use as a seed.(package private) static long[]
createLongArray
(int n, int from, int to) Creates an array oflong
numbers for use as a seed.(package private) static void
ensureNonZero
(byte[] seed, int from, int to, UniformRandomProvider source) Ensure the seed is not all-zero within the specified sub-range.(package private) static void
ensureNonZero
(int[] seed, int from, int to) Ensure the seed is not all-zero within the specified sub-range.(package private) static void
ensureNonZero
(long[] seed, int from, int to) Ensure the seed is not all-zero within the specified sub-range.(package private) static long
ensureNonZero
(RandomLongSource source, long value) Ensure the value is non-zero.private static void
fillIntArray
(int[] array, int start, int end) Fill the array betweenstart
inclusive andend
exclusive from the seed generator.private static void
fillLongArray
(long[] array, int start, int end) Fill the array betweenstart
inclusive andend
exclusive from the seed generator.
-
Field Details
-
XO_RO_SHI_RO_1024_STATE_SIZE
private static final int XO_RO_SHI_RO_1024_STATE_SIZESize of the state array of "XoRoShiRo1024PlusPlus".- See Also:
-
INT_ARRAY_BLOCK_SIZE
private static final int INT_ARRAY_BLOCK_SIZESize of block to fill in anint[]
seed per synchronized operation.- See Also:
-
LONG_ARRAY_BLOCK_SIZE
private static final int LONG_ARRAY_BLOCK_SIZESize of block to fill in along[]
seed per synchronized operation.- See Also:
-
LOCK
The lock to own when using the seed generator. This lock is unfair and there is no particular access order for waiting threads.This is used as an alternative to
synchronized
statements to guard access to the seed generator. -
SEED_GENERATOR
Generator with a long period.
-
-
Constructor Details
-
SeedFactory
private SeedFactory()Class contains only static methods.
-
-
Method Details
-
createInt
public static int createInt()Creates anint
number for use as a seed.- Returns:
- a random number.
-
createLong
public static long createLong()Creates along
number for use as a seed.- Returns:
- a random number.
-
createIntArray
public static int[] createIntArray(int n) Creates an array ofint
numbers for use as a seed.- Parameters:
n
- Size of the array to create.- Returns:
- an array of
n
random numbers.
-
createIntArray
static int[] createIntArray(int n, int from, int to) Creates an array ofint
numbers for use as a seed. Optionally ensure a sub-range of the array is not all-zero.This method is package-private for use by
NativeSeedType
.- Parameters:
n
- Size of the array to create.from
- The start of the not all-zero sub-range (inclusive).to
- The end of the not all-zero sub-range (exclusive).- Returns:
- an array of
n
random numbers. - Throws:
IndexOutOfBoundsException
- if the sub-range is invalid- Since:
- 1.5
-
createLongArray
public static long[] createLongArray(int n) Creates an array oflong
numbers for use as a seed.- Parameters:
n
- Size of the array to create.- Returns:
- an array of
n
random numbers.
-
createLongArray
static long[] createLongArray(int n, int from, int to) Creates an array oflong
numbers for use as a seed. Optionally ensure a sub-range of the array is not all-zero.This method is package-private for use by
NativeSeedType
.- Parameters:
n
- Size of the array to create.from
- The start of the not all-zero sub-range (inclusive).to
- The end of the not all-zero sub-range (exclusive).- Returns:
- an array of
n
random numbers. - Throws:
IndexOutOfBoundsException
- if the sub-range is invalid- Since:
- 1.5
-
fillIntArray
private static void fillIntArray(int[] array, int start, int end) Fill the array betweenstart
inclusive andend
exclusive from the seed generator. The lock is used to guard access to the generator.- Parameters:
array
- Array data.start
- Start (inclusive).end
- End (exclusive).
-
fillLongArray
private static void fillLongArray(long[] array, int start, int end) Fill the array betweenstart
inclusive andend
exclusive from the seed generator. The lock is used to guard access to the generator.- Parameters:
array
- Array data.start
- Start (inclusive).end
- End (exclusive).
-
createByteArray
Creates an array ofbyte
numbers for use as a seed using the supplied source of randomness. A sub-range can be specified that must not contain all zeros.- Parameters:
source
- Source of randomness.n
- Size of the array to create.from
- The start of the not all-zero sub-range (inclusive).to
- The end of the not all-zero sub-range (exclusive).- Returns:
- an array of
n
random numbers.
-
ensureNonZero
static void ensureNonZero(int[] seed, int from, int to) Ensure the seed is not all-zero within the specified sub-range.This method will check the sub-range and if all are zero it will fill the range with a random sequence seeded from the default source of random int values. The fill ensures position
from
has a non-zero value; and the entire sub-range has a maximum of one zero. The method ensures any length sub-range contains non-zero bits. The output seed is suitable for generators that cannot be seeded with all zeros in the specified sub-range.- Parameters:
seed
- Seed array (modified in place).from
- The start of the not all-zero sub-range (inclusive).to
- The end of the not all-zero sub-range (exclusive).- Throws:
IndexOutOfBoundsException
- if the sub-range is invalid- See Also:
-
ensureNonZero
static void ensureNonZero(long[] seed, int from, int to) Ensure the seed is not all-zero within the specified sub-range.This method will check the sub-range and if all are zero it will fill the range with a random sequence seeded from the default source of random long values. The fill ensures position
from
has a non-zero value; and the entire sub-range has a maximum of one zero. The method ensures any length sub-range contains non-zero bits. The output seed is suitable for generators that cannot be seeded with all zeros in the specified sub-range.- Parameters:
seed
- Seed array (modified in place).from
- The start of the not all-zero sub-range (inclusive).to
- The end of the not all-zero sub-range (exclusive).- Throws:
IndexOutOfBoundsException
- if the sub-range is invalid- See Also:
-
ensureNonZero
Ensure the seed is not all-zero within the specified sub-range.This method will check the sub-range and if all are zero it will fill the range with a random sequence seeded from the provided source of randomness. If the range length is above 8 then the first 8 bytes in the range are ensured to not all be zero. If the range length is below 8 then the first byte in the range is ensured to be non-zero. The method ensures any length sub-range contains non-zero bits. The output seed is suitable for generators that cannot be seeded with all zeros in the specified sub-range.
- Parameters:
seed
- Seed array (modified in place).from
- The start of the not all-zero sub-range (inclusive).to
- The end of the not all-zero sub-range (exclusive).source
- Source of randomness.- Throws:
IndexOutOfBoundsException
- if the sub-range is invalid
-
ensureNonZero
Ensure the value is non-zero.This method will replace a zero with a non-zero random number from the random source.
- Parameters:
source
- Source of randomness.value
- Value.- Returns:
value
if non-zero; else a new random number
-