1 // Copyright 2017 The Abseil Authors.
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
7 // https://www.apache.org/licenses/LICENSE-2.0
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.
15 // -----------------------------------------------------------------------------
17 // -----------------------------------------------------------------------------
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.
24 // The Abseil random library provides the following URBG types:
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.
31 #ifndef ABSL_RANDOM_RANDOM_H_
32 #define ABSL_RANDOM_RANDOM_H_
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
45 // -----------------------------------------------------------------------------
47 // -----------------------------------------------------------------------------
49 // `absl::BitGen` is a general-purpose random bit generator for generating
50 // random values for use within the Abseil random library. Typically, you use a
51 // bit generator in combination with a distribution to provide random values.
55 // // Create an absl::BitGen. There is no need to seed this bit generator.
58 // // Generate an integer value in the closed interval [1,6]
59 // int die_roll = absl::uniform_int_distribution<int>(1, 6)(gen);
61 // `absl::BitGen` is seeded by default with non-deterministic data to produce
62 // different sequences of random values across different instances, including
63 // different binary invocations. This behavior is different than the standard
64 // library bit generators, which use golden values as their seeds. Default
65 // construction intentionally provides no stability guarantees, to avoid
66 // accidental dependence on such a property.
68 // `absl::BitGen` may be constructed with an optional seed sequence type,
69 // conforming to [rand.req.seed_seq], which will be mixed with additional
70 // non-deterministic data.
74 // // Create an absl::BitGen using an std::seed_seq seed sequence
75 // std::seed_seq seq{1,2,3};
76 // absl::BitGen gen_with_seed(seq);
78 // // Generate an integer value in the closed interval [1,6]
79 // int die_roll2 = absl::uniform_int_distribution<int>(1, 6)(gen_with_seed);
81 // `absl::BitGen` meets the requirements of the Uniform Random Bit Generator
82 // (URBG) concept as per the C++17 standard [rand.req.urng] though differs
83 // slightly with [rand.req.eng]. Like its standard library equivalents (e.g.
84 // `std::mersenne_twister_engine`) `absl::BitGen` is not cryptographically
87 // Constructing two `absl::BitGen`s with the same seed sequence in the same
88 // binary will produce the same sequence of variates within the same binary, but
89 // need not do so across multiple binary invocations.
91 // This type has been optimized to perform better than Mersenne Twister
92 // (https://en.wikipedia.org/wiki/Mersenne_Twister) and many other complex URBG
93 // types on modern x86, ARM, and PPC architectures.
95 // This type is thread-compatible, but not thread-safe.
97 // ---------------------------------------------------------------------------
98 // absl::BitGen member functions
99 // ---------------------------------------------------------------------------
101 // absl::BitGen::operator()()
103 // Calls the BitGen, returning a generated value.
105 // absl::BitGen::min()
107 // Returns the smallest possible value from this bit generator.
109 // absl::BitGen::max()
111 // Returns the largest possible value from this bit generator., and
113 // absl::BitGen::discard(num)
115 // Advances the internal state of this bit generator by `num` times, and
116 // discards the intermediate results.
117 // ---------------------------------------------------------------------------
119 using BitGen = random_internal::NonsecureURBGBase<
120 random_internal::randen_engine<uint64_t>>;
122 // -----------------------------------------------------------------------------
123 // absl::InsecureBitGen
124 // -----------------------------------------------------------------------------
126 // `absl::InsecureBitGen` is an efficient random bit generator for generating
127 // random values, recommended only for performance-sensitive use cases where
128 // `absl::BitGen` is not satisfactory when compute-bounded by bit generation
133 // // Create an absl::InsecureBitGen
134 // absl::InsecureBitGen gen;
135 // for (size_t i = 0; i < 1000000; i++) {
137 // // Generate a bunch of random values from some complex distribution
138 // auto my_rnd = some_distribution(gen, 1, 1000);
141 // Like `absl::BitGen`, `absl::InsecureBitGen` is seeded by default with
142 // non-deterministic data to produce different sequences of random values across
143 // different instances, including different binary invocations. (This behavior
144 // is different than the standard library bit generators, which use golden
145 // values as their seeds.)
147 // `absl::InsecureBitGen` may be constructed with an optional seed sequence
148 // type, conforming to [rand.req.seed_seq], which will be mixed with additional
149 // non-deterministic data. (See std_seed_seq.h for more information.)
151 // `absl::InsecureBitGen` meets the requirements of the Uniform Random Bit
152 // Generator (URBG) concept as per the C++17 standard [rand.req.urng] though
153 // its implementation differs slightly with [rand.req.eng]. Like its standard
154 // library equivalents (e.g. `std::mersenne_twister_engine`)
155 // `absl::InsecureBitGen` is not cryptographically secure.
157 // Prefer `absl::BitGen` over `absl::InsecureBitGen` as the general type is
158 // often fast enough for the vast majority of applications.
160 using InsecureBitGen =
161 random_internal::NonsecureURBGBase<random_internal::pcg64_2018_engine>;
163 // ---------------------------------------------------------------------------
164 // absl::InsecureBitGen member functions
165 // ---------------------------------------------------------------------------
167 // absl::InsecureBitGen::operator()()
169 // Calls the InsecureBitGen, returning a generated value.
171 // absl::InsecureBitGen::min()
173 // Returns the smallest possible value from this bit generator.
175 // absl::InsecureBitGen::max()
177 // Returns the largest possible value from this bit generator.
179 // absl::InsecureBitGen::discard(num)
181 // Advances the internal state of this bit generator by `num` times, and
182 // discards the intermediate results.
183 // ---------------------------------------------------------------------------
187 #endif // ABSL_RANDOM_RANDOM_H_