|
1 /* |
|
2 * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. |
|
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
4 * |
|
5 * This code is free software; you can redistribute it and/or modify it |
|
6 * under the terms of the GNU General Public License version 2 only, as |
|
7 * published by the Free Software Foundation. Oracle designates this |
|
8 * particular file as subject to the "Classpath" exception as provided |
|
9 * by Oracle in the LICENSE file that accompanied this code. |
|
10 * |
|
11 * This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 * version 2 for more details (a copy is included in the LICENSE file that |
|
15 * accompanied this code). |
|
16 * |
|
17 * You should have received a copy of the GNU General Public License version |
|
18 * 2 along with this work; if not, write to the Free Software Foundation, |
|
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 * |
|
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
22 * or visit www.oracle.com if you need additional information or have any |
|
23 * questions. |
|
24 */ |
|
25 |
|
26 /** |
|
27 * Classes and interfaces that support the definition and use of "random generators", a term that |
|
28 * is meant to cover what have traditionally been called "random number generators" as well as |
|
29 * generators of other sorts of randomly chosen values, and also to cover not only deterministic |
|
30 * (pseudorandom) algorithms but also generators of values that use some "truly random" physical |
|
31 * source (perhaps making use of thermal noise, for example, or quantum-mechanical effects). |
|
32 * |
|
33 * The principal interface is {@link java.util.random.RandomGenerator}, which provides methods |
|
34 * for requesting individual values of type {@code int}, {@code long}, {@code float}, {@code double}, or {@code boolean} |
|
35 * chosen (pseudo)randomly from a uniform distribution; methods for requesting values of type {@code double} |
|
36 * chosen (pseudo)randomly from a normal distribution or from an exponential distribution; |
|
37 * and methods for creating streams of (pseudo)randomly chosen values of type {@code int}, {@code long}, or {@code double}. |
|
38 * These streams are spliterator-based, allowing for parallel processing of their elements. |
|
39 * |
|
40 * An important subsidiary interface is {@link java.util.random.RandomGenerator.StreamableGenerator}, |
|
41 * which provides methods for creating spliterator-based streams of {@code RandomGenerator} objects, |
|
42 * allowing for allowing for parallel processing of these objects using multiple threads. |
|
43 * Unlike {@link java.util.Random}, most implementations of {@code java.util.random.RandomGenerator} |
|
44 * are <i>not</i> thread-safe. The intent is that instances should not be shared among threads; |
|
45 * rather, each thread should have its own random generator(s) to use. The various pseudorandom algorithms |
|
46 * provided by this package are designed so that multiple instances will (with very high probability) behave as |
|
47 * if statistically independent. |
|
48 * |
|
49 * Historically, most pseudorandom generator algorithms have been based on some sort of |
|
50 * finite-state machine with a single, large cycle of states; when it is necessary to have |
|
51 * multiple threads use the same algorithm simultaneously, the usual technique is to arrange for |
|
52 * each thread to traverse a different region of the state cycle. These regions may be doled out |
|
53 * to threads by starting with a single initial state and then using a "jump function" that |
|
54 * travels a long distance around the cycle (perhaps 2<sup>64</sup> steps or more); the jump function is applied repeatedly |
|
55 * and sequentially, to identify widely spaced initial states for each thread's generator. This strategy is |
|
56 * supported by the interface {@link java.util.random.RandomGenerator.JumpableGenerator}. |
|
57 * Sometimes it is desirable to support two levels of jumping (by long distances and |
|
58 * by <i>really</i> long distances); this strategy is supported by the interface |
|
59 * {@link java.util.random.RandomGenerator.LeapableGenerator}. There is also an interface |
|
60 * {@link java.util.random.RandomGenerator.ArbitrarilyJumpableGenerator} for algorithms that |
|
61 * allow jumping along the state cycle by any user-specified distance. |
|
62 * In this package, implementations of these interfaces include |
|
63 * {@link java.util.random.Xoroshiro128PlusPlus}, |
|
64 * {@link java.util.random.Xoroshiro128StarStar}, |
|
65 * {@link java.util.random.Xoshiro256StarStar}, |
|
66 * and {@link java.util.random.MRG32K3A}. |
|
67 * |
|
68 * A more recent category of "splittable" pseudorandom generator algorithms uses a large family |
|
69 * of state cycles and makes some attempt to ensure that distinct instances use different state |
|
70 * cycles; but even if two instances "accidentally" use the same state cycle, they are highly |
|
71 * likely to traverse different regions parts of that shared state cycle. This strategy is |
|
72 * supported by the interface {@link java.util.random.RandomGenerator.SplittableGenerator}. |
|
73 * In this package, implementations of this interface include |
|
74 * {@link java.util.random.L32X64MixRandom}, |
|
75 * {@link java.util.random.L64X128MixRandom}, |
|
76 * {@link java.util.random.L64X128PlusPlusRandom}, |
|
77 * {@link java.util.random.L64X128StarStarMixRandom}, |
|
78 * {@link java.util.random.L64X256MixRandom}, |
|
79 * {@link java.util.random.L64X1024MixRandom}, |
|
80 * {@link java.util.random.L128X128MixRandom}, |
|
81 * {@link java.util.random.L128X128PlusPlusRandom}, |
|
82 * {@link java.util.random.L128X128StarStarMixRandom}, |
|
83 * {@link java.util.random.L128X256MixRandom}, |
|
84 * {@link java.util.random.L128X1024MixRandom}, |
|
85 * and {@link java.util.SplittableRandom}. |
|
86 * Generally speaking, among the "{@code LmmmXnnn}" generators, the state size of the generator is |
|
87 * {@code (mmm - 1 + nnn)} bits and the memory required for an instance is {@code (2 * mmm + nnn)} bits; |
|
88 * larger values of "{@code mmm}" imply a lower probability that two instances will traverse the |
|
89 * same state cycle; and larger values of "{@code nnn}" imply that the generator is equidistributed |
|
90 * in a larger number of dimensions. A class with "{@code Mix}" in its name uses a strong mixing |
|
91 * function with excellent avalanche characteristics; a class with "{@code StarStar}" or "{@code PlusPlus}" |
|
92 * in its name uses a weaker but faster mixing function. See the documentation for individual classes |
|
93 * for details about their specific characteristics. |
|
94 * |
|
95 * The class {@link java.util.random.RandomSupport} provides utility methods, constants, and |
|
96 * abstract classes frequently useful in the implementation of pseudorandom number generators |
|
97 * that satisfy the interface {@link RandomGenerator}. |
|
98 * |
|
99 * @since 14 |
|
100 */ |
|
101 |
|
102 package java.util.random; |
|
103 |
|
104 |