1 // Copyright 2017 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //      https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 //
15 // -----------------------------------------------------------------------------
16 // File: random.h
17 // -----------------------------------------------------------------------------
18 //
19 // This header defines the recommended Uniform Random Bit Generator (URBG)
20 // types for use within the Abseil Random library. These types are not
21 // suitable for security-related use-cases, but should suffice for most other
22 // uses of generating random values.
23 //
24 // The Abseil random library provides the following URBG types:
25 //
26 //   * BitGen, a good general-purpose bit generator, optimized for generating
27 //     random (but not cryptographically secure) values
28 //   * InsecureBitGen, a slightly faster, though less random, bit generator, for
29 //     cases where the existing BitGen is a drag on performance.
30 
31 #ifndef ABSL_RANDOM_RANDOM_H_
32 #define ABSL_RANDOM_RANDOM_H_
33 
34 #include <random>
35 
36 #include "absl/random/distributions.h"  // IWYU pragma: export
37 #include "absl/random/internal/nonsecure_base.h"  // IWYU pragma: export
38 #include "absl/random/internal/pcg_engine.h"  // IWYU pragma: export
39 #include "absl/random/internal/pool_urbg.h"
40 #include "absl/random/internal/randen_engine.h"
41 #include "absl/random/seed_sequences.h"  // IWYU pragma: export
42 
43 namespace absl {
44 ABSL_NAMESPACE_BEGIN
45 
46 // -----------------------------------------------------------------------------
47 // absl::BitGen
48 // -----------------------------------------------------------------------------
49 //
50 // `absl::BitGen` is a general-purpose random bit generator for generating
51 // random values for use within the Abseil random library. Typically, you use a
52 // bit generator in combination with a distribution to provide random values.
53 //
54 // Example:
55 //
56 //   // Create an absl::BitGen. There is no need to seed this bit generator.
57 //   absl::BitGen gen;
58 //
59 //   // Generate an integer value in the closed interval [1,6]
60 //   int die_roll = absl::uniform_int_distribution<int>(1, 6)(gen);
61 //
62 // `absl::BitGen` is seeded by default with non-deterministic data to produce
63 // different sequences of random values across different instances, including
64 // different binary invocations. This behavior is different than the standard
65 // library bit generators, which use golden values as their seeds. Default
66 // construction intentionally provides no stability guarantees, to avoid
67 // accidental dependence on such a property.
68 //
69 // `absl::BitGen` may be constructed with an optional seed sequence type,
70 // conforming to [rand.req.seed_seq], which will be mixed with additional
71 // non-deterministic data.
72 //
73 // Example:
74 //
75 //  // Create an absl::BitGen using an std::seed_seq seed sequence
76 //  std::seed_seq seq{1,2,3};
77 //  absl::BitGen gen_with_seed(seq);
78 //
79 //  // Generate an integer value in the closed interval [1,6]
80 //  int die_roll2 = absl::uniform_int_distribution<int>(1, 6)(gen_with_seed);
81 //
82 // `absl::BitGen` meets the requirements of the Uniform Random Bit Generator
83 // (URBG) concept as per the C++17 standard [rand.req.urng] though differs
84 // slightly with [rand.req.eng]. Like its standard library equivalents (e.g.
85 // `std::mersenne_twister_engine`) `absl::BitGen` is not cryptographically
86 // secure.
87 //
88 // Constructing two `absl::BitGen`s with the same seed sequence in the same
89 // binary will produce the same sequence of variates within the same binary, but
90 // need not do so across multiple binary invocations.
91 //
92 // This type has been optimized to perform better than Mersenne Twister
93 // (https://en.wikipedia.org/wiki/Mersenne_Twister) and many other complex URBG
94 // types on modern x86, ARM, and PPC architectures.
95 //
96 // This type is thread-compatible, but not thread-safe.
97 
98 // ---------------------------------------------------------------------------
99 // absl::BitGen member functions
100 // ---------------------------------------------------------------------------
101 
102 // absl::BitGen::operator()()
103 //
104 // Calls the BitGen, returning a generated value.
105 
106 // absl::BitGen::min()
107 //
108 // Returns the smallest possible value from this bit generator.
109 
110 // absl::BitGen::max()
111 //
112 // Returns the largest possible value from this bit generator.
113 
114 // absl::BitGen::discard(num)
115 //
116 // Advances the internal state of this bit generator by `num` times, and
117 // discards the intermediate results.
118 // ---------------------------------------------------------------------------
119 
120 using BitGen = random_internal::NonsecureURBGBase<
121     random_internal::randen_engine<uint64_t>>;
122 
123 // -----------------------------------------------------------------------------
124 // absl::InsecureBitGen
125 // -----------------------------------------------------------------------------
126 //
127 // `absl::InsecureBitGen` is an efficient random bit generator for generating
128 // random values, recommended only for performance-sensitive use cases where
129 // `absl::BitGen` is not satisfactory when compute-bounded by bit generation
130 // costs.
131 //
132 // Example:
133 //
134 //   // Create an absl::InsecureBitGen
135 //   absl::InsecureBitGen gen;
136 //   for (size_t i = 0; i < 1000000; i++) {
137 //
138 //     // Generate a bunch of random values from some complex distribution
139 //     auto my_rnd = some_distribution(gen, 1, 1000);
140 //   }
141 //
142 // Like `absl::BitGen`, `absl::InsecureBitGen` is seeded by default with
143 // non-deterministic data to produce different sequences of random values across
144 // different instances, including different binary invocations. (This behavior
145 // is different than the standard library bit generators, which use golden
146 // values as their seeds.)
147 //
148 // `absl::InsecureBitGen` may be constructed with an optional seed sequence
149 // type, conforming to [rand.req.seed_seq], which will be mixed with additional
150 // non-deterministic data. (See std_seed_seq.h for more information.)
151 //
152 // `absl::InsecureBitGen` meets the requirements of the Uniform Random Bit
153 // Generator (URBG) concept as per the C++17 standard [rand.req.urng] though
154 // its implementation differs slightly with [rand.req.eng]. Like its standard
155 // library equivalents (e.g. `std::mersenne_twister_engine`)
156 // `absl::InsecureBitGen` is not cryptographically secure.
157 //
158 // Prefer `absl::BitGen` over `absl::InsecureBitGen` as the general type is
159 // often fast enough for the vast majority of applications.
160 
161 using InsecureBitGen =
162     random_internal::NonsecureURBGBase<random_internal::pcg64_2018_engine>;
163 
164 // ---------------------------------------------------------------------------
165 // absl::InsecureBitGen member functions
166 // ---------------------------------------------------------------------------
167 
168 // absl::InsecureBitGen::operator()()
169 //
170 // Calls the InsecureBitGen, returning a generated value.
171 
172 // absl::InsecureBitGen::min()
173 //
174 // Returns the smallest possible value from this bit generator.
175 
176 // absl::InsecureBitGen::max()
177 //
178 // Returns the largest possible value from this bit generator.
179 
180 // absl::InsecureBitGen::discard(num)
181 //
182 // Advances the internal state of this bit generator by `num` times, and
183 // discards the intermediate results.
184 // ---------------------------------------------------------------------------
185 
186 ABSL_NAMESPACE_END
187 }  // namespace absl
188 
189 #endif  // ABSL_RANDOM_RANDOM_H_
190