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