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: seed_sequences.h
17 // -----------------------------------------------------------------------------
18 //
19 // This header contains utilities for creating and working with seed sequences
20 // conforming to [rand.req.seedseq]. In general, direct construction of seed
21 // sequences is discouraged, but use-cases for construction of identical bit
22 // generators (using the same seed sequence) may be helpful (e.g. replaying a
23 // simulation whose state is derived from variates of a bit generator).
24
25 #ifndef ABSL_RANDOM_SEED_SEQUENCES_H_
26 #define ABSL_RANDOM_SEED_SEQUENCES_H_
27
28 #include <iterator>
29 #include <random>
30
31 #include "absl/base/config.h"
32 #include "absl/base/nullability.h"
33 #include "absl/random/internal/salted_seed_seq.h"
34 #include "absl/random/internal/seed_material.h"
35 #include "absl/random/seed_gen_exception.h"
36 #include "absl/strings/string_view.h"
37 #include "absl/types/span.h"
38
39 namespace absl {
40 ABSL_NAMESPACE_BEGIN
41
42 // -----------------------------------------------------------------------------
43 // absl::SeedSeq
44 // -----------------------------------------------------------------------------
45 //
46 // `absl::SeedSeq` constructs a seed sequence according to [rand.req.seedseq]
47 // for use within bit generators. `absl::SeedSeq`, unlike `std::seed_seq`
48 // additionally salts the generated seeds with extra implementation-defined
49 // entropy. For that reason, you can use `absl::SeedSeq` in combination with
50 // standard library bit generators (e.g. `std::mt19937`) to introduce
51 // non-determinism in your seeds.
52 //
53 // Example:
54 //
55 // absl::SeedSeq my_seed_seq({a, b, c});
56 // std::mt19937 my_bitgen(my_seed_seq);
57 //
58 using SeedSeq = random_internal::SaltedSeedSeq<std::seed_seq>;
59
60 // -----------------------------------------------------------------------------
61 // absl::CreateSeedSeqFrom(bitgen*)
62 // -----------------------------------------------------------------------------
63 //
64 // Constructs a seed sequence conforming to [rand.req.seedseq] using variates
65 // produced by a provided bit generator.
66 //
67 // You should generally avoid direct construction of seed sequences, but
68 // use-cases for reuse of a seed sequence to construct identical bit generators
69 // may be helpful (eg. replaying a simulation whose state is derived from bit
70 // generator values).
71 //
72 // If bitgen == nullptr, then behavior is undefined.
73 //
74 // Example:
75 //
76 // absl::BitGen my_bitgen;
77 // auto seed_seq = absl::CreateSeedSeqFrom(&my_bitgen);
78 // absl::BitGen new_engine(seed_seq); // derived from my_bitgen, but not
79 // // correlated.
80 //
81 template <typename URBG>
CreateSeedSeqFrom(URBG * urbg)82 SeedSeq CreateSeedSeqFrom(URBG* urbg) {
83 SeedSeq::result_type
84 seed_material[random_internal::kEntropyBlocksNeeded];
85
86 if (!random_internal::ReadSeedMaterialFromURBG(
87 urbg, absl::MakeSpan(seed_material))) {
88 random_internal::ThrowSeedGenException();
89 }
90 return SeedSeq(std::begin(seed_material), std::end(seed_material));
91 }
92
93 // -----------------------------------------------------------------------------
94 // absl::MakeSeedSeq()
95 // -----------------------------------------------------------------------------
96 //
97 // Constructs an `absl::SeedSeq` salting the generated values using
98 // implementation-defined entropy. The returned sequence can be used to create
99 // equivalent bit generators correlated using this sequence.
100 //
101 // Example:
102 //
103 // auto my_seed_seq = absl::MakeSeedSeq();
104 // std::mt19937 rng1(my_seed_seq);
105 // std::mt19937 rng2(my_seed_seq);
106 // EXPECT_EQ(rng1(), rng2());
107 //
108 SeedSeq MakeSeedSeq();
109
110 ABSL_NAMESPACE_END
111 } // namespace absl
112
113 #endif // ABSL_RANDOM_SEED_SEQUENCES_H_
114